/**
* Store any amount of any type of data accessible by an identifier string.
*
- * @todo Deprecate access by index after NamedData has been deprecated
- * for long enough, then change to a map.
+ * @todo Deprecate access by index after NamedData has been deprecated for
+ * long enough, then change to a map.
*/
class AnyData :
public Subscriptor
/**
* @brief Access to stored data object by name.
*
- * Find the object with given name, try to convert it to
- * <tt>type</tt> and return it. This function throws an exception
- * if either the name does not exist or if the conversion
- * fails. If such an exception is not desired, use try_read()
- * instead.
+ * Find the object with given name, try to convert it to <tt>type</tt> and
+ * return it. This function throws an exception if either the name does not
+ * exist or if the conversion fails. If such an exception is not desired,
+ * use try_read() instead.
*/
template <typename type>
type entry (const std::string &name);
/**
* @brief Read-only access to stored data object by name.
*
- * Find the object with given name, try to convert it to
- * <tt>type</tt> and return it. This function throws an exception
- * if either the name does not exist or if the conversion
- * fails. If such an exception is not desired, use try_read()
- * instead.
+ * Find the object with given name, try to convert it to <tt>type</tt> and
+ * return it. This function throws an exception if either the name does not
+ * exist or if the conversion fails. If such an exception is not desired,
+ * use try_read() instead.
*/
template <typename type>
const type entry (const std::string &name) const;
/**
* @brief Dedicated read only access by name.
*
- * For a constant object, this function equals entry(). For a
- * non-const object, it forces read only access to the data. In
- * particular, it throws an exception if the object is not found
- * or cannot be converted to type. If such an exception is not
- * desired, use try_read() instead.
+ * For a constant object, this function equals entry(). For a non-const
+ * object, it forces read only access to the data. In particular, it throws
+ * an exception if the object is not found or cannot be converted to type.
+ * If such an exception is not desired, use try_read() instead.
*
- * @warning Do not use this function for stored objects which are
- * pointers. Use read_ptr() instead!
+ * @warning Do not use this function for stored objects which are pointers.
+ * Use read_ptr() instead!
*/
template <typename type>
const type read (const std::string &name) const;
/**
* @brief Dedicated read only access by name for pointer data.
*
- * If the stored data object is a pointer to a constant object, the logic
- * of access becomes fairly complicated. Namely, the standard read
- * function may fail, depending on whether it was a const pointer
- * or a regular pointer. This function fixes the logic and
- * ascertains that the object does not become mutable by accident.
+ * If the stored data object is a pointer to a constant object, the logic of
+ * access becomes fairly complicated. Namely, the standard read function may
+ * fail, depending on whether it was a const pointer or a regular pointer.
+ * This function fixes the logic and ascertains that the object does not
+ * become mutable by accident.
*/
template <typename type>
const type *read_ptr (const std::string &name) const;
/**
- * Perform the same action as read_ptr(), but do not throw an
- * exception if the pointer does not exist. Return a null pointer
- * instead.
+ * Perform the same action as read_ptr(), but do not throw an exception if
+ * the pointer does not exist. Return a null pointer instead.
*/
template <typename type>
const type *try_read_ptr (const std::string &name) const;
/**
* @brief Dedicated read only access by name without exceptions.
*
- * This function tries to find the name in the list and return a
- * pointer to the associated object. If either the name is not
- * found or the object cannot be converted to the return type, a
- * null pointer is returned.
+ * This function tries to find the name in the list and return a pointer to
+ * the associated object. If either the name is not found or the object
+ * cannot be converted to the return type, a null pointer is returned.
*/
template <typename type>
const type *try_read (const std::string &name) const;
/**
* @brief Find index of a named object
*
- * Try to find the objecty and return its index in the list. Throw
- * an exception if the object has not been found.
+ * Try to find the objecty and return its index in the list. Throw an
+ * exception if the object has not been found.
*/
unsigned int find(const std::string &name) const;
/**
* @brief Try to find index of a named object
*
- * Try to find the objecty and return its index in the
- * list. returns numbers::invalid_unsigned_int if the name was not
- * found.
+ * Try to find the objecty and return its index in the list. returns
+ * numbers::invalid_unsigned_int if the name was not found.
*/
unsigned int try_find(const std::string &name) const;
<< " must coincide");
/**
- * Exception indicating that a function expected a vector to have a
- * certain name, but NamedData had a different name in that
- * position.
+ * Exception indicating that a function expected a vector to have a certain
+ * name, but NamedData had a different name in that position.
*/
DeclException2(ExcNameMismatch, int, std::string,
<< "Name at position " << arg1 << " is not equal to " << arg2);
namespace Algorithms
{
/**
- * Operator class performing Newton's iteration with standard step
- * size control and adaptive matrix generation.
+ * Operator class performing Newton's iteration with standard step size
+ * control and adaptive matrix generation.
*
- * This class performs a Newton iteration up to convergence
- * determined by #control. If after an update the norm of the residual
- * has become larger, then step size control is activated and the
- * update is subsequently divided by two until the residual actually
- * becomes smaller (or the minimal scaling factor determined by
- * #n_stepsize_iterations is reached).
+ * This class performs a Newton iteration up to convergence determined by
+ * #control. If after an update the norm of the residual has become larger,
+ * then step size control is activated and the update is subsequently
+ * divided by two until the residual actually becomes smaller (or the
+ * minimal scaling factor determined by #n_stepsize_iterations is reached).
*
- * Since assembling matrices, depending on the implementation, tends
- * to be costly, this method applies an adaptive reassembling
- * strategy. Only if the reduction factor for the residual is more
- * than #threshold, the event Algorithms::bad_derivative is submitted to
- * #inverse_derivative. It is up to this object to implement
- * reassembling accordingly.
+ * Since assembling matrices, depending on the implementation, tends to be
+ * costly, this method applies an adaptive reassembling strategy. Only if
+ * the reduction factor for the residual is more than #threshold, the event
+ * Algorithms::bad_derivative is submitted to #inverse_derivative. It is up
+ * to this object to implement reassembling accordingly.
*
* <h3>Contents of the AnyData objects</h3>
*
* The only value used by the Newton method is the first vector in the
- * parameter <tt>out</tt> of operator()(). It serves as the start
- * vector of Newton's method and in the end contains the solution. All
- * other vectors of <tt>out</tt> are ignored by Newton's method and
- * its inner Operator objects. All vectors of <tt>in</tt> are forwarded to
- * the inner Operator objects, with additional information added as follows.
+ * parameter <tt>out</tt> of operator()(). It serves as the start vector of
+ * Newton's method and in the end contains the solution. All other vectors
+ * of <tt>out</tt> are ignored by Newton's method and its inner Operator
+ * objects. All vectors of <tt>in</tt> are forwarded to the inner Operator
+ * objects, with additional information added as follows.
*
* When calling (*#residual)(), the NamedData <tt>in</tt> given to the
- * Newton iteration is prepended by a vector <tt>"Newton iterate"</tt>,
- * the current value of the Newton iterate, which can be used to
- * evaluate the residual at this point.
+ * Newton iteration is prepended by a vector <tt>"Newton iterate"</tt>, the
+ * current value of the Newton iterate, which can be used to evaluate the
+ * residual at this point.
*
* For the call to (*#inverse_derivative), the vector <tt>"Newton
* residual"</tt> is inserted before <tt>"Newton iterate"</tt>.
{
public:
/**
- * Constructor, receiving the
- * applications computing the
- * residual and solving the
- * linear problem, respectively.
+ * Constructor, receiving the applications computing the residual and
+ * solving the linear problem, respectively.
*/
Newton (Operator<VECTOR> &residual, Operator<VECTOR> &inverse_derivative);
void initialize (ParameterHandler ¶m) DEAL_II_DEPRECATED;
/**
- * Initialize the pointer
- * data_out for debugging.
+ * Initialize the pointer data_out for debugging.
*/
void initialize (OutputOperator<VECTOR> &output);
/**
- * The actual Newton
- * iteration. The initial value
- * is in <tt>out(0)</tt>, which
- * also contains the result
- * after convergence. Values in
- * <tt>in</tt> are not used by
- * Newton, but will be handed
- * down to the objects
+ * The actual Newton iteration. The initial value is in <tt>out(0)</tt>,
+ * which also contains the result after convergence. Values in <tt>in</tt>
+ * are not used by Newton, but will be handed down to the objects
* #residual and #inverse_derivative.
*/
virtual void operator() (AnyData &out, const AnyData &in);
virtual void notify(const Event &);
/**
- * Set the maximal residual
- * reduction allowed without
- * triggering assembling in the
- * next step. Return the
- * previous value.
+ * Set the maximal residual reduction allowed without triggering
+ * assembling in the next step. Return the previous value.
*/
double threshold(double new_value);
/**
- * Control object for the
- * Newton iteration.
+ * Control object for the Newton iteration.
*/
ReductionControl control;
private:
SmartPointer<Operator<VECTOR>, Newton<VECTOR> > residual;
/**
- * The operator applying the
- * inverse derivative to the residual.
+ * The operator applying the inverse derivative to the residual.
*/
SmartPointer<Operator<VECTOR>, Newton<VECTOR> > inverse_derivative;
/**
- * The operator handling the output
- * in case the debug_vectors is true.
+ * The operator handling the output in case the debug_vectors is true.
* Call the initialize function first.
*/
SmartPointer<OutputOperator<VECTOR>, Newton<VECTOR> > data_out;
/**
- * This flag is set by the
- * function assemble(),
- * indicating that the matrix
- * must be assembled anew upon
- * start.
+ * This flag is set by the function assemble(), indicating that the matrix
+ * must be assembled anew upon start.
*/
bool assemble_now;
/**
- * A flag used to decide how
- * many stepsize iteration
- * should be made. Default is
- * the original value of 21.
+ * A flag used to decide how many stepsize iteration should be made.
+ * Default is the original value of 21.
*
- * Enter zero here to turn of
- * stepsize control.
+ * Enter zero here to turn of stepsize control.
*
- * @note Controlled by
- * <tt>Stepsize iterations</tt> in
- * parameter file
+ * @note Controlled by <tt>Stepsize iterations</tt> in parameter file
*/
unsigned int n_stepsize_iterations;
/**
* Threshold for re-assembling matrix.
*
- * If the quotient of two
- * consecutive residuals is
- * smaller than this threshold,
- * the system matrix is not
- * assembled in this step.
+ * If the quotient of two consecutive residuals is smaller than this
+ * threshold, the system matrix is not assembled in this step.
*
- * @note This parameter should be
- * adjusted to the residual gain
- * of the inner solver.
+ * @note This parameter should be adjusted to the residual gain of the
+ * inner solver.
*
- * The default values is zero,
- * resulting in reassembling in
- * every Newton step.
+ * The default values is zero, resulting in reassembling in every Newton
+ * step.
*/
double assemble_threshold;
public:
/**
- * Print residual, update and
- * updated solution after each
- * step into file
+ * Print residual, update and updated solution after each step into file
* <tt>Newton_NNN</tt>?
*/
bool debug_vectors;
/**
- * Write debug output to
- * @p deallog; the higher the
- * number, the more output.
+ * Write debug output to @p deallog; the higher the number, the more
+ * output.
*/
unsigned int debug;
};
/**
* Namespace containing numerical algorithms in a unified form.
*
- * All algorithmic classes in this namespace are derived from either
- * Operator or OutputOperator, depending on whether they return a
- * value or not. See the documentation of those classes for more
- * detailed information on how to use them.
+ * All algorithmic classes in this namespace are derived from either Operator
+ * or OutputOperator, depending on whether they return a value or not. See the
+ * documentation of those classes for more detailed information on how to use
+ * them.
*
* @author Guido Kanschat
* @date 2012, 2013
/**
* @todo Update this documentation and the one of Operator
*
- * The abstract base class of all algorithms in this library. An
- * operator is an object with an operator(), which transforms a set
- * of named vectors into another set of named vectors.
+ * The abstract base class of all algorithms in this library. An operator is
+ * an object with an operator(), which transforms a set of named vectors
+ * into another set of named vectors.
*
- * Furthermore, an operator can be notified of parameter changes by
- * the calling routine. The outer iteration can notify() the Operator
- * of an Event, which could be for instance a change of mesh, a
- * different time step size or too slow convergence of Newton's
- * method, which would then trigger reassembling of a matrix or
- * similar things.
+ * Furthermore, an operator can be notified of parameter changes by the
+ * calling routine. The outer iteration can notify() the Operator of an
+ * Event, which could be for instance a change of mesh, a different time
+ * step size or too slow convergence of Newton's method, which would then
+ * trigger reassembling of a matrix or similar things.
*
* <h3>Usage for nested iterations</h3>
*
- * This is probably the most prominent use for Operator, where an
- * outer iterative method calls an inner solver and so on. Typically,
- * the innermost method in such a nested system will have to compute a
- * residual using values from all outer iterations. Since the depth
- * and order of such a nesting is hardly predictable when designing a
- * general tool, we use AnyData to access these vectors. Typically,
- * the first vector in <tt>out</tt> contains the start vector when
- * operator()() is called, and the solution when the function
- * returns. The object <tt>in</tt> is providing additional information
- * and forwarded to the inner Operator objects of the nested
- * iteration.
+ * This is probably the most prominent use for Operator, where an outer
+ * iterative method calls an inner solver and so on. Typically, the
+ * innermost method in such a nested system will have to compute a residual
+ * using values from all outer iterations. Since the depth and order of such
+ * a nesting is hardly predictable when designing a general tool, we use
+ * AnyData to access these vectors. Typically, the first vector in
+ * <tt>out</tt> contains the start vector when operator()() is called, and
+ * the solution when the function returns. The object <tt>in</tt> is
+ * providing additional information and forwarded to the inner Operator
+ * objects of the nested iteration.
*
* @author Guido Kanschat
* @date 2014
~OperatorBase();
/**
- * The actual operation, which
- * is implemented in a derived class.
+ * The actual operation, which is implemented in a derived class.
*/
virtual void operator() (AnyData &out, const AnyData &in) = 0;
/**
- * Register an event triggered
- * by an outer iteration.
+ * Register an event triggered by an outer iteration.
*/
virtual void notify(const Event &);
/**
void clear_events();
protected:
/**
- * Accumulate events here. If any of
- * those is set, the function
- * solve() of a terminal
- * application must take care
- * of reassembling the matrix.
+ * Accumulate events here. If any of those is set, the function solve() of
+ * a terminal application must take care of reassembling the matrix.
*/
Event notifications;
/**
* @deprecated This class has been replaced by OperatorBase.
*
- * The abstract base class of all algorithms in this library. An
- * operator is an object with an operator(), which transforms a set
- * of named vectors into another set of named vectors.
+ * The abstract base class of all algorithms in this library. An operator is
+ * an object with an operator(), which transforms a set of named vectors
+ * into another set of named vectors.
*
- * Furthermore, an operator can be notified of parameter changes by
- * the calling routine. The outer iteration can notify() the Operator
- * of an Event, which could be for instance a change of mesh, a
- * different time step size or too slow convergence of Newton's
- * method, which would then trigger reassembling of a matrix or
- * similar things.
+ * Furthermore, an operator can be notified of parameter changes by the
+ * calling routine. The outer iteration can notify() the Operator of an
+ * Event, which could be for instance a change of mesh, a different time
+ * step size or too slow convergence of Newton's method, which would then
+ * trigger reassembling of a matrix or similar things.
*
* <h3>Usage for nested iterations</h3>
*
- * This is probably the most prominent use for Operator, where an
- * outer iterative method calls an inner solver and so on. Typically,
- * the innermost method in such a nested system will have to compute a
- * residual using values from all outer iterations. Since the depth
- * and order of such a nesting is hardly predictable when designing a
- * general tool, we use NamedData to access these vectors. Typically,
- * the first vector in <tt>out</tt> contains the start vector when
- * operator()() is called, and the solution when the function
- * returns. The object <tt>in</tt> is providing additional information
- * and forwarded to the inner Operator objects of the nested
- * iteration.
+ * This is probably the most prominent use for Operator, where an outer
+ * iterative method calls an inner solver and so on. Typically, the
+ * innermost method in such a nested system will have to compute a residual
+ * using values from all outer iterations. Since the depth and order of such
+ * a nesting is hardly predictable when designing a general tool, we use
+ * NamedData to access these vectors. Typically, the first vector in
+ * <tt>out</tt> contains the start vector when operator()() is called, and
+ * the solution when the function returns. The object <tt>in</tt> is
+ * providing additional information and forwarded to the inner Operator
+ * objects of the nested iteration.
*
* @author Guido Kanschat, 2010
*/
/**
* Implementation of the function in the base class in order to do
- * compatibility conversions between the old and the new
- * interface.
+ * compatibility conversions between the old and the new interface.
*/
virtual void operator() (AnyData &out, const AnyData &in);
/**
- * @deprecated It is in particular this function which should not be used anymore.
+ * @deprecated It is in particular this function which should not be used
+ * anymore.
*
- * The actual operation, which
- * is implemented in a derived class.
+ * The actual operation, which is implemented in a derived class.
*/
virtual void operator() (NamedData<VECTOR *> &out, const NamedData<VECTOR *> &in);
private:
/**
- * While we are providing compatibility functions to the old
- * interface, this variable will ensure there is no endless loop.
+ * While we are providing compatibility functions to the old interface,
+ * this variable will ensure there is no endless loop.
*/
bool compatibility_flag;
};
/**
- * An unary operator base class, intended to output the vectors in
- * NamedData in each step of an iteration.
+ * An unary operator base class, intended to output the vectors in NamedData
+ * in each step of an iteration.
*
* @author Guido Kanschat, 2010
*/
virtual ~OutputOperator();
/**
- * Set the stream @p os to
- * which data is written. If
- * no stream is selected with
- * this function, data goes
- * to @p deallog.
+ * Set the stream @p os to which data is written. If no stream is selected
+ * with this function, data goes to @p deallog.
*/
void initialize_stream(std::ostream &stream);
/**
namespace Algorithms
{
/**
- * A little structure, gathering the size of a timestep and the
- * current time. Time stepping schemes can use this to provide time
- * step information to the classes actually performing a single step.
+ * A little structure, gathering the size of a timestep and the current
+ * time. Time stepping schemes can use this to provide time step information
+ * to the classes actually performing a single step.
*
* The definition of what is considered "current time" depends on the
- * scheme. For an explicit scheme, this is the time at the beginning
- * of the step. For an implicit scheme, it is usually the time at the
- * end.
+ * scheme. For an explicit scheme, this is the time at the beginning of the
+ * step. For an implicit scheme, it is usually the time at the end.
*/
struct TimestepData
{
* Application class performing the theta timestepping scheme.
*
* The theta scheme is an abstraction of implicit and explicit Euler
- * schemes, the Crank-Nicholson scheme and linear combinations of
- * those. The choice of the actual scheme is controlled by the
- * parameter #theta as follows.
+ * schemes, the Crank-Nicholson scheme and linear combinations of those. The
+ * choice of the actual scheme is controlled by the parameter #theta as
+ * follows.
* <ul>
* <li> #theta=0: explicit Euler scheme
* <li> #theta=1: implicit Euler scheme
* <li> #theta=½: Crank-Nicholson scheme
* </ul>
*
- * For fixed #theta, the Crank-Nicholson scheme is the only second
- * order scheme. Nevertheless, further stability may be achieved by
- * choosing #theta larger than ½, thereby introducing a first order
- * error term. In order to avoid a loss of convergence order, the
- * adaptive theta scheme can be used, where <i>#theta=½+c dt</i>.
+ * For fixed #theta, the Crank-Nicholson scheme is the only second order
+ * scheme. Nevertheless, further stability may be achieved by choosing
+ * #theta larger than ½, thereby introducing a first order error term. In
+ * order to avoid a loss of convergence order, the adaptive theta scheme can
+ * be used, where <i>#theta=½+c dt</i>.
*
* Assume that we want to solve the equation <i>u' + F(u) = 0</i> with a
* step size <i>k</i>. A step of the theta scheme can be written as
* @f]
*
* Here, <i>M</i> is the mass matrix. We see, that the right hand side
- * amounts to an explicit Euler step with modified step size in weak
- * form (up to inversion of M). The left hand side corresponds to an
- * implicit Euler step with modified step size (right hand side
- * given). Thus, the implementation of the theta scheme will use two
- * Operator objects, one for the explicit, one for the implicit
- * part. Each of these will use its own TimestepData to account for
- * the modified step sizes (and different times if the problem is not
- * autonomous). Note that once the explicit part has been computed,
- * the left hand side actually constitutes a linear or nonlinear
- * system which has to be solved.
+ * amounts to an explicit Euler step with modified step size in weak form
+ * (up to inversion of M). The left hand side corresponds to an implicit
+ * Euler step with modified step size (right hand side given). Thus, the
+ * implementation of the theta scheme will use two Operator objects, one for
+ * the explicit, one for the implicit part. Each of these will use its own
+ * TimestepData to account for the modified step sizes (and different times
+ * if the problem is not autonomous). Note that once the explicit part has
+ * been computed, the left hand side actually constitutes a linear or
+ * nonlinear system which has to be solved.
*
* <h3>Usage AnyData</h3>
*
- * ThetaTimestepping uses AnyData for communicating vectors and time
- * step information. With
- * outer or inner Operator objects. It does not use itself the input
- * vectors provided, but forwards them to the explicit and implicit
- * operators.
+ * ThetaTimestepping uses AnyData for communicating vectors and time step
+ * information. With outer or inner Operator objects. It does not use itself
+ * the input vectors provided, but forwards them to the explicit and
+ * implicit operators.
*
* <h4>Vector data</h4>
*
- * The explicit Operator #op_explicit receives in its input in first
- * place the vector "Previous iterate", which is the solution
- * value after the previous timestep. It is followed by all vectors
- * provided to ThetaTimestepping::operator() as input
- * argument. #op_explicit is supposed to write its result into the
- * first position of its output argument, labeled "Result".
+ * The explicit Operator #op_explicit receives in its input in first place
+ * the vector "Previous iterate", which is the solution value after the
+ * previous timestep. It is followed by all vectors provided to
+ * ThetaTimestepping::operator() as input argument. #op_explicit is supposed
+ * to write its result into the first position of its output argument,
+ * labeled "Result".
*
- * The implicit Operator #op_implicit receives the result of
- * #op_explicit in its first input vector labeled "Previous
- * time". It is followed by all vectors provided to
- * ThetaTimestepping::operator() as input argument. The output of
- * #op_implicit is directly written into the output argument given to
- * ThetaTimestepping.
+ * The implicit Operator #op_implicit receives the result of #op_explicit in
+ * its first input vector labeled "Previous time". It is followed by all
+ * vectors provided to ThetaTimestepping::operator() as input argument. The
+ * output of #op_implicit is directly written into the output argument given
+ * to ThetaTimestepping.
*
* <h4>Scalar data</h4>
*
* Since the introduction of AnyData, ThetaTimestepping is able to
- * communicate the current time step information through AnyData as
- * well. Therefore, the AnyData objects handed as input to
- * #op_explicit and #op_implicit contain two entries of type
- * `const double*` named "Time" and "Timestep". Note
- * that "Time" refers to the time at the beginning of the current
- * step for #op_explicit and at the end for #op_implicit,
+ * communicate the current time step information through AnyData as well.
+ * Therefore, the AnyData objects handed as input to #op_explicit and
+ * #op_implicit contain two entries of type `const double*` named "Time" and
+ * "Timestep". Note that "Time" refers to the time at the beginning of the
+ * current step for #op_explicit and at the end for #op_implicit,
* respectively.
*
* <h3>Usage of ThetaTimestepping</h3>
*
- * The use ThetaTimestepping is more complicated than for instance
- * Newton, since the inner operators will usually need to access the
- * TimeStepData. Thus, we have a circular dependency of information,
- * and we include the following example for its use. It can be found
- * in <tt>examples/doxygen/theta_timestepping.cc</tt>
+ * The use ThetaTimestepping is more complicated than for instance Newton,
+ * since the inner operators will usually need to access the TimeStepData.
+ * Thus, we have a circular dependency of information, and we include the
+ * following example for its use. It can be found in
+ * <tt>examples/doxygen/theta_timestepping.cc</tt>
*
* @dontinclude theta_timestepping.cc
*
- * First, we define the two operators used by ThetaTimestepping and
- * call them <code>Implicit</code> and <code>Explicit</code>. They
- * both share the public interface of Operator, and additionally
- * provide storage for the matrices to be used and a pointer to
- * TimestepData. Note that we do not use a SmartPointer here, since
- * the TimestepData will be destroyed before the operator.
+ * First, we define the two operators used by ThetaTimestepping and call
+ * them <code>Implicit</code> and <code>Explicit</code>. They both share the
+ * public interface of Operator, and additionally provide storage for the
+ * matrices to be used and a pointer to TimestepData. Note that we do not
+ * use a SmartPointer here, since the TimestepData will be destroyed before
+ * the operator.
*
- * @skip class Explicit
- * @until End of declarations
+ * @skip class Explicit @until End of declarations
*
- * These operators will be implemented after the main program. But let
- * us look first at how they get used. First, let us define a matrix to be
- * used for our system and also an OutputOperator in order to write
- * the data of each timestep to a file.
+ * These operators will be implemented after the main program. But let us
+ * look first at how they get used. First, let us define a matrix to be used
+ * for our system and also an OutputOperator in order to write the data of
+ * each timestep to a file.
*
- * @skipline main
- * @until out.initialize
+ * @skipline main @until out.initialize
*
- * Now we create objects for the implicit and explicit parts of the
- * steps as well as the ThetaTimestepping itself. We initialize the
- * timestepping with the output operator in order to be able to see
- * the output in every step.
+ * Now we create objects for the implicit and explicit parts of the steps as
+ * well as the ThetaTimestepping itself. We initialize the timestepping with
+ * the output operator in order to be able to see the output in every step.
*
* @until set_output
*
- * The next step is providing the vectors to be used. <tt>value</tt>
- * is filled with the initial value and is also the vector where the
- * solution at each timestep will be. Because the interface of
- * Operator has to be able to handle several vectors, we need to store
- * it in an AnyData object. Since our problem has no additional
- * parameters, the input AnyData object remains empty.
+ * The next step is providing the vectors to be used. <tt>value</tt> is
+ * filled with the initial value and is also the vector where the solution
+ * at each timestep will be. Because the interface of Operator has to be
+ * able to handle several vectors, we need to store it in an AnyData object.
+ * Since our problem has no additional parameters, the input AnyData object
+ * remains empty.
*
* @until add
*
- * Finally, we are ready to tell the solver, that we are starting at
- * the initial timestep and run it.
+ * Finally, we are ready to tell the solver, that we are starting at the
+ * initial timestep and run it.
*
* @until }
*
- * First the constructor, which simply copies the system matrix into
- * the member pointer for later use.
+ * First the constructor, which simply copies the system matrix into the
+ * member pointer for later use.
*
- * @skip Explicit::
- * @until }
+ * @skip Explicit:: @until }
*
* Now we need to study the application of the implicit and explicit
- * operator. We assume that the pointer <code>matrix</code> points to
- * the matrix created in the main program (the constructor did this
- * for us). Here, we first get the time step size from the AnyData
- * object that was provided as input. Then, if we are in the first
- * step or if the timestep has changed, we fill the local matrix
- * $m$, such that with the given matrix $M$, it becomes
- * \f[
- * m = I - \Delta t M.
- * \f]
- * After we have worked off the notifications, we clear them, such
- * that the matrix is only generated when necessary.
- *
- * @skipline void
- * @until clear
+ * operator. We assume that the pointer <code>matrix</code> points to the
+ * matrix created in the main program (the constructor did this for us).
+ * Here, we first get the time step size from the AnyData object that was
+ * provided as input. Then, if we are in the first step or if the timestep
+ * has changed, we fill the local matrix $m$, such that with the given
+ * matrix $M$, it becomes \f[ m = I - \Delta t M. \f] After we have worked
+ * off the notifications, we clear them, such that the matrix is only
+ * generated when necessary.
+ *
+ * @skipline void @until clear
*
* Now we multiply the input vector with the new matrix and store on output.
*
- * @until }
- * The code for the implicit operator is almost the same, except
- * that we change the sign in front of the timestep and use the
- * inverse of t he matrix.
+ * @until } The code for the implicit operator is almost the same, except
+ * that we change the sign in front of the timestep and use the inverse of t
+ * he matrix.
*
- * @until vmult
- * @until }
+ * @until vmult @until }
* @author Guido Kanschat
* @date 2010
*/
{
public:
/**
- * Constructor, receiving the
- * two operators stored in
- * #op_explicit and #op_implicit. For
- * their meening, see the
- * description of those variables.
+ * Constructor, receiving the two operators stored in #op_explicit and
+ * #op_implicit. For their meening, see the description of those
+ * variables.
*/
ThetaTimestepping (Operator<VECTOR> &op_explicit,
Operator<VECTOR> &op_implicit);
/**
* The timestepping scheme.
*
- * @param in is ignored by
- * ThetaTimestepping, but is merged into the AnyData objects used
- * as input for the operators #op_explicit and #op_implicit.
+ * @param in is ignored by ThetaTimestepping, but is merged into the
+ * AnyData objects used as input for the operators #op_explicit and
+ * #op_implicit.
*
- * @param out in its first argument must contain a pointer to a
- * `VECTOR`, which contains the initial value when the operator is
- * called. It contains the final value when the operator returns.
+ * @param out in its first argument must contain a pointer to a `VECTOR`,
+ * which contains the initial value when the operator is called. It
+ * contains the final value when the operator returns.
*/
virtual void operator() (AnyData &out, const AnyData &in);
virtual void operator() (NamedData<VECTOR *> &out, const NamedData<VECTOR *> &in);
/**
- * Register an event triggered
- * by an outer iteration.
+ * Register an event triggered by an outer iteration.
*/
virtual void notify(const Event &);
/**
- * Define an operator which will output the result in each
- * step. Note that no output will be generated without this.
+ * Define an operator which will output the result in each step. Note that
+ * no output will be generated without this.
*/
void set_output(OutputOperator<VECTOR> &output);
*/
void initialize (ParameterHandler ¶m) DEAL_II_DEPRECATED;
/**
- * The current time in the
- * timestepping scheme.
+ * The current time in the timestepping scheme.
*/
double current_time() const;
/**
/**
* The data handed to the #op_explicit time stepping operator.
*
- * The time in here is the time at the beginning of the current
- * step, the time step is (1-#theta) times the actual time step.
+ * The time in here is the time at the beginning of the current step, the
+ * time step is (1-#theta) times the actual time step.
*/
const TimestepData &explicit_data() const;
/**
* The data handed to the #op_implicit time stepping operator.
*
- * The time in here is the time at the beginning of the current
- * step, the time step is #theta times the actual time step.
+ * The time in here is the time at the beginning of the current step, the
+ * time step is #theta times the actual time step.
*/
const TimestepData &implicit_data() const;
private:
/**
- * The object controlling the time step size and computing the new
- * time in each step.
+ * The object controlling the time step size and computing the new time in
+ * each step.
*/
TimestepControl control;
/**
- * The control parameter theta in the range <tt>[0,1]</tt>. It
- * defaults to 0.5.
+ * The control parameter theta in the range <tt>[0,1]</tt>. It defaults to
+ * 0.5.
*/
double vtheta;
/**
/**
- * The operator computing the explicit part of the scheme. This
- * will receive in its input data the value at the current time
- * with name "Current time solution". It should obtain the current
- * time and time step size from explicit_data().
+ * The operator computing the explicit part of the scheme. This will
+ * receive in its input data the value at the current time with name
+ * "Current time solution". It should obtain the current time and time
+ * step size from explicit_data().
*
- * Its return value is $ Mu+cF(u) $, where $u$ is the
- * current state vector, $M$ the mass matrix, $F$ the
- * operator in space and $c$ is the adjusted
- * time step size $(1-\theta) \Delta t$.
+ * Its return value is $ Mu+cF(u) $, where $u$ is the current state
+ * vector, $M$ the mass matrix, $F$ the operator in space and $c$ is the
+ * adjusted time step size $(1-\theta) \Delta t$.
*/
SmartPointer<Operator<VECTOR>, ThetaTimestepping<VECTOR> > op_explicit;
/**
- * The operator solving the implicit part of the scheme. It will
- * receive in its input data the vector "Previous
- * time". Information on the timestep should be obtained from
- * implicit_data().
+ * The operator solving the implicit part of the scheme. It will receive
+ * in its input data the vector "Previous time". Information on the
+ * timestep should be obtained from implicit_data().
*
- * Its return value is the solution <i>u</i> of <i>Mu-cF(u)=f</i>,
- * where <i>f</i> is the dual space vector found in the "Previous
- * time" entry of the input data, <i>M</i> the mass matrix,
- * <i>F</i> the operator in space and <i>c</i> is the adjusted
- * time step size $ \theta \Delta t$
+ * Its return value is the solution <i>u</i> of <i>Mu-cF(u)=f</i>, where
+ * <i>f</i> is the dual space vector found in the "Previous time" entry of
+ * the input data, <i>M</i> the mass matrix, <i>F</i> the operator in
+ * space and <i>c</i> is the adjusted time step size $ \theta \Delta t$
*/
SmartPointer<Operator<VECTOR>, ThetaTimestepping<VECTOR> > op_implicit;
namespace Algorithms
{
/**
- * Control class for timestepping schemes. Its main task is
- * determining the size of the next time step and the according point
- * in the time interval. Additionally, it controls writing the
- * solution to a file.
+ * Control class for timestepping schemes. Its main task is determining the
+ * size of the next time step and the according point in the time interval.
+ * Additionally, it controls writing the solution to a file.
*
* The size of the next time step is determined as follows:
* <ol>
* <li> According to the strategy, the step size is tentatively added to the
* current time.
- * <li> If the resulting time exceeds the final time of the interval,
- * the step size is reduced in order to meet this time.
- * <li> If the resulting time is below the final time by just a
- * fraction of the step size, the step size is increased in order to
- * meet this time.
+ * <li> If the resulting time exceeds the final time of the interval, the
+ * step size is reduced in order to meet this time.
+ * <li> If the resulting time is below the final time by just a fraction of
+ * the step size, the step size is increased in order to meet this time.
* <li> The resulting step size is used from the current time.
* </ol>
*
- * The variable @p print_step can be used to control the amount of
- * output generated by the timestepping scheme.
+ * The variable @p print_step can be used to control the amount of output
+ * generated by the timestepping scheme.
*/
class TimestepControl : public Subscriptor
{
public:
/**
- * The time stepping
- * strategies. These are
- * controlled by the value of
+ * The time stepping strategies. These are controlled by the value of
* tolerance() and start_step().
*/
enum Strategy
{
/**
- * Choose a uniform time
- * step size. The step size
- * is determined by
- * start_step(),
- * tolerance() is ignored.
+ * Choose a uniform time step size. The step size is determined by
+ * start_step(), tolerance() is ignored.
*/
uniform,
/**
- * Start with the time step
- * size given by
- * start_step() and double it
- * in every
- * step. tolerance() is
- * ignored.
+ * Start with the time step size given by start_step() and double it in
+ * every step. tolerance() is ignored.
*
- * This strategy is
- * intended for
- * pseudo-timestepping
- * schemes computing a
+ * This strategy is intended for pseudo-timestepping schemes computing a
* stationary limit.
*/
doubling
};
/**
- * Constructor setting default
- * values
+ * Constructor setting default values
*/
TimestepControl (double start = 0.,
double final = 1.,
*/
double start () const;
/**
- * The right end of the time interval. The control mechanism
- * ensures that the final time step ends at this point.
+ * The right end of the time interval. The control mechanism ensures that
+ * the final time step ends at this point.
*/
double final () const;
/**
double now () const;
/**
- * Compute the size of the next step and return true if it differs
- * from the current step size. Advance the current time by the new
- * step size.
+ * Compute the size of the next step and return true if it differs from
+ * the current step size. Advance the current time by the new step size.
*/
bool advance ();
void max_step (double);
/**
- * Set now() equal to start(). Initialize step() and print() to
- * their initial values.
+ * Set now() equal to start(). Initialize step() and print() to their
+ * initial values.
*/
void restart ();
/**
double max_step_val;
double min_step_val;
/**
- * The size of the current time
- * step. This may differ from
- * @p step_val, if we aimed at @p final_val.
+ * The size of the current time step. This may differ from @p step_val, if
+ * we aimed at @p final_val.
*/
double current_step_val;
double step_val;
* VectorizedArray and derived data types. It allocates memory aligned to
* addresses of a vectorized data type (in order to avoid segmentation faults
* when a variable of type VectorizedArray which the compiler assumes to be
- * aligned to certain memory addresses does not actually follow these
- * rules). This could also be achieved by proving std::vector with a
- * user-defined allocator. On the other hand, writing an own small vector
- * class lets us implement parallel copy and move operations with TBB, insert
- * deal.II-style assertions, and cut some unnecessary functionality. Note that
- * this vector is a bit more memory-consuming than std::vector because of
- * alignment, so it is recommended to only use this vector on long vectors.
+ * aligned to certain memory addresses does not actually follow these rules).
+ * This could also be achieved by proving std::vector with a user-defined
+ * allocator. On the other hand, writing an own small vector class lets us
+ * implement parallel copy and move operations with TBB, insert deal.II-style
+ * assertions, and cut some unnecessary functionality. Note that this vector
+ * is a bit more memory-consuming than std::vector because of alignment, so it
+ * is recommended to only use this vector on long vectors.
*
* @p author Katharina Kormann, Martin Kronbichler, 2011
*/
size_type memory_consumption () const;
/**
- * Write the data of this object to
- * a stream for the purpose of serialization.
+ * Write the data of this object to a stream for the purpose of
+ * serialization.
*/
template <class Archive>
void save (Archive &ar, const unsigned int version) const;
/**
- * Read the data of this object
- * from a stream for the purpose of serialization.
+ * Read the data of this object from a stream for the purpose of
+ * serialization.
*/
template <class Archive>
void load (Archive &ar, const unsigned int version);
// ------------------------------- inline functions --------------------------
/**
- * This namespace defines the copy and set functions used in
- * AlignedVector. These functions operate in parallel when there are enough
- * elements in the vector.
+ * This namespace defines the copy and set functions used in AlignedVector.
+ * These functions operate in parallel when there are enough elements in the
+ * vector.
*/
namespace internal
{
/**
- * Move and class that actually issues the copy commands in
- * AlignedVector. This class is based on the specialized for loop base class
+ * Move and class that actually issues the copy commands in AlignedVector.
+ * This class is based on the specialized for loop base class
* ParallelForLoop in parallel.h whose purpose is the following: When
* calling a parallel for loop on AlignedVector with apply_to_subranges, it
* generates different code for every different argument we might choose (as
DEAL_II_NAMESPACE_OPEN
/**
- * This class automatically computes the gradient of a function by
- * employing numerical difference quotients. This only, if the user
- * function does not provide the gradient function himself.
+ * This class automatically computes the gradient of a function by employing
+ * numerical difference quotients. This only, if the user function does not
+ * provide the gradient function himself.
*
- * The following example of an user defined function overloads and
- * implements only the value() function but not the gradient()
- * function. If the gradient() function is invoked then the gradient
- * function implemented by the AutoDerivativeFunction is called,
- * where the latter function imployes numerical difference quotients.
+ * The following example of an user defined function overloads and implements
+ * only the value() function but not the gradient() function. If the
+ * gradient() function is invoked then the gradient function implemented by
+ * the AutoDerivativeFunction is called, where the latter function imployes
+ * numerical difference quotients.
*
* @code
* class UserFunction: public AutoDerivativeFunction
* Tensor<1,dim> grad=user_function.gradient(some_point);
* @endcode
*
- * If the user overloads and implements also the gradient function,
- * then, of course, the users gradient function is called.
+ * If the user overloads and implements also the gradient function, then, of
+ * course, the users gradient function is called.
*
- * Note, that the usage of the value() and gradient() functions
- * explained above, also applies to the value_list() and
- * gradient_list() functions as well as to the vector valued
- * versions of these functions, see e.g. vector_value(),
- * vector_gradient(), vector_value_list() and
+ * Note, that the usage of the value() and gradient() functions explained
+ * above, also applies to the value_list() and gradient_list() functions as
+ * well as to the vector valued versions of these functions, see e.g.
+ * vector_value(), vector_gradient(), vector_value_list() and
* vector_gradient_list().
*
* The gradient() and gradient_list() functions make use of the
* Function::value() function. The vector_gradient() and
- * vector_gradient_list() make use of the Function::vector_value()
- * function. Make sure that the user defined function implements the
- * value() function and the vector_value() function, respectively.
+ * vector_gradient_list() make use of the Function::vector_value() function.
+ * Make sure that the user defined function implements the value() function
+ * and the vector_value() function, respectively.
*
* Furthermore note, that an object of this class does <b>not</b> represent
- * the derivative of a function, like FunctionDerivative, that
- * gives a directional derivate by calling the value() function. In
- * fact, this class (the AutoDerivativeFunction class) can
- * substitute the Function class as base class for user defined
- * classes. This class implements the gradient() functions for
- * automatic computation of numerical difference quotients and serves
- * as intermediate class between the base Function class and the
- * user defined function class.
+ * the derivative of a function, like FunctionDerivative, that gives a
+ * directional derivate by calling the value() function. In fact, this class
+ * (the AutoDerivativeFunction class) can substitute the Function class as
+ * base class for user defined classes. This class implements the gradient()
+ * functions for automatic computation of numerical difference quotients and
+ * serves as intermediate class between the base Function class and the user
+ * defined function class.
*
* @ingroup functions
* @author Ralf Hartmann, 2001
enum DifferenceFormula
{
/**
- * The symmetric Euler
- * formula of second order:
+ * The symmetric Euler formula of second order:
* @f[
* u'(t) \approx
* \frac{u(t+h) -
*/
Euler,
/**
- * The upwind Euler
- * formula of first order:
+ * The upwind Euler formula of first order:
* @f[
* u'(t) \approx
* \frac{u(t) -
};
/**
- * Constructor. Takes the
- * difference step size
- * <tt>h</tt>. It's within the user's
- * responsibility to choose an
- * appropriate value here. <tt>h</tt>
- * should be chosen taking into
- * account the absolute value as
- * well as the amount of local
- * variation of the function.
- * Setting <tt>h=1e-6</tt> might be a
- * good choice for functions with
- * an absolute value of about 1,
- * that furthermore does not vary
- * to much.
+ * Constructor. Takes the difference step size <tt>h</tt>. It's within the
+ * user's responsibility to choose an appropriate value here. <tt>h</tt>
+ * should be chosen taking into account the absolute value as well as the
+ * amount of local variation of the function. Setting <tt>h=1e-6</tt> might
+ * be a good choice for functions with an absolute value of about 1, that
+ * furthermore does not vary to much.
*
- * <tt>h</tt> can be changed later
- * using the set_h() function.
+ * <tt>h</tt> can be changed later using the set_h() function.
*
- * Sets DifferenceFormula
- * <tt>formula</tt> to the default
- * <tt>Euler</tt> formula of the
- * set_formula()
- * function. Change this preset
- * formula by calling the
- * set_formula() function.
+ * Sets DifferenceFormula <tt>formula</tt> to the default <tt>Euler</tt>
+ * formula of the set_formula() function. Change this preset formula by
+ * calling the set_formula() function.
*/
AutoDerivativeFunction (const double h,
const unsigned int n_components = 1,
const double initial_time = 0.0);
/**
- * Virtual destructor; absolutely
- * necessary in this case.
+ * Virtual destructor; absolutely necessary in this case.
*/
virtual ~AutoDerivativeFunction ();
/**
- * Choose the difference formula.
- * See the enum #DifferenceFormula
- * for available choices.
+ * Choose the difference formula. See the enum #DifferenceFormula for
+ * available choices.
*/
void set_formula (const DifferenceFormula formula = Euler);
/**
- * Takes the difference step size
- * <tt>h</tt>. It's within the user's
- * responsibility to choose an
- * appropriate value here. <tt>h</tt>
- * should be chosen taking into
- * account the absolute value of
- * as well as the amount of local
- * variation of the function.
- * Setting <tt>h=1e-6</tt> might be a
- * good choice for functions with
- * an absolute value of about 1,
- * that furthermore does not vary
- * to much.
+ * Takes the difference step size <tt>h</tt>. It's within the user's
+ * responsibility to choose an appropriate value here. <tt>h</tt> should be
+ * chosen taking into account the absolute value of as well as the amount of
+ * local variation of the function. Setting <tt>h=1e-6</tt> might be a good
+ * choice for functions with an absolute value of about 1, that furthermore
+ * does not vary to much.
*/
void set_h (const double h);
/**
- * Return the gradient of the
- * specified component of the
- * function at the given point.
+ * Return the gradient of the specified component of the function at the
+ * given point.
*
- * Computes numerical difference
- * quotients using the preset
+ * Computes numerical difference quotients using the preset
* #DifferenceFormula.
*/
virtual Tensor<1,dim> gradient (const Point<dim> &p,
const unsigned int component = 0) const;
/**
- * Return the gradient of all
- * components of the
- * function at the given point.
+ * Return the gradient of all components of the function at the given point.
*
- * Computes numerical difference
- * quotients using the preset
+ * Computes numerical difference quotients using the preset
* #DifferenceFormula.
*/
virtual void vector_gradient (const Point<dim> &p,
std::vector<Tensor<1,dim> > &gradients) const;
/**
- * Set <tt>gradients</tt> to the
- * gradients of the specified
- * component of the function at
- * the <tt>points</tt>. It is assumed
- * that <tt>gradients</tt> already has the
- * right size, i.e. the same
- * size as the <tt>points</tt> array.
+ * Set <tt>gradients</tt> to the gradients of the specified component of the
+ * function at the <tt>points</tt>. It is assumed that <tt>gradients</tt>
+ * already has the right size, i.e. the same size as the <tt>points</tt>
+ * array.
*
- * Computes numerical difference
- * quotients using the preset
+ * Computes numerical difference quotients using the preset
* #DifferenceFormula.
*/
virtual void gradient_list (const std::vector<Point<dim> > &points,
const unsigned int component = 0) const;
/**
- * Set <tt>gradients</tt> to the gradients of
- * the function at the <tt>points</tt>,
- * for all components.
- * It is assumed that <tt>gradients</tt>
- * already has the right size, i.e.
- * the same size as the <tt>points</tt> array.
+ * Set <tt>gradients</tt> to the gradients of the function at the
+ * <tt>points</tt>, for all components. It is assumed that
+ * <tt>gradients</tt> already has the right size, i.e. the same size as the
+ * <tt>points</tt> array.
*
- * The outer loop over
- * <tt>gradients</tt> is over the points
- * in the list, the inner loop
- * over the different components
- * of the function.
+ * The outer loop over <tt>gradients</tt> is over the points in the list,
+ * the inner loop over the different components of the function.
*
- * Computes numerical difference
- * quotients using the preset
+ * Computes numerical difference quotients using the preset
* #DifferenceFormula.
*/
virtual void vector_gradient_list (const std::vector<Point<dim> > &points,
std::vector<std::vector<Tensor<1,dim> > > &gradients) const;
/**
- * Returns a
- * #DifferenceFormula of the
- * order <tt>ord</tt> at minimum.
+ * Returns a #DifferenceFormula of the order <tt>ord</tt> at minimum.
*/
static
DifferenceFormula
private:
/**
- * Step size of the difference
- * formula. Set by the set_h()
- * function.
+ * Step size of the difference formula. Set by the set_h() function.
*/
double h;
/**
- * Includes the unit vectors
- * scaled by <tt>h</tt>.
+ * Includes the unit vectors scaled by <tt>h</tt>.
*/
std::vector<Tensor<1,dim> > ht;
/**
- * Difference formula. Set by the
- * set_formula() function.
+ * Difference formula. Set by the set_formula() function.
*/
DifferenceFormula formula;
};
/**
* A class that allows printing to an output stream, e.g. @p std::cout,
- * depending on the ConditionalOStream object being active (default)
- * or not. The condition of this object can be changed by
- * set_condition() and in the constructor. This class is used in the
- * step-17, step-18, step-32,
- * step-33, and step-35
- * tutorial programs.
+ * depending on the ConditionalOStream object being active (default) or not.
+ * The condition of this object can be changed by set_condition() and in the
+ * constructor. This class is used in the step-17, step-18, step-32, step-33,
+ * and step-35 tutorial programs.
*
* This class is mostly useful in parallel computations. Ordinarily, you would
* use @p std::cout to print messages like what the program is presently
* parallel programs, this means that each of the MPI processes write to the
* screen, which yields many repetitions of the same text. To avoid it, one
* would have to have a designated process, say the one with MPI process
- * number zero, do the output, and guard each write statement with an
- * if-condition. This becomes cumbersome and clutters up the code. Rather than
+ * number zero, do the output, and guard each write statement with an if-
+ * condition. This becomes cumbersome and clutters up the code. Rather than
* doing so, the present class can be used: objects of its type act just like
* a standard output stream, but they only print something based on a
* condition that can be set to, for example, <tt>mpi_process==0</tt>, so that
* pout << "done" << std::endl;
* @endcode
*
- * Here, `Reading parameter file on process xy' is printed by each
- * process separately. In contrast to that, `Solving ...' and `done'
- * is printed to standard output only once, namely by process 0.
+ * Here, `Reading parameter file on process xy' is printed by each process
+ * separately. In contrast to that, `Solving ...' and `done' is printed to
+ * standard output only once, namely by process 0.
*
* This class is not derived from ostream. Therefore
* @code
* system_matrix.print_formatted(pout);
* @endcode
- * is <em>not</em> possible. Instead use the is_active() function for a
- * work-around:
+ * is <em>not</em> possible. Instead use the is_active() function for a work-
+ * around:
*
* @code
* if (pout.is_active())
{
public:
/**
- * Constructor. Set the stream to which
- * we want to write, and the condition
- * based on which writes are actually
- * forwarded. Per default the condition
+ * Constructor. Set the stream to which we want to write, and the condition
+ * based on which writes are actually forwarded. Per default the condition
* of an object is active.
*/
ConditionalOStream (std::ostream &stream,
const bool active = true);
/**
- * Depending on the
- * <tt>active</tt> flag set the
- * condition of this stream to
- * active (true) or non-active
- * (false). An object of this
- * class prints to <tt>cout</tt>
- * if and only if its condition
- * is active.
+ * Depending on the <tt>active</tt> flag set the condition of this stream to
+ * active (true) or non-active (false). An object of this class prints to
+ * <tt>cout</tt> if and only if its condition is active.
*/
void set_condition (const bool active);
bool is_active() const;
/**
- * Return a reference to the stream
- * currently in use.
+ * Return a reference to the stream currently in use.
*/
std::ostream &get_stream () const;
/**
- * Output a constant something through
- * this stream. This function must be @p
- * const so that member objects of this
- * type can also be used from @p const
- * member functions of the surrounding
- * class.
+ * Output a constant something through this stream. This function must be @p
+ * const so that member objects of this type can also be used from @p const
+ * member functions of the surrounding class.
*/
template <typename T>
const ConditionalOStream &
operator << (const T &t) const;
/**
- * Treat ostream manipulators. This
- * function must be @p const so that
- * member objects of this type can also
- * be used from @p const member functions
- * of the surrounding class.
+ * Treat ostream manipulators. This function must be @p const so that member
+ * objects of this type can also be used from @p const member functions of
+ * the surrounding class.
*
- * Note that compilers want to see this
- * treated differently from the general
- * template above since functions like @p
- * std::endl are actually overloaded and
- * can't be bound directly to a template
- * type.
+ * Note that compilers want to see this treated differently from the general
+ * template above since functions like @p std::endl are actually overloaded
+ * and can't be bound directly to a template type.
*/
const ConditionalOStream &
operator<< (std::ostream& (*p) (std::ostream &)) const;
private:
/**
- * Reference to the stream we
- * want to write to.
+ * Reference to the stream we want to write to.
*/
std::ostream &output_stream;
/**
- * Stores the actual condition
- * the object is in.
+ * Stores the actual condition the object is in.
*/
bool active_flag;
};
/**
- * The ConvergenceTable class is an application to the TableHandler
- * class and stores some convergence data, such as residuals of the
- * cg-method, or some evaluated <i>L<sup>2</sup></i>-errors of
- * discrete solutions, etc, and evaluates convergence rates or orders.
+ * The ConvergenceTable class is an application to the TableHandler class and
+ * stores some convergence data, such as residuals of the cg-method, or some
+ * evaluated <i>L<sup>2</sup></i>-errors of discrete solutions, etc, and
+ * evaluates convergence rates or orders.
*
- * The already implemented #RateMode's are #reduction_rate,
- * where the convergence rate is the quotient of two following rows, and
- * #reduction_rate_log2, that evaluates the order of convergence.
- * These standard evaluations are useful for global refinement, for local refinement
+ * The already implemented #RateMode's are #reduction_rate, where the
+ * convergence rate is the quotient of two following rows, and
+ * #reduction_rate_log2, that evaluates the order of convergence. These
+ * standard evaluations are useful for global refinement, for local refinement
* this may not be an appropriate method, as the convergence rates should be
* set in relation to the number of cells or the number of DoFs. The
* implementations of these non-standard methods is left to a user.
* functions evaluate_convergence_rates() and evaluate_all_convergence_rates()
* may be called.
*
- * There are two possibilities of how to evaluate the convergence rates of multiple
- * columns in the same RateMode.
+ * There are two possibilities of how to evaluate the convergence rates of
+ * multiple columns in the same RateMode.
* <ol>
* <li> call evaluate_convergence_rates() for all wanted columns
- * <li> call omit_column_from_convergence_rate_evaluation() for all
- * columns for which this evaluation is not desired and then
- * evaluate_all_convergence_rates() to evaluate the convergence rates of all columns
- * that have not been flagged for omission.
+ * <li> call omit_column_from_convergence_rate_evaluation() for all columns
+ * for which this evaluation is not desired and then
+ * evaluate_all_convergence_rates() to evaluate the convergence rates of all
+ * columns that have not been flagged for omission.
* </ol>
*
* A detailed discussion of this class can also be found in the step-7 and
* $1/h$, remember to set the dimension to 1 also when working in 3D to get
* correct rates.
*
- * The new rate column and the data column will be merged to a
- * supercolumn. The tex caption of the supercolumn will be (by default) the
- * same as the one of the data column. This may be changed by using the
+ * The new rate column and the data column will be merged to a supercolumn.
+ * The tex caption of the supercolumn will be (by default) the same as the
+ * one of the data column. This may be changed by using the
* <tt>set_tex_supercaption (...)</tt> function of the base class
* TableHandler.
*
* This method behaves in the following way:
*
- * If RateMode is reduction_rate, then the computed output is
- * $ \frac{e_{n-1}/k_{n-1}}{e_n/k_n}, $
- * where $k$ is the reference column (no dimension dependence!).
+ * If RateMode is reduction_rate, then the computed output is $
+ * \frac{e_{n-1}/k_{n-1}}{e_n/k_n}, $ where $k$ is the reference column (no
+ * dimension dependence!).
*
- * If RateMode is reduction_rate_log2, then the computed output is
- * $
- * dim \frac{\log |e_{n-1}/e_{n}|}{\log |k_n/k_{n-1}|}
- * $.
+ * If RateMode is reduction_rate_log2, then the computed output is $ dim
+ * \frac{\log |e_{n-1}/e_{n}|}{\log |k_n/k_{n-1}|} $.
*
* This is useful, for example, if we use as reference key the number of
* degrees of freedom or better, the number of cells. Assuming that the
* error is proportional to $ C (1/\sqrt{k})^r $ in 2D, then this method
- * will produce the rate $r$ as a result. For general dimension, as described
- * by the last parameter of this function, the formula needs to be
+ * will produce the rate $r$ as a result. For general dimension, as
+ * described by the last parameter of this function, the formula needs to be
* $ C (1/\sqrt[dim]{k})^r $.
*
* @note Since this function adds columns to the table after several rows
* types of the table entries of the data column is a number, i.e. double,
* float, (unsigned) int, and so on.
*
- * The new rate column and the data column will be merged to a
- * supercolumn. The tex caption of the supercolumn will be (by default) the
- * same as the one of the data column. This may be changed by using the
+ * The new rate column and the data column will be merged to a supercolumn.
+ * The tex caption of the supercolumn will be (by default) the same as the
+ * one of the data column. This may be changed by using the
* set_tex_supercaption() function of the base class TableHandler.
*
* @note Since this function adds columns to the table after several rows
* convergence rate for almost all columns of a table without calling
* evaluate_convergence_rates() for each column separately.
*
- * Example:
- * Columns like <tt>n cells</tt> or <tt>n dofs</tt> columns may be wanted to
- * be omitted in the evaluation of the convergence rates. Hence they should
- * omitted by calling the omit_column_from_convergence_rate_evaluation().
+ * Example: Columns like <tt>n cells</tt> or <tt>n dofs</tt> columns may be
+ * wanted to be omitted in the evaluation of the convergence rates. Hence
+ * they should omitted by calling the
+ * omit_column_from_convergence_rate_evaluation().
*/
void
evaluate_all_convergence_rates(const std::string &reference_column_key,
* convergence rate for almost all columns of a table without calling
* evaluate_convergence_rates() for each column separately.
*
- * Example:
- * Columns like <tt>n cells</tt> or <tt>n dofs</tt> columns may be wanted to
- * be omitted in the evaluation of the convergence rates. Hence they should
- * omitted by calling the omit_column_from_convergence_rate_evaluation().
+ * Example: Columns like <tt>n cells</tt> or <tt>n dofs</tt> columns may be
+ * wanted to be omitted in the evaluation of the convergence rates. Hence
+ * they should omitted by calling the
+ * omit_column_from_convergence_rate_evaluation().
*/
void
evaluate_all_convergence_rates(const RateMode rate_mode);
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
class XDMFEntry;
/**
- * This is a base class for output of data on meshes of very general
- * form. Output data is expected as a set of <tt>patches</tt> and
- * written to the output stream in the format expected by the
- * visualization tool. For a list of output formats, check the
- * enumeration #OutputFormat. For each format listed there, this class
- * contains a function <tt>write_format</tt>, writing the
- * output. Refer to the documentation of those functions for details
- * on a certain format.
+ * This is a base class for output of data on meshes of very general form.
+ * Output data is expected as a set of <tt>patches</tt> and written to the
+ * output stream in the format expected by the visualization tool. For a list
+ * of output formats, check the enumeration #OutputFormat. For each format
+ * listed there, this class contains a function <tt>write_format</tt>, writing
+ * the output. Refer to the documentation of those functions for details on a
+ * certain format.
*
* <h3>Structure of the output data</h3>
*
- * Data is not written with the deal.II mesh structure. Instead, it
- * relies on a set of <tt>patches</tt> created by a derived class (for
- * example the DataOut, DataOutStack, DataOutFaces, DataOutRotation,
- * or MatrixOut classes). Each Patch describes a single logical cell
- * of a mesh, possibly subdivided a number of times to represent
- * higher order polynomials defined on this cell. To this end, a patch
- * consists of a <tt>dim</tt>-dimensional regular grid with the same
- * number of grid points in each direction. In the simplest case it
- * may consist of the corner points of a single mesh cell. For each
- * point of this local grid, the Patch contains an arbitrary number of
- * data values, though the number of data sets must be the same for
- * each point on each patch.
+ * Data is not written with the deal.II mesh structure. Instead, it relies on
+ * a set of <tt>patches</tt> created by a derived class (for example the
+ * DataOut, DataOutStack, DataOutFaces, DataOutRotation, or MatrixOut
+ * classes). Each Patch describes a single logical cell of a mesh, possibly
+ * subdivided a number of times to represent higher order polynomials defined
+ * on this cell. To this end, a patch consists of a <tt>dim</tt>-dimensional
+ * regular grid with the same number of grid points in each direction. In the
+ * simplest case it may consist of the corner points of a single mesh cell.
+ * For each point of this local grid, the Patch contains an arbitrary number
+ * of data values, though the number of data sets must be the same for each
+ * point on each patch.
*
- * By offering this interface to the different output formats, it is simple
- * to extend this class to new formats without depending on such things
- * as actual triangulations and handling of data vectors. These things shall
- * be provided by derived class which have a user callable interface then.
+ * By offering this interface to the different output formats, it is simple to
+ * extend this class to new formats without depending on such things as actual
+ * triangulations and handling of data vectors. These things shall be provided
+ * by derived class which have a user callable interface then.
*
- * Inside each patch, the data is organized in the usual
- * lexicographical order, <i>x</i> running fastest, then <i>y</i> and
- * <i>z</i>. Nodes are stored in this order and cells as well. Each
- * cell in 3D is stored such that the front face is in the
- * <i>xz</i>-plane. In order to enhance intellegibility of this
- * concept, the following two sections are kept from a previous
- * version of this documentation.
+ * Inside each patch, the data is organized in the usual lexicographical
+ * order, <i>x</i> running fastest, then <i>y</i> and <i>z</i>. Nodes are
+ * stored in this order and cells as well. Each cell in 3D is stored such that
+ * the front face is in the <i>xz</i>-plane. In order to enhance
+ * intellegibility of this concept, the following two sections are kept from a
+ * previous version of this documentation.
*
*
* <h4>Patches</h4>
*
* Grids can be thought of as a collection of cells; if you want to write out
- * data on such a grid, you can do so by writing them one cell at a time.
- * The functions in this class therefore take a list of objects describing the
+ * data on such a grid, you can do so by writing them one cell at a time. The
+ * functions in this class therefore take a list of objects describing the
* data on one cell each. This data for each cell usually consists of a list
* of vertices for this cell, and a list of data values (for example solution
* data, error information, etc) at each of these vertices.
*
* In some cases, this interface to a cell is too restricted, however. For
- * example, you may have higher order elements and printing the values at
- * the vertices only is not enough. For this reason, we not only provide
- * writing the data on the vertices only, but the data is organizes as a
- * tensor product grid on each cell. The parameter <tt>n_subdivision</tt>, which is
+ * example, you may have higher order elements and printing the values at the
+ * vertices only is not enough. For this reason, we not only provide writing
+ * the data on the vertices only, but the data is organizes as a tensor
+ * product grid on each cell. The parameter <tt>n_subdivision</tt>, which is
* given for each patch separately, denotes how often the cell is to be
- * divided for output; for example, <tt>n_subdivisions==1</tt> yields no subdivision
- * of the cell, <tt>n_subdivisions==2</tt> will produce a grid of 3 times 3 points
- * in two spatial dimensions and 3 times 3 times 3 points in three dimensions,
- * <tt>n_subdivisions==3</tt> will yield 4 times 4 (times 4) points, etc. The actual
- * location of these points on the patch will be computed by a multilinear
- * transformation from the vertices given for this patch.
-
- * For cells at the boundary, a mapping might be used to calculate the position
- * of the inner points. In that case the coordinates are stored inside the
- * Patch, as they cannot be easily recovered otherwise.
+ * divided for output; for example, <tt>n_subdivisions==1</tt> yields no
+ * subdivision of the cell, <tt>n_subdivisions==2</tt> will produce a grid of
+ * 3 times 3 points in two spatial dimensions and 3 times 3 times 3 points in
+ * three dimensions, <tt>n_subdivisions==3</tt> will yield 4 times 4 (times 4)
+ * points, etc. The actual location of these points on the patch will be
+ * computed by a multilinear transformation from the vertices given for this
+ * patch. For cells at the boundary, a mapping might be used to calculate the
+ * position of the inner points. In that case the coordinates are stored
+ * inside the Patch, as they cannot be easily recovered otherwise.
*
- * Given these comments, the actual data to be printed on this patch of
- * points consists of several data sets each of which has a value at each
- * of the patch points. For example with <tt>n_subdivisions==2</tt> in two space
- * dimensions, each data set has to provide nine values, and since the
- * patch is to be printed as a tensor product (or its transformation to the
- * real space cell), its values are to be ordered like
- * <i>(x0,y0) (x0,y1) (x0,y2) (x1,y0) (x1,y1) (x1,y2) (x2,y0) (x2,y1) (x2,y2)</i>,
- * i.e. the z-coordinate runs fastest, then the y-coordinate, then x (if there
- * are that many space directions).
+ * Given these comments, the actual data to be printed on this patch of points
+ * consists of several data sets each of which has a value at each of the
+ * patch points. For example with <tt>n_subdivisions==2</tt> in two space
+ * dimensions, each data set has to provide nine values, and since the patch
+ * is to be printed as a tensor product (or its transformation to the real
+ * space cell), its values are to be ordered like <i>(x0,y0) (x0,y1) (x0,y2)
+ * (x1,y0) (x1,y1) (x1,y2) (x2,y0) (x2,y1) (x2,y2)</i>, i.e. the z-coordinate
+ * runs fastest, then the y-coordinate, then x (if there are that many space
+ * directions).
*
*
* <h4>Generalized patches</h4>
*
- * In general, the patches as explained above might be too
- * restricted. For example, one might want to draw only the outer
- * faces of a domain in a three-dimensional computation, if one is not
- * interested in what happens inside. Then, the objects that should be
- * drawn are two-dimensional in a three-dimensional world. The
- * Patch class and associated output functions handle these
- * cases. The Patch class therefore takes two template parameters,
- * the first, named <tt>dim</tt> denoting the dimension of the object (in
- * the above example, this would be two), while the second, named
- * <tt>spacedim</tt>, denotes the dimension of the embedding space (this
- * would be three). The corner points of a patch have the dimension of
- * the space, while their number is determined by the dimension of the
- * patch. By default, the second template parameter has the same value
- * as the first, which would correspond to outputting a cell, rather
- * than a face or something else.
+ * In general, the patches as explained above might be too restricted. For
+ * example, one might want to draw only the outer faces of a domain in a
+ * three-dimensional computation, if one is not interested in what happens
+ * inside. Then, the objects that should be drawn are two-dimensional in a
+ * three-dimensional world. The Patch class and associated output functions
+ * handle these cases. The Patch class therefore takes two template
+ * parameters, the first, named <tt>dim</tt> denoting the dimension of the
+ * object (in the above example, this would be two), while the second, named
+ * <tt>spacedim</tt>, denotes the dimension of the embedding space (this would
+ * be three). The corner points of a patch have the dimension of the space,
+ * while their number is determined by the dimension of the patch. By default,
+ * the second template parameter has the same value as the first, which would
+ * correspond to outputting a cell, rather than a face or something else.
*
* <h3>DataOutBaseInterface</h3>
*
* The members of this namespace are not usually called from user code
- * directly. Rather, classes that use the functions declared here
- * are typically derived from DataOutInterface.
+ * directly. Rather, classes that use the functions declared here are
+ * typically derived from DataOutInterface.
*
* The interface of this class basically consists of the declaration of a data
* type describing a patch and a bunch of functions taking a list of patches
* and writing them in one format or other to the stream. It is in the
- * responsibility of the derived classes to provide this list of patches.
- * In addition to the list of patches, a name for each data set may be given.
+ * responsibility of the derived classes to provide this list of patches. In
+ * addition to the list of patches, a name for each data set may be given.
*
*
* <h3>Querying interface</h3>
* <h3>Output parameters</h3>
*
* All functions take a parameter which is a structure of type
- * <tt>XFlags</tt>, where <tt>X</tt> is the name of the output
- * format. To find out what flags are presently supported, read the
- * documentation of the different structures.
+ * <tt>XFlags</tt>, where <tt>X</tt> is the name of the output format. To find
+ * out what flags are presently supported, read the documentation of the
+ * different structures.
*
* Note that usually the output formats used for scientific visualization
- * programs have no or very few parameters (apart from some compatibility flags)
- * because there the actual appearance of output is determined using the
- * visualization program and the files produced by this class store more or less
- * only raw data.
+ * programs have no or very few parameters (apart from some compatibility
+ * flags) because there the actual appearance of output is determined using
+ * the visualization program and the files produced by this class store more
+ * or less only raw data.
*
* The direct output formats, like Postscript or Povray need to be given a lot
* more parameters, though, since there the output file has to contain all
*
* <h3>Writing backends</h3>
*
- * An abstraction layer has been introduced to facilitate coding
- * backends for additional visualization tools. It is applicable for
- * data formats separating the information into a field of vertices, a
- * field of connection information for the grid cells and data fields.
+ * An abstraction layer has been introduced to facilitate coding backends for
+ * additional visualization tools. It is applicable for data formats
+ * separating the information into a field of vertices, a field of connection
+ * information for the grid cells and data fields.
*
* For each of these fields, output functions are implemented, namely
- * write_nodes(), write_cells() and write_data(). In order to use
- * these functions, a format specific output stream must be written,
- * following the examples of DXStream, GmvStream, VtkStream and so on,
- * implemented in the .cc file.
+ * write_nodes(), write_cells() and write_data(). In order to use these
+ * functions, a format specific output stream must be written, following the
+ * examples of DXStream, GmvStream, VtkStream and so on, implemented in the
+ * .cc file.
*
- * In this framework, the implementation of a new output format is
- * reduced to writing the section headers and the new output stream
- * class for writing a single mesh object.
+ * In this framework, the implementation of a new output format is reduced to
+ * writing the section headers and the new output stream class for writing a
+ * single mesh object.
*
* <h3>Credits</h3>
* <ul>
*
- * <li>EPS output based on an earlier implementation by Stefan Nauber
- * for the old DataOut class
+ * <li>EPS output based on an earlier implementation by Stefan Nauber for the
+ * old DataOut class
*
* <li>Povray output by Thomas Richter
*
* </ul>
*
* @ingroup output
- * @author Wolfgang Bangerth, Guido Kanschat 1999, 2000, 2001, 2002, 2005, 2006.
+ * @author Wolfgang Bangerth, Guido Kanschat 1999, 2000, 2001, 2002, 2005,
+ * 2006.
*/
namespace DataOutBase
{
* A patch consists of the following data:
* <ul>
* <li>the corner #vertices,
- * <li> the number #n_subdivisions of the number of cells the Patch
- * has in each space direction,
- * <li> the #data attached to each vertex, in the usual
- * lexicographic ordering,
+ * <li> the number #n_subdivisions of the number of cells the Patch has in
+ * each space direction,
+ * <li> the #data attached to each vertex, in the usual lexicographic
+ * ordering,
* <li> Information on #neighbors.
* </ul>
*
* See the general documentation of the DataOutBase class for more
- * information on its contents and purposes. In the case of two
- * dimensions, the next picture ist an example of
- * <tt>n_subdivision</tt> = 4 because the number of (sub)cells
- * within each patch is equal to <tt>2<sup>dim</sup></tt>.
+ * information on its contents and purposes. In the case of two dimensions,
+ * the next picture ist an example of <tt>n_subdivision</tt> = 4 because the
+ * number of (sub)cells within each patch is equal to
+ * <tt>2<sup>dim</sup></tt>.
*
* @ingroup output
*
static const unsigned int space_dim=spacedim;
/**
- * Corner points of a patch. Inner points are computed by a
- * multilinear transform of the unit cell to the cell specified by
- * these corner points. The order of points is the same as for
- * cells in the triangulation.
+ * Corner points of a patch. Inner points are computed by a multilinear
+ * transform of the unit cell to the cell specified by these corner
+ * points. The order of points is the same as for cells in the
+ * triangulation.
*/
Point<spacedim> vertices[GeometryInfo<dim>::vertices_per_cell];
/**
- * Numbers of neighbors of a patch. OpenDX format requires
- * neighbor information for advanced output. Here the neighborship
- * relationship of patches is stored. During output, this must be
- * transformed into neighborship of sub-grid cells.
+ * Numbers of neighbors of a patch. OpenDX format requires neighbor
+ * information for advanced output. Here the neighborship relationship of
+ * patches is stored. During output, this must be transformed into
+ * neighborship of sub-grid cells.
*/
unsigned int neighbors[dim > 0
?
1];
/**
- * Number of this patch. Since we are not sure patches are handled
- * in the same order, always, we better store this.
+ * Number of this patch. Since we are not sure patches are handled in the
+ * same order, always, we better store this.
*/
unsigned int patch_index;
/**
- * Number of subdivisions with which this patch is to be
- * written. <tt>1</tt> means no subdivision, <tt>2</tt> means
- * bisection, <tt>3</tt> trisection, etc.
+ * Number of subdivisions with which this patch is to be written.
+ * <tt>1</tt> means no subdivision, <tt>2</tt> means bisection, <tt>3</tt>
+ * trisection, etc.
*/
unsigned int n_subdivisions;
/**
- * Data vectors. The format is as follows: <tt>data(i,.)</tt>
- * denotes the data belonging to the <tt>i</tt>th data
- * vector. <tt>data.n()</tt> therefore equals the number of output
- * points; this number is <tt>(subdivisions+1)^{dim</tt>}.
- * <tt>data.m()</tt> equals the number of data vectors.
+ * Data vectors. The format is as follows: <tt>data(i,.)</tt> denotes the
+ * data belonging to the <tt>i</tt>th data vector. <tt>data.n()</tt>
+ * therefore equals the number of output points; this number is
+ * <tt>(subdivisions+1)^{dim</tt>}. <tt>data.m()</tt> equals the number of
+ * data vectors.
*
- * Within each column, <tt>data(.,j)</tt> are the data values at
- * the output point <tt>j</tt>, where <tt>j</tt> denotes the usual
- * lexicographic ordering in deal.II. This is also the order of
- * points as provided by the <tt>QIterated</tt> class when used
- * with the <tt>QTrapez</tt> class as subquadrature.
+ * Within each column, <tt>data(.,j)</tt> are the data values at the
+ * output point <tt>j</tt>, where <tt>j</tt> denotes the usual
+ * lexicographic ordering in deal.II. This is also the order of points as
+ * provided by the <tt>QIterated</tt> class when used with the
+ * <tt>QTrapez</tt> class as subquadrature.
*
- * Since the number of data vectors is usually the same for all
- * patches to be printed, <tt>data.size()</tt> should yield the
- * same value for all patches provided. The exception are patches
- * for which points_are_available are set, where the actual
- * coordinates of the point are appended to the 'data' field, see
- * the documentation of the points_are_available flag.
+ * Since the number of data vectors is usually the same for all patches to
+ * be printed, <tt>data.size()</tt> should yield the same value for all
+ * patches provided. The exception are patches for which
+ * points_are_available are set, where the actual coordinates of the point
+ * are appended to the 'data' field, see the documentation of the
+ * points_are_available flag.
*/
Table<2,float> data;
Patch ();
/**
- * Compare the present patch for equality with another one. This
- * is used in a few of the automated tests in our testsuite.
+ * Compare the present patch for equality with another one. This is used
+ * in a few of the automated tests in our testsuite.
*/
bool operator == (const Patch &patch) const;
/**
- * Determine an estimate for the memory consumption (in bytes) of
- * this object. Since sometimes the size of objects can not be
- * determined exactly (for example: what is the memory consumption
- * of an STL <tt>std::map</tt> type with a certain number of
- * elements?), this is only an estimate. however often quite close
- * to the true value.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object. Since sometimes the size of objects can not be determined
+ * exactly (for example: what is the memory consumption of an STL
+ * <tt>std::map</tt> type with a certain number of elements?), this is
+ * only an estimate. however often quite close to the true value.
*/
std::size_t memory_consumption () const;
* Value to be used if this patch has no neighbor on one side.
*/
static const unsigned int no_neighbor = numbers::invalid_unsigned_int;
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
struct DXFlags
{
/**
- * Write neighbor information. This information is necessary for
- * instance, if OpenDX is supposed to compute integral curves
- * (streamlines). If it is not present, streamlines end at cell
- * boundaries.
+ * Write neighbor information. This information is necessary for instance,
+ * if OpenDX is supposed to compute integral curves (streamlines). If it
+ * is not present, streamlines end at cell boundaries.
*/
bool write_neighbors;
/**
bool data_binary;
/**
- * Write binary coordinate vectors as double (64 bit) numbers
- * instead of float (32 bit).
+ * Write binary coordinate vectors as double (64 bit) numbers instead of
+ * float (32 bit).
*/
bool data_double;
const bool data_binary = false);
/**
- * Declare all flags with name and type as offered by this class,
- * for use in input files.
+ * Declare all flags with name and type as offered by this class, for use
+ * in input files.
*/
static void declare_parameters (ParameterHandler &prm);
/**
- * Read the parameters declared in declare_parameters() and set
- * the flags for this output format accordingly.
+ * Read the parameters declared in declare_parameters() and set the flags
+ * for this output format accordingly.
*
- * The flags thus obtained overwrite all previous contents of this
- * object.
+ * The flags thus obtained overwrite all previous contents of this object.
*/
void parse_parameters (const ParameterHandler &prm);
/**
- * Determine an estimate for the memory consumption (in bytes) of
- * this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
};
struct UcdFlags
{
/**
- * Write a comment at the beginning of the file stating the date
- * of creation and some other data. While this is supported by
- * the UCD format and AVS, some other programs get confused by
- * this, so the default is to not write a preamble. However, a
- * preamble can be written using this flag.
+ * Write a comment at the beginning of the file stating the date of
+ * creation and some other data. While this is supported by the UCD
+ * format and AVS, some other programs get confused by this, so the
+ * default is to not write a preamble. However, a preamble can be written
+ * using this flag.
*
* Default: <code>false</code>.
*/
UcdFlags (const bool write_preamble = false);
/**
- * Declare all flags with name and type as offered by this class,
- * for use in input files.
+ * Declare all flags with name and type as offered by this class, for use
+ * in input files.
*/
static void declare_parameters (ParameterHandler &prm);
/**
- * Read the parameters declared in declare_parameters() and
- * set the flags for this output format accordingly.
+ * Read the parameters declared in declare_parameters() and set the flags
+ * for this output format accordingly.
*
- * The flags thus obtained overwrite all previous contents of this
- * object.
+ * The flags thus obtained overwrite all previous contents of this object.
*/
void parse_parameters (const ParameterHandler &prm);
/**
- * Determine an estimate for the memory consumption (in bytes) of
- * this object. Since sometimes the size of objects can not be
- * determined exactly (for example: what is the memory consumption
- * of an STL <tt>std::map</tt> type with a certain number of
- * elements?), this is only an estimate. however often quite close
- * to the true value.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object. Since sometimes the size of objects can not be determined
+ * exactly (for example: what is the memory consumption of an STL
+ * <tt>std::map</tt> type with a certain number of elements?), this is
+ * only an estimate. however often quite close to the true value.
*/
std::size_t memory_consumption () const;
};
/**
- * Flags controlling the details of output in Gnuplot format. At
- * present no flags are implemented.
+ * Flags controlling the details of output in Gnuplot format. At present no
+ * flags are implemented.
*
* @ingroup output
*/
private:
/**
* Dummy entry to suppress compiler warnings when copying an empty
- * structure. Remove this member when adding the first flag to
- * this structure (and remove the <tt>private</tt> as well).
+ * structure. Remove this member when adding the first flag to this
+ * structure (and remove the <tt>private</tt> as well).
*/
int dummy;
GnuplotFlags ();
/**
- * Declare all flags with name and type as offered by this class,
- * for use in input files.
+ * Declare all flags with name and type as offered by this class, for use
+ * in input files.
*/
static void declare_parameters (ParameterHandler &prm);
/**
- * Read the parameters declared in declare_parameters() and set
- * the flags for this output format accordingly.
+ * Read the parameters declared in declare_parameters() and set the flags
+ * for this output format accordingly.
*
- * The flags thus obtained overwrite all previous contents of this
- * object.
+ * The flags thus obtained overwrite all previous contents of this object.
*/
void parse_parameters (const ParameterHandler &prm) const;
/**
- * Determine an estimate for the memory consumption (in bytes) of
- * this object. Since sometimes the size of objects can not be
- * determined exactly (for example: what is the memory consumption
- * of an STL <tt>std::map</tt> type with a certain number of
- * elements?), this is only an estimate. however often quite close
- * to the true value.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object. Since sometimes the size of objects can not be determined
+ * exactly (for example: what is the memory consumption of an STL
+ * <tt>std::map</tt> type with a certain number of elements?), this is
+ * only an estimate. however often quite close to the true value.
*/
std::size_t memory_consumption () const;
};
/**
- * Flags controlling the details of output in Povray format. Several
- * flags are implemented, see their respective documentation.
+ * Flags controlling the details of output in Povray format. Several flags
+ * are implemented, see their respective documentation.
*
* @ingroup output
*/
bool bicubic_patch;
/**
- * include external "data.inc" with camera, light and texture
- * definition for the scene.
+ * include external "data.inc" with camera, light and texture definition
+ * for the scene.
*
* default = false
*/
const bool external_data = false);
/**
- * Declare all flags with name and type as offered by this class,
- * for use in input files.
+ * Declare all flags with name and type as offered by this class, for use
+ * in input files.
*/
static void declare_parameters (ParameterHandler &prm);
/**
- * Read the parameters declared in declare_parameters() and
- * set the flags for this output format accordingly.
+ * Read the parameters declared in declare_parameters() and set the flags
+ * for this output format accordingly.
*
- * The flags thus obtained overwrite all previous contents of this
- * object.
+ * The flags thus obtained overwrite all previous contents of this object.
*/
void parse_parameters (const ParameterHandler &prm);
/**
- * Determine an estimate for the memory consumption (in bytes) of
- * this object. Since sometimes the size of objects can not be
- * determined exactly (for example: what is the memory consumption
- * of an STL <tt>std::map</tt> type with a certain number of
- * elements?), this is only an estimate. however often quite close
- * to the true value.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object. Since sometimes the size of objects can not be determined
+ * exactly (for example: what is the memory consumption of an STL
+ * <tt>std::map</tt> type with a certain number of elements?), this is
+ * only an estimate. however often quite close to the true value.
*/
std::size_t memory_consumption () const;
};
/**
- * Flags controlling the details of output in encapsulated
- * postscript format.
+ * Flags controlling the details of output in encapsulated postscript
+ * format.
*
* @ingroup output
*/
struct EpsFlags
{
/**
- * This denotes the number of the data vector which shall be used
- * for generating the height information. By default, the first
- * data vector is taken, i.e. <tt>height_vector==0</tt>, if there
- * is any data vector. If there is no data vector, no height
- * information is generated.
+ * This denotes the number of the data vector which shall be used for
+ * generating the height information. By default, the first data vector is
+ * taken, i.e. <tt>height_vector==0</tt>, if there is any data vector. If
+ * there is no data vector, no height information is generated.
*/
unsigned int height_vector;
/**
- * Number of the vector which is to be taken to colorize cells.
- * The same applies as for #height_vector.
+ * Number of the vector which is to be taken to colorize cells. The same
+ * applies as for #height_vector.
*/
unsigned int color_vector;
/**
- * Enum denoting the possibilities whether the scaling should be
- * done such that the given <tt>size</tt> equals the width or the
- * height of the resulting picture.
+ * Enum denoting the possibilities whether the scaling should be done such
+ * that the given <tt>size</tt> equals the width or the height of the
+ * resulting picture.
*/
enum SizeType
{
SizeType size_type;
/**
- * Width or height of the output as given in postscript units This
- * usually is given by the strange unit 1/72 inch. Whether this is
- * height or width is specified by the flag <tt>size_type</tt>.
+ * Width or height of the output as given in postscript units This usually
+ * is given by the strange unit 1/72 inch. Whether this is height or width
+ * is specified by the flag <tt>size_type</tt>.
*
* Default is 300, which represents a size of roughly 10 cm.
*/
double azimut_angle;
/**
- * Angle by which the viewers position projected onto the
- * x-y-plane is rotated around the z-axis, in positive sense when
- * viewed from above. The unit are degrees, and zero equals a
- * position above or below the negative y-axis.
+ * Angle by which the viewers position projected onto the x-y-plane is
+ * rotated around the z-axis, in positive sense when viewed from above.
+ * The unit are degrees, and zero equals a position above or below the
+ * negative y-axis.
*
- * Default is the Gnuplot-default of 30. An example of a
- * Gnuplot-default of 0 is the following:
+ * Default is the Gnuplot-default of 30. An example of a Gnuplot-default
+ * of 0 is the following:
*
* @verbatim
*
double turn_angle;
/**
- * Factor by which the z-axis is to be stretched as compared to
- * the x- and y-axes. This is to compensate for the different
- * sizes that coordinate and solution values may have and to
- * prevent that the plot looks to much out-of-place (no elevation
- * at all if solution values are much smaller than coordinate
- * values, or the common "extremely mountainous area" in the
- * opposite case.
+ * Factor by which the z-axis is to be stretched as compared to the x- and
+ * y-axes. This is to compensate for the different sizes that coordinate
+ * and solution values may have and to prevent that the plot looks to much
+ * out-of-place (no elevation at all if solution values are much smaller
+ * than coordinate values, or the common "extremely mountainous area" in
+ * the opposite case.
*
* Default is <tt>1.0</tt>.
*/
double z_scaling;
/**
- * Flag the determines whether the lines bounding the cells (or
- * the parts of each patch) are to be plotted.
+ * Flag the determines whether the lines bounding the cells (or the parts
+ * of each patch) are to be plotted.
*
* Default: <tt>true</tt>.
*/
bool draw_mesh;
/**
- * Flag whether to fill the regions between the lines bounding the
- * cells or not. If not, no hidden line removal is performed,
- * which in this crude implementation is done through writing the
- * cells in a back-to-front order, thereby hiding the cells in the
- * background by cells in the foreground.
+ * Flag whether to fill the regions between the lines bounding the cells
+ * or not. If not, no hidden line removal is performed, which in this
+ * crude implementation is done through writing the cells in a back-to-
+ * front order, thereby hiding the cells in the background by cells in the
+ * foreground.
*
- * If this flag is <tt>false</tt> and #draw_mesh is <tt>false</tt>
- * as well, nothing will be printed.
+ * If this flag is <tt>false</tt> and #draw_mesh is <tt>false</tt> as
+ * well, nothing will be printed.
*
- * If this flag is <tt>true</tt>, then the cells will be drawn
- * either colored by one of the data sets (if #shade_cells is
- * <tt>true</tt>), or pure white (if #shade_cells is false or if
- * there are no data sets).
+ * If this flag is <tt>true</tt>, then the cells will be drawn either
+ * colored by one of the data sets (if #shade_cells is <tt>true</tt>), or
+ * pure white (if #shade_cells is false or if there are no data sets).
*
* Default is <tt>true</tt>.
*/
bool draw_cells;
/**
- * Flag to determine whether the cells shall be colorized by the
- * data set denoted by #color_vector, or simply be painted in
- * white. This flag only makes sense if
- * <tt>#draw_cells==true</tt>. Colorization is done through
+ * Flag to determine whether the cells shall be colorized by the data set
+ * denoted by #color_vector, or simply be painted in white. This flag only
+ * makes sense if <tt>#draw_cells==true</tt>. Colorization is done through
* #color_function.
*
* Default is <tt>true</tt>.
float blue;
/**
- * Return <tt>true</tt> if the color represented by the three
- * color values is a grey scale, i.e. all components are equal.
+ * Return <tt>true</tt> if the color represented by the three color
+ * values is a grey scale, i.e. all components are equal.
*/
bool is_grey () const;
};
/**
- * Definition of a function pointer type taking a value and
- * returning a triple of color values in RGB values.
+ * Definition of a function pointer type taking a value and returning a
+ * triple of color values in RGB values.
*
- * Besides the actual value by which the color is to be computed,
- * min and max values of the data to be colorized are given as
- * well.
+ * Besides the actual value by which the color is to be computed, min and
+ * max values of the data to be colorized are given as well.
*/
typedef RgbValues (*ColorFunction) (const double value,
const double min_value,
const double max_value);
/**
- * This is a pointer to the function which is used to colorize the
- * cells. By default, it points to the static function
- * default_color_function() which is a member of this class.
+ * This is a pointer to the function which is used to colorize the cells.
+ * By default, it points to the static function default_color_function()
+ * which is a member of this class.
*/
ColorFunction color_function;
/**
- * Default colorization function. This one does what one usually
- * wants: It shifts colors from black (lowest value) through blue,
- * green and red to white (highest value). For the exact defition
- * of the color scale refer to the implementation.
+ * Default colorization function. This one does what one usually wants: It
+ * shifts colors from black (lowest value) through blue, green and red to
+ * white (highest value). For the exact defition of the color scale refer
+ * to the implementation.
*
* This function was originally written by Stefan Nauber.
*/
const double max_value);
/**
- * This is an alternative color function producing a grey scale
- * between black (lowest values) and white (highest values). You
- * may use it by setting the #color_function variable to the
- * address of this function.
+ * This is an alternative color function producing a grey scale between
+ * black (lowest values) and white (highest values). You may use it by
+ * setting the #color_function variable to the address of this function.
*/
static RgbValues
grey_scale_color_function (const double value,
const double max_value);
/**
- * This is one more alternative color function producing a grey
- * scale between white (lowest values) and black (highest values),
- * i.e. the scale is reversed to the previous one. You may use it
- * by setting the #color_function variable to the address of this
- * function.
+ * This is one more alternative color function producing a grey scale
+ * between white (lowest values) and black (highest values), i.e. the
+ * scale is reversed to the previous one. You may use it by setting the
+ * #color_function variable to the address of this function.
*/
static RgbValues
reverse_grey_scale_color_function (const double value,
const ColorFunction color_function= &default_color_function);
/**
- * Declare all flags with name and type as offered by this class,
- * for use in input files.
+ * Declare all flags with name and type as offered by this class, for use
+ * in input files.
*
- * For coloring, only the color functions declared in this class
- * are offered.
+ * For coloring, only the color functions declared in this class are
+ * offered.
*/
static void declare_parameters (ParameterHandler &prm);
/**
- * Read the parameters declared in declare_parameters() and set
- * the flags for this output format accordingly.
+ * Read the parameters declared in declare_parameters() and set the flags
+ * for this output format accordingly.
*
- * The flags thus obtained overwrite all previous contents of this
- * object.
+ * The flags thus obtained overwrite all previous contents of this object.
*/
void parse_parameters (const ParameterHandler &prm);
/**
- * Determine an estimate for the memory consumption (in bytes) of
- * this object. Since sometimes the size of objects can not be
- * determined exactly (for example: what is the memory consumption
- * of an STL <tt>std::map</tt> type with a certain number of
- * elements?), this is only an estimate. however often quite close
- * to the true value.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object. Since sometimes the size of objects can not be determined
+ * exactly (for example: what is the memory consumption of an STL
+ * <tt>std::map</tt> type with a certain number of elements?), this is
+ * only an estimate. however often quite close to the true value.
*/
std::size_t memory_consumption () const;
};
/**
- * Flags controlling the details of output in GMV format. At present
- * no flags are implemented.
+ * Flags controlling the details of output in GMV format. At present no
+ * flags are implemented.
*
* @ingroup output
*/
private:
/**
* Dummy entry to suppress compiler warnings when copying an empty
- * structure. Remove this member when adding the first flag to
- * this structure (and remove the <tt>private</tt> as well).
+ * structure. Remove this member when adding the first flag to this
+ * structure (and remove the <tt>private</tt> as well).
*/
int dummy;
GmvFlags ();
/**
- * Declare all flags with name and type as offered by this class,
- * for use in input files.
+ * Declare all flags with name and type as offered by this class, for use
+ * in input files.
*/
static void declare_parameters (ParameterHandler &prm);
/**
- * Read the parameters declared in declare_parameters() and set
- * the flags for this output format accordingly.
+ * Read the parameters declared in declare_parameters() and set the flags
+ * for this output format accordingly.
*
- * The flags thus obtained overwrite all previous contents of this
- * object.
+ * The flags thus obtained overwrite all previous contents of this object.
*/
void parse_parameters (const ParameterHandler &prm) const;
/**
- * Determine an estimate for the memory consumption (in bytes) of
- * this object. Since sometimes the size of objects can not be
- * determined exactly (for example: what is the memory consumption
- * of an STL <tt>std::map</tt> type with a certain number of
- * elements?), this is only an estimate. however often quite close
- * to the true value.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object. Since sometimes the size of objects can not be determined
+ * exactly (for example: what is the memory consumption of an STL
+ * <tt>std::map</tt> type with a certain number of elements?), this is
+ * only an estimate. however often quite close to the true value.
*/
std::size_t memory_consumption () const;
};
public:
/**
- * This variable is needed to hold the output file name when using
- * the Tecplot API to write binary files. If the user doesn't set
- * the file name with this variable only ASCII Tecplot output will
- * be produced.
+ * This variable is needed to hold the output file name when using the
+ * Tecplot API to write binary files. If the user doesn't set the file
+ * name with this variable only ASCII Tecplot output will be produced.
*/
const char *tecplot_binary_file_name;
/**
- * Tecplot allows to assign names to zones. This variable stores
- * this name.
+ * Tecplot allows to assign names to zones. This variable stores this
+ * name.
*/
const char *zone_name;
/**
* Constructor
- **/
+ */
TecplotFlags (const char *tecplot_binary_file_name = NULL,
const char *zone_name = NULL);
/**
- * Declare all flags with name and type as offered by this class,
- * for use in input files.
+ * Declare all flags with name and type as offered by this class, for use
+ * in input files.
*/
static void declare_parameters (ParameterHandler &prm);
/**
- * Read the parameters declared in declare_parameters() and set
- * the flags for this output format accordingly.
+ * Read the parameters declared in declare_parameters() and set the flags
+ * for this output format accordingly.
*
- * The flags thus obtained overwrite all previous contents of this
- * object.
+ * The flags thus obtained overwrite all previous contents of this object.
*/
void parse_parameters (const ParameterHandler &prm) const;
/**
- * Determine an estimate for the memory consumption (in bytes) of
- * this object. Since sometimes the size of objects can not be
- * determined exactly (for example: what is the memory consumption
- * of an STL <tt>std::map</tt> type with a certain number of
- * elements?), this is only an estimate. however often quite close
- * to the true value.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object. Since sometimes the size of objects can not be determined
+ * exactly (for example: what is the memory consumption of an STL
+ * <tt>std::map</tt> type with a certain number of elements?), this is
+ * only an estimate. however often quite close to the true value.
*/
std::size_t memory_consumption () const;
};
{
public:
/**
- * The time of the time step if this file is part of a time
- * dependent simulation.
+ * The time of the time step if this file is part of a time dependent
+ * simulation.
*
- * The value of this variable is written into the output file
- * according to the instructions provided in
+ * The value of this variable is written into the output file according to
+ * the instructions provided in
* http://www.visitusers.org/index.php?title=Time_and_Cycle_in_VTK_files
* unless it is at its default value of
* std::numeric_limits<double>::min().
double time;
/**
- * The number of the time step if this file is part of a time
- * dependent simulation, or the cycle within a nonlinear or other
- * iteration.
+ * The number of the time step if this file is part of a time dependent
+ * simulation, or the cycle within a nonlinear or other iteration.
*
- * The value of this variable is written into the output file
- * according to the instructions provided in
+ * The value of this variable is written into the output file according to
+ * the instructions provided in
* http://www.visitusers.org/index.php?title=Time_and_Cycle_in_VTK_files
- * unless it is at its default value of
- * std::numeric_limits<unsigned int>::min().
+ * unless it is at its default value of std::numeric_limits<unsigned
+ * int>::min().
*/
unsigned int cycle;
/**
- * Flag to determine whether the current date and time shall be
- * printed as a comment in the file's second line.
- *
- * Default is <tt>true</tt>.
- */
+ * Flag to determine whether the current date and time shall be printed as
+ * a comment in the file's second line.
+ *
+ * Default is <tt>true</tt>.
+ */
bool print_date_and_time;
/**
const bool print_date_and_time = true);
/**
- * Declare the flags with name and type as offered by this class,
- * for use in input files.
+ * Declare the flags with name and type as offered by this class, for use
+ * in input files.
*
- * Unlike the flags in many of the other classes similar to this one, we do
- * not actually declare parameters for the #cycle and #time member variables
- * of this class. The reason is that there wouldn't appear to be a case where
- * one would want to declare these parameters in an input file. Rather, these
- * are typically values that change during the course of a simulation and
- * can only reasonably be set as part of the execution of a program, rather
- * than a priori by a user who runs this program.
+ * Unlike the flags in many of the other classes similar to this one, we
+ * do not actually declare parameters for the #cycle and #time member
+ * variables of this class. The reason is that there wouldn't appear to be
+ * a case where one would want to declare these parameters in an input
+ * file. Rather, these are typically values that change during the course
+ * of a simulation and can only reasonably be set as part of the execution
+ * of a program, rather than a priori by a user who runs this program.
*/
static void declare_parameters (ParameterHandler &prm);
/**
- * Read the parameters declared in declare_parameters() and
- * set the flags for this output format accordingly.
+ * Read the parameters declared in declare_parameters() and set the flags
+ * for this output format accordingly.
*
- * The flags thus obtained overwrite all previous contents of this
- * object.
+ * The flags thus obtained overwrite all previous contents of this object.
*/
void parse_parameters (const ParameterHandler &prm) const;
/**
- * Determine an estimate for the memory consumption (in bytes) of
- * this object. Since sometimes the size of objects can not be
- * determined exactly (for example: what is the memory consumption
- * of an STL <tt>std::map</tt> type with a certain number of
- * elements?), this is only an estimate. however often quite close
- * to the true value.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object. Since sometimes the size of objects can not be determined
+ * exactly (for example: what is the memory consumption of an STL
+ * <tt>std::map</tt> type with a certain number of elements?), this is
+ * only an estimate. however often quite close to the true value.
*/
std::size_t memory_consumption () const;
};
{
public:
/**
- * Height of the image in SVG
- * units. Default value is 4000.
- */
+ * Height of the image in SVG units. Default value is 4000.
+ */
unsigned int height;
/**
- * Width of the image in SVG
- units. If left zero, the width is computed from the height.
- */
+ * Width of the image in SVG units. If left zero, the width is computed
+ * from the height.
+ */
unsigned int width;
/**
- * This denotes the number of the data vector which shall be used
- * for generating the height information. By default, the first
- * data vector is taken, i.e. <tt>#height_vector==0</tt>, if there
- * is any data vector. If there is no data vector, no height
- * information is generated.
+ * This denotes the number of the data vector which shall be used for
+ * generating the height information. By default, the first data vector is
+ * taken, i.e. <tt>#height_vector==0</tt>, if there is any data vector. If
+ * there is no data vector, no height information is generated.
*/
unsigned int height_vector;
unsigned int line_thickness;
/**
- * Draw a margin of 5% around the plotted area
- */
+ * Draw a margin of 5% around the plotted area
+ */
bool margin;
/**
- * Draw a colorbar encoding the cell coloring
- */
+ * Draw a colorbar encoding the cell coloring
+ */
bool draw_colorbar;
/**
- * Constructor.
- */
+ * Constructor.
+ */
SvgFlags(const unsigned int height_vector = 0,
const int azimuth_angle = 37,
const int polar_angle = 45,
const bool draw_colorbar = true);
/**
- * Determine an estimate for the memory consumption (in bytes) of
- * this object. Since sometimes the size of objects can not be
- * determined exactly (for example: what is the memory consumption
- * of an STL <tt>std::map</tt> type with a certain number of
- * elements?), this is only an estimate. however often quite close
- * to the true value.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object. Since sometimes the size of objects can not be determined
+ * exactly (for example: what is the memory consumption of an STL
+ * <tt>std::map</tt> type with a certain number of elements?), this is
+ * only an estimate. however often quite close to the true value.
*/
std::size_t memory_consumption () const;
};
/**
- * Flags controlling the details of output in deal.II intermediate
- * format. At present no flags are implemented.
+ * Flags controlling the details of output in deal.II intermediate format.
+ * At present no flags are implemented.
*
* @ingroup output
*/
{
/**
* An indicator of the currect file format version used to write
- * intermediate format. We do not attempt to be backward
- * compatible, so this number is used only to verify that the
- * format we are writing is what the current readers and writers
- * understand.
+ * intermediate format. We do not attempt to be backward compatible, so
+ * this number is used only to verify that the format we are writing is
+ * what the current readers and writers understand.
*/
static const unsigned int format_version = 3;
private:
/**
* Dummy entry to suppress compiler warnings when copying an empty
- * structure. Remove this member when adding the first flag to
- * this structure (and remove the <tt>private</tt> as well).
+ * structure. Remove this member when adding the first flag to this
+ * structure (and remove the <tt>private</tt> as well).
*/
int dummy;
Deal_II_IntermediateFlags ();
/**
- * Declare all flags with name and type as offered by this class,
- * for use in input files.
+ * Declare all flags with name and type as offered by this class, for use
+ * in input files.
*/
static void declare_parameters (ParameterHandler &prm);
/**
- * Read the parameters declared in declare_parameters() and
- * set the flags for this output format accordingly.
+ * Read the parameters declared in declare_parameters() and set the flags
+ * for this output format accordingly.
*
- * The flags thus obtained overwrite
- * all previous contents of this object.
+ * The flags thus obtained overwrite all previous contents of this object.
*/
void parse_parameters (const ParameterHandler &prm) const;
/**
- * Determine an estimate for the memory consumption (in bytes) of
- * this object. Since sometimes the size of objects can not be
- * determined exactly (for example: what is the memory consumption
- * of an STL <tt>std::map</tt> type with a certain number of
- * elements?), this is only an estimate. however often quite close
- * to the true value.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object. Since sometimes the size of objects can not be determined
+ * exactly (for example: what is the memory consumption of an STL
+ * <tt>std::map</tt> type with a certain number of elements?), this is
+ * only an estimate. however often quite close to the true value.
*/
std::size_t memory_consumption () const;
};
struct DataOutFilterFlags
{
/**
- * Filter duplicate vertices and associated values. This will
- * drastically reduce the output data size but may affect the
- * correctness of some calculated values.
+ * Filter duplicate vertices and associated values. This will drastically
+ * reduce the output data size but may affect the correctness of some
+ * calculated values.
*/
bool filter_duplicate_vertices;
/**
- * Whether the XDMF output refers to HDF5 files.
- * This affects how output is structured.
+ * Whether the XDMF output refers to HDF5 files. This affects how output
+ * is structured.
*/
bool xdmf_hdf5_output;
const bool xdmf_hdf5_output = false);
/**
- * Declare all flags with name
- * and type as offered by this
- * class, for use in input files.
+ * Declare all flags with name and type as offered by this class, for use
+ * in input files.
*/
static void declare_parameters (ParameterHandler &prm);
/**
- * Read the parameters declared in
- * <tt>declare_parameters</tt> and set the
- * flags for this output format
- * accordingly.
+ * Read the parameters declared in <tt>declare_parameters</tt> and set the
+ * flags for this output format accordingly.
*
- * The flags thus obtained overwrite
- * all previous contents of this object.
+ * The flags thus obtained overwrite all previous contents of this object.
*/
void parse_parameters (const ParameterHandler &prm);
/**
- * Determine an estimate for
- * the memory consumption (in
- * bytes) of this
+ * Determine an estimate for the memory consumption (in bytes) of this
* object.
*/
std::size_t memory_consumption () const;
/**
* DataOutFilter provides a way to remove redundant vertices and values
* generated by the deal.II output. By default, DataOutBase and the classes
- * that build on it output data at each corner of each cell. This means
- * that data is output multiple times for each vertex of the mesh. The
- * purpose of this scheme is to support output of discontinuous quantities,
- * either because the finite element space is discontinuous or because the
- * quantity that is output is computed from a solution field and is
- * discontinuous across faces.
+ * that build on it output data at each corner of each cell. This means that
+ * data is output multiple times for each vertex of the mesh. The purpose of
+ * this scheme is to support output of discontinuous quantities, either
+ * because the finite element space is discontinuous or because the quantity
+ * that is output is computed from a solution field and is discontinuous
+ * across faces.
*
* This class is an attempt to rein in the amount of data that is written.
* If the fields that are written to files are indeed discontinuous, the
- * only way to faithfully represent them is indeed to write multiple
- * values for each vertex (this is typically done by writing multiple
- * node locations for the same vertex and defining data at these nodes).
- * However, for fine meshes, one may not necessarily be interested in an
- * exact representation of output fields that will likely only have
- * small discontinuities. Rather, it may be sufficient to just output one
- * value per vertex, which may be chosen arbitrarily from among those that
- * are defined at this vertex from any of the adjacent cells.
+ * only way to faithfully represent them is indeed to write multiple values
+ * for each vertex (this is typically done by writing multiple node
+ * locations for the same vertex and defining data at these nodes). However,
+ * for fine meshes, one may not necessarily be interested in an exact
+ * representation of output fields that will likely only have small
+ * discontinuities. Rather, it may be sufficient to just output one value
+ * per vertex, which may be chosen arbitrarily from among those that are
+ * defined at this vertex from any of the adjacent cells.
*/
class DataOutFilter
{
DataOutFilter(const DataOutBase::DataOutFilterFlags &flags) : flags(flags) {};
/**
- * Write a point with the specified index into the filtered
- * data set. If the point already exists and we are filtering
- * redundant values, the provided index will internally refer
- * to another recorded point.
+ * Write a point with the specified index into the filtered data set. If
+ * the point already exists and we are filtering redundant values, the
+ * provided index will internally refer to another recorded point.
*/
template<int dim>
void write_point(const unsigned int &index, const Point<dim> &p);
void write_cell(unsigned int index, unsigned int start, unsigned int d1, unsigned int d2, unsigned int d3);
/**
- * Filter and record a data set. If there are multiple values
- * at a given vertex and redundant values are being removed, one
- * is arbitrarily chosen as the recorded value. In the future
- * this can be expanded to average/min/max multiple values
- * at a given vertex.
+ * Filter and record a data set. If there are multiple values at a given
+ * vertex and redundant values are being removed, one is arbitrarily
+ * chosen as the recorded value. In the future this can be expanded to
+ * average/min/max multiple values at a given vertex.
*/
void write_data_set(const std::string &name, const unsigned int &dimension, const unsigned int &set_num, const Table<2,double> &data_vectors);
/**
- * Resize and fill a vector with all the filtered
- * node vertex points, for output to a file.
+ * Resize and fill a vector with all the filtered node vertex points, for
+ * output to a file.
*/
void fill_node_data(std::vector<double> &node_data) const;
/**
- * Resize and fill a vector with all the filtered
- * cell vertex indices, for output to a file.
+ * Resize and fill a vector with all the filtered cell vertex indices, for
+ * output to a file.
*/
void fill_cell_data(const unsigned int &local_node_offset, std::vector<unsigned int> &cell_data) const;
};
/**
- * Get the raw double valued data of the data set indicated by the set number.
+ * Get the raw double valued data of the data set indicated by the set
+ * number.
*/
const double *get_data_set(const unsigned int &set_num) const
{
};
/**
- * Return the number of filtered data sets in this DataOutFilter. Data sets are
- * not filtered so this will be the original number of data sets.
+ * Return the number of filtered data sets in this DataOutFilter. Data
+ * sets are not filtered so this will be the original number of data sets.
*/
unsigned int n_data_sets() const
{
};
/**
- * Empty functions to do base class inheritance.
- */
+ * Empty functions to do base class inheritance.
+ */
void flush_points () {};
/**
/**
- * Provide a data type specifying the presently supported output
- * formats.
+ * Provide a data type specifying the presently supported output formats.
*/
enum OutputFormat
{
tecplot,
/**
- * Output for Tecplot in binary format. Faster and smaller than
- * text format.
+ * Output for Tecplot in binary format. Faster and smaller than text
+ * format.
*/
tecplot_binary,
/**
- * Write the given list of patches to the output stream in OpenDX
- * format.
+ * Write the given list of patches to the output stream in OpenDX format.
*
- * Since OpenDX uses some kind of visual data flow oriented
- * programming language, some of these programs are provided in
- * <tt>contrib/dx</tt>.
+ * Since OpenDX uses some kind of visual data flow oriented programming
+ * language, some of these programs are provided in <tt>contrib/dx</tt>.
*/
template <int dim, int spacedim>
void write_dx (const std::vector<Patch<dim,spacedim> > &patches,
/**
* Write the given list of patches to the output stream in eps format.
*
- * Output in this format circumvents the use of auxiliary graphic
- * programs converting some output format into a graphics
- * format. This has the advantage that output is easy and fast, and
- * the disadvantage that you have to give a whole bunch of
- * parameters which determine the direction of sight, the mode of
- * colorization, the scaling of the height axis, etc. (Of course,
- * all these parameters have reasonable default values, which you
+ * Output in this format circumvents the use of auxiliary graphic programs
+ * converting some output format into a graphics format. This has the
+ * advantage that output is easy and fast, and the disadvantage that you
+ * have to give a whole bunch of parameters which determine the direction of
+ * sight, the mode of colorization, the scaling of the height axis, etc. (Of
+ * course, all these parameters have reasonable default values, which you
* may want to change.)
*
- * This function only supports output for two-dimensional
- * domains (i.e., with dim==2), with values in the vertical
- * direction taken from a data vector.
- *
- * Basically, output consists of the mesh and the cells in between
- * them. You can draw either of these, or both, or none if you are
- * really interested in an empty picture. If written, the mesh uses
- * black lines. The cells in between the mesh are either not printed
- * (this will result in a loss of hidden line removal, i.e. you can
- * "see through" the cells to lines behind), printed in white (which
- * does nothing apart from the hidden line removal), or colorized
- * using one of the data vectors (which need not be the same as the
- * one used for computing the height information) and a customizable
- * color function. The default color functions chooses the color
- * between black, blue, green, red and white, with growing values of
- * the data field chosen for colorization. At present, cells are
- * displayed with one color per cell only, which is taken from the
- * value of the data field at the center of the cell; bilinear
- * interpolation of the color on a cell is not used.
+ * This function only supports output for two-dimensional domains (i.e.,
+ * with dim==2), with values in the vertical direction taken from a data
+ * vector.
+ *
+ * Basically, output consists of the mesh and the cells in between them. You
+ * can draw either of these, or both, or none if you are really interested
+ * in an empty picture. If written, the mesh uses black lines. The cells in
+ * between the mesh are either not printed (this will result in a loss of
+ * hidden line removal, i.e. you can "see through" the cells to lines
+ * behind), printed in white (which does nothing apart from the hidden line
+ * removal), or colorized using one of the data vectors (which need not be
+ * the same as the one used for computing the height information) and a
+ * customizable color function. The default color functions chooses the
+ * color between black, blue, green, red and white, with growing values of
+ * the data field chosen for colorization. At present, cells are displayed
+ * with one color per cell only, which is taken from the value of the data
+ * field at the center of the cell; bilinear interpolation of the color on a
+ * cell is not used.
*
* By default, the viewpoint is chosen like the default viewpoint in
- * GNUPLOT, i.e. with an angle of 60 degrees with respect to the
- * positive z-axis and rotated 30 degrees in positive sense (as seen
- * from above) away from the negative y-axis. Of course you can
- * change these settings.
+ * GNUPLOT, i.e. with an angle of 60 degrees with respect to the positive
+ * z-axis and rotated 30 degrees in positive sense (as seen from above) away
+ * from the negative y-axis. Of course you can change these settings.
*
* EPS output is written without a border around the picture, i.e. the
- * bounding box is close to the output on all four sides. Coordinates
- * are written using at most five digits, to keep picture size at a
- * reasonable size.
+ * bounding box is close to the output on all four sides. Coordinates are
+ * written using at most five digits, to keep picture size at a reasonable
+ * size.
*
* All parameters along with their default values are listed in the
- * documentation of the <tt>EpsFlags</tt> member class of this
- * class. See there for more and detailed information.
+ * documentation of the <tt>EpsFlags</tt> member class of this class. See
+ * there for more and detailed information.
*/
template <int spacedim>
void write_eps (const std::vector<Patch<2,spacedim> > &patches,
std::ostream &out);
/**
- * This is the same function as above except for domains that are
- * not two-dimensional. This function is not implemented (and will
- * throw an error if called) but is declared to allow for
- * dimension-independent programs.
+ * This is the same function as above except for domains that are not two-
+ * dimensional. This function is not implemented (and will throw an error if
+ * called) but is declared to allow for dimension-independent programs.
*/
template <int dim, int spacedim>
void write_eps (const std::vector<Patch<dim,spacedim> > &patches,
/**
- * Write the given list of patches to the output stream in
- * GMV format.
+ * Write the given list of patches to the output stream in GMV format.
*
- * Data is written in the following format: nodes are considered the
- * points of the patches. In spatial dimensions less than three,
- * zeroes are inserted for the missing coordinates. The data vectors
- * are written as node or cell data, where for the first the data
- * space is interpolated to (bi-,tri-)linear elements.
+ * Data is written in the following format: nodes are considered the points
+ * of the patches. In spatial dimensions less than three, zeroes are
+ * inserted for the missing coordinates. The data vectors are written as
+ * node or cell data, where for the first the data space is interpolated to
+ * (bi-,tri-)linear elements.
*/
template <int dim, int spacedim>
void write_gmv (const std::vector<Patch<dim,spacedim> > &patches,
std::ostream &out);
/**
- * Write the given list of patches to the output stream in gnuplot
- * format. Visualization of two-dimensional data can then be achieved by
- * starting <tt>gnuplot</tt> and endtering the commands
+ * Write the given list of patches to the output stream in gnuplot format.
+ * Visualization of two-dimensional data can then be achieved by starting
+ * <tt>gnuplot</tt> and endtering the commands
*
* @verbatim
* set data style lines
* splot "filename" using 1:2:n
* @endverbatim
- * This example assumes that the number of the data vector displayed
- * is <b>n-2</b>.
+ * This example assumes that the number of the data vector displayed is
+ * <b>n-2</b>.
*
* The GNUPLOT format is not able to handle data on unstructured grids
- * directly. Directly would mean that you only give the vertices and
- * the solution values thereon and the program constructs its own grid
- * to represent the data. This is only possible for a structured
- * tensor product grid in two dimensions. However, it is possible to
- * give several such patches within one file, which is exactly what
- * the respective function of this class does: writing each cell's
- * data as a patch of data, at least if the patches as passed from
- * derived classes represent cells. Note that the functions on patches
- * need not be continuous at interfaces between patches, so this
- * method also works for discontinuous elements. Note also, that
- * GNUPLOT can do hidden line removal for patched data.
+ * directly. Directly would mean that you only give the vertices and the
+ * solution values thereon and the program constructs its own grid to
+ * represent the data. This is only possible for a structured tensor product
+ * grid in two dimensions. However, it is possible to give several such
+ * patches within one file, which is exactly what the respective function of
+ * this class does: writing each cell's data as a patch of data, at least if
+ * the patches as passed from derived classes represent cells. Note that the
+ * functions on patches need not be continuous at interfaces between
+ * patches, so this method also works for discontinuous elements. Note also,
+ * that GNUPLOT can do hidden line removal for patched data.
*
* While this discussion applies to two spatial dimensions, it is more
- * complicated in 3d. The reason is that we could still use patches,
- * but it is difficult when trying to visualize them, since if we use
- * a cut through the data (by, for example, using x- and
- * z-coordinates, a fixed y-value and plot function values in
- * z-direction, then the patched data is not a patch in the sense
- * GNUPLOT wants it any more. Therefore, we use another approach,
- * namely writing the data on the 3d grid as a sequence of lines,
- * i.e. two points each associated with one or more data sets. There
- * are therefore 12 lines for each subcells of a patch.
- *
- * Given the lines as described above, a cut through this data in
- * Gnuplot can then be achieved like this (& stands for the dollar
- * sign in the following):
+ * complicated in 3d. The reason is that we could still use patches, but it
+ * is difficult when trying to visualize them, since if we use a cut through
+ * the data (by, for example, using x- and z-coordinates, a fixed y-value
+ * and plot function values in z-direction, then the patched data is not a
+ * patch in the sense GNUPLOT wants it any more. Therefore, we use another
+ * approach, namely writing the data on the 3d grid as a sequence of lines,
+ * i.e. two points each associated with one or more data sets. There are
+ * therefore 12 lines for each subcells of a patch.
+ *
+ * Given the lines as described above, a cut through this data in Gnuplot
+ * can then be achieved like this (& stands for the dollar sign in the
+ * following):
* @verbatim
* set data style lines
* splot [:][:][0:] "T" using 1:2:(&3==.5 ? &4 : -1)
* @endverbatim
*
* This command plots data in x- and y-direction unbounded, but in
- * z-direction only those data points which are above the x-y-plane
- * (we assume here a positive solution, if it has negative values, you
- * might want to decrease the lower bound). Furthermore, it only takes
- * the data points with z-values (<tt>&3</tt>) equal to 0.5, i.e. a
- * cut through the domain at <tt>z=0.5</tt>. For the data points on
- * this plane, the data values of the first data set (<tt>&4</tt>) are
- * raised in z-direction above the x-y-plane; all other points are
- * denoted the value <tt>-1</tt> instead of the value of the data
- * vector and are not plotted due to the lower bound in z plotting
- * direction, given in the third pair of brackets.
- *
- * More complex cuts are possible, including nonlinear ones. Note
- * however, that only those points which are actually on the
- * cut-surface are plotted.
+ * z-direction only those data points which are above the x-y-plane (we
+ * assume here a positive solution, if it has negative values, you might
+ * want to decrease the lower bound). Furthermore, it only takes the data
+ * points with z-values (<tt>&3</tt>) equal to 0.5, i.e. a cut through the
+ * domain at <tt>z=0.5</tt>. For the data points on this plane, the data
+ * values of the first data set (<tt>&4</tt>) are raised in z-direction
+ * above the x-y-plane; all other points are denoted the value <tt>-1</tt>
+ * instead of the value of the data vector and are not plotted due to the
+ * lower bound in z plotting direction, given in the third pair of brackets.
+ *
+ * More complex cuts are possible, including nonlinear ones. Note however,
+ * that only those points which are actually on the cut-surface are plotted.
*/
template <int dim, int spacedim>
void write_gnuplot (const std::vector<Patch<dim,spacedim> > &patches,
std::ostream &out);
/**
- * Write the given list of patches to the output stream for the
- * Povray raytracer.
+ * Write the given list of patches to the output stream for the Povray
+ * raytracer.
*
- * Output in this format creates a povray source file, include
- * standard camera and light source definition for rendering with
- * povray 3.1 At present, this format only supports output for
- * two-dimensional data, with values in the third direction taken from
- * a data vector.
+ * Output in this format creates a povray source file, include standard
+ * camera and light source definition for rendering with povray 3.1 At
+ * present, this format only supports output for two-dimensional data, with
+ * values in the third direction taken from a data vector.
*
* The output uses two different povray-objects:
*
* <ul>
- * <li> <tt>BICUBIC_PATCH</tt>
- * A <tt>bicubic_patch</tt> is a 3-dimensional Bezier patch. It consists of 16 Points
- * describing the surface. The 4 corner points are touched by the object,
- * while the other 12 points pull and stretch the patch into shape.
- * One <tt>bicubic_patch</tt> is generated on each patch. Therefor the number of
- * subdivisions has to be 3 to provide the patch with 16 points.
- * A bicubic patch is not exact but generates very smooth images.
- *
- * <li> <tt>MESH</tt>
- * The mesh object is used to store large number of triangles.
- * Every square of the patch data is split into one upper-left and one
- * lower-right triangle. If the number of subdivisions is three, 32 triangle
- * are generated for every patch.
+ * <li> <tt>BICUBIC_PATCH</tt> A <tt>bicubic_patch</tt> is a 3-dimensional
+ * Bezier patch. It consists of 16 Points describing the surface. The 4
+ * corner points are touched by the object, while the other 12 points pull
+ * and stretch the patch into shape. One <tt>bicubic_patch</tt> is generated
+ * on each patch. Therefor the number of subdivisions has to be 3 to provide
+ * the patch with 16 points. A bicubic patch is not exact but generates very
+ * smooth images.
+ *
+ * <li> <tt>MESH</tt> The mesh object is used to store large number of
+ * triangles. Every square of the patch data is split into one upper-left
+ * and one lower-right triangle. If the number of subdivisions is three, 32
+ * triangle are generated for every patch.
*
* Using the smooth flag povray interpolates the normals on the triangles,
* imitating a curved surface
*
* All objects get one texture definition called Tex. This texture has to be
* declared somewhere before the object data. This may be in an external
- * data file or at the beginning of the output file.
- * Setting the <tt>external_data</tt> flag to false, an standard camera, light and
+ * data file or at the beginning of the output file. Setting the
+ * <tt>external_data</tt> flag to false, an standard camera, light and
* texture (scaled to fit the scene) is added to the outputfile. Set to true
- * an include file "data.inc" is included. This file is not generated by deal
- * and has to include camera, light and the texture definition Tex.
+ * an include file "data.inc" is included. This file is not generated by
+ * deal and has to include camera, light and the texture definition Tex.
*
- * You need povray (>=3.0) to render the scene. The minimum options for povray
- * are:
+ * You need povray (>=3.0) to render the scene. The minimum options for
+ * povray are:
* @verbatim
* povray +I<inputfile> +W<horiz. size> +H<ver. size> +L<include path>
* @endverbatim
std::ostream &out);
/**
- * Write the given list of patches to the output stream in
- * Tecplot ASCII format (FEBLOCK).
+ * Write the given list of patches to the output stream in Tecplot ASCII
+ * format (FEBLOCK).
*
- * For more information consult the Tecplot Users and Reference
- * manuals.
+ * For more information consult the Tecplot Users and Reference manuals.
*/
template <int dim, int spacedim>
void write_tecplot (const std::vector<Patch<dim,spacedim> > &patches,
std::ostream &out);
/**
- * Write the given list of patches to the output stream in
- * Tecplot binary format.
+ * Write the given list of patches to the output stream in Tecplot binary
+ * format.
*
- * For this to work properly <tt>./configure</tt> checks for the
- * Tecplot API at build time. To write Tecplot binary files directly
- * make sure that the TECHOME environment variable points to the
- * Tecplot installation directory, and that the files
- * \$TECHOME/include/TECIO.h and \$TECHOME/lib/tecio.a are readable.
- * If these files are not available (or in the case of 1D) this
- * function will simply call write_tecplot() and thus larger ASCII
- * data files will be produced rather than more efficient Tecplot
- * binary files.
+ * For this to work properly <tt>./configure</tt> checks for the Tecplot API
+ * at build time. To write Tecplot binary files directly make sure that the
+ * TECHOME environment variable points to the Tecplot installation
+ * directory, and that the files \$TECHOME/include/TECIO.h and
+ * \$TECHOME/lib/tecio.a are readable. If these files are not available (or
+ * in the case of 1D) this function will simply call write_tecplot() and
+ * thus larger ASCII data files will be produced rather than more efficient
+ * Tecplot binary files.
*
- * @warning TecplotFlags::tecplot_binary_file_name indicates the name
- * of the file to be written. If the file name is not set ASCII
- * output is produced.
+ * @warning TecplotFlags::tecplot_binary_file_name indicates the name of the
+ * file to be written. If the file name is not set ASCII output is
+ * produced.
*
- * For more information consult the Tecplot Users and Reference
- * manuals.
+ * For more information consult the Tecplot Users and Reference manuals.
*/
template <int dim, int spacedim>
void write_tecplot_binary (
/**
* Write the given list of patches to the output stream in UCD format
- * described in the AVS developer's guide (now AVS). Due
- * to limitations in the present format, only node based data can be
- * output, which in one reason why we invented the patch concept. In
- * order to write higher order elements, you may split them up into
- * several subdivisions of each cell. These subcells will then,
- * however, also appear as different cells by programs which
- * understand the UCD format.
- *
- * No use is made of the possibility to give model data since these
- * are not supported by all UCD aware programs. You may give cell data
- * in derived classes by setting all values of a given data set on a
- * patch to the same value.
+ * described in the AVS developer's guide (now AVS). Due to limitations in
+ * the present format, only node based data can be output, which in one
+ * reason why we invented the patch concept. In order to write higher order
+ * elements, you may split them up into several subdivisions of each cell.
+ * These subcells will then, however, also appear as different cells by
+ * programs which understand the UCD format.
+ *
+ * No use is made of the possibility to give model data since these are not
+ * supported by all UCD aware programs. You may give cell data in derived
+ * classes by setting all values of a given data set on a patch to the same
+ * value.
*/
template <int dim, int spacedim>
void write_ucd (const std::vector<Patch<dim,spacedim> > &patches,
std::ostream &out);
/**
- * Write the given list of patches to the output stream in VTK
- * format. The data is written in the traditional VTK format as opposed to the
- * XML-based format that write_vtu() produces.
+ * Write the given list of patches to the output stream in VTK format. The
+ * data is written in the traditional VTK format as opposed to the XML-based
+ * format that write_vtu() produces.
*
* The vector_data_ranges argument denotes ranges of components in the
- * output that are considered a vector, rather than simply a
- * collection of scalar fields. The VTK output format has special
- * provisions that allow these components to be output by a single
- * name rather than having to group several scalar fields into a
- * vector later on in the visualization program.
+ * output that are considered a vector, rather than simply a collection of
+ * scalar fields. The VTK output format has special provisions that allow
+ * these components to be output by a single name rather than having to
+ * group several scalar fields into a vector later on in the visualization
+ * program.
*
* @note VTK is a legacy format and has largely been supplanted by the VTU
* format (an XML-structured version of VTK). In particular, VTU allows for
- * the compression of data and consequently leads to much smaller file
- * sizes that equivalent VTK files for large files. Since all visualization
+ * the compression of data and consequently leads to much smaller file sizes
+ * that equivalent VTK files for large files. Since all visualization
* programs that support VTK also support VTU, you should consider using the
* latter file format instead, by using the write_vtu() function.
*/
/**
- * Write the given list of patches to the output stream in VTU
- * format. The data is written in the XML-based VTK format as opposed to the
- * traditional format that write_vtk() produces.
+ * Write the given list of patches to the output stream in VTU format. The
+ * data is written in the XML-based VTK format as opposed to the traditional
+ * format that write_vtk() produces.
*
* The vector_data_ranges argument denotes ranges of components in the
- * output that are considered a vector, rather than simply a
- * collection of scalar fields. The VTK output format has special
- * provisions that allow these components to be output by a single
- * name rather than having to group several scalar fields into a
- * vector later on in the visualization program.
- *
- * Some visualization programs, such as ParaView, can read several
- * separate VTU files to parallelize visualization. In that case, you
- * need a <code>.pvtu</code> file that describes which VTU files form
- * a group. The DataOutInterface::write_pvtu_record() function can
- * generate such a master record. Likewise,
- * DataOutInterface::write_visit_record() does the same for VisIt
- * (although VisIt can also read <code>pvtu</code> records since version 2.5.1).
- * Finally, for time dependent problems, you may also want to look
- * at DataOutInterface::write_pvd_record()
+ * output that are considered a vector, rather than simply a collection of
+ * scalar fields. The VTK output format has special provisions that allow
+ * these components to be output by a single name rather than having to
+ * group several scalar fields into a vector later on in the visualization
+ * program.
+ *
+ * Some visualization programs, such as ParaView, can read several separate
+ * VTU files to parallelize visualization. In that case, you need a
+ * <code>.pvtu</code> file that describes which VTU files form a group. The
+ * DataOutInterface::write_pvtu_record() function can generate such a master
+ * record. Likewise, DataOutInterface::write_visit_record() does the same
+ * for VisIt (although VisIt can also read <code>pvtu</code> records since
+ * version 2.5.1). Finally, for time dependent problems, you may also want
+ * to look at DataOutInterface::write_pvd_record()
*
* The use of this function is explained in step-40.
*/
std::ostream &out);
/**
- * This writes the header for the xml based vtu file format. This
- * routine is used internally together with
- * DataOutInterface::write_vtu_footer() and DataOutInterface::write_vtu_main()
- * by DataOutBase::write_vtu().
+ * This writes the header for the xml based vtu file format. This routine is
+ * used internally together with DataOutInterface::write_vtu_footer() and
+ * DataOutInterface::write_vtu_main() by DataOutBase::write_vtu().
*/
void write_vtu_header (std::ostream &out,
const VtkFlags &flags);
/**
- * This writes the footer for the xml based vtu file format. This
- * routine is used internally together with
- * DataOutInterface::write_vtu_header() and DataOutInterface::write_vtu_main()
- * by DataOutBase::write_vtu().
+ * This writes the footer for the xml based vtu file format. This routine is
+ * used internally together with DataOutInterface::write_vtu_header() and
+ * DataOutInterface::write_vtu_main() by DataOutBase::write_vtu().
*/
void write_vtu_footer (std::ostream &out);
/**
- * This writes the main part for the xml based vtu file format. This
- * routine is used internally together with
- * DataOutInterface::write_vtu_header() and DataOutInterface::write_vtu_footer()
- * by DataOutBase::write_vtu().
+ * This writes the main part for the xml based vtu file format. This routine
+ * is used internally together with DataOutInterface::write_vtu_header() and
+ * DataOutInterface::write_vtu_footer() by DataOutBase::write_vtu().
*/
template <int dim, int spacedim>
void write_vtu_main (const std::vector<Patch<dim,spacedim> > &patches,
* Write the given list of patches to the output stream in SVG format.
*
* SVG (Scalable Vector Graphics) is an XML-based vector image format
- * developed and maintained by the World Wide Web Consortium (W3C).
- * This function conforms to the latest specification SVG 1.1,
- * released on August 16, 2011. Controlling the graphic output is
- * possible by setting or clearing the respective flags (see the
- * SvgFlags struct). At present, this format only supports output
- * for two-dimensional data, with values in the third direction
- * taken from a data vector.
- *
- * For the output, each patch is subdivided into four triangles
- * which are then written as polygons and filled with a linear
- * color gradient. The arising coloring of the patches visualizes
- * the data values at the vertices taken from the specified data
- * vector. A colorbar can be drawn to encode the coloring.
- *
- * @note This function is so far only implemented for two dimensions
- * with an additional dimension reserved for data information.
+ * developed and maintained by the World Wide Web Consortium (W3C). This
+ * function conforms to the latest specification SVG 1.1, released on August
+ * 16, 2011. Controlling the graphic output is possible by setting or
+ * clearing the respective flags (see the SvgFlags struct). At present, this
+ * format only supports output for two-dimensional data, with values in the
+ * third direction taken from a data vector.
+ *
+ * For the output, each patch is subdivided into four triangles which are
+ * then written as polygons and filled with a linear color gradient. The
+ * arising coloring of the patches visualizes the data values at the
+ * vertices taken from the specified data vector. A colorbar can be drawn to
+ * encode the coloring.
+ *
+ * @note This function is so far only implemented for two dimensions with an
+ * additional dimension reserved for data information.
*/
template <int spacedim>
void write_svg (const std::vector<Patch<2,spacedim> > &patches,
* Write the given list of patches to the output stream in deal.II
* intermediate format. This is not a format understood by any other
* graphics program, but is rather a direct dump of the intermediate
- * internal format used by deal.II. This internal format is generated
- * by the various classes that can generate output using the
- * DataOutBase class, for example from a finite element solution, and
- * is then converted in the present class to the final graphics
- * format.
- *
- * Note that the intermediate format is what its name suggests: a
- * direct representation of internal data. It isn't standardized and
- * will change whenever we change our internal representation. You can
- * only expect to process files written in this format using the same
- * version of deal.II that was used for writing.
- *
- * The reason why we offer to write out this intermediate format is
- * that it can be read back into a deal.II program using the
- * DataOutReader class, which is helpful in at least two contexts:
- * First, this can be used to later generate graphical output in any
- * other graphics format presently understood; this way, it is not
- * necessary to know at run-time which output format is requested, or
- * if multiple output files in different formats are needed. Secondly,
- * in contrast to almost all other graphics formats, it is possible to
- * merge several files that contain intermediate format data, and
- * generate a single output file from it, which may be again in
- * intermediate format or any of the final formats. This latter option
- * is most helpful for parallel programs: as demonstrated in the
+ * internal format used by deal.II. This internal format is generated by the
+ * various classes that can generate output using the DataOutBase class, for
+ * example from a finite element solution, and is then converted in the
+ * present class to the final graphics format.
+ *
+ * Note that the intermediate format is what its name suggests: a direct
+ * representation of internal data. It isn't standardized and will change
+ * whenever we change our internal representation. You can only expect to
+ * process files written in this format using the same version of deal.II
+ * that was used for writing.
+ *
+ * The reason why we offer to write out this intermediate format is that it
+ * can be read back into a deal.II program using the DataOutReader class,
+ * which is helpful in at least two contexts: First, this can be used to
+ * later generate graphical output in any other graphics format presently
+ * understood; this way, it is not necessary to know at run-time which
+ * output format is requested, or if multiple output files in different
+ * formats are needed. Secondly, in contrast to almost all other graphics
+ * formats, it is possible to merge several files that contain intermediate
+ * format data, and generate a single output file from it, which may be
+ * again in intermediate format or any of the final formats. This latter
+ * option is most helpful for parallel programs: as demonstrated in the
* step-17 example program, it is possible to let only one processor
- * generate the graphical output for the entire parallel program, but
- * this can become vastly inefficient if many processors are involved,
- * because the load is no longer balanced. The way out is to let each
- * processor generate intermediate graphical output for its chunk of
- * the domain, and the later merge the different files into one, which
- * is an operation that is much cheaper than the generation of the
- * intermediate data.
+ * generate the graphical output for the entire parallel program, but this
+ * can become vastly inefficient if many processors are involved, because
+ * the load is no longer balanced. The way out is to let each processor
+ * generate intermediate graphical output for its chunk of the domain, and
+ * the later merge the different files into one, which is an operation that
+ * is much cheaper than the generation of the intermediate data.
*
- * Intermediate format deal.II data is usually stored in files with
- * the ending <tt>.d2</tt>.
+ * Intermediate format deal.II data is usually stored in files with the
+ * ending <tt>.d2</tt>.
*/
template <int dim, int spacedim>
void write_deal_II_intermediate (
std::ostream &out);
/**
- * Write the data in data_filter to a single HDF5 file containing both
- * the mesh and solution values.
+ * Write the data in data_filter to a single HDF5 file containing both the
+ * mesh and solution values.
*/
template <int dim, int spacedim>
void write_hdf5_parallel (const std::vector<Patch<dim,spacedim> > &patches,
MPI_Comm comm);
/**
- * Write the data in data_filter to HDF5 file(s). If write_mesh_file
- * is false, the mesh data will not be written and the solution
- * file will contain only the solution values. If write_mesh_file
- * is true and the filenames are the same, the resulting file will
- * contain both mesh data and solution values.
+ * Write the data in data_filter to HDF5 file(s). If write_mesh_file is
+ * false, the mesh data will not be written and the solution file will
+ * contain only the solution values. If write_mesh_file is true and the
+ * filenames are the same, the resulting file will contain both mesh data
+ * and solution values.
*/
template <int dim, int spacedim>
void write_hdf5_parallel (const std::vector<Patch<dim,spacedim> > &patches,
/**
* Given an input stream that contains data written by
* write_deal_II_intermediate(), determine the <tt>dim</tt> and
- * <tt>spacedim</tt> template parameters with which that function
- * was called, and return them as a pair of values.
+ * <tt>spacedim</tt> template parameters with which that function was
+ * called, and return them as a pair of values.
*
- * Note that this function eats a number of elements at the present
- * position of the stream, and therefore alters it. In order to read
- * from it using, for example, the DataOutReader class, you may wish
- * to either reset the stream to its previous position, or close and
- * reopen it.
+ * Note that this function eats a number of elements at the present position
+ * of the stream, and therefore alters it. In order to read from it using,
+ * for example, the DataOutReader class, you may wish to either reset the
+ * stream to its previous position, or close and reopen it.
*/
std::pair<unsigned int, unsigned int>
determine_intermediate_format_dimensions (std::istream &input);
/**
- * Return the OutputFormat value corresponding to the given
- * string. If the string does not match any known format, an
- * exception is thrown.
+ * Return the OutputFormat value corresponding to the given string. If the
+ * string does not match any known format, an exception is thrown.
*
* The main purpose of this function is to allow a program to use any
- * implemented output format without the need to extend the
- * program's parser each time a new format is implemented.
+ * implemented output format without the need to extend the program's parser
+ * each time a new format is implemented.
*
- * To get a list of presently available format names, e.g. to give
- * it to the ParameterHandler class, use the function
- * get_output_format_names().
+ * To get a list of presently available format names, e.g. to give it to the
+ * ParameterHandler class, use the function get_output_format_names().
*/
OutputFormat parse_output_format (const std::string &format_name);
/**
- * Return a list of implemented output formats. The different names
- * are separated by vertical bar signs (<tt>`|'</tt>) as used by the
+ * Return a list of implemented output formats. The different names are
+ * separated by vertical bar signs (<tt>`|'</tt>) as used by the
* ParameterHandler classes.
*/
std::string get_output_format_names ();
/**
- * Provide a function which tells us which suffix a file with a
- * given output format usually has. At present the following formats
- * are defined:
+ * Provide a function which tells us which suffix a file with a given output
+ * format usually has. At present the following formats are defined:
* <ul>
* <li> <tt>dx</tt>: <tt>.dx</tt>
* <li> <tt>ucd</tt>: <tt>.inp</tt>
*/
std::string default_suffix (const OutputFormat output_format);
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
*/
DeclException0 (ExcNoPatches);
/**
- * Exception
- */
+ * Exception
+ */
DeclException0 (ExcTecplotAPIError);
/**
* Exception
/**
- * This class is the interface to the functions in the DataOutBase namespace, as already its name
- * might suggest. It does not offer much functionality apart from a way to
- * access the implemented formats and a way to dynamically dispatch what output
- * format to chose.
+ * This class is the interface to the functions in the DataOutBase namespace,
+ * as already its name might suggest. It does not offer much functionality
+ * apart from a way to access the implemented formats and a way to dynamically
+ * dispatch what output format to chose.
*
- * This class is thought as a base class to classes actually
- * generating data for output. It has two abstract virtual functions,
- * get_patches() and get_dataset_names() produce the data which is
- * actually needed. These are the only functions that need to be
- * overloaded by a derived class. In additional to that, it has a
- * function for each output format supported by the underlying base
- * class which gets the output data using these two virtual functions
- * and passes them to the raw output functions.
+ * This class is thought as a base class to classes actually generating data
+ * for output. It has two abstract virtual functions, get_patches() and
+ * get_dataset_names() produce the data which is actually needed. These are
+ * the only functions that need to be overloaded by a derived class. In
+ * additional to that, it has a function for each output format supported by
+ * the underlying base class which gets the output data using these two
+ * virtual functions and passes them to the raw output functions.
*
- * The purpose of this class is mainly two-fold: to support storing flags
- * by which the output in the different output formats are controlled,
- * and means to work with output in a way where output format, flags and
- * other things are determined at run time. In addition to that it offers
- * the abstract interface to derived classes briefly discussed above.
+ * The purpose of this class is mainly two-fold: to support storing flags by
+ * which the output in the different output formats are controlled, and means
+ * to work with output in a way where output format, flags and other things
+ * are determined at run time. In addition to that it offers the abstract
+ * interface to derived classes briefly discussed above.
*
*
* <h3>Output flags</h3>
*
- * The way we treat flags in this class is very similar to that used in
- * the <tt>GridOut</tt> class. For detailed information on the why's and how's,
- * as well as an example of programming, we refer to the documentation
- * of that class.
+ * The way we treat flags in this class is very similar to that used in the
+ * <tt>GridOut</tt> class. For detailed information on the why's and how's, as
+ * well as an example of programming, we refer to the documentation of that
+ * class.
*
* Basically, this class stores a set of flags for each output format
* supported by the underlying <tt>DataOutBase</tt> class. These are used
* whenever one of the <tt>write_*</tt> functions is used. By default, the
- * values of these flags are set to reasonable start-ups, but in case
- * you want to change them, you can create a structure holding the flags
- * for one of the output formats and set it using the <tt>set_flags</tt> functions
- * of this class to determine all future output the object might produce
- * by that output format.
+ * values of these flags are set to reasonable start-ups, but in case you want
+ * to change them, you can create a structure holding the flags for one of the
+ * output formats and set it using the <tt>set_flags</tt> functions of this
+ * class to determine all future output the object might produce by that
+ * output format.
*
* For information on what parameters are supported by different output
- * functions, please see the documentation of the <tt>DataOutBase</tt> class and
- * its member classes.
+ * functions, please see the documentation of the <tt>DataOutBase</tt> class
+ * and its member classes.
*
*
* <h3>Run time selection of output parameters</h3>
*
- * In the output flags classes, described above, many flags are
- * defined for output in the different formats. In order to make them
- * available to the input file handler class <tt>ParameterHandler</tt>, each
- * of these has a function declaring these flags to the parameter
- * handler and to read them back from an actual input file. In order
- * to avoid that in user programs these functions have to be called
- * for each available output format and the respective flag class, the
- * present <tt>DataOutInterface</tt> class offers a function
- * <tt>declare_parameters</tt> which calls the respective function of all
- * known output format flags classes. The flags of each such format
- * are packed together in a subsection in the input file.
- * Likewise, there is a function <tt>parse_parameters</tt> which reads
- * these parameters and stores them in the flags associated with
- * this object (see above).
+ * In the output flags classes, described above, many flags are defined for
+ * output in the different formats. In order to make them available to the
+ * input file handler class <tt>ParameterHandler</tt>, each of these has a
+ * function declaring these flags to the parameter handler and to read them
+ * back from an actual input file. In order to avoid that in user programs
+ * these functions have to be called for each available output format and the
+ * respective flag class, the present <tt>DataOutInterface</tt> class offers a
+ * function <tt>declare_parameters</tt> which calls the respective function of
+ * all known output format flags classes. The flags of each such format are
+ * packed together in a subsection in the input file. Likewise, there is a
+ * function <tt>parse_parameters</tt> which reads these parameters and stores
+ * them in the flags associated with this object (see above).
*
- * Using these functions, you do not have to track which formats are
- * presently implemented.
+ * Using these functions, you do not have to track which formats are presently
+ * implemented.
*
* Usage is as follows:
* @code
* prm.leave_subsection ();
* ...
* @endcode
- * Note that in the present example, the class <tt>DataOut</tt> was used. However, any
- * other class derived from <tt>DataOutInterface</tt> would work alike.
+ * Note that in the present example, the class <tt>DataOut</tt> was used.
+ * However, any other class derived from <tt>DataOutInterface</tt> would work
+ * alike.
*
*
* <h3>Run time selection of formats</h3>
* one of the actual <tt>write_*</tt> functions depending on the output format
* selected by this value.
*
- * The functions offering the different output format names are,
- * respectively, <tt>default_suffix</tt>, <tt>parse_output_format</tt>, and
+ * The functions offering the different output format names are, respectively,
+ * <tt>default_suffix</tt>, <tt>parse_output_format</tt>, and
* <tt>get_output_format_names</tt>. They make the selection of ouput formats
- * in parameter files much easier, and especially independent of
- * the formats presently implemented. User programs need therefore not
- * be changed whenever a new format is implemented.
+ * in parameter files much easier, and especially independent of the formats
+ * presently implemented. User programs need therefore not be changed whenever
+ * a new format is implemented.
*
- * Additionally, objects of this class have a default format, which
- * can be set by the parameter "Output format" of the parameter
- * file. Within a program, this can be changed by the member function
- * <tt>set_default_format</tt>. Using this default format, it is possible to leave
- * the format selection completely to the parameter file. A suitable
- * suffix for the output file name can be obtained by <tt>default_suffix</tt>
- * without arguments.
+ * Additionally, objects of this class have a default format, which can be set
+ * by the parameter "Output format" of the parameter file. Within a program,
+ * this can be changed by the member function <tt>set_default_format</tt>.
+ * Using this default format, it is possible to leave the format selection
+ * completely to the parameter file. A suitable suffix for the output file
+ * name can be obtained by <tt>default_suffix</tt> without arguments.
*
* @ingroup output
* @author Wolfgang Bangerth, 1999
DataOutInterface ();
/**
- * Destructor. Does nothing, but is
- * declared virtual since this class has
+ * Destructor. Does nothing, but is declared virtual since this class has
* virtual functions.
*/
virtual ~DataOutInterface ();
/**
- * Obtain data through get_patches()
- * and write it to <tt>out</tt>
- * in OpenDX format. See
- * DataOutBase::write_dx.
+ * Obtain data through get_patches() and write it to <tt>out</tt> in OpenDX
+ * format. See DataOutBase::write_dx.
*/
void write_dx (std::ostream &out) const;
/**
- * Obtain data through get_patches()
- * and write it to <tt>out</tt>
- * in EPS format. See
- * DataOutBase::write_eps.
+ * Obtain data through get_patches() and write it to <tt>out</tt> in EPS
+ * format. See DataOutBase::write_eps.
*/
void write_eps (std::ostream &out) const;
/**
- * Obtain data through get_patches()
- * and write it to <tt>out</tt>
- * in GMV format. See
- * DataOutBase::write_gmv.
+ * Obtain data through get_patches() and write it to <tt>out</tt> in GMV
+ * format. See DataOutBase::write_gmv.
*/
void write_gmv (std::ostream &out) const;
/**
- * Obtain data through get_patches()
- * and write it to <tt>out</tt>
- * in GNUPLOT format. See
- * DataOutBase::write_gnuplot.
+ * Obtain data through get_patches() and write it to <tt>out</tt> in GNUPLOT
+ * format. See DataOutBase::write_gnuplot.
*/
void write_gnuplot (std::ostream &out) const;
/**
- * Obtain data through get_patches()
- * and write it to <tt>out</tt>
- * in POVRAY format. See
- * DataOutBase::write_povray.
+ * Obtain data through get_patches() and write it to <tt>out</tt> in POVRAY
+ * format. See DataOutBase::write_povray.
*/
void write_povray (std::ostream &out) const;
/**
- * Obtain data through get_patches()
- * and write it to <tt>out</tt>
- * in Tecplot format. See
- * DataOutBase::write_tecplot.
+ * Obtain data through get_patches() and write it to <tt>out</tt> in Tecplot
+ * format. See DataOutBase::write_tecplot.
*/
void write_tecplot (std::ostream &out) const;
/**
- * Obtain data through
- * get_patches() and write it in
- * the Tecplot binary output
- * format. Note that the name of
- * the output file must be
- * specified through the
- * TecplotFlags interface.
+ * Obtain data through get_patches() and write it in the Tecplot binary
+ * output format. Note that the name of the output file must be specified
+ * through the TecplotFlags interface.
*/
void write_tecplot_binary (std::ostream &out) const;
/**
- * Obtain data through
- * get_patches() and write it to
- * <tt>out</tt> in UCD format for
- * AVS. See
- * DataOutBase::write_ucd.
+ * Obtain data through get_patches() and write it to <tt>out</tt> in UCD
+ * format for AVS. See DataOutBase::write_ucd.
*/
void write_ucd (std::ostream &out) const;
/**
- * Obtain data through get_patches()
- * and write it to <tt>out</tt>
- * in Vtk format. See
- * DataOutBase::write_vtk.
+ * Obtain data through get_patches() and write it to <tt>out</tt> in Vtk
+ * format. See DataOutBase::write_vtk.
*
* @note VTK is a legacy format and has largely been supplanted by the VTU
* format (an XML-structured version of VTK). In particular, VTU allows for
- * the compression of data and consequently leads to much smaller file
- * sizes that equivalent VTK files for large files. Since all visualization
+ * the compression of data and consequently leads to much smaller file sizes
+ * that equivalent VTK files for large files. Since all visualization
* programs that support VTK also support VTU, you should consider using the
* latter file format instead, by using the write_vtu() function.
*/
void write_vtk (std::ostream &out) const;
/**
- * Obtain data through get_patches()
- * and write it to <tt>out</tt>
- * in Vtu (VTK's XML) format. See
- * DataOutBase::write_vtu.
- *
- * Some visualization programs,
- * such as ParaView, can read
- * several separate VTU files to
- * parallelize visualization. In
- * that case, you need a
- * <code>.pvtu</code> file that
- * describes which VTU files form
- * a group. The
- * DataOutInterface::write_pvtu_record()
- * function can generate such a
- * master record. Likewise,
- * DataOutInterface::write_visit_record()
- * does the same for older versions of VisIt
- * (although VisIt can also read <code>pvtu</code> records since version 2.5.1).
- * Finally, DataOutInterface::write_pvd_record()
- * can be used to group together
- * the files that jointly make up
- * a time dependent simulation.
+ * Obtain data through get_patches() and write it to <tt>out</tt> in Vtu
+ * (VTK's XML) format. See DataOutBase::write_vtu.
+ *
+ * Some visualization programs, such as ParaView, can read several separate
+ * VTU files to parallelize visualization. In that case, you need a
+ * <code>.pvtu</code> file that describes which VTU files form a group. The
+ * DataOutInterface::write_pvtu_record() function can generate such a master
+ * record. Likewise, DataOutInterface::write_visit_record() does the same
+ * for older versions of VisIt (although VisIt can also read
+ * <code>pvtu</code> records since version 2.5.1). Finally,
+ * DataOutInterface::write_pvd_record() can be used to group together the
+ * files that jointly make up a time dependent simulation.
*/
void write_vtu (std::ostream &out) const;
/**
- * Collective MPI call to write the
- * solution from all participating nodes
- * (those in the given communicator) to a
- * single compressed .vtu file on a
- * shared file system. The communicator
- * can be a sub communicator of the one
- * used by the computation. This routine
- * uses MPI I/O to achieve high
- * performance on parallel filesystems.
- * Also see
+ * Collective MPI call to write the solution from all participating nodes
+ * (those in the given communicator) to a single compressed .vtu file on a
+ * shared file system. The communicator can be a sub communicator of the
+ * one used by the computation. This routine uses MPI I/O to achieve high
+ * performance on parallel filesystems. Also see
* DataOutInterface::write_vtu().
*/
void write_vtu_in_parallel (const char *filename, MPI_Comm comm) const;
/**
- * Some visualization programs, such as
- * ParaView, can read several separate
- * VTU files to parallelize
- * visualization. In that case, you need
- * a <code>.pvtu</code> file that
- * describes which VTU files (written,
- * for example, through the write_vtu()
- * function) form a group. The current
- * function can generate such a master
- * record.
- *
- * The file so written contains a list of
- * (scalar or vector) fields whose values
- * are described by the individual files
- * that comprise the set of parallel VTU
- * files along with the names of these
- * files. This function gets the names
- * and types of fields through the
- * get_patches() function of this class
- * like all the other write_xxx()
- * functions. The second argument to this
- * function specifies the names of the
- * files that form the parallel set.
- *
- * @note See DataOutBase::write_vtu for
- * writing each piece. Also note that
- * only one parallel process needs to
- * call the current function, listing the
- * names of the files written by all
- * parallel processes.
- *
- * @note The use of this function is
- * explained in step-40.
- *
- * @note In order to tell Paraview to
- * group together multiple <code>pvtu</code>
- * files that each describe one time
- * step of a time dependent simulation,
- * see the
- * DataOutInterface::write_pvd_record()
- * function.
+ * Some visualization programs, such as ParaView, can read several separate
+ * VTU files to parallelize visualization. In that case, you need a
+ * <code>.pvtu</code> file that describes which VTU files (written, for
+ * example, through the write_vtu() function) form a group. The current
+ * function can generate such a master record.
+ *
+ * The file so written contains a list of (scalar or vector) fields whose
+ * values are described by the individual files that comprise the set of
+ * parallel VTU files along with the names of these files. This function
+ * gets the names and types of fields through the get_patches() function of
+ * this class like all the other write_xxx() functions. The second argument
+ * to this function specifies the names of the files that form the parallel
+ * set.
+ *
+ * @note See DataOutBase::write_vtu for writing each piece. Also note that
+ * only one parallel process needs to call the current function, listing the
+ * names of the files written by all parallel processes.
*
- * @note Older versions of VisIt (before 2.5.1),
- * can not read <code>pvtu</code>
- * records. However, it can read
- * visit records as written by
- * the write_visit_record()
+ * @note The use of this function is explained in step-40.
+ *
+ * @note In order to tell Paraview to group together multiple
+ * <code>pvtu</code> files that each describe one time step of a time
+ * dependent simulation, see the DataOutInterface::write_pvd_record()
* function.
+ *
+ * @note Older versions of VisIt (before 2.5.1), can not read
+ * <code>pvtu</code> records. However, it can read visit records as written
+ * by the write_visit_record() function.
*/
void write_pvtu_record (std::ostream &out,
const std::vector<std::string> &piece_names) const;
/**
- * In ParaView it is possible to visualize time-dependent
- * data tagged with the current
- * integration time of a time dependent simulation. To use this
- * feature you need a <code>.pvd</code>
- * file that describes which VTU or PVTU file
- * belongs to which timestep. This function writes a file that
- * provides this mapping, i.e., it takes a list of pairs each of
- * which indicates a particular time instant and the corresponding
- * file that contains the graphical data for this time instant.
- *
- * A typical use case, in program that computes a time dependent
- * solution, would be the following (<code>time</code> and
- * <code>time_step</code> are member variables of the class with types
- * <code>double</code> and <code>unsigned int</code>, respectively;
- * the variable <code>times_and_names</code> is of type
+ * In ParaView it is possible to visualize time-dependent data tagged with
+ * the current integration time of a time dependent simulation. To use this
+ * feature you need a <code>.pvd</code> file that describes which VTU or
+ * PVTU file belongs to which timestep. This function writes a file that
+ * provides this mapping, i.e., it takes a list of pairs each of which
+ * indicates a particular time instant and the corresponding file that
+ * contains the graphical data for this time instant.
+ *
+ * A typical use case, in program that computes a time dependent solution,
+ * would be the following (<code>time</code> and <code>time_step</code> are
+ * member variables of the class with types <code>double</code> and
+ * <code>unsigned int</code>, respectively; the variable
+ * <code>times_and_names</code> is of type
* <code>std::vector@<std::pair@<double,std::string@> @></code>):
*
* @code
* }
* @endcode
*
- * @note See DataOutBase::write_vtu or
- * DataOutInterface::write_pvtu_record for writing solutions at each
- * timestep.
+ * @note See DataOutBase::write_vtu or DataOutInterface::write_pvtu_record
+ * for writing solutions at each timestep.
*
- * @note The second element of each pair, i.e., the file in which
- * the graphical data for each time is stored, may itself be again
- * a file that references other files. For example, it could be
- * the name for a <code>.pvtu</code> file that references multiple
- * parts of a parallel computation.
+ * @note The second element of each pair, i.e., the file in which the
+ * graphical data for each time is stored, may itself be again a file that
+ * references other files. For example, it could be the name for a
+ * <code>.pvtu</code> file that references multiple parts of a parallel
+ * computation.
*
* @author Marco Engelhard, 2012
*/
const std::vector<std::pair<double,std::string> > ×_and_names) const;
/**
- * This function is the exact equivalent of the write_pvtu_record()
- * function but for older versions of the VisIt visualization program and for one visualization graph
- * (or one time step only). See there for the purpose of this function.
+ * This function is the exact equivalent of the write_pvtu_record() function
+ * but for older versions of the VisIt visualization program and for one
+ * visualization graph (or one time step only). See there for the purpose of
+ * this function.
*
- * This function is documented in the "Creating a master file for
- * parallel" section (section 5.7) of the "Getting data into VisIt"
- * report that can be found here:
+ * This function is documented in the "Creating a master file for parallel"
+ * section (section 5.7) of the "Getting data into VisIt" report that can be
+ * found here:
* https://wci.llnl.gov/codes/visit/2.0.0/GettingDataIntoVisIt2.0.0.pdf
*/
void write_visit_record (std::ostream &out,
const std::vector<std::string> &piece_names) const;
/**
- * This function is equivalent to the write_visit_record() above but for multiple
- * time steps. Here is an example of how the function would be used:
+ * This function is equivalent to the write_visit_record() above but for
+ * multiple time steps. Here is an example of how the function would be
+ * used:
* @code
* DataOut<dim> data_out;
*
* data_out.write_visit_record(visit_output, piece_names);
* @endcode
*
- * This function is documented in the "Creating a master file for
- * parallel" section (section 5.7) of the "Getting data into VisIt"
- * report that can be found here:
+ * This function is documented in the "Creating a master file for parallel"
+ * section (section 5.7) of the "Getting data into VisIt" report that can be
+ * found here:
* https://wci.llnl.gov/codes/visit/2.0.0/GettingDataIntoVisIt2.0.0.pdf
*/
void write_visit_record (std::ostream &out,
const std::vector<std::vector<std::string> > &piece_names) const;
/**
- * Obtain data through get_patches() and write it to <tt>out</tt> in
- * SVG format. See DataOutBase::write_svg.
+ * Obtain data through get_patches() and write it to <tt>out</tt> in SVG
+ * format. See DataOutBase::write_svg.
*/
void write_svg(std::ostream &out) const;
/**
- * Obtain data through get_patches() and write it to <tt>out</tt> in
- * deal.II intermediate format. See
- * DataOutBase::write_deal_II_intermediate.
+ * Obtain data through get_patches() and write it to <tt>out</tt> in deal.II
+ * intermediate format. See DataOutBase::write_deal_II_intermediate.
*
- * Note that the intermediate format is what its name suggests: a
- * direct representation of internal data. It isn't standardized and
- * will change whenever we change our internal representation. You
- * can only expect to process files written in this format using the
- * same version of deal.II that was used for writing.
+ * Note that the intermediate format is what its name suggests: a direct
+ * representation of internal data. It isn't standardized and will change
+ * whenever we change our internal representation. You can only expect to
+ * process files written in this format using the same version of deal.II
+ * that was used for writing.
*/
void write_deal_II_intermediate (std::ostream &out) const;
/**
* Create an XDMFEntry based on the data in this DataOutInterface.
- @deprecated: use create_xdmf_entry(DataOutFilter, ...) instead
+ * @deprecated: use create_xdmf_entry(DataOutFilter, ...) instead
*/
XDMFEntry create_xdmf_entry (const std::string &h5_filename,
const double cur_time,
MPI_Comm comm) const;
/**
- * Write an XDMF file based on the provided vector of XDMFEntry objects. Below is
- * an example of how to use this function with HDF5 and the DataOutFilter:
+ * Write an XDMF file based on the provided vector of XDMFEntry objects.
+ * Below is an example of how to use this function with HDF5 and the
+ * DataOutFilter:
*
* @code
* DataOutBase::DataOutFilter data_filter(DataOutBase::DataOutFilterFlags(true, true));
MPI_Comm comm) const;
/**
- * Write the data in this class without redundancy filtering to a
- * single HDF5 file containing both the mesh and solution values.
- @deprecated: use write_hdf5_parallel(DataOutFilter, ...) instead
+ * Write the data in this class without redundancy filtering to a single
+ * HDF5 file containing both the mesh and solution values.
+ * @deprecated: use write_hdf5_parallel(DataOutFilter, ...) instead
*/
void write_hdf5_parallel (const std::string &filename,
MPI_Comm comm) const DEAL_II_DEPRECATED;
/**
- * Write the data in data_filter to a single HDF5 file containing both
- * the mesh and solution values. Below is an example of how to use this
- * function with the DataOutFilter:
+ * Write the data in data_filter to a single HDF5 file containing both the
+ * mesh and solution values. Below is an example of how to use this function
+ * with the DataOutFilter:
*
* @code
* DataOutBase::DataOutFilter data_filter(DataOutBase::DataOutFilterFlags(true, true));
const std::string &filename, MPI_Comm comm) const;
/**
- * Write the data in data_filter to HDF5 file(s). If write_mesh_file
- * is false, the mesh data will not be written and the solution
- * file will contain only the solution values. If write_mesh_file
- * is true and the filenames are the same, the resulting file will
- * contain both mesh data and solution values.
+ * Write the data in data_filter to HDF5 file(s). If write_mesh_file is
+ * false, the mesh data will not be written and the solution file will
+ * contain only the solution values. If write_mesh_file is true and the
+ * filenames are the same, the resulting file will contain both mesh data
+ * and solution values.
*/
void write_hdf5_parallel (const DataOutBase::DataOutFilter &data_filter,
const bool write_mesh_file, const std::string &mesh_filename, const std::string &solution_filename, MPI_Comm comm) const;
/**
- * Write data and grid to <tt>out</tt>
- * according to the given data
- * format. This function simply
- * calls the appropriate
- * <tt>write_*</tt> function. If no
- * output format is requested,
- * the <tt>default_format</tt> is
- * written.
+ * Write data and grid to <tt>out</tt> according to the given data format.
+ * This function simply calls the appropriate <tt>write_*</tt> function. If
+ * no output format is requested, the <tt>default_format</tt> is written.
*
- * An error occurs if no format
- * is provided and the default
- * format is <tt>default_format</tt>.
+ * An error occurs if no format is provided and the default format is
+ * <tt>default_format</tt>.
*/
void write (std::ostream &out,
const DataOutBase::OutputFormat output_format = DataOutBase::default_format) const;
/**
- * Set the default format. The value set here is used anytime,
- * output for format <tt>default_format</tt> is requested.
+ * Set the default format. The value set here is used anytime, output for
+ * format <tt>default_format</tt> is requested.
*/
void set_default_format (const DataOutBase::OutputFormat default_format);
void set_flags (const DataOutBase::SvgFlags &svg_flags);
/**
- * Set the flags to be used for output in deal.II intermediate
- * format.
+ * Set the flags to be used for output in deal.II intermediate format.
*/
void set_flags (const DataOutBase::Deal_II_IntermediateFlags &deal_II_intermediate_flags);
/**
- * A function that returns the same string as the respective
- * function in the base class does; the only exception being that if
- * the parameter is omitted, then the value for the present default
- * format is returned, i.e. the correct suffix for the format that
- * was set through set_default_format() or parse_parameters() before
- * calling this function.
+ * A function that returns the same string as the respective function in the
+ * base class does; the only exception being that if the parameter is
+ * omitted, then the value for the present default format is returned, i.e.
+ * the correct suffix for the format that was set through
+ * set_default_format() or parse_parameters() before calling this function.
*/
std::string
default_suffix (const DataOutBase::OutputFormat output_format = DataOutBase::default_format) const;
/**
- * Declare parameters for all output formats by declaring
- * subsections within the parameter file for each output format and
- * call the respective <tt>declare_parameters</tt> functions of the
- * flag classes for each output format.
+ * Declare parameters for all output formats by declaring subsections within
+ * the parameter file for each output format and call the respective
+ * <tt>declare_parameters</tt> functions of the flag classes for each output
+ * format.
*
* Some of the declared subsections may not contain entries, if the
* respective format does not export any flags.
*
- * Note that the top-level parameters denoting the number of
- * subdivisions per patch and the output format are not declared,
- * since they are only passed to virtual functions and are not
- * stored inside objects of this type. You have to declare them
- * yourself.
+ * Note that the top-level parameters denoting the number of subdivisions
+ * per patch and the output format are not declared, since they are only
+ * passed to virtual functions and are not stored inside objects of this
+ * type. You have to declare them yourself.
*/
static void declare_parameters (ParameterHandler &prm);
/**
- * Read the parameters declared in declare_parameters() and
- * set the flags for the output formats accordingly.
+ * Read the parameters declared in declare_parameters() and set the flags
+ * for the output formats accordingly.
*
- * The flags thus obtained overwrite all previous contents of the
- * flag objects as default-constructed or set by the set_flags()
- * function.
+ * The flags thus obtained overwrite all previous contents of the flag
+ * objects as default-constructed or set by the set_flags() function.
*/
void parse_parameters (ParameterHandler &prm);
/**
- * Determine an estimate for the memory consumption (in bytes) of
- * this object. Since sometimes the size of objects can not be
- * determined exactly (for example: what is the memory consumption
- * of an STL <tt>std::map</tt> type with a certain number of
- * elements?), this is only an estimate. however often quite close
- * to the true value.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object. Since sometimes the size of objects can not be determined exactly
+ * (for example: what is the memory consumption of an STL <tt>std::map</tt>
+ * type with a certain number of elements?), this is only an estimate.
+ * however often quite close to the true value.
*/
std::size_t memory_consumption () const;
protected:
/**
- * This is the abstract function through which derived classes
- * propagate preprocessed data in the form of Patch structures
- * (declared in the base class DataOutBase) to the actual output
- * function. You need to overload this function to allow the output
- * functions to know what they shall print.
+ * This is the abstract function through which derived classes propagate
+ * preprocessed data in the form of Patch structures (declared in the base
+ * class DataOutBase) to the actual output function. You need to overload
+ * this function to allow the output functions to know what they shall
+ * print.
*/
virtual
const std::vector<DataOutBase::Patch<dim,spacedim> > &
get_patches () const = 0;
/**
- * Abstract virtual function through which the names of data sets
- * are obtained by the output functions of the base class.
+ * Abstract virtual function through which the names of data sets are
+ * obtained by the output functions of the base class.
*/
virtual
std::vector<std::string>
get_dataset_names () const = 0;
/**
- * This functions returns information about how the individual
- * components of output files that consist of more than one data set
- * are to be interpreted.
+ * This functions returns information about how the individual components of
+ * output files that consist of more than one data set are to be
+ * interpreted.
*
- * It returns a list of index pairs and corresponding name
- * indicating which components of the output are to be considered
- * vector-valued rather than just a collection of scalar data. The
- * index pairs are inclusive; for example, if we have a Stokes
- * problem in 2d with components (u,v,p), then the corresponding
- * vector data range should be (0,1), and the returned list would
- * consist of only a single element with a tuple such as
+ * It returns a list of index pairs and corresponding name indicating which
+ * components of the output are to be considered vector-valued rather than
+ * just a collection of scalar data. The index pairs are inclusive; for
+ * example, if we have a Stokes problem in 2d with components (u,v,p), then
+ * the corresponding vector data range should be (0,1), and the returned
+ * list would consist of only a single element with a tuple such as
* (0,1,"velocity").
*
- * Since some of the derived classes do not know about vector data,
- * this function has a default implementation that simply returns an
- * empty string, meaning that all data is to be considered a
- * collection of scalar fields.
+ * Since some of the derived classes do not know about vector data, this
+ * function has a default implementation that simply returns an empty
+ * string, meaning that all data is to be considered a collection of scalar
+ * fields.
*/
virtual
std::vector<std_cxx11::tuple<unsigned int, unsigned int, std::string> >
/**
* The default number of subdivisions for patches. This is filled by
- * parse_parameters() and should be obeyed by build_patches() in
- * derived classes.
+ * parse_parameters() and should be obeyed by build_patches() in derived
+ * classes.
*/
unsigned int default_subdivisions;
private:
/**
- * Standard output format. Use this format, if output format
- * default_format is requested. It can be changed by the
- * <tt>set_format</tt> function or in a parameter file.
+ * Standard output format. Use this format, if output format default_format
+ * is requested. It can be changed by the <tt>set_format</tt> function or in
+ * a parameter file.
*/
DataOutBase::OutputFormat default_fmt;
/**
- * Flags to be used upon output of OpenDX data. Can be changed by
- * using the <tt>set_flags</tt> function.
+ * Flags to be used upon output of OpenDX data. Can be changed by using the
+ * <tt>set_flags</tt> function.
*/
DataOutBase::DXFlags dx_flags;
/**
- * Flags to be used upon output of UCD data. Can be changed by using
- * the <tt>set_flags</tt> function.
+ * Flags to be used upon output of UCD data. Can be changed by using the
+ * <tt>set_flags</tt> function.
*/
DataOutBase::UcdFlags ucd_flags;
/**
- * Flags to be used upon output of GNUPLOT data. Can be changed by
- * using the <tt>set_flags</tt> function.
+ * Flags to be used upon output of GNUPLOT data. Can be changed by using the
+ * <tt>set_flags</tt> function.
*/
DataOutBase::GnuplotFlags gnuplot_flags;
/**
- * Flags to be used upon output of POVRAY data. Can be changed by
- * using the <tt>set_flags</tt> function.
+ * Flags to be used upon output of POVRAY data. Can be changed by using the
+ * <tt>set_flags</tt> function.
*/
DataOutBase::PovrayFlags povray_flags;
/**
- * Flags to be used upon output of EPS data in one space
- * dimension. Can be changed by using the <tt>set_flags</tt>
- * function.
+ * Flags to be used upon output of EPS data in one space dimension. Can be
+ * changed by using the <tt>set_flags</tt> function.
*/
DataOutBase::EpsFlags eps_flags;
/**
- * Flags to be used upon output of gmv data in one space
- * dimension. Can be changed by using the <tt>set_flags</tt>
- * function.
+ * Flags to be used upon output of gmv data in one space dimension. Can be
+ * changed by using the <tt>set_flags</tt> function.
*/
DataOutBase::GmvFlags gmv_flags;
/**
- * Flags to be used upon output of Tecplot data in one space
- * dimension. Can be changed by using the <tt>set_flags</tt>
- * function.
+ * Flags to be used upon output of Tecplot data in one space dimension. Can
+ * be changed by using the <tt>set_flags</tt> function.
*/
DataOutBase::TecplotFlags tecplot_flags;
/**
- * Flags to be used upon output of vtk data in one space
- * dimension. Can be changed by using the <tt>set_flags</tt>
- * function.
+ * Flags to be used upon output of vtk data in one space dimension. Can be
+ * changed by using the <tt>set_flags</tt> function.
*/
DataOutBase::VtkFlags vtk_flags;
/**
- * Flags to be used upon output of svg data in one space
- * dimension. Can be changed by using the <tt>set_flags</tt>
- * function.
+ * Flags to be used upon output of svg data in one space dimension. Can be
+ * changed by using the <tt>set_flags</tt> function.
*/
DataOutBase::SvgFlags svg_flags;
/**
- * Flags to be used upon output of deal.II intermediate data in one
- * space dimension. Can be changed by using the <tt>set_flags</tt>
- * function.
+ * Flags to be used upon output of deal.II intermediate data in one space
+ * dimension. Can be changed by using the <tt>set_flags</tt> function.
*/
DataOutBase::Deal_II_IntermediateFlags deal_II_intermediate_flags;
};
/**
- * A class that is used to read data written in deal.II intermediate
- * format back in, so that it can be written out in any of the other
- * supported graphics formats. This class has two main purposes:
+ * A class that is used to read data written in deal.II intermediate format
+ * back in, so that it can be written out in any of the other supported
+ * graphics formats. This class has two main purposes:
*
- * The first use of this class is so that application programs can
- * defer the decision of which graphics format to use until after the
- * program has been run. The data is written in intermediate format
- * into a file, and later on it can then be converted into any
- * graphics format you wish. This may be useful, for example, if you
- * want to convert it to gnuplot format to get a quick glimpse and
- * later on want to convert it to OpenDX format as well to get a high
- * quality version of the data. The present class allows to read this
- * intermediate format back into the program, and allows it to be
- * written in any other supported format using the relevant functions
- * of the base class.
+ * The first use of this class is so that application programs can defer the
+ * decision of which graphics format to use until after the program has been
+ * run. The data is written in intermediate format into a file, and later on
+ * it can then be converted into any graphics format you wish. This may be
+ * useful, for example, if you want to convert it to gnuplot format to get a
+ * quick glimpse and later on want to convert it to OpenDX format as well to
+ * get a high quality version of the data. The present class allows to read
+ * this intermediate format back into the program, and allows it to be written
+ * in any other supported format using the relevant functions of the base
+ * class.
*
- * The second use is mostly useful in parallel programs: rather than
- * having one central process generate the graphical output for the
- * entire program, one can let each process generate the graphical
- * data for the cells it owns, and write it into a separate file in
- * intermediate format. Later on, all these intermediate files can
- * then be read back in and merged together, a process that is fast
- * compared to generating the data in the first place. The use of the
- * intermediate format is mostly because it allows separate files to
- * be merged, while this is almost impossible once the data has been
+ * The second use is mostly useful in parallel programs: rather than having
+ * one central process generate the graphical output for the entire program,
+ * one can let each process generate the graphical data for the cells it owns,
+ * and write it into a separate file in intermediate format. Later on, all
+ * these intermediate files can then be read back in and merged together, a
+ * process that is fast compared to generating the data in the first place.
+ * The use of the intermediate format is mostly because it allows separate
+ * files to be merged, while this is almost impossible once the data has been
* written out in any of the supported established graphics formats.
*
- * This second use scenario is explained in some detail in the step-18
- * example program.
+ * This second use scenario is explained in some detail in the step-18 example
+ * program.
*
* Both these applications are implemented in the step-19 example program.
* There, a slight complication is also explained: in order to read data back
* around using the DataOutBase::determine_intermediate_format_dimensions()
* function is explained in step-19.
*
- * Note that the intermediate format is what its name suggests: a
- * direct representation of internal data. It isn't standardized and
- * will change whenever we change our internal representation. You can
- * only expect to process files written in this format using the same
- * version of deal.II that was used for writing.
+ * Note that the intermediate format is what its name suggests: a direct
+ * representation of internal data. It isn't standardized and will change
+ * whenever we change our internal representation. You can only expect to
+ * process files written in this format using the same version of deal.II that
+ * was used for writing.
*
* @ingroup input output
* @author Wolfgang Bangerth, 2005
public:
/**
* Read a sequence of patches as written previously by
- * <tt>DataOutBase::write_deal_II_intermediate</tt> and store them
- * in the present object. This overwrites any previous content.
+ * <tt>DataOutBase::write_deal_II_intermediate</tt> and store them in the
+ * present object. This overwrites any previous content.
*/
void read (std::istream &in);
/**
- * This function can be used to merge the patches read by the other
- * object into the patches that this present object stores. This is
- * sometimes handy if one has, for example, a domain decomposition
- * algorithm where each block is represented by a DoFHandler of its
- * own, but one wants to output the solution on all the blocks at
- * the same time. Alternatively, it may also be used for parallel
- * programs, where each process only generates output for its share
- * of the cells, even if all processes can see all cells.
+ * This function can be used to merge the patches read by the other object
+ * into the patches that this present object stores. This is sometimes handy
+ * if one has, for example, a domain decomposition algorithm where each
+ * block is represented by a DoFHandler of its own, but one wants to output
+ * the solution on all the blocks at the same time. Alternatively, it may
+ * also be used for parallel programs, where each process only generates
+ * output for its share of the cells, even if all processes can see all
+ * cells.
*
- * For this to work, the input files for the present object and the
- * given argument need to have the same number of output vectors,
- * and they need to use the same number of subdivisions per
- * patch. The output will probably look rather funny if patches in
- * both objects overlap in space.
+ * For this to work, the input files for the present object and the given
+ * argument need to have the same number of output vectors, and they need to
+ * use the same number of subdivisions per patch. The output will probably
+ * look rather funny if patches in both objects overlap in space.
*
- * If you call read() for this object after merging in patches, the
- * previous state is overwritten, and the merged-in patches are
- * lost.
+ * If you call read() for this object after merging in patches, the previous
+ * state is overwritten, and the merged-in patches are lost.
*
- * This function will fail if either this or the other object did
- * not yet set up any patches.
+ * This function will fail if either this or the other object did not yet
+ * set up any patches.
*
* The use of this function is demonstrated in step-19.
*/
protected:
/**
- * This is the function through which this class propagates
- * preprocessed data in the form of Patch structures (declared in
- * the base class DataOutBase) to the actual output function.
+ * This is the function through which this class propagates preprocessed
+ * data in the form of Patch structures (declared in the base class
+ * DataOutBase) to the actual output function.
*
- * It returns the patches as read the last time a stream was given
- * to the read() function.
+ * It returns the patches as read the last time a stream was given to the
+ * read() function.
*/
virtual const std::vector<dealii::DataOutBase::Patch<dim,spacedim> > &
get_patches () const;
/**
- * Abstract virtual function through which the names of data sets
- * are obtained by the output functions of the base class.
+ * Abstract virtual function through which the names of data sets are
+ * obtained by the output functions of the base class.
*
- * Return the names of the variables as read the last time we read a
- * file.
+ * Return the names of the variables as read the last time we read a file.
*/
virtual std::vector<std::string> get_dataset_names () const;
/**
- * This functions returns information about how the individual
- * components of output files that consist of more than one data set
- * are to be interpreted.
+ * This functions returns information about how the individual components of
+ * output files that consist of more than one data set are to be
+ * interpreted.
*
- * It returns a list of index pairs and corresponding name
- * indicating which components of the output are to be considered
- * vector-valued rather than just a collection of scalar data. The
- * index pairs are inclusive; for example, if we have a Stokes
- * problem in 2d with components (u,v,p), then the corresponding
- * vector data range should be (0,1), and the returned list would
- * consist of only a single element with a tuple such as
+ * It returns a list of index pairs and corresponding name indicating which
+ * components of the output are to be considered vector-valued rather than
+ * just a collection of scalar data. The index pairs are inclusive; for
+ * example, if we have a Stokes problem in 2d with components (u,v,p), then
+ * the corresponding vector data range should be (0,1), and the returned
+ * list would consist of only a single element with a tuple such as
* (0,1,"velocity").
*
- * Since some of the derived classes do not know about vector data,
- * this function has a default implementation that simply returns an
- * empty string, meaning that all data is to be considered a
- * collection of scalar fields.
+ * Since some of the derived classes do not know about vector data, this
+ * function has a default implementation that simply returns an empty
+ * string, meaning that all data is to be considered a collection of scalar
+ * fields.
*/
virtual
std::vector<std_cxx11::tuple<unsigned int, unsigned int, std::string> >
std::vector<std::string> dataset_names;
/**
- * Information about whether certain components of the output field
- * are to be considered vectors.
+ * Information about whether certain components of the output field are to
+ * be considered vectors.
*/
std::vector<std_cxx11::tuple<unsigned int, unsigned int, std::string> >
vector_data_ranges;
/**
- * A class to store relevant data to use when writing the light data
- * XDMF file. This should only contain valid data on the root node which
- * writes the files, the rest of the nodes will have valid set to false.
- * The XDMF file in turn points to heavy data files (such as HDF5) where
- * the actual simulation data is stored. This allows flexibility in
- * arranging the data, and also allows the mesh to be separated from
- * the the point data.
+ * A class to store relevant data to use when writing the light data XDMF
+ * file. This should only contain valid data on the root node which writes the
+ * files, the rest of the nodes will have valid set to false. The XDMF file in
+ * turn points to heavy data files (such as HDF5) where the actual simulation
+ * data is stored. This allows flexibility in arranging the data, and also
+ * allows the mesh to be separated from the the point data.
*/
class XDMFEntry
{
/* -------------------- template functions ------------------- */
/**
- * Output operator for an object of type
- * <tt>DataOutBase::Patch</tt>. This operator dumps the intermediate
- * graphics format represented by the patch data structure. It may
- * later be converted into regular formats for a number of graphics
- * programs.
+ * Output operator for an object of type <tt>DataOutBase::Patch</tt>. This
+ * operator dumps the intermediate graphics format represented by the patch
+ * data structure. It may later be converted into regular formats for a
+ * number of graphics programs.
*
* @author Wolfgang Bangerth, 2005
*/
/**
- * Input operator for an object of type
- * <tt>DataOutBase::Patch</tt>. This operator reads the intermediate
- * graphics format represented by the patch data structure, using the
- * format in which it was written using the operator<<.
+ * Input operator for an object of type <tt>DataOutBase::Patch</tt>. This
+ * operator reads the intermediate graphics format represented by the patch
+ * data structure, using the format in which it was written using the
+ * operator<<.
*
* @author Wolfgang Bangerth, 2005
*/
DEAL_II_NAMESPACE_OPEN
/**
- This class represents the (tangential) derivatives of a function
- $ f: {\mathbb R}^{\text{dim}} \rightarrow {\mathbb R}^{\text{spacedim}}$.
- Such functions are always used to map the reference dim-dimensional
- cell into spacedim-dimensional space.
- For such objects, the first derivative of the function is a linear map from
- ${\mathbb R}^{\text{dim}}$ to ${\mathbb R}^{\text{spacedim}}$,
- the second derivative a bilinear map
- from ${\mathbb R}^{\text{dim}} \times {\mathbb R}^{\text{dim}}$
- to ${\mathbb R}^{\text{spacedim}}$ and so on.
-
- In deal.II we represent these derivaties using objects of
- type DerivativeForm<1,dim,spacedim>, DerivativeForm<2,dim,spacedim> and so on.
-
- @author Sebastian Pauletti, 2011
-*/
+ * This class represents the (tangential) derivatives of a function $ f:
+ * {\mathbb R}^{\text{dim}} \rightarrow {\mathbb R}^{\text{spacedim}}$. Such
+ * functions are always used to map the reference dim-dimensional cell into
+ * spacedim-dimensional space. For such objects, the first derivative of the
+ * function is a linear map from ${\mathbb R}^{\text{dim}}$ to ${\mathbb
+ * R}^{\text{spacedim}}$, the second derivative a bilinear map from ${\mathbb
+ * R}^{\text{dim}} \times {\mathbb R}^{\text{dim}}$ to ${\mathbb
+ * R}^{\text{spacedim}}$ and so on. In deal.II we represent these derivaties
+ * using objects of type DerivativeForm<1,dim,spacedim>,
+ * DerivativeForm<2,dim,spacedim> and so on.
+ * @author Sebastian Pauletti, 2011
+ */
template <int order, int dim, int spacedim>
class DerivativeForm
{
public:
/**
- * Constructor. Initialize all entries
- * to zero.
+ * Constructor. Initialize all entries to zero.
*/
DerivativeForm ();
/**
- Constructor from a second order tensor.
- */
+ * Constructor from a second order tensor.
+ */
DerivativeForm (const Tensor<2,dim> &);
/**
const Tensor<order,dim> &operator [] (const unsigned int i) const;
/**
- * Assignment operator.
+ * Assignment operator.
*/
DerivativeForm &operator = (const DerivativeForm <order, dim, spacedim> &);
/**
- * Assignment operator.
+ * Assignment operator.
*/
DerivativeForm &operator = (const Tensor<2,dim> &);
/**
- * Assignment operator.
+ * Assignment operator.
*/
DerivativeForm &operator = (const Tensor<1,dim> &);
/**
- Converts a DerivativeForm <1,dim, dim>
- to Tensor<2,dim>.
- If the derivative is the Jacobian of F,
- then Tensor[i] = grad(F^i).
- */
+ * Converts a DerivativeForm <1,dim, dim> to Tensor<2,dim>. If the
+ * derivative is the Jacobian of F, then Tensor[i] = grad(F^i).
+ */
operator Tensor<2,dim>() const;
/**
- Converts a DerivativeForm <1, dim, 1>
- to Tensor<1,dim>.
- */
+ * Converts a DerivativeForm <1, dim, 1> to Tensor<1,dim>.
+ */
operator Tensor<1,dim>() const;
/**
- Return the transpose of a rectangular DerivativeForm,
- that is to say viewed as a two dimensional matrix.
- */
+ * Return the transpose of a rectangular DerivativeForm, that is to say
+ * viewed as a two dimensional matrix.
+ */
DerivativeForm<1, spacedim, dim> transpose () const;
/**
- Computes the volume element associated with the
- jacobian of the tranformation F.
- That is to say if $DF$ is square, it computes
- $\det(DF)$, in case DF is not square returns
- $\sqrt(\det(DF^{t} * DF))$.
- */
+ * Computes the volume element associated with the jacobian of the
+ * tranformation F. That is to say if $DF$ is square, it computes
+ * $\det(DF)$, in case DF is not square returns $\sqrt(\det(DF^{t} * DF))$.
+ */
double determinant () const;
/**
- Assuming (*this) stores the jacobian of
- the mapping F, it computes its covariant
- matrix, namely $DF*G^{-1}$, where
- $G = DF^{t}*DF$.
- If $DF$ is square, covariant from
- gives $DF^{-t}$.
- */
+ * Assuming (*this) stores the jacobian of the mapping F, it computes its
+ * covariant matrix, namely $DF*G^{-1}$, where $G = DF^{t}*DF$. If $DF$ is
+ * square, covariant from gives $DF^{-t}$.
+ */
DerivativeForm<1, dim, spacedim> covariant_form() const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
static std::size_t memory_consumption ();
private:
- /** Auxiliary function that computes
- (*this) * T^{t} */
+ /**
+ * Auxiliary function that computes (*this) * T^{t}
+ */
DerivativeForm<1, dim, spacedim> times_T_t (Tensor<2,dim> T) const;
private:
/**
- * Array of tensors holding the
- * subelements.
+ * Array of tensors holding the subelements.
*/
Tensor<order,dim> tensor[spacedim];
/**
- One of the uses of DerivativeForm is to apply it as a transformation.
- This is what this function does.
-
- If @p T is DerivativeForm<1,dim,1> it computes $DF * T$,
- if @p T is DerivativeForm<1,dim,rank> it computes $T*DF^{t}$.
-
- @relates DerivativeForm
- @author Sebastian Pauletti, 2011
-*/
+ * One of the uses of DerivativeForm is to apply it as a transformation. This
+ * is what this function does. If @p T is DerivativeForm<1,dim,1> it computes
+ * $DF * T$, if @p T is DerivativeForm<1,dim,rank> it computes $T*DF^{t}$.
+ * @relates DerivativeForm
+ * @author Sebastian Pauletti, 2011
+ */
template <int spacedim, int dim>
inline
Tensor<1, spacedim>
/**
- Similar to previous apply_transformation.
- It computes $T*DF^{t}$
- @relates DerivativeForm
- @author Sebastian Pauletti, 2011
-*/
+ * Similar to previous apply_transformation. It computes $T*DF^{t}$ @relates
+ * DerivativeForm
+ * @author Sebastian Pauletti, 2011
+ */
//rank=2
template <int spacedim, int dim>
inline
}
/**
- Similar to previous apply_transformation.
- It computes $DF2*DF1^{t}$
- @relates DerivativeForm
- @author Sebastian Pauletti, 2011
-*/
+ * Similar to previous apply_transformation. It computes $DF2*DF1^{t}$
+ * @relates DerivativeForm
+ * @author Sebastian Pauletti, 2011
+ */
template <int spacedim, int dim>
inline
Tensor<2, spacedim>
/**
- Transpose of a rectangular DerivativeForm DF,
- mostly for compatibility reasons.
- @relates DerivativeForm
- @author Sebastian Pauletti, 2011
-*/
+ * Transpose of a rectangular DerivativeForm DF, mostly for compatibility
+ * reasons. @relates DerivativeForm
+ * @author Sebastian Pauletti, 2011
+ */
template <int dim, int spacedim>
inline
DerivativeForm<1,spacedim,dim>
namespace Algorithms
{
/**
- * Objects of this kind are used to notify interior applications of
- * changes provoked by an outer loop. They are handed to the
- * application through Operator::notify() and it is up to the
- * actual application how to handle them.
+ * Objects of this kind are used to notify interior applications of changes
+ * provoked by an outer loop. They are handed to the application through
+ * Operator::notify() and it is up to the actual application how to handle
+ * them.
*
- * Event is organized as an extensible binary enumerator. Every class
- * can add its own events using assign(). A typical code example is
+ * Event is organized as an extensible binary enumerator. Every class can
+ * add its own events using assign(). A typical code example is
*
* @code
* class A
{
public:
/**
- * This function registers a
- * new event type and assigns a
- * unique identifier to it. The
- * result of this function
- * should be stored for later
- * use.
+ * This function registers a new event type and assigns a unique
+ * identifier to it. The result of this function should be stored for
+ * later use.
*/
static Event assign (const char *name);
/**
- * If you forgot to store the
- * result of assign, here is
- * how to retrieve it knowing
- * the name.
+ * If you forgot to store the result of assign, here is how to retrieve it
+ * knowing the name.
*/
// static Event find(const std::string& name);
/**
- * Constructor, generating a
- * clear Event.
+ * Constructor, generating a clear Event.
*/
Event ();
Event &operator -= (const Event &event);
/**
- * Test whether all the flags
- * set in the other Event are
- * also set in this one.
+ * Test whether all the flags set in the other Event are also set in this
+ * one.
*/
bool test (const Event &event) const;
/**
- * Return <tt>true</tt> if any
- * event is set.
+ * Return <tt>true</tt> if any event is set.
*/
bool any () const;
private:
/**
- * Sometimes, actions have to
- * be taken by all
- * means. Therefore, if this
- * value is true, test() always
- * returns true.
+ * Sometimes, actions have to be taken by all means. Therefore, if this
+ * value is true, test() always returns true.
*/
bool all_true;
namespace Events
{
/**
- * The program has just started
- * and everything should be
- * new.
+ * The program has just started and everything should be new.
*/
extern const Event initial;
extern const Event remesh;
/**
- * The current derivative leads
- * to slow convergence of
- * Newton's method.
+ * The current derivative leads to slow convergence of Newton's method.
*/
extern const Event bad_derivative;
/**
- * The time stepping scheme
- * starts a new time step.
+ * The time stepping scheme starts a new time step.
*/
extern const Event new_time;
/**
- * Output shift operator for
- * events. Calls Event::print().
+ * Output shift operator for events. Calls Event::print().
*
* @relates Event
*/
#define __deal2__exceptions_h
/**
- * @file
- * Here, the deal.II exception handling is located.
+ * @file Here, the deal.II exception handling is located.
*/
#include <deal.II/base/config.h>
/**
- * This class is the base class for all exception classes. Do not use
- * its methods and variables directly since the interface and
- * mechanism may be subject to change. Rather create new exception
- * classes using the <tt>DeclException</tt> macro family.
+ * This class is the base class for all exception classes. Do not use its
+ * methods and variables directly since the interface and mechanism may be
+ * subject to change. Rather create new exception classes using the
+ * <tt>DeclException</tt> macro family.
*
- * See the @ref Exceptions module for more details on this class and
- * what can be done with classes derived from it.
+ * See the @ref Exceptions module for more details on this class and what can
+ * be done with classes derived from it.
*
* @ingroup Exceptions
* @author Wolfgang Bangerth, 1997, 1998, Matthias Maier, 2013
virtual ~ExceptionBase () throw();
/**
- * Set the file name and line of where the exception appeared as
- * well as the violated condition and the name of the exception as
- * a char pointer. This function also populates the stacktrace.
+ * Set the file name and line of where the exception appeared as well as the
+ * violated condition and the name of the exception as a char pointer. This
+ * function also populates the stacktrace.
*/
void set_fields (const char *file,
const int line,
void print_exc_data (std::ostream &out) const;
/**
- * Print more specific information about the exception which
- * occurred. Overload this function in your own exception classes.
+ * Print more specific information about the exception which occurred.
+ * Overload this function in your own exception classes.
*/
virtual void print_info (std::ostream &out) const;
/**
- * Print a stacktrace, if one has been recorded previously, to the
- * given stream.
+ * Print a stacktrace, if one has been recorded previously, to the given
+ * stream.
*/
void print_stack_trace (std::ostream &out) const;
const char *exc;
/**
- * A backtrace to the position where the problem happened, if the
- * system supports this.
+ * A backtrace to the position where the problem happened, if the system
+ * supports this.
*/
mutable char **stacktrace;
/**
- * The number of stacktrace frames that are stored in the previous
- * variable. Zero if the system does not support stack traces.
+ * The number of stacktrace frames that are stored in the previous variable.
+ * Zero if the system does not support stack traces.
*/
int n_stacktrace_frames;
void generate_message() const;
/**
- * A pointer to the c_string that will be printed by what(). It is
- * populated by generate_message()
+ * A pointer to the c_string that will be printed by what(). It is populated
+ * by generate_message()
*/
mutable std::string what_str;
};
/**
- * In this namespace, functions in connection with the Assert and
- * AssertThrow mechanism are declared.
+ * In this namespace, functions in connection with the Assert and AssertThrow
+ * mechanism are declared.
*
* @ingroup Exceptions
*/
* Set a string that is printed upon output of the message indicating a
* triggered <tt>Assert</tt> statement. This string, which is printed in
* addition to the usual output may indicate information that is otherwise
- * not readily available unless we are using a debugger. For example,
- * with distributed programs on cluster computers, the output of all
- * processes is redirected to the same console window. In this case,
- * it is convenient to set as additional name the name of the host on
- * which the program runs, so that one can see in which instance of the
- * program the exception occurred.
+ * not readily available unless we are using a debugger. For example, with
+ * distributed programs on cluster computers, the output of all processes is
+ * redirected to the same console window. In this case, it is convenient to
+ * set as additional name the name of the host on which the program runs, so
+ * that one can see in which instance of the program the exception occurred.
*
* The string pointed to by the argument is copied, so doesn't need to be
* stored after the call to this function.
void set_additional_assert_output (const char *const p);
/**
- * Calling this function disables printing a stacktrace along with
- * the other output printed when an exception occurs. Most of the time,
- * you will want to see such a stacktrace; suppressing it, however, is
- * useful if one wants to compare the output of a program across different
- * machines and systems, since the stacktrace shows memory addresses
- * and library names/paths that depend on the exact setup of a machine.
+ * Calling this function disables printing a stacktrace along with the other
+ * output printed when an exception occurs. Most of the time, you will want
+ * to see such a stacktrace; suppressing it, however, is useful if one wants
+ * to compare the output of a program across different machines and systems,
+ * since the stacktrace shows memory addresses and library names/paths that
+ * depend on the exact setup of a machine.
*/
void suppress_stacktrace_in_exceptions ();
/**
- * Calling this function switches off the use of <tt>std::abort()</tt>
- * when an exception is created using the Assert() macro. Instead, the
- * Exception will be thrown using 'throw', so it can be caught if
- * desired. Generally, you want to abort the execution of a program when
- * Assert() is called, but it needs to be switched off if you want to log
- * all exceptions created, or if you want to test if an assertion is
- * working correctly. This is done for example in regression tests.
- * Please note that some fatal errors will still call abort(), e.g. when
- * an exception is caught during exception handling.
+ * Calling this function switches off the use of <tt>std::abort()</tt> when
+ * an exception is created using the Assert() macro. Instead, the Exception
+ * will be thrown using 'throw', so it can be caught if desired. Generally,
+ * you want to abort the execution of a program when Assert() is called, but
+ * it needs to be switched off if you want to log all exceptions created, or
+ * if you want to test if an assertion is working correctly. This is done
+ * for example in regression tests. Please note that some fatal errors will
+ * still call abort(), e.g. when an exception is caught during exception
+ * handling.
*/
void disable_abort_on_exception ();
/**
- * The functions in this namespace are in connection with the Assert
- * and AssertThrow mechanism but are solely for internal purposes and
- * are not for use outside the exception handling and throwing
- * mechanism.
+ * The functions in this namespace are in connection with the Assert and
+ * AssertThrow mechanism but are solely for internal purposes and are not
+ * for use outside the exception handling and throwing mechanism.
*
* @ingroup Exceptions
*/
* Conditionally abort the program.
*
* Depending on whether disable_abort_on_exception was called, this
- * function either aborts the program flow by printing the error
- * message provided by @p exc and calling <tt>std::abort()</tt>, or
- * throws @p exc instead (if @p nothrow is set to <tt>false</tt>).
+ * function either aborts the program flow by printing the error message
+ * provided by @p exc and calling <tt>std::abort()</tt>, or throws @p exc
+ * instead (if @p nothrow is set to <tt>false</tt>).
*
- * If the boolean @p nothrow is set to true and
- * disable_abort_on_exception was called, the exception type is just
- * printed to deallog and program flow continues. This is useful if
- * throwing an exception is prohibited (e.g. in a destructor with
- * <tt>noexcept(true)</tt> or <tt>throw()</tt>).
+ * If the boolean @p nothrow is set to true and disable_abort_on_exception
+ * was called, the exception type is just printed to deallog and program
+ * flow continues. This is useful if throwing an exception is prohibited
+ * (e.g. in a destructor with <tt>noexcept(true)</tt> or
+ * <tt>throw()</tt>).
*/
void abort (const ExceptionBase &exc, bool nothrow = false);
};
/**
- * This routine does the main work for the exception generation
- * mechanism used in the <tt>Assert</tt> macro.
+ * This routine does the main work for the exception generation mechanism
+ * used in the <tt>Assert</tt> macro.
*
* @ref ExceptionBase
*/
/**
- * This is the main routine in the exception mechanism for debug mode
- * error checking. It asserts that a certain condition is fulfilled,
- * otherwise issues an error and aborts the program.
+ * This is the main routine in the exception mechanism for debug mode error
+ * checking. It asserts that a certain condition is fulfilled, otherwise
+ * issues an error and aborts the program.
*
* See the <tt>ExceptionBase</tt> class for more information.
*
/**
- * A variant of the <tt>Assert</tt> macro above that exhibits the same
- * runtime behaviour as long as disable_abort_on_exception was not called.
+ * A variant of the <tt>Assert</tt> macro above that exhibits the same runtime
+ * behaviour as long as disable_abort_on_exception was not called.
*
- * However, if disable_abort_on_exception was called, this macro merely
- * prints the exception that would be thrown to deallog and continues
- * normally without throwing an exception.
+ * However, if disable_abort_on_exception was called, this macro merely prints
+ * the exception that would be thrown to deallog and continues normally
+ * without throwing an exception.
*
* See the <tt>ExceptionBase</tt> class for more information.
*
/**
- * This is the main routine in the exception mechanism for run-time
- * mode error checking. It assert that a certain condition is
- * fulfilled, otherwise issues an error and aborts the program.
+ * This is the main routine in the exception mechanism for run-time mode error
+ * checking. It assert that a certain condition is fulfilled, otherwise issues
+ * an error and aborts the program.
*
* See the <tt>ExceptionBase</tt> class for more information.
*
/**
- * Declare an exception class derived from ExceptionBase with one
- * additional parameter.
+ * Declare an exception class derived from ExceptionBase with one additional
+ * parameter.
*
* @ingroup Exceptions
*/
/**
- * Declare an exception class derived from ExceptionBase with
- * two additional parameters.
+ * Declare an exception class derived from ExceptionBase with two additional
+ * parameters.
*
* @ingroup Exceptions
*/
/**
- * Declare an exception class derived from ExceptionBase with
- * three additional parameters.
+ * Declare an exception class derived from ExceptionBase with three additional
+ * parameters.
*
* @ingroup Exceptions
*/
/**
- * Declare an exception class derived from ExceptionBase with
- * four additional parameters.
+ * Declare an exception class derived from ExceptionBase with four additional
+ * parameters.
*
* @ingroup Exceptions
*/
/**
- * Declare an exception class derived from ExceptionBase with
- * five additional parameters.
+ * Declare an exception class derived from ExceptionBase with five additional
+ * parameters.
*
* @ingroup Exceptions
*/
/**
- * Declare an exception class derived from ExceptionBase with one
- * additional parameter.
+ * Declare an exception class derived from ExceptionBase with one additional
+ * parameter.
*
* @ingroup Exceptions
*/
/**
- * Declare an exception class derived from ExceptionBase with two
- * additional parameters.
+ * Declare an exception class derived from ExceptionBase with two additional
+ * parameters.
*
* @ingroup Exceptions
*/
/**
- * Declare an exception class derived from ExceptionBase with three
- * additional parameters.
+ * Declare an exception class derived from ExceptionBase with three additional
+ * parameters.
*
* @ingroup Exceptions
*/
/**
- * Declare an exception class derived from ExceptionBase with four
- * additional parameters.
+ * Declare an exception class derived from ExceptionBase with four additional
+ * parameters.
*
* @ingroup Exceptions
*/
/**
- * Declare an exception class derived from ExceptionBase with five
- * additional parameters.
+ * Declare an exception class derived from ExceptionBase with five additional
+ * parameters.
*
* @ingroup Exceptions
*/
/**
- * Declare some exceptions that occur over and over. This way, you can
- * simply use these exceptions, instead of having to declare them locally
- * in your class. The namespace in which these exceptions are declared is
- * later included into the global namespace by
+ * Declare some exceptions that occur over and over. This way, you can simply
+ * use these exceptions, instead of having to declare them locally in your
+ * class. The namespace in which these exceptions are declared is later
+ * included into the global namespace by
* @code
* using namespace StandardExceptions;
* @endcode
/**
* Exception raised if a number is not finite.
*
- * This exception should be used to catch infinite or not a number
- * results of arithmetic operations that do not result from a division by
- * zero (use ExcDivideByZero for those).
+ * This exception should be used to catch infinite or not a number results
+ * of arithmetic operations that do not result from a division by zero (use
+ * ExcDivideByZero for those).
*/
DeclException0 (ExcNumberNotFinite);
DeclException0 (ExcOutOfMemory);
/**
- * A memory handler reached a point where all allocated objects should
- * have been released. Since this exception is thrown, some were still
- * allocated.
+ * A memory handler reached a point where all allocated objects should have
+ * been released. Since this exception is thrown, some were still allocated.
*/
DeclException1 (ExcMemoryLeak, int,
<< "Destroying memory handler while " << arg1
/**
* An error occurred opening the named file.
*
- * The constructor takes a single argument of type <tt>char*</tt>
- * naming the file.
+ * The constructor takes a single argument of type <tt>char*</tt> naming the
+ * file.
*/
DeclException1 (ExcFileNotOpen,
char *,
<< "Could not open file " << arg1);
/**
- * Exception denoting a part of the library or application program that
- * has not yet been implemented. In many cases, this only indicates that
- * there wasn't much need for something yet, not that this is difficult
- * to implement. It is therefore quite worth the effort to take a look
- * at the corresponding place and see whether it can be implemented
- * without too much effort.
+ * Exception denoting a part of the library or application program that has
+ * not yet been implemented. In many cases, this only indicates that there
+ * wasn't much need for something yet, not that this is difficult to
+ * implement. It is therefore quite worth the effort to take a look at the
+ * corresponding place and see whether it can be implemented without too
+ * much effort.
*/
DeclException0 (ExcNotImplemented);
/**
- * This exception usually indicates that some condition which the
- * programmer thinks must be satisfied at a certain point in an algorithm,
- * is not fulfilled. This might be due to some programming error above,
- * due to changes to the algorithm that did not preserve this assertion,
- * or due to assumptions the programmer made that are not valid at all
- * (i.e. the exception is thrown although there is no error here). Within
- * the library, this exception is most often used when we write some kind
- * of complicated algorithm and are not yet sure whether we got it right;
- * we then put in assertions after each part of the algorithm that check
- * for some conditions that should hold there, and throw an exception
- * if they do not.
+ * This exception usually indicates that some condition which the programmer
+ * thinks must be satisfied at a certain point in an algorithm, is not
+ * fulfilled. This might be due to some programming error above, due to
+ * changes to the algorithm that did not preserve this assertion, or due to
+ * assumptions the programmer made that are not valid at all (i.e. the
+ * exception is thrown although there is no error here). Within the library,
+ * this exception is most often used when we write some kind of complicated
+ * algorithm and are not yet sure whether we got it right; we then put in
+ * assertions after each part of the algorithm that check for some
+ * conditions that should hold there, and throw an exception if they do not.
*
- * We usually leave in these assertions even after we are confident
- * that the implementation is correct, since if someone later changes
- * or extends the algorithm, these exceptions will indicate to him if he
- * violates assumptions that are used later in the algorithm. Furthermore,
- * it sometimes happens that an algorithm does not work in very rare
- * corner cases. These cases will then be trapped sooner or later by the
- * exception, so that the algorithm can then be fixed for these cases
- * as well.
+ * We usually leave in these assertions even after we are confident that the
+ * implementation is correct, since if someone later changes or extends the
+ * algorithm, these exceptions will indicate to him if he violates
+ * assumptions that are used later in the algorithm. Furthermore, it
+ * sometimes happens that an algorithm does not work in very rare corner
+ * cases. These cases will then be trapped sooner or later by the exception,
+ * so that the algorithm can then be fixed for these cases as well.
*/
DeclException0 (ExcInternalError);
/**
- * This exception is used in functions that may not be called (i.e. in
- * pure functions) but could not be declared pure since the class is
- * intended to be used anyway, even though the respective function may
- * only be called if a derived class is used.
+ * This exception is used in functions that may not be called (i.e. in pure
+ * functions) but could not be declared pure since the class is intended to
+ * be used anyway, even though the respective function may only be called if
+ * a derived class is used.
*/
DeclException0 (ExcPureFunctionCalled);
/**
- * Used for constructors that are disabled. Examples are copy
- * constructors and assignment operators of large objects, which are
- * only allowed for empty objects.
+ * Used for constructors that are disabled. Examples are copy constructors
+ * and assignment operators of large objects, which are only allowed for
+ * empty objects.
*/
DeclException0 (ExcInvalidConstructorCall);
DeclException0 (ExcInvalidState);
/**
- * This exception is raised if a functionality is not possible in the
- * given dimension. Mostly used to throw function calls in 1d.
+ * This exception is raised if a functionality is not possible in the given
+ * dimension. Mostly used to throw function calls in 1d.
*
* The constructor takes a single <tt>int</tt>, denoting the dimension.
*/
DeclException0(ExcEmptyObject);
/**
- * This exception is raised whenever the sizes of two objects were
- * assumed to be equal, but were not.
+ * This exception is raised whenever the sizes of two objects were assumed
+ * to be equal, but were not.
*
- * Parameters to the constructor are the first and second size, both of
- * type <tt>int</tt>.
+ * Parameters to the constructor are the first and second size, both of type
+ * <tt>int</tt>.
*/
DeclException2 (ExcDimensionMismatch,
std::size_t, std::size_t,
<< "Dimension " << arg1 << " not equal to " << arg2);
/**
- * The first dimension should be either equal to the second or the
- * third, but it is neither.
+ * The first dimension should be either equal to the second or the third,
+ * but it is neither.
*/
DeclException3 (ExcDimensionMismatch2,
int, int, int,
<< " nor to " << arg3);
/**
- * This exception is one of the most often used ones, and indicates
- * that an index is not within the expected range. For example, you
- * might try to access an element of a vector which does not exist.
+ * This exception is one of the most often used ones, and indicates that an
+ * index is not within the expected range. For example, you might try to
+ * access an element of a vector which does not exist.
*
* The constructor takes three <tt>int</tt>, namely
* <ol>
- * <li> the violating index
- * <li> the lower bound
- * <li> the upper bound plus one
+ * <li> the violating index
+ * <li> the lower bound
+ * <li> the upper bound plus one
* </ol>
*/
DeclException3 (ExcIndexRange,
<< arg3 << "[");
/**
- * This generic exception will allow(enforce) the user to specify
- * the type of indices which adds type safety to the program.
+ * This generic exception will allow(enforce) the user to specify the type
+ * of indices which adds type safety to the program.
*/
template<typename T>
DeclException3 (ExcIndexRangeType,
<< arg2);
/**
- * This exception indicates that the first argument should be an
- * integer multiple of the second, but is not.
+ * This exception indicates that the first argument should be an integer
+ * multiple of the second, but is not.
*/
DeclException2 (ExcNotMultiple,
int, int,
<< " has remainder different from zero");
/**
- * This exception is thrown if the iterator you access has corrupted
- * data. It might for instance be, that the container it refers does
- * not have an entry at the point the iterator refers.
+ * This exception is thrown if the iterator you access has corrupted data.
+ * It might for instance be, that the container it refers does not have an
+ * entry at the point the iterator refers.
*
* Typically, this will be an internal error of deal.II, because the
- * increment and decrement operators should never yield an invalid
- * iterator.
+ * increment and decrement operators should never yield an invalid iterator.
*/
DeclException0 (ExcInvalidIterator);
/**
- * This exception is thrown if the iterator you incremented or
- * decremented was already at its final state.
+ * This exception is thrown if the iterator you incremented or decremented
+ * was already at its final state.
*/
DeclException0 (ExcIteratorPastEnd);
/**
- * This exception works around a design flaw in the
- * <tt>DeclException0</tt> macro: exceptions declared through
- * DeclException0 do not allow one to specify a message that is displayed
- * when the exception is raised, as opposed to the other exceptions which
- * allow to show a text along with the given parameters.
+ * This exception works around a design flaw in the <tt>DeclException0</tt>
+ * macro: exceptions declared through DeclException0 do not allow one to
+ * specify a message that is displayed when the exception is raised, as
+ * opposed to the other exceptions which allow to show a text along with the
+ * given parameters.
*
* When throwing this exception, you can give a message as a
- * <tt>std::string</tt> as argument to the exception that is then
- * displayed. The argument can, of course, be constructed at run-time,
- * for example including the name of a file that can't be opened, or
- * any other text you may want to assemble from different pieces.
+ * <tt>std::string</tt> as argument to the exception that is then displayed.
+ * The argument can, of course, be constructed at run-time, for example
+ * including the name of a file that can't be opened, or any other text you
+ * may want to assemble from different pieces.
*/
DeclException1 (ExcMessage,
std::string,
DeclException0 (ExcGhostsPresent);
/**
- * Some of our numerical classes allow for setting alll entries to
- * zero using the assignment operator <tt>=</tt>.
+ * Some of our numerical classes allow for setting alll entries to zero
+ * using the assignment operator <tt>=</tt>.
*
- * In many cases, this assignment operator makes sense <b>only</b>
- * for the argument zero. In other cases, this exception is thrown.
+ * In many cases, this assignment operator makes sense <b>only</b> for the
+ * argument zero. In other cases, this exception is thrown.
*/
DeclException0 (ExcScalarAssignmentOnlyForZeroValue);
* Special assertion for dimension mismatch.
*
* Since this is used very often and always repeats the arguments, we
- * introduce this special assertion for ExcDimensionMismatch in order
- * to keep the user codes shorter.
+ * introduce this special assertion for ExcDimensionMismatch in order to keep
+ * the user codes shorter.
*
* @ingroup Exceptions
* @author Guido Kanschat 2007
/**
- * Special assertion, testing whether <tt>vec</tt> has size
- * <tt>dim1</tt>, and each entry of the vector has the
- * size <tt>dim2</tt>
+ * Special assertion, testing whether <tt>vec</tt> has size <tt>dim1</tt>, and
+ * each entry of the vector has the size <tt>dim2</tt>
*
* @ingroup Exceptions
* @author Guido Kanschat 2010
* Special assertion for index range of nonnegative indices.
*
* Since this is used very often and always repeats the arguments, we
- * introduce this special assertion for ExcIndexRange in order
- * to keep the user codes shorter.
+ * introduce this special assertion for ExcIndexRange in order to keep the
+ * user codes shorter.
*
- * Called wit arguments <tt>index</tt> and <tt>range</tt> it asserts
- * that <tt>index<range</tt> and throws
- * ExcIndexRange(index,0,range) if it fails.
+ * Called wit arguments <tt>index</tt> and <tt>range</tt> it asserts that
+ * <tt>index<range</tt> and throws ExcIndexRange(index,0,range) if it
+ * fails.
*
* @ingroup Exceptions
* @author Guido Kanschat 2007
* Base class for analytic solutions to incompressible flow problems.
*
* Additional to the Function interface, this function provides for an
- * offset of the pressure: if the pressure of the computed solution
- * has an integral mean value different from zero, this value can be
- * given to pressure_adjustment() in order to compute correct pressure
- * errors.
+ * offset of the pressure: if the pressure of the computed solution has an
+ * integral mean value different from zero, this value can be given to
+ * pressure_adjustment() in order to compute correct pressure errors.
*
- * @note Derived classes should implement pressures with integral mean
- * value zero always.
+ * @note Derived classes should implement pressures with integral mean value
+ * zero always.
*
- * @note Thread safety: Some of the functions make use of internal data to compute
- * values. Therefore, every thread should obtain its own object of
+ * @note Thread safety: Some of the functions make use of internal data to
+ * compute values. Therefore, every thread should obtain its own object of
* derived classes.
*
* @ingroup functions
{
public:
/**
- * Constructor, setting up some
- * internal data structures.
+ * Constructor, setting up some internal data structures.
*/
FlowFunction();
virtual ~FlowFunction();
/**
- * Store an adjustment for the
- * pressure function, such that
- * its mean value is
- * <tt>p</tt>.
+ * Store an adjustment for the pressure function, such that its mean value
+ * is <tt>p</tt>.
*/
void pressure_adjustment(double p);
/**
- * Values in a structure more
- * suitable for vector valued
- * functions. The outer vector
- * is indexed by solution
- * component, the inner by
- * quadrature point.
+ * Values in a structure more suitable for vector valued functions. The
+ * outer vector is indexed by solution component, the inner by quadrature
+ * point.
*/
virtual void vector_values (const std::vector<Point<dim> > &points,
std::vector<std::vector<double> > &values) const = 0;
/**
- * Gradients in a structure more
- * suitable for vector valued
- * functions. The outer vector
- * is indexed by solution
- * component, the inner by
- * quadrature point.
+ * Gradients in a structure more suitable for vector valued functions. The
+ * outer vector is indexed by solution component, the inner by quadrature
+ * point.
*/
virtual void vector_gradients (const std::vector<Point<dim> > &points,
std::vector<std::vector<Tensor<1,dim> > > &gradients) const = 0;
/**
- * Force terms in a structure more
- * suitable for vector valued
- * functions. The outer vector
- * is indexed by solution
- * component, the inner by
+ * Force terms in a structure more suitable for vector valued functions.
+ * The outer vector is indexed by solution component, the inner by
* quadrature point.
*
- * @warning This is not the
- * true Laplacian, but the
- * force term to be used as
- * right hand side in Stokes'
- * equations
+ * @warning This is not the true Laplacian, but the force term to be used
+ * as right hand side in Stokes' equations
*/
virtual void vector_laplacians (const std::vector<Point<dim> > &points,
std::vector<std::vector<double> > &values) const = 0;
virtual void vector_gradient_list (const std::vector<Point<dim> > &points,
std::vector<std::vector<Tensor<1,dim> > > &gradients) const;
/**
- * The force term in the
- * momentum equation.
+ * The force term in the momentum equation.
*/
virtual void vector_laplacian_list (const std::vector<Point<dim> > &points,
std::vector<Vector<double> > &values) const;
protected:
/**
- * Mean value of the pressure
- * to be added by derived
- * classes.
+ * Mean value of the pressure to be added by derived classes.
*/
double mean_pressure;
private:
/**
- * A mutex that guards the
- * following scratch arrays.
+ * A mutex that guards the following scratch arrays.
*/
mutable Threads::Mutex mutex;
/**
- * Auxiliary values for the usual
- * Function interface.
+ * Auxiliary values for the usual Function interface.
*/
mutable std::vector<std::vector<double> > aux_values;
/**
- * Auxiliary values for the usual
- * Function interface.
+ * Auxiliary values for the usual Function interface.
*/
mutable std::vector<std::vector<Tensor<1,dim> > > aux_gradients;
};
/**
- * Laminar pipe flow in two and three dimensions. The channel
- * stretches along the <i>x</i>-axis and has radius @p radius. The
- * @p Reynolds number is used to scale the pressure properly for a
- * Navier-Stokes problem.
+ * Laminar pipe flow in two and three dimensions. The channel stretches
+ * along the <i>x</i>-axis and has radius @p radius. The @p Reynolds number
+ * is used to scale the pressure properly for a Navier-Stokes problem.
*
* @ingroup functions
* @author Guido Kanschat, 2007
{
public:
/**
- * Construct an object for the
- * given channel radius
- * <tt>r</tt> and the Reynolds
- * number <tt>Re</tt>.
+ * Construct an object for the given channel radius <tt>r</tt> and the
+ * Reynolds number <tt>Re</tt>.
*/
PoisseuilleFlow<dim> (const double r,
const double Re);
/**
- * Artificial divergence free function with homogeneous boundary
- * conditions on the cube [-1,1]<sup>dim</sup>.
+ * Artificial divergence free function with homogeneous boundary conditions
+ * on the cube [-1,1]<sup>dim</sup>.
*
* The function in 2D is
* @f[
{
public:
/**
- * Constructor setting the
- * Reynolds number required for
- * pressure computation and
- * scaling of the right hand side.
+ * Constructor setting the Reynolds number required for pressure
+ * computation and scaling of the right hand side.
*/
StokesCosine (const double viscosity = 1., const double reaction = 0.);
/**
- * Change the viscosity and the
- * reaction parameter.
+ * Change the viscosity and the reaction parameter.
*/
void set_parameters (const double viscosity, const double reaction);
virtual ~StokesCosine();
/**
* Flow solution in 2D by Kovasznay (1947).
*
- * This function is valid on the half plane right of the line
- * <i>x=1/2</i>.
+ * This function is valid on the half plane right of the line <i>x=1/2</i>.
*
* @ingroup functions
* @author Guido Kanschat, 2007
{
public:
/**
- * Construct an object for the
- * give Reynolds number
- * <tt>Re</tt>. If the
- * parameter <tt>Stokes</tt> is
- * true, the right hand side of
- * the momentum equation
- * returned by
- * vector_laplacians() contains
- * the nonlinearity, such that
- * the Kovasznay solution can
- * be obtained as the solution
- * to a Stokes problem.
+ * Construct an object for the give Reynolds number <tt>Re</tt>. If the
+ * parameter <tt>Stokes</tt> is true, the right hand side of the momentum
+ * equation returned by vector_laplacians() contains the nonlinearity,
+ * such that the Kovasznay solution can be obtained as the solution to a
+ * Stokes problem.
*/
Kovasznay (const double Re, bool Stokes = false);
virtual ~Kovasznay();
* to evaluate the function, returns a vector of values with one or more
* components.
*
- * The class serves the purpose
- * of representing both scalar and vector valued functions. To this end, we
- * consider scalar functions as a special case of vector valued
- * functions, in the former case only having a single component return
- * vector. Since handling vectors is comparatively expensive, the interface
- * of this class has functions which only ask for a single component of the
- * vector-valued results (this is what you will usually need in case you know that
- * your function is scalar-valued) as well as functions you can ask for an
- * entire vector of results with as many components as the function object
- * represents. Access to function objects therefore is through the following
- * methods:
+ * The class serves the purpose of representing both scalar and vector valued
+ * functions. To this end, we consider scalar functions as a special case of
+ * vector valued functions, in the former case only having a single component
+ * return vector. Since handling vectors is comparatively expensive, the
+ * interface of this class has functions which only ask for a single component
+ * of the vector-valued results (this is what you will usually need in case
+ * you know that your function is scalar-valued) as well as functions you can
+ * ask for an entire vector of results with as many components as the function
+ * object represents. Access to function objects therefore is through the
+ * following methods:
* @code
* // access to one component at one point
* double value (const Point<dim, Number> &p,
* std::vector<Vector<double> > &value_list) const;
* @endcode
*
- * Furthermore, there are functions returning the gradient of the
- * function or even higher derivatives at one or several points.
+ * Furthermore, there are functions returning the gradient of the function or
+ * even higher derivatives at one or several points.
*
- * You will usually only overload those functions you need; the
- * functions returning several values at a time (value_list(),
- * vector_value_list(), and gradient analogs) will call those
- * returning only one value (value(), vector_value(), and gradient
- * analogs), while those ones will throw an exception when called but
- * not overloaded.
+ * You will usually only overload those functions you need; the functions
+ * returning several values at a time (value_list(), vector_value_list(), and
+ * gradient analogs) will call those returning only one value (value(),
+ * vector_value(), and gradient analogs), while those ones will throw an
+ * exception when called but not overloaded.
*
* Note however, that conversely the functions returning all components of the
* function at one or several points (i.e. vector_value(),
- * vector_value_list()), will not call the function returning one
- * component at one point repeatedly, once for each point and
- * component. The reason is efficiency: this would amount to too many
- * virtual function calls. If you have vector-valued functions, you
- * should therefore also provide overloads of the virtual functions
- * for all components at a time.
+ * vector_value_list()), will not call the function returning one component at
+ * one point repeatedly, once for each point and component. The reason is
+ * efficiency: this would amount to too many virtual function calls. If you
+ * have vector-valued functions, you should therefore also provide overloads
+ * of the virtual functions for all components at a time.
*
- * Also note, that unless only called a very small number of times,
- * you should overload all sets of functions (returning only one
- * value, as well as those returning a whole array), since the cost of
- * evaluation of a point value is often less than the virtual function
- * call itself.
+ * Also note, that unless only called a very small number of times, you should
+ * overload all sets of functions (returning only one value, as well as those
+ * returning a whole array), since the cost of evaluation of a point value is
+ * often less than the virtual function call itself.
*
*
- * Support for time dependent functions can be found in the base
- * class FunctionTime.
+ * Support for time dependent functions can be found in the base class
+ * FunctionTime.
*
- * @note If the functions you are dealing with have sizes which
- * are a priori known (for example, <tt>dim</tt> elements), you might
- * consider using the TensorFunction class instead. On the other hand,
- * functions like VectorTools::interpolate or
- * VectorTools::interpolate_boundary_values definitely only want objects
- * of the current type. You can use the VectorFunctionFromTensorFunction
- * class to convert the former to the latter.
+ * @note If the functions you are dealing with have sizes which are a priori
+ * known (for example, <tt>dim</tt> elements), you might consider using the
+ * TensorFunction class instead. On the other hand, functions like
+ * VectorTools::interpolate or VectorTools::interpolate_boundary_values
+ * definitely only want objects of the current type. You can use the
+ * VectorFunctionFromTensorFunction class to convert the former to the latter.
*
* @ingroup functions
* @author Wolfgang Bangerth, 1998, 1999, Luca Heltai 2014
{
public:
/**
- * Export the value of the template parameter as a static member
- * constant. Sometimes useful for some expression template programming.
+ * Export the value of the template parameter as a static member constant.
+ * Sometimes useful for some expression template programming.
*/
static const unsigned int dimension = dim;
/**
* Constructor. May take an initial value for the number of components
- * (which defaults to one, i.e. a scalar function), and the time
- * variable, which defaults to zero.
+ * (which defaults to one, i.e. a scalar function), and the time variable,
+ * which defaults to zero.
*/
Function (const unsigned int n_components = 1,
const Number initial_time = 0.0);
* Virtual destructor; absolutely necessary in this case.
*
* This destructor is declared pure virtual, such that objects of this class
- * cannot be created. Since all the other virtual functions have a
- * pseudo-implementation to avoid overhead in derived classes, they can not
- * be abstract. As a consequence, we could generate an object of this class
+ * cannot be created. Since all the other virtual functions have a pseudo-
+ * implementation to avoid overhead in derived classes, they can not be
+ * abstract. As a consequence, we could generate an object of this class
* because none of this class's functions are abstract.
*
* We circumvent this problem by making the destructor of this class
* abstract virtual. This ensures that at least one member function is
- * abstract, and consequently, no objects of type Function can be
- * created. However, there is no need for derived classes to explicitly
- * implement a destructor: every class has a destructor, either explicitly
- * implemented or implicitly generated by the compiler, and this resolves
- * the abstractness of any derived class even if they do not have an
- * explicitly declared destructor.
+ * abstract, and consequently, no objects of type Function can be created.
+ * However, there is no need for derived classes to explicitly implement a
+ * destructor: every class has a destructor, either explicitly implemented
+ * or implicitly generated by the compiler, and this resolves the
+ * abstractness of any derived class even if they do not have an explicitly
+ * declared destructor.
*
- * Nonetheless, since derived classes want to call the destructor of a
- * base class, this destructor is implemented (despite it being pure
- * virtual).
+ * Nonetheless, since derived classes want to call the destructor of a base
+ * class, this destructor is implemented (despite it being pure virtual).
*/
virtual ~Function () = 0;
/**
* Assignment operator. This is here only so that you can have objects of
- * derived classes in containers, or assign them otherwise. It will raise
- * an exception if the object from which you assign has a different
- * number of components than the one being assigned to.
+ * derived classes in containers, or assign them otherwise. It will raise an
+ * exception if the object from which you assign has a different number of
+ * components than the one being assigned to.
*/
Function &operator= (const Function &f);
/**
- * Return the value of the function at the given point. Unless there is
- * only one component (i.e. the function is scalar), you should state the
- * component you want to have evaluated; it defaults to zero, i.e. the
- * first component.
+ * Return the value of the function at the given point. Unless there is only
+ * one component (i.e. the function is scalar), you should state the
+ * component you want to have evaluated; it defaults to zero, i.e. the first
+ * component.
*/
virtual Number value (const Point<dim, Number> &p,
const unsigned int component = 0) const;
/**
* Return all components of a vector-valued function at a given point.
*
- * <tt>values</tt> shall have the right size beforehand, i.e.
- * #n_components.
+ * <tt>values</tt> shall have the right size beforehand, i.e. #n_components.
*
* The default implementation will call value() for each component.
*/
Vector<Number> &values) const;
/**
- * Set <tt>values</tt> to the point values of the specified component of
- * the function at the <tt>points</tt>. It is assumed that
- * <tt>values</tt> already has the right size, i.e. the same size as the
- * <tt>points</tt> array.
+ * Set <tt>values</tt> to the point values of the specified component of the
+ * function at the <tt>points</tt>. It is assumed that <tt>values</tt>
+ * already has the right size, i.e. the same size as the <tt>points</tt>
+ * array.
*
* By default, this function repeatedly calls value() for each point
* separately, to fill the output array.
* all elements be vectors with the same number of components as this
* function has.
*
- * By default, this function repeatedly calls vector_value() for each
- * point separately, to fill the output array.
+ * By default, this function repeatedly calls vector_value() for each point
+ * separately, to fill the output array.
*/
virtual void vector_value_list (const std::vector<Point<dim, Number> > &points,
std::vector<Vector<Number> > &values) const;
/**
- * For each component of the function, fill a vector of values, one for
- * each point.
+ * For each component of the function, fill a vector of values, one for each
+ * point.
*
* The default implementation of this function in Function calls
* value_list() for each component. In order to improve performance, this
const unsigned int component = 0) const;
/**
- * Return the gradient of all components of the function at the given
- * point.
+ * Return the gradient of all components of the function at the given point.
*/
virtual void vector_gradient (const Point<dim, Number> &p,
std::vector<Tensor<1,dim, Number> > &gradients) const;
/**
- * Set <tt>gradients</tt> to the gradients of the specified component of
- * the function at the <tt>points</tt>. It is assumed that
- * <tt>gradients</tt> already has the right size, i.e. the same size as
- * the <tt>points</tt> array.
+ * Set <tt>gradients</tt> to the gradients of the specified component of the
+ * function at the <tt>points</tt>. It is assumed that <tt>gradients</tt>
+ * already has the right size, i.e. the same size as the <tt>points</tt>
+ * array.
*/
virtual void gradient_list (const std::vector<Point<dim, Number> > &points,
std::vector<Tensor<1,dim, Number> > &gradients,
const unsigned int component = 0) const;
/**
- * For each component of the function, fill a vector of gradient values,
- * one for each point.
+ * For each component of the function, fill a vector of gradient values, one
+ * for each point.
*
* The default implementation of this function in Function calls
* value_list() for each component. In order to improve performance, this
/**
* Set <tt>gradients</tt> to the gradients of the function at the
* <tt>points</tt>, for all components. It is assumed that
- * <tt>gradients</tt> already has the right size, i.e. the same size as
- * the <tt>points</tt> array.
+ * <tt>gradients</tt> already has the right size, i.e. the same size as the
+ * <tt>points</tt> array.
*
* The outer loop over <tt>gradients</tt> is over the points in the list,
* the inner loop over the different components of the function.
/**
* Determine an estimate for the memory consumption (in bytes) of this
- * object. Since sometimes the size of objects can not be determined
- * exactly (for example: what is the memory consumption of an STL
- * <tt>std::map</tt> type with a certain number of elements?), this is
- * only an estimate. however often quite close to the true value.
+ * object. Since sometimes the size of objects can not be determined exactly
+ * (for example: what is the memory consumption of an STL <tt>std::map</tt>
+ * type with a certain number of elements?), this is only an estimate.
+ * however often quite close to the true value.
*/
std::size_t memory_consumption () const;
};
/**
- * Provide a function which always returns zero. Obviously, also the
- * derivates of this function are zero. Also, it returns zero on all
- * components in case the function is not a scalar one, which can be
- * obtained by passing the constructor the appropriate number of
- * components.
+ * Provide a function which always returns zero. Obviously, also the derivates
+ * of this function are zero. Also, it returns zero on all components in case
+ * the function is not a scalar one, which can be obtained by passing the
+ * constructor the appropriate number of components.
*
* This function is of use when you want to implement homogeneous boundary
* conditions, or zero initial conditions.
/**
- * Provide a function which always returns the constant value
- * handed to the constructor.
+ * Provide a function which always returns the constant value handed to the
+ * constructor.
*
- * Obviously, the derivates of this function are zero, which is why we
- * derive this class from <tt>ZeroFunction</tt>: we then only have to
- * overload the value functions, not all the derivatives. In some way, it
- * would be more obvious to do the derivation in the opposite direction,
- * i.e. let <tt>ZeroFunction</tt> be a more specialized version of
- * <tt>ConstantFunction</tt>; however, this would be less efficient, since
- * we could not make use of the fact that the function value of the
+ * Obviously, the derivates of this function are zero, which is why we derive
+ * this class from <tt>ZeroFunction</tt>: we then only have to overload the
+ * value functions, not all the derivatives. In some way, it would be more
+ * obvious to do the derivation in the opposite direction, i.e. let
+ * <tt>ZeroFunction</tt> be a more specialized version of
+ * <tt>ConstantFunction</tt>; however, this would be less efficient, since we
+ * could not make use of the fact that the function value of the
* <tt>ZeroFunction</tt> is known at compile time and need not be looked up
* somewhere in memory.
*
* You can pass to the constructor an integer denoting the number of
- * components this function shall have. It defaults to one. If it is
- * greater than one, then the function will return the constant value in
- * all its components, which might not be overly useful a feature in most
- * cases, however.
+ * components this function shall have. It defaults to one. If it is greater
+ * than one, then the function will return the constant value in all its
+ * components, which might not be overly useful a feature in most cases,
+ * however.
*
* @ingroup functions
* @author Wolfgang Bangerth, 1998, 1999
{
public:
/**
- * Constructor; takes the constant function value as an argument. The
- * number of components is preset to one.
+ * Constructor; takes the constant function value as an argument. The number
+ * of components is preset to one.
*/
ConstantFunction (const Number value,
const unsigned int n_components = 1);
/**
- * This is a constant vector-valued function, in which one or more
- * components of the vector have a constant value and all other components
- * are zero. It is especially useful as a weight function for
- * VectorTools::integrate_difference, where it allows to integrate only one
- * or a few vector components, rather than the entire vector-valued
- * solution. In other words, it acts as a component mask with a single
- * component selected (see the @ref GlossComponentMask "the glossary entry
- * on component masks"). See the step-20 tutorial program for a detailed
- * explanation and a use case.
+ * This is a constant vector-valued function, in which one or more components
+ * of the vector have a constant value and all other components are zero. It
+ * is especially useful as a weight function for
+ * VectorTools::integrate_difference, where it allows to integrate only one or
+ * a few vector components, rather than the entire vector-valued solution. In
+ * other words, it acts as a component mask with a single component selected
+ * (see the @ref GlossComponentMask "the glossary entry on component masks").
+ * See the step-20 tutorial program for a detailed explanation and a use case.
*
* @ingroup functions
* @author Guido Kanschat, 2000, Wolfgang Bangerth 2006
public:
/**
* Constructor if only a single component shall be non-zero. Arguments
- * denote the component selected, the value for that component and the
- * total number of vector components.
+ * denote the component selected, the value for that component and the total
+ * number of vector components.
*/
ComponentSelectFunction (const unsigned int selected,
const Number value,
const unsigned int n_components);
/**
- * Constructor if multiple components shall have non-zero, unit values
- * (i.e. this should be a mask for multiple components). The first
- * argument denotes a half-open interval of components (for example
- * std::pair(0,dim) for the first dim components), and the second
- * argument is the total number of vector components.
+ * Constructor if multiple components shall have non-zero, unit values (i.e.
+ * this should be a mask for multiple components). The first argument
+ * denotes a half-open interval of components (for example std::pair(0,dim)
+ * for the first dim components), and the second argument is the total
+ * number of vector components.
*/
ComponentSelectFunction (const std::pair<unsigned int, unsigned int> &selected,
const unsigned int n_components);
/**
- * Return the value of the function at the given point for all
- * components.
+ * Return the value of the function at the given point for all components.
*/
virtual void vector_value (const Point<dim, Number> &p,
Vector<Number> &return_value) const;
/**
* Set <tt>values</tt> to the point values of the function at the
- * <tt>points</tt>, for all components. It is assumed that
- * <tt>values</tt> already has the right size, i.e. the same size as the
- * <tt>points</tt> array.
+ * <tt>points</tt>, for all components. It is assumed that <tt>values</tt>
+ * already has the right size, i.e. the same size as the <tt>points</tt>
+ * array.
*/
virtual void vector_value_list (const std::vector<Point<dim, Number> > &points,
std::vector<Vector<Number> > &values) const;
/**
* Determine an estimate for the memory consumption (in bytes) of this
- * object. Since sometimes the size of objects can not be determined
- * exactly (for example: what is the memory consumption of an STL
- * <tt>std::map</tt> type with a certain number of elements?), this is
- * only an estimate. however often quite close to the true value.
+ * object. Since sometimes the size of objects can not be determined exactly
+ * (for example: what is the memory consumption of an STL <tt>std::map</tt>
+ * type with a certain number of elements?), this is only an estimate.
+ * however often quite close to the true value.
*/
std::size_t memory_consumption () const;
* @endcode
* into an object of type Function@<dim@>. Since the argument returns a
* scalar, the result is clearly a Function object for which
- * <code>function.n_components==1</code>. The class works by storing a
- * pointer to the given function and every time
+ * <code>function.n_components==1</code>. The class works by storing a pointer
+ * to the given function and every time
* <code>function.value(p,component)</code> is called, calls
- * <code>foo(p)</code> and returns the corresponding value. It also makes
- * sure that <code>component</code> is in fact zero, as needs be for scalar
+ * <code>foo(p)</code> and returns the corresponding value. It also makes sure
+ * that <code>component</code> is in fact zero, as needs be for scalar
* functions.
*
* The class provides an easy way to turn a simple global function into
* something that has the required Function@<dim@> interface for operations
* like VectorTools::interpolate_boundary_values() etc., and thereby allows
- * for simpler experimenting without having to write all the boiler plate
- * code of declaring a class that is derived from Function and implementing
- * the Function::value() function. An example of this is given in the results
+ * for simpler experimenting without having to write all the boiler plate code
+ * of declaring a class that is derived from Function and implementing the
+ * Function::value() function. An example of this is given in the results
* section of step-53.
*
- * The class gains additional expressive power because the argument it
- * takes does not have to be a pointer to an actual function. Rather, it is
- * a function object, i.e., it can also be the result of call to std::bind
- * (or boost::bind) or some other object that can be called with a single
- * argument. For example, if you need a Function object that returns the
- * norm of a point, you could write it like so:
+ * The class gains additional expressive power because the argument it takes
+ * does not have to be a pointer to an actual function. Rather, it is a
+ * function object, i.e., it can also be the result of call to std::bind (or
+ * boost::bind) or some other object that can be called with a single
+ * argument. For example, if you need a Function object that returns the norm
+ * of a point, you could write it like so:
* @code
* template <int dim, typename Number>
* class Norm : public Function<dim, Number> {
*
* Norm<2> my_norm_object;
* @endcode
- * and then pass the <code>my_norm_object</code> around, or you could write
- * it like so:
+ * and then pass the <code>my_norm_object</code> around, or you could write it
+ * like so:
* @code
* ScalarFunctionFromFunctionObject<dim, Number> my_norm_object (&Point<dim, Number>::norm);
* @endcode
public:
/**
* Given a function object that takes a Point and returns a Number value,
- * convert this into an object that matches the Function<dim, Number> interface.
+ * convert this into an object that matches the Function<dim, Number>
+ * interface.
*/
ScalarFunctionFromFunctionObject (const std_cxx11::function<Number (const Point<dim, Number> &)> &function_object);
/**
* The function object which we call when this class's value() or
* value_list() functions are called.
- **/
+ */
const std_cxx11::function<Number (const Point<dim, Number> &)> function_object;
};
/**
- * This class is similar to the ScalarFunctionFromFunctionObject class in
- * that it allows for the easy conversion of a function object to something
- * that satisfies the interface of the Function base class. The difference
- * is that here, the given function object is still a scalar function (i.e.
- * it has a single value at each space point) but that the Function object
- * generated is vector valued. The number of vector components is specified
- * in the constructor, where one also selectes a single one of these vector
+ * This class is similar to the ScalarFunctionFromFunctionObject class in that
+ * it allows for the easy conversion of a function object to something that
+ * satisfies the interface of the Function base class. The difference is that
+ * here, the given function object is still a scalar function (i.e. it has a
+ * single value at each space point) but that the Function object generated is
+ * vector valued. The number of vector components is specified in the
+ * constructor, where one also selectes a single one of these vector
* components that should be filled by the passed object. The result is a
* vector Function object that returns zero in each component except the
- * single selected one where it returns the value returned by the given as
- * the first argument to the constructor.
+ * single selected one where it returns the value returned by the given as the
+ * first argument to the constructor.
*
* @note In the above discussion, note the difference between the (scalar)
- * "function object" (i.e., a C++ object <code>x</code> that can be called
- * as in <code>x(p)</code>) and the capitalized (vector valued) "Function
- * object" (i.e., an object of a class that is derived from the Function
- * base class).
+ * "function object" (i.e., a C++ object <code>x</code> that can be called as
+ * in <code>x(p)</code>) and the capitalized (vector valued) "Function object"
+ * (i.e., an object of a class that is derived from the Function base class).
*
* To be more concrete, let us consider the following example:
* @code
* component_mask (&one, 1, 3);
* @endcode
* Here, <code>component_mask</code> then represents a Function object that
- * for every point returns the vector $(0, 1, 0)^T$, i.e. a mask function
- * that could, for example, be passed to
- * VectorTools::integrate_difference(). This effect can also be achieved
- * using the ComponentSelectFunction class but is obviously easily extended
- * to functions that are non-constant in their one component.
+ * for every point returns the vector $(0, 1, 0)^T$, i.e. a mask function that
+ * could, for example, be passed to VectorTools::integrate_difference(). This
+ * effect can also be achieved using the ComponentSelectFunction class but is
+ * obviously easily extended to functions that are non-constant in their one
+ * component.
*
* @author Wolfgang Bangerth, 2011
*/
{
public:
/**
- * Given a function object that takes a Point and returns a Number
- * value, convert this into an object that matches the Function@<dim@>
- * interface.
+ * Given a function object that takes a Point and returns a Number value,
+ * convert this into an object that matches the Function@<dim@> interface.
*
* @param function_object The scalar function that will form one component
- * of the resulting Function object.
+ * of the resulting Function object.
* @param n_components The total number of vector components of the
- * resulting Function object.
- * @param selected_component The single component that should be
- * filled by the first argument.
- **/
+ * resulting Function object.
+ * @param selected_component The single component that should be filled by
+ * the first argument.
+ */
VectorFunctionFromScalarFunctionObject (const std_cxx11::function<Number (const Point<dim, Number> &)> &function_object,
const unsigned int selected_component,
const unsigned int n_components);
/**
* Return all components of a vector-valued function at a given point.
*
- * <tt>values</tt> shall have the right size beforehand, i.e.
- * #n_components.
+ * <tt>values</tt> shall have the right size beforehand, i.e. #n_components.
*/
virtual void vector_value (const Point<dim, Number> &p,
Vector<Number> &values) const;
/**
* The function object which we call when this class's value() or
* value_list() functions are called.
- **/
+ */
const std_cxx11::function<Number (const Point<dim, Number> &)> function_object;
/**
/**
- * This class is built as a means of translating the <code>Tensor<1,dim, Number>
- * </code> values produced by objects of type TensorFunction and returning
- * them as a multiple component version of the same thing as a Vector for
- * use in, for example, the VectorTools::interpolate or the many other
- * functions taking Function objects. It allows the user to place the
+ * This class is built as a means of translating the <code>Tensor<1,dim,
+ * Number> </code> values produced by objects of type TensorFunction and
+ * returning them as a multiple component version of the same thing as a
+ * Vector for use in, for example, the VectorTools::interpolate or the many
+ * other functions taking Function objects. It allows the user to place the
* desired components into an <tt>n_components</tt> long vector starting at
- * the <tt>selected_component</tt> location in that vector and have all
- * other components be 0.
+ * the <tt>selected_component</tt> location in that vector and have all other
+ * components be 0.
*
- * For example: Say you created a class called
+ * For example: Say you created a class called
* @code
* class RightHandSide : public TensorFunction<rank,dim, Number>
* @endcode
- * which extends the TensorFunction class and you have an object
+ * which extends the TensorFunction class and you have an object
* @code
* RightHandSide<1,dim, Number> rhs;
* @endcode
- * of that class which you want to interpolate onto your mesh using the
- * VectorTools::interpolate function, but the finite element you use for
- * the DoFHandler object has 3 copies of a finite element with
- * <tt>dim</tt> components, for a total of 3*dim components. To
- * interpolate onto that DoFHandler, you need an object of type Function
- * that has 3*dim vector components. Creating such an object from the
- * existing <code>rhs</code> object is done using this piece of code:
+ * of that class which you want to interpolate onto your mesh using the
+ * VectorTools::interpolate function, but the finite element you use for the
+ * DoFHandler object has 3 copies of a finite element with <tt>dim</tt>
+ * components, for a total of 3*dim components. To interpolate onto that
+ * DoFHandler, you need an object of type Function that has 3*dim vector
+ * components. Creating such an object from the existing <code>rhs</code>
+ * object is done using this piece of code:
* @code
* RighHandSide<1,dim, Number> rhs;
* VectorFunctionFromTensorFunction<dim, Number> rhs_vector_function (rhs, 0, 3*dim);
* @endcode
- * where the <code>dim</code> components of the tensor function are placed into
- * the first <code>dim</code> components of the function object.
+ * where the <code>dim</code> components of the tensor function are placed
+ * into the first <code>dim</code> components of the function object.
*
* @author Spencer Patty, 2013
*/
{
public:
/**
- * Given a TensorFunction object that takes a <tt>Point</tt> and returns
- * a <tt>Tensor<1,dim, Number></tt> value, convert this into an object that
+ * Given a TensorFunction object that takes a <tt>Point</tt> and returns a
+ * <tt>Tensor<1,dim, Number></tt> value, convert this into an object that
* matches the Function@<dim@> interface.
*
* By default, create a Vector object of the same size as
* <tt>tensor_function</tt> returns, i.e., with <tt>dim</tt> components.
*
- * @param tensor_function The TensorFunction that will form one component
- * of the resulting Vector Function object.
+ * @param tensor_function The TensorFunction that will form one component of
+ * the resulting Vector Function object.
* @param n_components The total number of vector components of the
- * resulting TensorFunction object.
- * @param selected_component The first component that should be
- * filled by the first argument. This should be such that the entire
- * tensor_function fits inside the <tt>n_component</tt> length return
- * vector.
+ * resulting TensorFunction object.
+ * @param selected_component The first component that should be filled by
+ * the first argument. This should be such that the entire tensor_function
+ * fits inside the <tt>n_component</tt> length return vector.
*/
VectorFunctionFromTensorFunction (const TensorFunction<1,dim, Number> &tensor_function,
const unsigned int selected_component=0,
virtual ~VectorFunctionFromTensorFunction();
/**
- * Return a single component of a vector-valued function at a given
- * point.
+ * Return a single component of a vector-valued function at a given point.
*/
virtual Number value (const Point<dim, Number> &p,
const unsigned int component = 0) const;
/**
* Return all components of a vector-valued function at a given point.
*
- * <tt>values</tt> shall have the right size beforehand, i.e.
- * #n_components.
+ * <tt>values</tt> shall have the right size beforehand, i.e. #n_components.
*/
virtual void vector_value (const Point<dim, Number> &p,
Vector<Number> &values) const;
private:
/**
- * The TensorFunction object which we call when this class's
- * vector_value() or vector_value_list() functions are called.
- **/
+ * The TensorFunction object which we call when this class's vector_value()
+ * or vector_value_list() functions are called.
+ */
const TensorFunction<1,dim,Number> &tensor_function;
/**
/**
- * Derivative of a function object. The value access functions of
- * this class return the directional derivative of a function with
- * respect to a direction provided on construction. If <tt>b</tt> is the
- * vector, the derivative <tt>b . grad f</tt> is computed. This derivative
- * is evaluated directly, not by computing the gradient of <tt>f</tt> and
- * its scalar product with <tt>b</tt>.
+ * Derivative of a function object. The value access functions of this class
+ * return the directional derivative of a function with respect to a direction
+ * provided on construction. If <tt>b</tt> is the vector, the derivative <tt>b
+ * . grad f</tt> is computed. This derivative is evaluated directly, not by
+ * computing the gradient of <tt>f</tt> and its scalar product with
+ * <tt>b</tt>.
*
* The derivative is computed numerically, using one of the provided
- * difference formulas (see <tt>set_formula</tt> for available
- * schemes). Experimenting with <tt>h</tt> and the difference scheme may be
- * necessary to obtain sufficient results.
+ * difference formulas (see <tt>set_formula</tt> for available schemes).
+ * Experimenting with <tt>h</tt> and the difference scheme may be necessary to
+ * obtain sufficient results.
*
* @ingroup functions
* @author Guido Kanschat, 2000
{
public:
/**
- * Constructor. Provided are the
- * functions to compute
- * derivatives of, the direction
- * vector of the differentiation
- * and the step size <tt>h</tt> of the
- * difference formula.
+ * Constructor. Provided are the functions to compute derivatives of, the
+ * direction vector of the differentiation and the step size <tt>h</tt> of
+ * the difference formula.
*/
FunctionDerivative (const Function<dim> &f,
const Point<dim> &direction,
const double h = 1.e-6);
/**
- * Constructor. Provided are the
- * functions to compute
- * derivatives of and the
- * direction vector of the
- * differentiation in each
- * quadrature point and the
+ * Constructor. Provided are the functions to compute derivatives of and the
+ * direction vector of the differentiation in each quadrature point and the
* difference step size.
*
- * This is the constructor for a
- * variable velocity field. Most
- * probably, a new object of
- * <tt>FunctionDerivative</tt> has to
- * be constructed for each set of
- * quadrature points.
+ * This is the constructor for a variable velocity field. Most probably, a
+ * new object of <tt>FunctionDerivative</tt> has to be constructed for each
+ * set of quadrature points.
*
- * The number of quadrature point
- * must still be the same, when
- * values are accessed.
+ * The number of quadrature point must still be the same, when values are
+ * accessed.
*/
FunctionDerivative (const Function<dim> &f,
const std::vector<Point<dim> > &direction,
const double h = 1.e-6);
/**
- * Choose the difference formula.
- * This is set to the default in
- * the constructor.
+ * Choose the difference formula. This is set to the default in the
+ * constructor.
*
- * Formulas implemented right now
- * are first order backward Euler
- * (<tt>UpwindEuler</tt>), second
- * order symmetric Euler
- * (<tt>Euler</tt>) and a symmetric
- * fourth order formula
- * (<tt>FourthOrder</tt>).
+ * Formulas implemented right now are first order backward Euler
+ * (<tt>UpwindEuler</tt>), second order symmetric Euler (<tt>Euler</tt>) and
+ * a symmetric fourth order formula (<tt>FourthOrder</tt>).
*/
void set_formula (typename AutoDerivativeFunction<dim>::DifferenceFormula formula
= AutoDerivativeFunction<dim>::Euler);
/**
- * Change the base step size of
- * the difference formula
+ * Change the base step size of the difference formula
*/
void set_h (const double h);
const unsigned int component = 0) const;
/**
- * Determine an estimate for
- * the memory consumption (in
- * bytes) of this
- * object. Since sometimes
- * the size of objects can
- * not be determined exactly
- * (for example: what is the
- * memory consumption of an
- * STL <tt>std::map</tt> type with a
- * certain number of
- * elements?), this is only
- * an estimate. however often
- * quite close to the true
- * value.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object. Since sometimes the size of objects can not be determined exactly
+ * (for example: what is the memory consumption of an STL <tt>std::map</tt>
+ * type with a certain number of elements?), this is only an estimate.
+ * however often quite close to the true value.
*/
std::size_t memory_consumption () const;
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception.
const Function<dim> &f;
/**
- * Step size of the difference
- * formula.
+ * Step size of the difference formula.
*/
double h;
typename AutoDerivativeFunction<dim>::DifferenceFormula formula;
/**
- * Helper object. Contains the
- * increment vector for the
- * formula.
+ * Helper object. Contains the increment vector for the formula.
*/
std::vector<Point<dim> > incr;
};
DEAL_II_NAMESPACE_OPEN
/**
- * 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 might be useful to others as well at some
- * point.
+ * 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 might be
+ * useful to others as well at some point.
*
* @ingroup functions
*/
/**
- * The function <tt>xy</tt> in 2d and 3d, not implemented in 1d.
- * This function serves as an example for
- * a vanishing Laplacian.
+ * The function <tt>xy</tt> in 2d and 3d, not implemented in 1d. This
+ * function serves as an example for a vanishing Laplacian.
*
* @ingroup functions
* @author: Guido Kanschat, 2000
* boundary values on the domain $(-1,1)^d$. In the inside, it is the
* product of $1-x_i^2$ over all space dimensions.
*
- * Providing a non-zero argument to the constructor, the whole function
- * can be offset by a constant.
+ * Providing a non-zero argument to the constructor, the whole function can
+ * be offset by a constant.
*
* Together with the function, its derivatives and Laplacian are defined.
*
{
public:
/**
- * Constructor. Provide a
- * constant that will be added to
- * each function value.
+ * Constructor. Provide a constant that will be added to each function
+ * value.
*/
PillowFunction (const double offset=0.);
/**
- * 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)$.
+ * 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
{
public:
/**
- * Constructor which allows to
- * optionally generate a vector
- * valued cosine function with
- * the same value in each
- * component.
+ * Constructor which allows to optionally generate a vector valued cosine
+ * function with the same value in each component.
*/
CosineFunction (const unsigned int n_components = 1);
const unsigned int component = 0) const;
/**
- * Second derivatives at a
- * single point.
+ * Second derivatives at a single point.
*/
virtual Tensor<2,dim> hessian (const Point<dim> &p,
const unsigned int component = 0) const;
/**
- * Second derivatives at
- * multiple points.
+ * Second derivatives at multiple points.
*/
virtual void hessian_list (const std::vector<Point<dim> > &points,
std::vector<Tensor<2,dim> > &hessians,
/**
* Gradient of the cosine-shaped pillow function.
*
- * This is a vector-valued function with @p dim components, the
- * gradient of CosineFunction. On the square [-1,1], it has tangential
- * boundary conditions zero. Thus, it can be used to test
- * implementations of Maxwell operators without bothering about
- * boundary terms.
+ * This is a vector-valued function with @p dim components, the gradient of
+ * CosineFunction. On the square [-1,1], it has tangential boundary
+ * conditions zero. Thus, it can be used to test implementations of Maxwell
+ * operators without bothering about boundary terms.
*
* @ingroup functions
* @author Guido Kanschat, 2010
{
public:
/**
- * Constructor, creating a
- * function with @p dim components.
+ * Constructor, creating a function with @p dim components.
*/
CosineGradFunction ();
/**
* Gradient of the harmonic singularity on the L-shaped domain in 2D.
*
- * The gradient of LSingularityFunction, which is a vector valued
- * function with vanishing curl and divergence.
+ * The gradient of LSingularityFunction, which is a vector valued function
+ * with vanishing curl and divergence.
*
* @ingroup functions
* @author Guido Kanschat, 2010
{
public:
/**
- * Default constructor setting
- * the dimension to 2.
+ * Default constructor setting the dimension to 2.
*/
LSingularityGradFunction ();
virtual double value (const Point<2> &p,
* A jump in x-direction transported into some direction.
*
* If the advection is parallel to the y-axis, the function is
- * <tt>-atan(sx)</tt>, where <tt>s</tt> is the steepness parameter provided in
- * the constructor.
+ * <tt>-atan(sx)</tt>, where <tt>s</tt> is the steepness parameter provided
+ * in the constructor.
*
- * For different advection directions, this function will be turned in
- * the parameter space.
+ * For different advection directions, this function will be turned in the
+ * parameter space.
*
* Together with the function, its derivatives and Laplacian are defined.
*
{
public:
/**
- * Constructor. Provide the
- * advection direction here and
- * the steepness of the slope.
+ * Constructor. Provide the advection direction here and the steepness of
+ * the slope.
*/
JumpFunction (const Point<dim> &direction,
const double steepness);
const unsigned int component = 0) const;
/**
- * Function values at multiple
- * points.
+ * Function values at multiple points.
*/
virtual void value_list (const std::vector<Point<dim> > &points,
std::vector<double> &values,
const unsigned int component = 0) const;
/**
- Gradients at multiple points.
- */
+ * Gradients at multiple points.
+ */
virtual void gradient_list (const std::vector<Point<dim> > &points,
std::vector<Tensor<1,dim> > &gradients,
const unsigned int component = 0) const;
const unsigned int component = 0) const;
/**
- * Determine an estimate for
- * the memory consumption (in
- * bytes) of this
- * object. Since sometimes
- * the size of objects can
- * not be determined exactly
- * (for example: what is the
- * memory consumption of an
- * STL <tt>std::map</tt> type with a
- * certain number of
- * elements?), this is only
- * an estimate. however often
- * quite close to the true
- * value.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object. Since sometimes the size of objects can not be determined
+ * exactly (for example: what is the memory consumption of an STL
+ * <tt>std::map</tt> type with a certain number of elements?), this is
+ * only an estimate. however often quite close to the true value.
*/
std::size_t memory_consumption () const;
const Point<dim> direction;
/**
- * Steepness (maximal derivative)
- * of the slope.
+ * Steepness (maximal derivative) of the slope.
*/
const double steepness;
/**
- * Given a wavenumber vector generate a cosine function. The
- * wavenumber coefficient is given as a $d$-dimensional point $k$
- * in Fourier space, and the function is then recovered as $f(x) =
- * \cos(\sum_i k_i x_i) = Re(\exp(i k.x))$.
+ * Given a wavenumber vector generate a cosine function. The wavenumber
+ * coefficient is given as a $d$-dimensional point $k$ in Fourier space, and
+ * the function is then recovered as $f(x) = \cos(\sum_i k_i x_i) =
+ * Re(\exp(i k.x))$.
*
- * The class has its name from the fact that it resembles one
- * component of a Fourier cosine decomposition.
+ * The class has its name from the fact that it resembles one component of a
+ * Fourier cosine decomposition.
*
* @ingroup functions
* @author Wolfgang Bangerth, 2001
{
public:
/**
- * Constructor. Take the Fourier
- * coefficients in each space
- * direction as argument.
+ * Constructor. Take the Fourier coefficients in each space direction as
+ * argument.
*/
FourierCosineFunction (const Point<dim> &fourier_coefficients);
/**
- * Return the value of the
- * function at the given
- * point. Unless there is only
- * one component (i.e. the
- * function is scalar), you
- * should state the component you
- * want to have evaluated; it
- * defaults to zero, i.e. the
+ * Return the value of the function at the given point. Unless there is
+ * only one component (i.e. the function is scalar), you should state the
+ * component you want to have evaluated; it defaults to zero, i.e. the
* first component.
*/
virtual double value (const Point<dim> &p,
const unsigned int component = 0) const;
/**
- * Return the gradient of the
- * specified component of the
- * function at the given point.
+ * Return the gradient of the specified component of the function at the
+ * given point.
*/
virtual Tensor<1,dim> gradient (const Point<dim> &p,
const unsigned int component = 0) const;
/**
- * Compute the Laplacian of a
- * given component at point <tt>p</tt>.
+ * Compute the Laplacian of a given component at point <tt>p</tt>.
*/
virtual double laplacian (const Point<dim> &p,
const unsigned int component = 0) const;
/**
- * Given a wavenumber vector generate a sine function. The
- * wavenumber coefficient is given as a $d$-dimensional point $k$
- * in Fourier space, and the function is then recovered as $f(x) =
- * \sin(\sum_i k_i x_i) = Im(\exp(i k.x))$.
+ * Given a wavenumber vector generate a sine function. The wavenumber
+ * coefficient is given as a $d$-dimensional point $k$ in Fourier space, and
+ * the function is then recovered as $f(x) = \sin(\sum_i k_i x_i) =
+ * Im(\exp(i k.x))$.
*
- * The class has its name from the fact that it resembles one
- * component of a Fourier sine decomposition.
+ * The class has its name from the fact that it resembles one component of a
+ * Fourier sine decomposition.
*
* @ingroup functions
* @author Wolfgang Bangerth, 2001
{
public:
/**
- * Constructor. Take the Fourier
- * coefficients in each space
- * direction as argument.
+ * Constructor. Take the Fourier coefficients in each space direction as
+ * argument.
*/
FourierSineFunction (const Point<dim> &fourier_coefficients);
/**
- * Return the value of the
- * function at the given
- * point. Unless there is only
- * one component (i.e. the
- * function is scalar), you
- * should state the component you
- * want to have evaluated; it
- * defaults to zero, i.e. the
+ * Return the value of the function at the given point. Unless there is
+ * only one component (i.e. the function is scalar), you should state the
+ * component you want to have evaluated; it defaults to zero, i.e. the
* first component.
*/
virtual double value (const Point<dim> &p,
const unsigned int component = 0) const;
/**
- * Return the gradient of the
- * specified component of the
- * function at the given point.
+ * Return the gradient of the specified component of the function at the
+ * given point.
*/
virtual Tensor<1,dim> gradient (const Point<dim> &p,
const unsigned int component = 0) const;
/**
- * Compute the Laplacian of a
- * given component at point <tt>p</tt>.
+ * Compute the Laplacian of a given component at point <tt>p</tt>.
*/
virtual double laplacian (const Point<dim> &p,
const unsigned int component = 0) const;
/**
- * Given a sequence of wavenumber vectors and weights generate a sum
- * of sine functions. Each wavenumber coefficient is given as a
- * $d$-dimensional point $k$ in Fourier space, and the entire
- * function is then recovered as
+ * Given a sequence of wavenumber vectors and weights generate a sum of sine
+ * functions. Each wavenumber coefficient is given as a $d$-dimensional
+ * point $k$ in Fourier space, and the entire 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
{
public:
/**
- * Constructor. Take the Fourier
- * coefficients in each space
- * direction as argument.
+ * Constructor. Take the Fourier coefficients in each space direction as
+ * argument.
*/
FourierSineSum (const std::vector<Point<dim> > &fourier_coefficients,
const std::vector<double> &weights);
/**
- * Return the value of the
- * function at the given
- * point. Unless there is only
- * one component (i.e. the
- * function is scalar), you
- * should state the component you
- * want to have evaluated; it
- * defaults to zero, i.e. the
+ * Return the value of the function at the given point. Unless there is
+ * only one component (i.e. the function is scalar), you should state the
+ * component you want to have evaluated; it defaults to zero, i.e. the
* first component.
*/
virtual double value (const Point<dim> &p,
const unsigned int component = 0) const;
/**
- * Return the gradient of the
- * specified component of the
- * function at the given point.
+ * Return the gradient of the specified component of the function at the
+ * given point.
*/
virtual Tensor<1,dim> gradient (const Point<dim> &p,
const unsigned int component = 0) const;
/**
- * Compute the Laplacian of a
- * given component at point <tt>p</tt>.
+ * Compute the Laplacian of a given component at point <tt>p</tt>.
*/
virtual double laplacian (const Point<dim> &p,
const unsigned int component = 0) const;
private:
/**
- * Stored Fourier coefficients
- * and weights.
+ * Stored Fourier coefficients and weights.
*/
const std::vector<Point<dim> > fourier_coefficients;
const std::vector<double> weights;
/**
- * Given a sequence of wavenumber vectors and weights generate a sum
- * of cosine functions. Each wavenumber coefficient is given as a
- * $d$-dimensional point $k$ in Fourier space, and the entire
- * 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))$.
+ * Given a sequence of wavenumber vectors and weights generate a sum of
+ * cosine functions. Each wavenumber coefficient is given as a
+ * $d$-dimensional point $k$ in Fourier space, and the entire 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
{
public:
/**
- * Constructor. Take the Fourier
- * coefficients in each space
- * direction as argument.
+ * Constructor. Take the Fourier coefficients in each space direction as
+ * argument.
*/
FourierCosineSum (const std::vector<Point<dim> > &fourier_coefficients,
const std::vector<double> &weights);
/**
- * Return the value of the
- * function at the given
- * point. Unless there is only
- * one component (i.e. the
- * function is scalar), you
- * should state the component you
- * want to have evaluated; it
- * defaults to zero, i.e. the
+ * Return the value of the function at the given point. Unless there is
+ * only one component (i.e. the function is scalar), you should state the
+ * component you want to have evaluated; it defaults to zero, i.e. the
* first component.
*/
virtual double value (const Point<dim> &p,
const unsigned int component = 0) const;
/**
- * Return the gradient of the
- * specified component of the
- * function at the given point.
+ * Return the gradient of the specified component of the function at the
+ * given point.
*/
virtual Tensor<1,dim> gradient (const Point<dim> &p,
const unsigned int component = 0) const;
/**
- * Compute the Laplacian of a
- * given component at point <tt>p</tt>.
+ * Compute the Laplacian of a given component at point <tt>p</tt>.
*/
virtual double laplacian (const Point<dim> &p,
const unsigned int component = 0) const;
private:
/**
- * Stored Fourier coefficients
- * and weights.
+ * Stored Fourier coefficients and weights.
*/
const std::vector<Point<dim> > fourier_coefficients;
const std::vector<double> weights;
/**
- * Base function for cut-off function. This class stores the center
- * and the radius of the supporting ball of a cut-off function. It
- * also stores the number of the non-zero component, if the function
- * is vector-valued.
+ * Base function for cut-off function. This class stores the center and the
+ * radius of the supporting ball of a cut-off function. It also stores the
+ * number of the non-zero component, if the function is vector-valued.
*
* @ingroup functions
* @author Guido Kanschat, 2002
{
public:
/**
- * Value used in the
- * constructor of this and
- * derived classes to denote
- * that no component is
- * selected.
+ * Value used in the constructor of this and derived classes to denote
+ * that no component is selected.
*/
static const unsigned int no_component = numbers::invalid_unsigned_int;
/**
- * Constructor. Arguments are the
- * center of the ball and its
- * radius.
+ * Constructor. Arguments are the center of the ball and its radius.
*
- * If an argument <tt>select</tt> is
- * given and not -1, the
- * cut-off function will be
- * non-zero for this component
- * only.
+ * If an argument <tt>select</tt> is given and not -1, the cut-off
+ * function will be non-zero for this component only.
*/
CutOffFunctionBase (const double radius = 1.,
const Point<dim> = Point<dim>(),
const unsigned int select = CutOffFunctionBase<dim>::no_component);
/**
- * Move the center of the ball
- * to new point <tt>p</tt>.
+ * Move the center of the ball to new point <tt>p</tt>.
*/
void new_center (const Point<dim> &p);
double radius;
/**
- * Component selected. If
- * <tt>no_component</tt>, the function is
- * the same in all components.
+ * Component selected. If <tt>no_component</tt>, the function is the same
+ * in all components.
*/
const unsigned int selected;
};
/**
- * Cut-off function in L-infinity for an arbitrary ball. This
- * function is the characteristic function of a ball around <tt>center</tt>
- * with a specified <tt>radius</tt>, that is,
- * \f[
- * f = \chi(B_r(c)).
- * \f]
- * If vector valued, it can be restricted
- * to a single component.
+ * Cut-off function in L-infinity for an arbitrary ball. This function is
+ * the characteristic function of a ball around <tt>center</tt> with a
+ * specified <tt>radius</tt>, that is, \f[ f = \chi(B_r(c)). \f] If vector
+ * valued, it can be restricted to a single component.
*
* @ingroup functions
* @author Guido Kanschat, 2001, 2002
{
public:
/**
- * Constructor. Arguments are the
- * center of the ball and its
- * radius.
+ * Constructor. Arguments are the center of the ball and its radius.
*
- * If an argument <tt>select</tt> is
- * given and not -1, the
- * cut-off function will be
- * non-zero for this component
- * only.
+ * If an argument <tt>select</tt> is given and not -1, the cut-off
+ * function will be non-zero for this component only.
*/
CutOffFunctionLinfty (const double radius = 1.,
const Point<dim> = Point<dim>(),
/**
- * Cut-off function for an arbitrary ball. This function is a cone
- * with support in a ball of certain <tt>radius</tt> around <tt>center</tt>. The
- * maximum value is 1. If vector valued, it can be restricted
- * to a single component.
+ * Cut-off function for an arbitrary ball. This function is a cone with
+ * support in a ball of certain <tt>radius</tt> around <tt>center</tt>. The
+ * maximum value is 1. If vector valued, it can be restricted to a single
+ * component.
*
* @ingroup functions
* @author Guido Kanschat, 2001, 2002
{
public:
/**
- * Constructor. Arguments are the
- * center of the ball and its
- * radius.
+ * Constructor. Arguments are the center of the ball and its radius.
* radius.
*
- * If an argument <tt>select</tt> is
- * given, the cut-off function
- * will be non-zero for this
- * component only.
+ * If an argument <tt>select</tt> is given, the cut-off function will be
+ * non-zero for this component only.
*/
CutOffFunctionW1 (const double radius = 1.,
const Point<dim> = Point<dim>(),
/**
- * Cut-off function for an arbitrary ball. This is the traditional
- * cut-off function in C-infinity for a ball of certain <tt>radius</tt>
- * around <tt>center</tt>, $f(r)=exp(1-1/(1-r**2/s**2))$, where $r$ is the
- * distance to the center, and $s$ is the radius of the sphere. If
- * vector valued, it can be restricted to a single component.
+ * Cut-off function for an arbitrary ball. This is the traditional cut-off
+ * function in C-infinity for a ball of certain <tt>radius</tt> around
+ * <tt>center</tt>, $f(r)=exp(1-1/(1-r**2/s**2))$, where $r$ is the 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
{
public:
/**
- * Constructor. Arguments are the
- * center of the ball and its
- * radius.
+ * Constructor. Arguments are the center of the ball and its radius.
* radius.
*
- * If an argument <tt>select</tt> is
- * given, the cut-off function
- * will be non-zero for this
- * component only.
+ * If an argument <tt>select</tt> is given, the cut-off function will be
+ * non-zero for this component only.
*/
CutOffFunctionCinfty (const double radius = 1.,
const Point<dim> = Point<dim>(),
* $x^\alpha$, in 2-d the form $x_1^{\alpha_1}x_2^{\alpha_2}$, and in 3-d
* $x_1^{\alpha_1}x_2^{\alpha_2}x_3^{\alpha_3}$. Monomials are therefore
* described by a $dim$-tuple of exponents. Consequently, the class's
- * constructor takes a Tensor<1,dim> to describe the set of exponents. Most of
- * the time these exponents will of course be integers, but real exponents are
- * of course equally valid.
+ * constructor takes a Tensor<1,dim> to describe the set of exponents. Most
+ * of the time these exponents will of course be integers, but real
+ * exponents are of course equally valid.
*
* @author Wolfgang Bangerth, 2006
*/
{
public:
/**
- * Constructor. The first argument is
- * explained in the general description
- * of the class. The second argument
- * denotes the number of vector
- * components this object shall
- * represent. All vector components
- * will have the same value.
+ * Constructor. The first argument is explained in the general description
+ * of the class. The second argument denotes the number of vector
+ * components this object shall represent. All vector components will have
+ * the same value.
*/
Monomial (const Tensor<1,dim> &exponents,
const unsigned int n_components = 1);
const unsigned int component = 0) const;
/**
- * Return all components of a
- * vector-valued function at a
- * given point.
+ * Return all components of a vector-valued function at a given point.
*
- * <tt>values</tt> shall have the right
- * size beforehand,
- * i.e. #n_components.
+ * <tt>values</tt> shall have the right size beforehand, i.e.
+ * #n_components.
*/
virtual void vector_value (const Point<dim> &p,
Vector<double> &values) const;
/**
- * A scalar function that computes its values by (bi-, tri-)linear interpolation
- * from a set of point data that are arranged on a possibly non-uniform
- * tensor product mesh. In other words, considering the three-dimensional case,
- * let there be points $x_0,\ldotx, x_{K-1}$,
+ * A scalar function that computes its values by (bi-, tri-)linear
+ * interpolation from a set of point data that are arranged on a possibly
+ * non-uniform tensor product mesh. In other words, considering the three-
+ * dimensional case, let there be points $x_0,\ldotx, x_{K-1}$,
* $y_0,\ldots,y_{L-1}$, $z_1,\ldots,z_{M-1}$, and data $d_{klm}$ defined at
- * point $(x_k,y_l,z_m)^T$, then evaluating the function at a point
- * $\mathbf x=(x,y,z)$ will find the box so that
- * $x_k\le x\le x_{k+1}, y_l\le x\le y_{l+1}, z_m\le z\le z_{m+1}$, and do a
- * trilinear interpolation of the data on this cell. Similar operations are
- * done in lower dimensions.
+ * point $(x_k,y_l,z_m)^T$, then evaluating the function at a point $\mathbf
+ * x=(x,y,z)$ will find the box so that $x_k\le x\le x_{k+1}, y_l\le x\le
+ * y_{l+1}, z_m\le z\le z_{m+1}$, and do a trilinear interpolation of the
+ * data on this cell. Similar operations are done in lower dimensions.
*
* This class is most often used for either evaluating coefficients or right
- * hand sides that are provided experimentally at a number of points inside the
- * domain, or for comparing outputs of a solution on a finite element mesh
- * against previously obtained data defined on a grid.
+ * hand sides that are provided experimentally at a number of points inside
+ * the domain, or for comparing outputs of a solution on a finite element
+ * mesh against previously obtained data defined on a grid.
*
- * @note If the points $x_i$ are actually equally spaced on an interval $[x_0,x_1]$
- * and the same is true for the other data points in higher dimensions, you should
- * use the InterpolatedUniformGridData class instead.
+ * @note If the points $x_i$ are actually equally spaced on an interval
+ * $[x_0,x_1]$ and the same is true for the other data points in higher
+ * dimensions, you should use the InterpolatedUniformGridData class instead.
*
* If a point is requested outside the box defined by the end points of the
* coordinate arrays, then the function is assumed to simply extend by
- * constant values beyond the last data point in each coordinate
- * direction. (The class does not throw an error if a point lies outside the
- * box since it frequently happens that a point lies just outside the box
- * by an amount on the order of numerical roundoff.)
+ * constant values beyond the last data point in each coordinate direction.
+ * (The class does not throw an error if a point lies outside the box since
+ * it frequently happens that a point lies just outside the box by an amount
+ * on the order of numerical roundoff.)
*
- * @note The use of the related class InterpolatedUniformGridData
- * is discussed in step-53.
+ * @note The use of the related class InterpolatedUniformGridData is
+ * discussed in step-53.
*
* @author Wolfgang Bangerth, 2013
*/
/**
* Constructor.
* @param coordinate_values An array of dim arrays. Each of the inner
- * arrays contains the coordinate values $x_0,\ldotx, x_{K-1}$ and
- * similarly for the other coordinate directions. These arrays
- * need not have the same size. Obviously, we need dim such arrays
- * for a dim-dimensional function object. The coordinate values
- * within this array are assumed to be strictly ascending to allow
- * for efficient lookup.
- * @param data_values A dim-dimensional table of data at each of the
- * mesh points defined by the coordinate arrays above. Note that the
- * Table class has a number of conversion constructors that allow
- * converting other data types into a table where you specify this
- * argument.
+ * arrays contains the coordinate values $x_0,\ldotx, x_{K-1}$ and
+ * similarly for the other coordinate directions. These arrays need not
+ * have the same size. Obviously, we need dim such arrays for a dim-
+ * dimensional function object. The coordinate values within this array
+ * are assumed to be strictly ascending to allow for efficient lookup.
+ * @param data_values A dim-dimensional table of data at each of the mesh
+ * points defined by the coordinate arrays above. Note that the Table
+ * class has a number of conversion constructors that allow converting
+ * other data types into a table where you specify this argument.
*/
InterpolatedTensorProductGridData (const std_cxx11::array<std::vector<double>,dim> &coordinate_values,
const Table<dim,double> &data_values);
*
* @param p The point at which the function is to be evaluated.
* @param component The vector component. Since this function is scalar,
- * only zero is a valid argument here.
- * @return The interpolated value at this point. If the point lies outside
- * the set of coordinates, the function is extended by a constant.
+ * only zero is a valid argument here. @return The interpolated value at
+ * this point. If the point lies outside the set of coordinates, the
+ * function is extended by a constant.
*/
virtual
double
/**
- * A scalar function that computes its values by (bi-, tri-)linear interpolation
- * from a set of point data that are arranged on a uniformly spaced
- * tensor product mesh. In other words, considering the three-dimensional case,
- * let there be points $x_0,\ldotx, x_{K-1}$ that result from a uniform subdivision
- * of the interval $[x_0,x_{K-1}]$ into $K-1$ sub-intervals of size $\Delta x
- * = (x_{K-1}-x_0)/(K-1)$, and similarly
- * $y_0,\ldots,y_{L-1}$, $z_1,\ldots,z_{M-1}$. Also consider data $d_{klm}$ defined at
- * point $(x_k,y_l,z_m)^T$, then evaluating the function at a point
- * $\mathbf x=(x,y,z)$ will find the box so that
- * $x_k\le x\le x_{k+1}, y_l\le x\le y_{l+1}, z_m\le z\le z_{m+1}$, and do a
- * trilinear interpolation of the data on this cell. Similar operations are
- * done in lower dimensions.
+ * A scalar function that computes its values by (bi-, tri-)linear
+ * interpolation from a set of point data that are arranged on a uniformly
+ * spaced tensor product mesh. In other words, considering the three-
+ * dimensional case, let there be points $x_0,\ldotx, x_{K-1}$ that result
+ * from a uniform subdivision of the interval $[x_0,x_{K-1}]$ into $K-1$
+ * sub-intervals of size $\Delta x = (x_{K-1}-x_0)/(K-1)$, and similarly
+ * $y_0,\ldots,y_{L-1}$, $z_1,\ldots,z_{M-1}$. Also consider data $d_{klm}$
+ * defined at point $(x_k,y_l,z_m)^T$, then evaluating the function at a
+ * point $\mathbf x=(x,y,z)$ will find the box so that $x_k\le x\le x_{k+1},
+ * y_l\le x\le y_{l+1}, z_m\le z\le z_{m+1}$, and do a trilinear
+ * interpolation of the data on this cell. Similar operations are done in
+ * lower dimensions.
*
* This class is most often used for either evaluating coefficients or right
- * hand sides that are provided experimentally at a number of points inside the
- * domain, or for comparing outputs of a solution on a finite element mesh
- * against previously obtained data defined on a grid.
+ * hand sides that are provided experimentally at a number of points inside
+ * the domain, or for comparing outputs of a solution on a finite element
+ * mesh against previously obtained data defined on a grid.
*
* @note If you have a problem where the points $x_i$ are not equally spaced
* (e.g., they result from a computation on a graded mesh that is denser
*
* If a point is requested outside the box defined by the end points of the
* coordinate arrays, then the function is assumed to simply extend by
- * constant values beyond the last data point in each coordinate
- * direction. (The class does not throw an error if a point lies outside the
- * box since it frequently happens that a point lies just outside the box
- * by an amount on the order of numerical roundoff.)
+ * constant values beyond the last data point in each coordinate direction.
+ * (The class does not throw an error if a point lies outside the box since
+ * it frequently happens that a point lies just outside the box by an amount
+ * on the order of numerical roundoff.)
*
* @note The use of this class is discussed in step-53.
*
public:
/**
* Constructor
- * @param interval_endpoints The left and right end points of the (uniformly
- * subdivided) intervals in each of the coordinate directions.
- * @param n_subdivisions The number of subintervals of the subintervals
- * in each coordinate direction. A value of one for a coordinate
- * means that the interval is considered as one subinterval consisting
- * of the entire range. A value of two means that there are two subintervals
- * each with one half of the range, etc.
- * @param data_values A dim-dimensional table of data at each of the
- * mesh points defined by the coordinate arrays above. Note that the
- * Table class has a number of conversion constructors that allow
- * converting other data types into a table where you specify this
- * argument.
+ * @param interval_endpoints The left and right end points of the
+ * (uniformly subdivided) intervals in each of the coordinate directions.
+ * @param n_subdivisions The number of subintervals of the subintervals in
+ * each coordinate direction. A value of one for a coordinate means that
+ * the interval is considered as one subinterval consisting of the entire
+ * range. A value of two means that there are two subintervals each with
+ * one half of the range, etc.
+ * @param data_values A dim-dimensional table of data at each of the mesh
+ * points defined by the coordinate arrays above. Note that the Table
+ * class has a number of conversion constructors that allow converting
+ * other data types into a table where you specify this argument.
*/
InterpolatedUniformGridData (const std_cxx11::array<std::pair<double,double>,dim> &interval_endpoints,
const std_cxx11::array<unsigned int,dim> &n_subintervals,
*
* @param p The point at which the function is to be evaluated.
* @param component The vector component. Since this function is scalar,
- * only zero is a valid argument here.
- * @return The interpolated value at this point. If the point lies outside
- * the set of coordinates, the function is extended by a constant.
+ * only zero is a valid argument here. @return The interpolated value at
+ * this point. If the point lies outside the set of coordinates, the
+ * function is extended by a constant.
*/
virtual
double
{
public:
/**
- * Constructor for Parsed functions. Its arguments are the same of the
- * base class Function. The only difference is that this object needs to
- * be initialized with initialize() method before you can use it. If an
- * attempt to use this function is made before the initialize() method has
- * been called, then an exception is thrown.
+ * Constructor for Parsed functions. Its arguments are the same of the base
+ * class Function. The only difference is that this object needs to be
+ * initialized with initialize() method before you can use it. If an attempt
+ * to use this function is made before the initialize() method has been
+ * called, then an exception is thrown.
*/
FunctionParser (const unsigned int n_components = 1,
const double initial_time = 0.0);
typedef ConstMap::iterator ConstMapIterator;
/**
- * Initialize the function. This methods accepts the following
- * parameters:
+ * Initialize the function. This methods accepts the following parameters:
*
* <b>vars</b>: a string with the variables that will be used by the
* expressions to be evaluated. Note that the variables can have any name
* component of the point in which the function is evaluated, the second
* variable to the second component and so forth. If this function is also
* time dependent, then it is necessary to specify it by setting the
- * <tt>time_dependent</tt> parameter to true. An exception is thrown if
- * the number of variables specified here is different from dim (if this
- * function is not time-dependent) or from dim+1 (if it is time-
- * dependent).
+ * <tt>time_dependent</tt> parameter to true. An exception is thrown if the
+ * number of variables specified here is different from dim (if this
+ * function is not time-dependent) or from dim+1 (if it is time- dependent).
*
* <b>expressions</b>: a list of strings containing the expressions that
- * will be byte compiled by the internal parser (FunctionParser). Note
- * that the size of this vector must match exactly the number of
- * components of the FunctionParser, as declared in the constructor. If
- * this is not the case, an exception is thrown.
+ * will be byte compiled by the internal parser (FunctionParser). Note that
+ * the size of this vector must match exactly the number of components of
+ * the FunctionParser, as declared in the constructor. If this is not the
+ * case, an exception is thrown.
*
*
- * <b>constants</b>: a map of constants used to pass any necessary
- * constant that we want to specify in our expressions (in the example
- * above the number pi). An expression is valid if and only if it contains
- * only defined variables and defined constants (other than the functions
+ * <b>constants</b>: a map of constants used to pass any necessary constant
+ * that we want to specify in our expressions (in the example above the
+ * number pi). An expression is valid if and only if it contains only
+ * defined variables and defined constants (other than the functions
* specified above). If a constant is given whose name is not valid (eg:
* <tt>constants["sin"] = 1.5;</tt>) an exception is thrown.
*
* <b>time_dependent</b>. If this is a time dependent function, then the
- * last variable declared in <b>vars</b> is assumed to be the time
- * variable, and this->get_time() is used to initialize it when evaluating
- * the function. Naturally the number of variables parsed by the
- * initialize() method in this case is dim+1. The value of this parameter
- * defaults to false, i.e. do not consider time.
+ * last variable declared in <b>vars</b> is assumed to be the time variable,
+ * and this->get_time() is used to initialize it when evaluating the
+ * function. Naturally the number of variables parsed by the initialize()
+ * method in this case is dim+1. The value of this parameter defaults to
+ * false, i.e. do not consider time.
*/
void initialize (const std::string &vars,
const std::vector<std::string> &expressions,
const bool use_degrees = false) DEAL_II_DEPRECATED;
/**
- * Initialize the function. Same as above, but accepts a string rather
- * than a vector of strings. If this is a vector valued function, its
- * components are expected to be separated by a semicolon. An exception is
- * thrown if this method is called and the number of components
- * successfully parsed does not match the number of components of the base
- * function.
+ * Initialize the function. Same as above, but accepts a string rather than
+ * a vector of strings. If this is a vector valued function, its components
+ * are expected to be separated by a semicolon. An exception is thrown if
+ * this method is called and the number of components successfully parsed
+ * does not match the number of components of the base function.
*/
void initialize (const std::string &vars,
const std::string &expression,
/**
* A function that returns default names for variables, to be used in the
- * first argument of the initialize() functions: it returns "x" in 1d,
- * "x,y" in 2d, and "x,y,z" in 3d.
+ * first argument of the initialize() functions: it returns "x" in 1d, "x,y"
+ * in 2d, and "x,y,z" in 3d.
*/
static
std::string
default_variable_names ();
/**
- * Return the value of the function at the given point. Unless there is
- * only one component (i.e. the function is scalar), you should state the
- * component you want to have evaluated; it defaults to zero, i.e. the
- * first component.
+ * Return the value of the function at the given point. Unless there is only
+ * one component (i.e. the function is scalar), you should state the
+ * component you want to have evaluated; it defaults to zero, i.e. the first
+ * component.
*/
virtual double value (const Point<dim> &p,
const unsigned int component = 0) const;
* Return all components of a vector-valued function at the given point @p
* p.
*
- * <tt>values</tt> shall have the right size beforehand, i.e.
- * #n_components.
+ * <tt>values</tt> shall have the right size beforehand, i.e. #n_components.
*/
virtual void vector_value (const Point<dim> &p,
Vector<double> &values) const;
mutable Threads::ThreadLocalStorage<std::vector<mu::Parser> > fp;
/**
- * An array to keep track of all the constants, required to
- * initialize fp in each thread.
+ * An array to keep track of all the constants, required to initialize fp in
+ * each thread.
*/
std::map<std::string, double> constants;
/**
- * An array for the variable names, required to initialize fp in
- * each thread.
+ * An array for the variable names, required to initialize fp in each
+ * thread.
*/
std::vector<std::string> var_names;
std::vector<std::string> expressions;
/**
- * Initialize fp and vars on the current thread. This function may
- * only be called once per thread. A thread can test whether the
- * function has already been called by testing whether
- * 'fp.get().size()==0' (not initialized) or >0 (already
- * initialized).
+ * Initialize fp and vars on the current thread. This function may only be
+ * called once per thread. A thread can test whether the function has
+ * already been called by testing whether 'fp.get().size()==0' (not
+ * initialized) or >0 (already initialized).
*/
void init_muparser() const;
#endif
bool initialized;
/**
- * Number of variables. If this is also a function of time, then the
- * number of variables is dim+1, otherwise it is dim. In the case that
- * this is a time dependent function, the time is supposed to be the last
- * variable. If #n_vars is not identical to the number of the variables
- * parsed by the initialize() method, then an exception is thrown.
+ * Number of variables. If this is also a function of time, then the number
+ * of variables is dim+1, otherwise it is dim. In the case that this is a
+ * time dependent function, the time is supposed to be the last variable. If
+ * #n_vars is not identical to the number of the variables parsed by the
+ * initialize() method, then an exception is thrown.
*/
unsigned int n_vars;
};
DEAL_II_NAMESPACE_OPEN
/**
- * Support for time dependent functions.
- * The library was also designed for time dependent problems. For this
- * purpose, the function objects also contain a field which stores the
- * time, as well as functions manipulating them. Time independent problems
- * should not access or even abuse them for other purposes, but since one
- * normally does not create thousands of function objects, the gain in
- * generality weighs out the fact that we need not store the time value
- * for not time dependent problems. The second advantage is that the derived
- * standard classes like <tt>ZeroFunction</tt>, <tt>ConstantFunction</tt> etc also work
- * for time dependent problems.
+ * Support for time dependent functions. The library was also designed for
+ * time dependent problems. For this purpose, the function objects also
+ * contain a field which stores the time, as well as functions manipulating
+ * them. Time independent problems should not access or even abuse them for
+ * other purposes, but since one normally does not create thousands of
+ * function objects, the gain in generality weighs out the fact that we need
+ * not store the time value for not time dependent problems. The second
+ * advantage is that the derived standard classes like <tt>ZeroFunction</tt>,
+ * <tt>ConstantFunction</tt> etc also work for time dependent problems.
*
- * Access to the time goes through the following functions:
+ * Access to the time goes through the following functions:
* @verbatim
* <li> <tt>get_time</tt>: return the present value of the time variable.
* <li> <tt>set_time</tt>: set the time value to a specific value.
* <li> <tt>advance_time</tt>: increase the time by a certain time step.
* @endverbatim
- * The latter two functions are virtual, so that derived classes can
- * perform computations which need only be done once for every new time.
- * For example, if a time dependent function had a factor <tt>sin(t)</tt>, then
- * it may be a reasonable choice to calculate this factor in a derived
- * version of <tt>set_time</tt>, store it in a member variable and use that one
- * rather than computing it every time <tt>operator()</tt>, <tt>value_list</tt> or one
- * of the other functions is called.
+ * The latter two functions are virtual, so that derived classes can perform
+ * computations which need only be done once for every new time. For example,
+ * if a time dependent function had a factor <tt>sin(t)</tt>, then it may be a
+ * reasonable choice to calculate this factor in a derived version of
+ * <tt>set_time</tt>, store it in a member variable and use that one rather
+ * than computing it every time <tt>operator()</tt>, <tt>value_list</tt> or
+ * one of the other functions is called.
*
- * By default, the <tt>advance_time</tt> function calls the <tt>set_time</tt> function
- * with the new time, so it is sufficient in most cases to overload only
- * <tt>set_time</tt> for computations as sketched out above.
+ * By default, the <tt>advance_time</tt> function calls the <tt>set_time</tt>
+ * function with the new time, so it is sufficient in most cases to overload
+ * only <tt>set_time</tt> for computations as sketched out above.
*
- * The constructor of this class takes an initial value for the time
- * variable, which defaults to zero. Because a default value is given,
- * none of the derived classes needs to take an initial value for the
- * time variable if not needed.
+ * The constructor of this class takes an initial value for the time variable,
+ * which defaults to zero. Because a default value is given, none of the
+ * derived classes needs to take an initial value for the time variable if not
+ * needed.
*
- * Once again the warning: do not use the <tt>time</tt> variable for any other
- * purpose than the intended one! This will inevitably lead to confusion.
+ * Once again the warning: do not use the <tt>time</tt> variable for any other
+ * purpose than the intended one! This will inevitably lead to confusion.
*
*
- * @ingroup functions
- * @author Wolfgang Bangerth, Guido Kanschat, 1998, 1999
+ * @ingroup functions
+ * @author Wolfgang Bangerth, Guido Kanschat, 1998, 1999
*/
template <typename Number=double>
class FunctionTime
{
public:
/**
- * Constructor. May take an initial vakue
- * for the time variable, which defaults
- * to zero.
+ * Constructor. May take an initial vakue for the time variable, which
+ * defaults to zero.
*/
FunctionTime (const Number initial_time = Number(0.0));
Number get_time () const;
/**
- * Set the time to <tt>new_time</tt>, overwriting
- * the old value.
+ * Set the time to <tt>new_time</tt>, overwriting the old value.
*/
virtual void set_time (const Number new_time);
/**
- * Advance the time by the given
- * time step <tt>delta_t</tt>.
+ * Advance the time by the given time step <tt>delta_t</tt>.
*/
virtual void advance_time (const Number delta_t);
/**
- * A class that can represent the kinds of objects a triangulation is
- * made up of: vertices, lines, quads and hexes.
+ * A class that can represent the kinds of objects a triangulation is made up
+ * of: vertices, lines, quads and hexes.
*
- * The class is rather primitive: it only stores a single integer
- * that represents the dimensionality of the object represented.
- * In other words, this class is useful primarily as a way to
- * pass around an object whose data type explains what it does
- * (unlike just passing around an integer), and for providing
- * symbolic names for these objects such as GeometryPrimitive::vertex
- * instead of an integer zero.
+ * The class is rather primitive: it only stores a single integer that
+ * represents the dimensionality of the object represented. In other words,
+ * this class is useful primarily as a way to pass around an object whose data
+ * type explains what it does (unlike just passing around an integer), and for
+ * providing symbolic names for these objects such as
+ * GeometryPrimitive::vertex instead of an integer zero.
*
- * Since the ability to identify such objects with the integral
- * dimension of the object represented, this class provides
- * conversion operators to and from unsigned integers.
+ * Since the ability to identify such objects with the integral dimension of
+ * the object represented, this class provides conversion operators to and
+ * from unsigned integers.
*
* @author Wolfgang Bangerth, 2014
*/
{
public:
/**
- * An enumeration providing symbolic names for the
- * objects that can be represented by this class.
- * The numeric values of these symbolic names equal
- * the geometric dimensionality of the represented
- * objects to make conversion from and to integer
- * variables simpler.
+ * An enumeration providing symbolic names for the objects that can be
+ * represented by this class. The numeric values of these symbolic names
+ * equal the geometric dimensionality of the represented objects to make
+ * conversion from and to integer variables simpler.
*/
enum Object
{
};
/**
- * Constructor. Initialize the object with the
- * given argument representing a vertex, line, etc.
+ * Constructor. Initialize the object with the given argument representing a
+ * vertex, line, etc.
*/
GeometryPrimitive (const Object object);
/**
- * Constructor. Initialize the object with an
- * integer that should represent the dimensionality of
- * the geometric object in question. This will usually be
- * a number between zero (a vertex) and three (a hexahedron).
+ * Constructor. Initialize the object with an integer that should represent
+ * the dimensionality of the geometric object in question. This will usually
+ * be a number between zero (a vertex) and three (a hexahedron).
*/
GeometryPrimitive (const unsigned int object_dimension);
/**
- * Return the integral dimension of the object
- * currently represented, i.e. zero for a vertex,
- * one for a line, etc.
+ * Return the integral dimension of the object currently represented, i.e.
+ * zero for a vertex, one for a line, etc.
*/
operator unsigned int () const;
/**
- * A class that provides possible choices for isotropic and
- * anisotropic refinement flags in the current space dimension.
+ * A class that provides possible choices for isotropic and anisotropic
+ * refinement flags in the current space dimension.
*
- * This general template is unused except in some weird template
- * constructs. Actual is made, however, of the specializations
+ * This general template is unused except in some weird template constructs.
+ * Actual is made, however, of the specializations
* <code>RefinementPossibilities@<1@></code>,
* <code>RefinementPossibilities@<2@></code>, and
* <code>RefinementPossibilities@<3@></code>.
struct RefinementPossibilities
{
/**
- * Possible values for refinement
- * cases in the current
- * dimension.
- *
- * Note the construction of the
- * values: the lowest bit
- * describes a cut of the x-axis,
- * the second to lowest bit
- * corresponds to a cut of the
- * y-axis and the third to lowest
- * bit corresponds to a cut of
- * the z-axis. Thus, the
- * following relations hold
- * (among others):
+ * Possible values for refinement cases in the current dimension.
+ *
+ * Note the construction of the values: the lowest bit describes a cut of
+ * the x-axis, the second to lowest bit corresponds to a cut of the y-axis
+ * and the third to lowest bit corresponds to a cut of the z-axis. Thus, the
+ * following relations hold (among others):
*
* @code
* cut_xy == cut_x | cut_y
* cut_x == cut_xy & cut_xz
* @endcode
*
- * Only those cuts that are
- * reasonable in a given space
- * dimension are offered, of
- * course.
+ * Only those cuts that are reasonable in a given space dimension are
+ * offered, of course.
*
- * In addition, the tag
- * <code>isotropic_refinement</code>
- * denotes isotropic refinement
- * in the space dimension
- * selected by the template
- * argument of this class.
+ * In addition, the tag <code>isotropic_refinement</code> denotes isotropic
+ * refinement in the space dimension selected by the template argument of
+ * this class.
*/
enum Possibilities
{
/**
- * A class that provides possible choices for isotropic and
- * anisotropic refinement flags in the current space dimension.
+ * A class that provides possible choices for isotropic and anisotropic
+ * refinement flags in the current space dimension.
*
* This specialization is used for <code>dim=1</code>, where it offers
* refinement in x-direction.
struct RefinementPossibilities<1>
{
/**
- * Possible values for refinement
- * cases in the current
- * dimension.
- *
- * Note the construction of the
- * values: the lowest bit
- * describes a cut of the x-axis,
- * the second to lowest bit
- * corresponds to a cut of the
- * y-axis and the third to lowest
- * bit corresponds to a cut of
- * the z-axis. Thus, the
- * following relations hold
- * (among others):
+ * Possible values for refinement cases in the current dimension.
+ *
+ * Note the construction of the values: the lowest bit describes a cut of
+ * the x-axis, the second to lowest bit corresponds to a cut of the y-axis
+ * and the third to lowest bit corresponds to a cut of the z-axis. Thus, the
+ * following relations hold (among others):
*
* @code
* cut_xy == cut_x | cut_y
* cut_x == cut_xy & cut_xz
* @endcode
*
- * Only those cuts that are
- * reasonable in a given space
- * dimension are offered, of
- * course.
+ * Only those cuts that are reasonable in a given space dimension are
+ * offered, of course.
*
- * In addition, the tag
- * <code>isotropic_refinement</code>
- * denotes isotropic refinement
- * in the space dimension
- * selected by the template
- * argument of this class.
+ * In addition, the tag <code>isotropic_refinement</code> denotes isotropic
+ * refinement in the space dimension selected by the template argument of
+ * this class.
*/
enum Possibilities
{
/**
- * A class that provides possible choices for isotropic and
- * anisotropic refinement flags in the current space dimension.
+ * A class that provides possible choices for isotropic and anisotropic
+ * refinement flags in the current space dimension.
*
* This specialization is used for <code>dim=2</code>, where it offers
* refinement in x- and y-direction separately, as well as isotropic
struct RefinementPossibilities<2>
{
/**
- * Possible values for refinement
- * cases in the current
- * dimension.
- *
- * Note the construction of the
- * values: the lowest bit
- * describes a cut of the x-axis,
- * the second to lowest bit
- * corresponds to a cut of the
- * y-axis and the third to lowest
- * bit corresponds to a cut of
- * the z-axis. Thus, the
- * following relations hold
- * (among others):
+ * Possible values for refinement cases in the current dimension.
+ *
+ * Note the construction of the values: the lowest bit describes a cut of
+ * the x-axis, the second to lowest bit corresponds to a cut of the y-axis
+ * and the third to lowest bit corresponds to a cut of the z-axis. Thus, the
+ * following relations hold (among others):
*
* @code
* cut_xy == cut_x | cut_y
* cut_x == cut_xy & cut_xz
* @endcode
*
- * Only those cuts that are
- * reasonable in a given space
- * dimension are offered, of
- * course.
+ * Only those cuts that are reasonable in a given space dimension are
+ * offered, of course.
*
- * In addition, the tag
- * <code>isotropic_refinement</code>
- * denotes isotropic refinement
- * in the space dimension
- * selected by the template
- * argument of this class.
+ * In addition, the tag <code>isotropic_refinement</code> denotes isotropic
+ * refinement in the space dimension selected by the template argument of
+ * this class.
*/
enum Possibilities
{
/**
- * A class that provides possible choices for isotropic and
- * anisotropic refinement flags in the current space dimension.
+ * A class that provides possible choices for isotropic and anisotropic
+ * refinement flags in the current space dimension.
*
* This specialization is used for <code>dim=3</code>, where it offers
- * refinement in x-, y- and z-direction separately, as well as
- * combinations of these and isotropic refinement in all directions at
- * the same time.
+ * refinement in x-, y- and z-direction separately, as well as combinations of
+ * these and isotropic refinement in all directions at the same time.
*
* @ingroup aniso
* @author Ralf Hartmann, 2005, Wolfgang Bangerth, 2007
struct RefinementPossibilities<3>
{
/**
- * Possible values for refinement
- * cases in the current
- * dimension.
- *
- * Note the construction of the
- * values: the lowest bit
- * describes a cut of the x-axis,
- * the second to lowest bit
- * corresponds to a cut of the
- * y-axis and the third to lowest
- * bit corresponds to a cut of
- * the z-axis. Thus, the
- * following relations hold
- * (among others):
+ * Possible values for refinement cases in the current dimension.
+ *
+ * Note the construction of the values: the lowest bit describes a cut of
+ * the x-axis, the second to lowest bit corresponds to a cut of the y-axis
+ * and the third to lowest bit corresponds to a cut of the z-axis. Thus, the
+ * following relations hold (among others):
*
* @code
* cut_xy == cut_x | cut_y
* cut_x == cut_xy & cut_xz
* @endcode
*
- * Only those cuts that are
- * reasonable in a given space
- * dimension are offered, of
- * course.
+ * Only those cuts that are reasonable in a given space dimension are
+ * offered, of course.
*
- * In addition, the tag
- * <code>isotropic_refinement</code>
- * denotes isotropic refinement
- * in the space dimension
- * selected by the template
- * argument of this class.
+ * In addition, the tag <code>isotropic_refinement</code> denotes isotropic
+ * refinement in the space dimension selected by the template argument of
+ * this class.
*/
enum Possibilities
{
/**
- * A class storing the possible anisotropic and isotropic refinement
- * cases of an object with <code>dim</code> dimensions (for example,
- * for a line <code>dim=1</code> in whatever space dimension we are,
- * for a quad <code>dim=2</code>, etc.). Possible values of this class
- * are the ones listed in the enumeration declared within the class.
+ * A class storing the possible anisotropic and isotropic refinement cases of
+ * an object with <code>dim</code> dimensions (for example, for a line
+ * <code>dim=1</code> in whatever space dimension we are, for a quad
+ * <code>dim=2</code>, etc.). Possible values of this class are the ones
+ * listed in the enumeration declared within the class.
*
* @ingroup aniso
* @author Ralf Hartmann, 2005, Wolfgang Bangerth, 2007
{
public:
/**
- * Default constructor. Initialize the
- * refinement case with no_refinement.
+ * Default constructor. Initialize the refinement case with no_refinement.
*/
RefinementCase ();
/**
- * Constructor. Take and store a
- * value indicating a particular
- * refinement from the list of
- * possible refinements specified
- * in the base class.
+ * Constructor. Take and store a value indicating a particular refinement
+ * from the list of possible refinements specified in the base class.
*/
RefinementCase (const typename RefinementPossibilities<dim>::Possibilities refinement_case);
/**
- * Constructor. Take and store a
- * value indicating a particular
- * refinement as a bit field. To
- * avoid implicit conversions to
- * and from integral values, this
- * constructor is marked as
- * explicit.
+ * Constructor. Take and store a value indicating a particular refinement as
+ * a bit field. To avoid implicit conversions to and from integral values,
+ * this constructor is marked as explicit.
*/
explicit RefinementCase (const unsigned char refinement_case);
/**
- * Return the numeric value
- * stored by this class. While
- * the presence of this operator
- * might seem dangerous, it is
- * useful in cases where one
- * would like to have code like
- * <tt>switch
- * (refinement_flag)... case
- * RefinementCase<dim>::cut_x:
- * ... </tt>, which can be
- * written as <code>switch
- * (static_cast@<unsigned
- * char@>(refinement_flag)</code>. Another
- * application is to use an
- * object of the current type as
- * an index into an array;
- * however, this use is
- * deprecated as it assumes a
- * certain mapping from the
- * symbolic flags defined in the
- * RefinementPossibilities base
- * class to actual numerical
- * values (the array indices).
+ * Return the numeric value stored by this class. While the presence of this
+ * operator might seem dangerous, it is useful in cases where one would like
+ * to have code like <tt>switch (refinement_flag)... case
+ * RefinementCase<dim>::cut_x: ... </tt>, which can be written as
+ * <code>switch (static_cast@<unsigned char@>(refinement_flag)</code>.
+ * Another application is to use an object of the current type as an index
+ * into an array; however, this use is deprecated as it assumes a certain
+ * mapping from the symbolic flags defined in the RefinementPossibilities
+ * base class to actual numerical values (the array indices).
*/
operator unsigned char () const;
/**
- * Return the union of the
- * refinement flags represented
- * by the current object and the
- * one given as argument.
+ * Return the union of the refinement flags represented by the current
+ * object and the one given as argument.
*/
RefinementCase operator | (const RefinementCase &r) const;
/**
- * Return the intersection of the
- * refinement flags represented
- * by the current object and the
- * one given as argument.
+ * Return the intersection of the refinement flags represented by the
+ * current object and the one given as argument.
*/
RefinementCase operator & (const RefinementCase &r) const;
/**
- * Return the negation of the
- * refinement flags represented
- * by the current object. For
- * example, in 2d, if the current
- * object holds the flag
- * <code>cut_x</code>, then the
- * returned value will be
- * <code>cut_y</code>; if the
- * current value is
- * <code>isotropic_refinement</code>
- * then the result will be
- * <code>no_refinement</code>;
- * etc.
+ * Return the negation of the refinement flags represented by the current
+ * object. For example, in 2d, if the current object holds the flag
+ * <code>cut_x</code>, then the returned value will be <code>cut_y</code>;
+ * if the current value is <code>isotropic_refinement</code> then the result
+ * will be <code>no_refinement</code>; etc.
*/
RefinementCase operator ~ () const;
/**
- * Return the flag that
- * corresponds to cutting a cell
- * along the axis given as
- * argument. For example, if
- * <code>i=0</code> then the
- * returned value is
+ * Return the flag that corresponds to cutting a cell along the axis given
+ * as argument. For example, if <code>i=0</code> then the returned value is
* <tt>RefinementPossibilities<dim>::cut_x</tt>.
*/
static
RefinementCase cut_axis (const unsigned int i);
/**
- * Return the amount of memory
- * occupied by an object of this
- * type.
+ * Return the amount of memory occupied by an object of this type.
*/
static std::size_t memory_consumption ();
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the purpose
+ * of serialization
*/
template <class Archive>
void serialize(Archive &ar,
private:
/**
- * Store the refinement case as a
- * bit field with as many bits as
- * are necessary in any given
- * dimension.
+ * Store the refinement case as a bit field with as many bits as are
+ * necessary in any given dimension.
*/
unsigned char value :
(dim > 0 ? dim : 1);
/**
- * A class that provides all possible situations a face (in the
- * current space dimension @p dim) might be subdivided into
- * subfaces. For <code>dim=1</code> and <code>dim=2</code> they
- * correspond to the cases given in
- * <code>RefinementPossibilities@<dim-1@></code>. However,
- * <code>SubfacePossibilities@<3@></code> includes the refinement
- * cases of <code>RefinementPossibilities@<2@></code>, but
- * additionally some subface possibilities a face might be subdivided
- * into which occur through repeated anisotropic refinement steps
- * performed on one of two neighboring cells.
+ * A class that provides all possible situations a face (in the current
+ * space dimension @p dim) might be subdivided into subfaces. For
+ * <code>dim=1</code> and <code>dim=2</code> they correspond to the cases
+ * given in <code>RefinementPossibilities@<dim-1@></code>. However,
+ * <code>SubfacePossibilities@<3@></code> includes the refinement cases of
+ * <code>RefinementPossibilities@<2@></code>, but additionally some subface
+ * possibilities a face might be subdivided into which occur through
+ * repeated anisotropic refinement steps performed on one of two neighboring
+ * cells.
*
- * This general template is unused except in some weird template
- * constructs. Actual is made, however, of the specializations
+ * This general template is unused except in some weird template constructs.
+ * Actual is made, however, of the specializations
* <code>SubfacePossibilities@<1@></code>,
* <code>SubfacePossibilities@<2@></code> and
* <code>SubfacePossibilities@<3@></code>.
struct SubfacePossibilities
{
/**
- * Possible cases of faces
- * being subdivided into
- * subface.
+ * Possible cases of faces being subdivided into subface.
*/
enum Possibilities
{
/**
- * A class that provides all possible situations a face (in the
- * current space dimension @p dim) might be subdivided into
- * subfaces.
+ * A class that provides all possible situations a face (in the current
+ * space dimension @p dim) might be subdivided into subfaces.
*
* For <code>dim=0</code> we provide a dummy implementation only.
*
struct SubfacePossibilities<0>
{
/**
- * Possible cases of faces
- * being subdivided into
- * subface.
+ * Possible cases of faces being subdivided into subface.
*
* Dummy implementation.
*/
/**
- * A class that provides all possible situations a face (in the
- * current space dimension @p dim) might be subdivided into
- * subfaces.
+ * A class that provides all possible situations a face (in the current
+ * space dimension @p dim) might be subdivided into subfaces.
*
- * For <code>dim=1</code> there are no faces. Thereby, there are no
- * subface possibilities.
+ * For <code>dim=1</code> there are no faces. Thereby, there are no subface
+ * possibilities.
*
* @ingroup aniso
* @author Ralf Hartmann, 2008
struct SubfacePossibilities<1>
{
/**
- * Possible cases of faces
- * being subdivided into
- * subface.
+ * Possible cases of faces being subdivided into subface.
*
- * In 1d there are no faces,
- * thus no subface
- * possibilities.
+ * In 1d there are no faces, thus no subface possibilities.
*/
enum Possibilities
{
/**
- * A class that provides all possible situations a face (in the
- * current space dimension @p dim) might be subdivided into
- * subfaces.
+ * A class that provides all possible situations a face (in the current
+ * space dimension @p dim) might be subdivided into subfaces.
*
- * This specialization is used for <code>dim=2</code>, where it offers
- * the following possibilities: a face (line) being refined
+ * This specialization is used for <code>dim=2</code>, where it offers the
+ * following possibilities: a face (line) being refined
* (<code>case_x</code>) or not refined (<code>case_no</code>).
*
* @ingroup aniso
struct SubfacePossibilities<2>
{
/**
- * Possible cases of faces
- * being subdivided into
- * subface.
+ * Possible cases of faces being subdivided into subface.
*
- * In 2d there are following
- * possibilities: a face (line)
- * being refined *
- * (<code>case_x</code>) or not
- * refined
- * (<code>case_no</code>).
- */
+ * In 2d there are following possibilities: a face (line) being refined *
+ * (<code>case_x</code>) or not refined (<code>case_no</code>).
+ */
enum Possibilities
{
case_none = 0,
/**
- * A class that provides all possible situations a face (in the
- * current space dimension @p dim) might be subdivided into
- * subfaces.
+ * A class that provides all possible situations a face (in the current
+ * space dimension @p dim) might be subdivided into subfaces.
*
* This specialization is used for dim=3, where it offers following
- * possibilities: a face (quad) being refined in x- or y-direction (in
- * the face-intern coordinate system) separately, (<code>case_x</code>
- * or (<code>case_y</code>), and in both directions
- * (<code>case_x</code> which corresponds to
- * (<code>case_isotropic</code>). Additionally, it offers the
- * possibilities a face can have through repeated anisotropic
- * refinement steps performed on one of the two neighboring cells. It
- * might be possible for example, that a face (quad) is refined with
- * <code>cut_x</code> and afterwards the left child is again refined
- * with <code>cut_y</code>, so that there are three active
- * subfaces. Note, however, that only refinement cases are allowed
- * such that each line on a face between two hexes has not more than
- * one hanging node. Furthermore, it is not allowed that two
- * neighboring hexes are refined such that one of the hexes refines
- * the common face with <code>cut_x</code> and the other hex refines
- * that face with <code>cut_y</code>. In fact,
+ * possibilities: a face (quad) being refined in x- or y-direction (in the
+ * face-intern coordinate system) separately, (<code>case_x</code> or
+ * (<code>case_y</code>), and in both directions (<code>case_x</code> which
+ * corresponds to (<code>case_isotropic</code>). Additionally, it offers the
+ * possibilities a face can have through repeated anisotropic refinement
+ * steps performed on one of the two neighboring cells. It might be
+ * possible for example, that a face (quad) is refined with
+ * <code>cut_x</code> and afterwards the left child is again refined with
+ * <code>cut_y</code>, so that there are three active subfaces. Note,
+ * however, that only refinement cases are allowed such that each line on a
+ * face between two hexes has not more than one hanging node. Furthermore,
+ * it is not allowed that two neighboring hexes are refined such that one of
+ * the hexes refines the common face with <code>cut_x</code> and the other
+ * hex refines that face with <code>cut_y</code>. In fact,
* Triangulation::prepare_coarsening_and_refinement takes care of this
- * situation and ensures that each face of a refined cell is
- * completely contained in a single face of neighboring cells.
+ * situation and ensures that each face of a refined cell is completely
+ * contained in a single face of neighboring cells.
*
- * The following drawings explain the SubfacePossibilities and give
- * the corresponding subface numbers:
+ * The following drawings explain the SubfacePossibilities and give the
+ * corresponding subface numbers:
* @code
-
- *-------*
- | |
- | 0 | case_none
- | |
- *-------*
-
- *---*---*
- | | |
- | 0 | 1 | case_x
- | | |
- *---*---*
-
- *---*---*
- | 1 | |
- *---* 2 | case_x1y
- | 0 | |
- *---*---*
-
- *---*---*
- | | 2 |
- | 0 *---* case_x2y
- | | 1 |
- *---*---*
-
- *---*---*
- | 1 | 3 |
- *---*---* case_x1y2y (successive refinement: first cut_x, then cut_y for both children)
- | 0 | 2 |
- *---*---*
-
- *-------*
- | 1 |
- *-------* case_y
- | 0 |
- *-------*
-
- *-------*
- | 2 |
- *---*---* case_y1x
- | 0 | 1 |
- *---*---*
-
- *---*---*
- | 1 | 2 |
- *---*---* case_y2x
- | 0 |
- *-------*
-
- *---*---*
- | 2 | 3 |
- *---*---* case_y1x2x (successive refinement: first cut_y, then cut_x for both children)
- | 0 | 1 |
- *---+---*
-
- *---*---*
- | 2 | 3 |
- *---*---* case_xy (one isotropic refinement step)
- | 0 | 1 |
- *---*---*
-
+ *
+ * *-------*
+ * | |
+ * | 0 | case_none
+ * | |
+ * *-------*
+ *
+ * *---*---*
+ * | | |
+ * | 0 | 1 | case_x
+ * | | |
+ * *---*---*
+ *
+ * *---*---*
+ * | 1 | |
+ * *---* 2 | case_x1y
+ * | 0 | |
+ * *---*---*
+ *
+ * *---*---*
+ * | | 2 |
+ * | 0 *---* case_x2y
+ * | | 1 |
+ * *---*---*
+ *
+ * *---*---*
+ * | 1 | 3 |
+ * *---*---* case_x1y2y (successive refinement: first cut_x, then cut_y for both children)
+ * | 0 | 2 |
+ * *---*---*
+ *
+ * *-------*
+ * | 1 |
+ * *-------* case_y
+ * | 0 |
+ * *-------*
+ *
+ * *-------*
+ * | 2 |
+ * *---*---* case_y1x
+ * | 0 | 1 |
+ * *---*---*
+ *
+ * *---*---*
+ * | 1 | 2 |
+ * *---*---* case_y2x
+ * | 0 |
+ * *-------*
+ *
+ * *---*---*
+ * | 2 | 3 |
+ * *---*---* case_y1x2x (successive refinement: first cut_y, then cut_x for both children)
+ * | 0 | 1 |
+ * *---+---*
+ *
+ * *---*---*
+ * | 2 | 3 |
+ * *---*---* case_xy (one isotropic refinement step)
+ * | 0 | 1 |
+ * *---*---*
+ *
* @endcode
*
* @ingroup aniso
struct SubfacePossibilities<3>
{
/**
- * Possible cases of faces
- * being subdivided into
- * subface.
+ * Possible cases of faces being subdivided into subface.
*
- * See documentation to the
- * SubfacePossibilities<3> for
- * more details on the subface
- * possibilities.
+ * See documentation to the SubfacePossibilities<3> for more details on
+ * the subface possibilities.
*/
enum Possibilities
{
/**
- * A class that provides all possible cases a face (in the
- * current space dimension @p dim) might be subdivided into
- * subfaces.
+ * A class that provides all possible cases a face (in the current space
+ * dimension @p dim) might be subdivided into subfaces.
*
* @ingroup aniso
* @author Ralf Hartmann, 2008
{
public:
/**
- * Constructor. Take and store
- * a value indicating a
- * particular subface
- * possibility in the list of
- * possible situations
- * specified in the base class.
+ * Constructor. Take and store a value indicating a particular subface
+ * possibility in the list of possible situations specified in the base
+ * class.
*/
SubfaceCase (const typename SubfacePossibilities<dim>::Possibilities subface_possibility);
/**
- * Return the numeric value
- * stored by this class. While
- * the presence of this operator
- * might seem dangerous, it is
- * useful in cases where one
- * would like to have code like
- * <code>switch
- * (subface_case)... case
- * SubfaceCase::case_x:
- * ... </code>, which can be
- * written as <code>switch
- * (static_cast@<unsigned
- * char@>(subface_case)</code>. Another
- * application is to use an
- * object of the current type as
- * an index into an array;
- * however, this use is
- * deprecated as it assumes a
- * certain mapping from the
- * symbolic flags defined in the
- * SubfacePossibilities
- * base class to actual numerical
- * values (the array indices).
+ * Return the numeric value stored by this class. While the presence of
+ * this operator might seem dangerous, it is useful in cases where one
+ * would like to have code like <code>switch (subface_case)... case
+ * SubfaceCase::case_x: ... </code>, which can be written as <code>switch
+ * (static_cast@<unsigned char@>(subface_case)</code>. Another application
+ * is to use an object of the current type as an index into an array;
+ * however, this use is deprecated as it assumes a certain mapping from
+ * the symbolic flags defined in the SubfacePossibilities base class to
+ * actual numerical values (the array indices).
*/
operator unsigned char () const;
/**
- * Return the amount of memory
- * occupied by an object of this
- * type.
+ * Return the amount of memory occupied by an object of this type.
*/
static std::size_t memory_consumption ();
private:
/**
- * Store the refinement case as a
- * bit field with as many bits as
- * are necessary in any given
- * dimension.
+ * Store the refinement case as a bit field with as many bits as are
+ * necessary in any given dimension.
*/
unsigned char value :
(dim == 3 ? 4 : 1);
/**
- * Topological description of zero dimensional cells,
- * i.e. points. This class might not look too useful but often is if
- * in a certain dimension we would like to enquire information about
- * objects with dimension one lower than the present, e.g. about
- * faces.
- *
- * This class contains as static members information on vertices and
- * faces of a @p dim-dimensional grid cell. The interface is the same
- * for all dimensions. If a value is of no use in a low dimensional
- * cell, it is (correctly) set to zero, e.g. #max_children_per_face in
- * 1d.
- *
- * This information should always replace hard-coded numbers of
- * vertices, neighbors and so on, since it can be used dimension
- * independently.
+ * Topological description of zero dimensional cells, i.e. points. This class
+ * might not look too useful but often is if in a certain dimension we would
+ * like to enquire information about objects with dimension one lower than the
+ * present, e.g. about faces.
+ *
+ * This class contains as static members information on vertices and faces of
+ * a @p dim-dimensional grid cell. The interface is the same for all
+ * dimensions. If a value is of no use in a low dimensional cell, it is
+ * (correctly) set to zero, e.g. #max_children_per_face in 1d.
+ *
+ * This information should always replace hard-coded numbers of vertices,
+ * neighbors and so on, since it can be used dimension independently.
*
* @ingroup grid geomprimitives aniso
* @author Wolfgang Bangerth, 1998
{
/**
- * Maximum number of children of
- * a cell, i.e. the number of
- * children of an isotropically
- * refined cell.
+ * Maximum number of children of a cell, i.e. the number of children of an
+ * isotropically refined cell.
*
- * If a cell is refined
- * anisotropically, the actual
- * number of children may be less
- * than the value given here.
+ * If a cell is refined anisotropically, the actual number of children may
+ * be less than the value given here.
*/
static const unsigned int max_children_per_cell = 1;
static const unsigned int faces_per_cell = 0;
/**
- * Maximum number of children of
- * a refined face, i.e. the
- * number of children of an
- * isotropically refined face.
+ * Maximum number of children of a refined face, i.e. the number of children
+ * of an isotropically refined face.
*
- * If a cell is refined
- * anisotropically, the actual
- * number of children may be less
- * than the value given here.
+ * If a cell is refined anisotropically, the actual number of children may
+ * be less than the value given here.
*/
static const unsigned int max_children_per_face = 0;
/**
- * Return the number of children
- * of a cell (or face) refined
- * with <tt>ref_case</tt>. Since
- * we are concerned here with
- * points, the number of children
- * is equal to one.
+ * Return the number of children of a cell (or face) refined with
+ * <tt>ref_case</tt>. Since we are concerned here with points, the number of
+ * children is equal to one.
*/
static unsigned int n_children(const RefinementCase<0> &refinement_case);
static const unsigned int vertices_per_cell = 1;
/**
- * Number of vertices each face has.
- * Since this is not useful in one
- * dimension, we provide a useless
- * number (in the hope that a compiler
- * may warn when it sees constructs like
- * <tt>for (i=0; i<vertices_per_face; ++i)</tt>,
- * at least if @p i is an <tt>unsigned int</tt>.
+ * Number of vertices each face has. Since this is not useful in one
+ * dimension, we provide a useless number (in the hope that a compiler may
+ * warn when it sees constructs like <tt>for (i=0; i<vertices_per_face;
+ * ++i)</tt>, at least if @p i is an <tt>unsigned int</tt>.
*/
static const unsigned int vertices_per_face = 0;
static const unsigned int lines_per_cell = 0;
/**
- * Number of quadrilaterals of a
- * cell.
+ * Number of quadrilaterals of a cell.
*/
static const unsigned int quads_per_cell = 0;
/**
- * Number of hexahedra of a
- * cell.
+ * Number of hexahedra of a cell.
*/
static const unsigned int hexes_per_cell = 0;
};
/**
* This class provides dimension independent information to all topological
- * structures that make up the unit, or
- * @ref GlossReferenceCell "reference cell".
+ * structures that make up the unit, or @ref GlossReferenceCell "reference
+ * cell".
*
* It is the one central point in the library where information about the
- * numbering of vertices, lines, or faces of the reference cell is
- * collected. Consequently, the information of this class is used extensively
- * in the geometric description of Triangulation objects, as well as in
- * various other parts of the code. In particular, it also serves as the focus
- * of writing code in a dimension independent way; for example, instead of
- * writing a loop over vertices 0<=v<4 in 2d, one would write it as
+ * numbering of vertices, lines, or faces of the reference cell is collected.
+ * Consequently, the information of this class is used extensively in the
+ * geometric description of Triangulation objects, as well as in various other
+ * parts of the code. In particular, it also serves as the focus of writing
+ * code in a dimension independent way; for example, instead of writing a loop
+ * over vertices 0<=v<4 in 2d, one would write it as
* 0<=v<GeometryInfo<dim>::vertices_per_cell, thus allowing the code to work
* in 3d as well without changes.
*
*
* <h3>Implementation conventions for two spatial dimensions</h3>
*
- * From version 5.2 onwards deal.II is based on a numbering scheme
- * that uses a lexicographic ordering (with x running fastest)
- * wherever possible, hence trying to adopt a kind of 'canonical'
- * ordering.
+ * From version 5.2 onwards deal.II is based on a numbering scheme that uses a
+ * lexicographic ordering (with x running fastest) wherever possible, hence
+ * trying to adopt a kind of 'canonical' ordering.
*
* The ordering of vertices and faces (lines) in 2d is defined by
*
* - Vertices are numbered in lexicographic ordering
*
- * - Faces (lines in 2d): first the two faces with normals in x-
- * and then y-direction. For each two faces: first the face with
- * normal in negative coordinate direction, then the one with normal
- * in positive direction, i.e. the faces are ordered according to
- * their normals pointing in -x, x, -y, y direction.
+ * - Faces (lines in 2d): first the two faces with normals in x- and then
+ * y-direction. For each two faces: first the face with normal in negative
+ * coordinate direction, then the one with normal in positive direction, i.e.
+ * the faces are ordered according to their normals pointing in -x, x, -y, y
+ * direction.
*
- * - The direction of a line is represented by the direction of
- * point 0 towards point 1 and is always in one of the coordinate
- * directions
+ * - The direction of a line is represented by the direction of point 0
+ * towards point 1 and is always in one of the coordinate directions
*
- * - Face lines in 3d are ordered, such that the induced 2d local
- * coordinate system (x,y) implies (right hand rule) a normal in
- * face normal direction, see N2/.
+ * - Face lines in 3d are ordered, such that the induced 2d local coordinate
+ * system (x,y) implies (right hand rule) a normal in face normal direction,
+ * see N2/.
*
- * The resulting numbering of vertices and faces (lines) in 2d as
- * well as the directions of lines is shown in the following.
+ * The resulting numbering of vertices and faces (lines) in 2d as well as the
+ * directions of lines is shown in the following.
* @verbatim
* 3
* 2-->--3
* Similarly we define, that the four children of a quad are adjacent to the
* vertex with the same number of the old quad.
*
- * Note that information about several of these conventions can be
- * extracted at run- or compile-time from the member functions and
- * variables of the present class.
+ * Note that information about several of these conventions can be extracted
+ * at run- or compile-time from the member functions and variables of the
+ * present class.
*
*
* <h4>Coordinate systems</h4>
*
* <h3>Implementation conventions for three spatial dimensions</h3>
*
- * By convention, we will use the following numbering conventions
- * for vertices, lines and faces of hexahedra in three space
- * dimensions. Before giving these conventions we declare the
- * following sketch to be the standard way of drawing 3d pictures of
- * hexahedra:
+ * By convention, we will use the following numbering conventions for
+ * vertices, lines and faces of hexahedra in three space dimensions. Before
+ * giving these conventions we declare the following sketch to be the standard
+ * way of drawing 3d pictures of hexahedra:
* @verbatim
* *-------* *-------*
* /| | / /|
* cube, while the right one shall be the top, right and front face. You may
* recover the whole cube by moving the two parts together into one.
*
- * Note again that information about several of the following
- * conventions can be extracted at run- or compile-time from the
- * member functions and variables of the present class.
+ * Note again that information about several of the following conventions can
+ * be extracted at run- or compile-time from the member functions and
+ * variables of the present class.
*
* <h4>Vertices</h4>
*
- * The ordering of vertices in 3d is defined by the same rules as in
- * the 2d case. In particular, the following is still true:
+ * The ordering of vertices in 3d is defined by the same rules as in the 2d
+ * case. In particular, the following is still true:
*
* - Vertices are numbered in lexicographic ordering.
*
* Here, the same holds as for the vertices:
*
* - Line ordering in 3d:
- * <ul>
- * <li>first the lines of face (z=0) in 2d line ordering,
- * <li>then the lines of face (z=1) in 2d line ordering,
- * <li>finally the lines in z direction in lexicographic ordering
- * </ul>
+ * <ul>
+ * <li>first the lines of face (z=0) in 2d line ordering,
+ * <li>then the lines of face (z=1) in 2d line ordering,
+ * <li>finally the lines in z direction in lexicographic ordering
+ * </ul>
* @verbatim
* *---7---* *---7---*
* /| | / /|
* *--->---* *--->---*
* @endverbatim
*
- * The fact that edges (just as vertices and faces) are entities that
- * are stored in their own right rather than constructed from cells
- * each time they are needed, means that adjacent cells actually have
- * pointers to edges that are thus shared between them. This implies
- * that the convention that sets of parallel edges have parallel
- * directions is not only a local condition. Before a list of cells is
- * passed to an object of the Triangulation class for creation of a
- * triangulation, you therefore have to make sure that cells are
- * oriented in a compatible fashion, so that edge directions are
- * globally according to above convention. However, the GridReordering
- * class can do this for you, by reorienting cells and edges of an
- * arbitrary list of input cells that need not be already sorted.
+ * The fact that edges (just as vertices and faces) are entities that are
+ * stored in their own right rather than constructed from cells each time they
+ * are needed, means that adjacent cells actually have pointers to edges that
+ * are thus shared between them. This implies that the convention that sets of
+ * parallel edges have parallel directions is not only a local condition.
+ * Before a list of cells is passed to an object of the Triangulation class
+ * for creation of a triangulation, you therefore have to make sure that cells
+ * are oriented in a compatible fashion, so that edge directions are globally
+ * according to above convention. However, the GridReordering class can do
+ * this for you, by reorienting cells and edges of an arbitrary list of input
+ * cells that need not be already sorted.
*
* <h4>Faces</h4>
*
* The numbering of faces in 3d is defined by a rule analogous to 2d:
*
- * - Faces (quads in 3d): first the two faces with normals in x-,
- * then y- and z-direction. For each two faces: first the face with
- * normal in negative coordinate direction, then the one with normal
- * in positive direction, i.e. the faces are ordered according to
- * their normals pointing in -x, x, -y, y, -z, z direction.
+ * - Faces (quads in 3d): first the two faces with normals in x-, then y- and
+ * z-direction. For each two faces: first the face with normal in negative
+ * coordinate direction, then the one with normal in positive direction, i.e.
+ * the faces are ordered according to their normals pointing in -x, x, -y, y,
+ * -z, z direction.
*
- * Therefore, the faces are numbered in the ordering: left, right,
- * front, back, bottom and top face:
+ * Therefore, the faces are numbered in the ordering: left, right, front,
+ * back, bottom and top face:
* @verbatim
* *-------* *-------*
* /| | / /|
* *-------* *-------*
* @endverbatim
*
- * The <em>standard</em> direction of the faces is such, that the
- * induced 2d local coordinate system (x,y) implies (right hand
- * rule) a normal in face normal direction, see N2a). In the
- * following we show the local coordinate system and the numbering
- * of face lines:
+ * The <em>standard</em> direction of the faces is such, that the induced 2d
+ * local coordinate system (x,y) implies (right hand rule) a normal in face
+ * normal direction, see N2a). In the following we show the local coordinate
+ * system and the numbering of face lines:
* <ul>
* <li> Faces 0 and 1:
* @verbatim
* @endverbatim
* </ul>
*
- * The face line numbers (0,1,2,3) correspond to following cell line
- * numbers.
+ * The face line numbers (0,1,2,3) correspond to following cell line numbers.
* <ul>
* <li> Face 0: lines 8, 10, 0, 4;
* <li> Face 1: lines 9, 11, 1, 5;
* <li> Face 4: lines 0, 1, 2, 3;
* <li> Face 5: lines 4, 5, 6, 7;
* </ul>
- * You can get these numbers using the
- * GeometryInfo<3>::face_to_cell_lines() function.
- *
- * The face normals can be deduced from the face orientation by
- * applying the right hand side rule (x,y -> normal). We note, that
- * in the standard orientation of faces in 2d, faces 0 and 2 have
- * normals that point into the cell, and faces 1 and 3 have normals
- * pointing outward. In 3d, faces 0, 2, and 4
- * have normals that point into the cell, while the normals of faces
- * 1, 3, and 5 point outward. This information, again, can be queried from
+ * You can get these numbers using the GeometryInfo<3>::face_to_cell_lines()
+ * function.
+ *
+ * The face normals can be deduced from the face orientation by applying the
+ * right hand side rule (x,y -> normal). We note, that in the standard
+ * orientation of faces in 2d, faces 0 and 2 have normals that point into the
+ * cell, and faces 1 and 3 have normals pointing outward. In 3d, faces 0, 2,
+ * and 4 have normals that point into the cell, while the normals of faces 1,
+ * 3, and 5 point outward. This information, again, can be queried from
* GeometryInfo<dim>::unit_normal_orientation.
*
- * However, it turns out that a significant number of 3d meshes cannot
- * satisfy this convention. This is due to the fact that the face
- * convention for one cell already implies something for the
- * neighbor, since they share a common face and fixing it for the
- * first cell also fixes the normal vectors of the opposite faces of
- * both cells. It is easy to construct cases of loops of cells for
- * which this leads to cases where we cannot find orientations for
+ * However, it turns out that a significant number of 3d meshes cannot satisfy
+ * this convention. This is due to the fact that the face convention for one
+ * cell already implies something for the neighbor, since they share a common
+ * face and fixing it for the first cell also fixes the normal vectors of the
+ * opposite faces of both cells. It is easy to construct cases of loops of
+ * cells for which this leads to cases where we cannot find orientations for
* all faces that are consistent with this convention.
*
* For this reason, above convention is only what we call the <em>standard
* normal vector is pointing the other direction. There are not very many
* places in application programs where you need this information actually,
* but a few places in the library make use of this. Note that in 2d, the
- * result is always @p true. More information on the topic can be found in this
- * @ref GlossFaceOrientation "glossary" article.
+ * result is always @p true. More information on the topic can be found in
+ * this @ref GlossFaceOrientation "glossary" article.
*
* In order to allow all kinds of meshes in 3d, including
- * <em>Moebius</em>-loops, a face might even be rotated looking
- * from one cell, whereas it is according to the standard looking at it from the
- * neighboring cell sharing that particular face. In order to cope with this,
- * two flags <tt>face_flip</tt> and <tt>face_rotation</tt> are available, to
- * represent rotations by 180 and 90 degree, respectively. Setting both flags
- * amounts to a rotation of 270 degrees (all counterclockwise). You can ask
- * the cell for these flags like for the <tt>face_orientation</tt>. In order to
- * enable rotated faces, even lines can deviate from their standard direction in
- * 3d. This information is available as the <tt>line_orientation</tt> flag for
+ * <em>Moebius</em>-loops, a face might even be rotated looking from one cell,
+ * whereas it is according to the standard looking at it from the neighboring
+ * cell sharing that particular face. In order to cope with this, two flags
+ * <tt>face_flip</tt> and <tt>face_rotation</tt> are available, to represent
+ * rotations by 180 and 90 degree, respectively. Setting both flags amounts to
+ * a rotation of 270 degrees (all counterclockwise). You can ask the cell for
+ * these flags like for the <tt>face_orientation</tt>. In order to enable
+ * rotated faces, even lines can deviate from their standard direction in 3d.
+ * This information is available as the <tt>line_orientation</tt> flag for
* cells and faces in 3d. Again, this is something that should be internal to
- * the library and application program will probably never have to bother about
- * it. For more information on this see also
- * @ref GlossFaceOrientation "this glossary entry" .
+ * the library and application program will probably never have to bother
+ * about it. For more information on this see also @ref GlossFaceOrientation
+ * "this glossary entry" .
*
*
* <h4>Children</h4>
*
- * The eight children of an isotropically refined cell are numbered according to
- * the vertices they are adjacent to:
+ * The eight children of an isotropically refined cell are numbered according
+ * to the vertices they are adjacent to:
* @verbatim
* *----*----* *----*----*
* /| 6 | 7 | / 6 / 7 /|
* *----*----* *----*----*
* @endverbatim
*
- * Taking into account the orientation of the faces, the following
- * children are adjacent to the respective faces:
+ * Taking into account the orientation of the faces, the following children
+ * are adjacent to the respective faces:
* <ul>
* <li> Face 0: children 0, 2, 4, 6;
* <li> Face 1: children 1, 3, 5, 7;
* <li> Face 4: children 0, 1, 2, 3;
* <li> Face 5: children 4, 5, 6, 7.
* </ul>
- * You can get these numbers using the
- * GeometryInfo<3>::child_cell_on_face() function. As each child is
- * adjacent to the vertex with the same number these numbers are
- * also given by the GeometryInfo<3>::face_to_cell_vertices()
- * function.
- *
- * Note that, again, the above list only holds for faces in their
- * standard orientation. If a face is not in standard orientation,
- * then the children at positions 1 and 2 (counting from 0 to 3)
- * would be swapped. In fact, this is what the child_cell_on_face
- * and the face_to_cell_vertices functions of GeometryInfo<3> do,
- * when invoked with a <tt>face_orientation=false</tt> argument.
- *
- * The information which child cell is at which position of which face
- * is most often used when computing jump terms across faces with
- * hanging nodes, using objects of type FESubfaceValues. Sitting on
- * one cell, you would look at a face and figure out which child of
- * the neighbor is sitting on a given subface between the present and
- * the neighboring cell. To avoid having to query the standard
- * orientation of the faces of the two cells every time in such cases,
- * you should use a function call like
- * <tt>cell->neighbor_child_on_subface(face_no,subface_no)</tt>, which
- * returns the correct result both in 2d (where face orientations are
- * immaterial) and 3d (where it is necessary to use the face
- * orientation as additional argument to
- * <tt>GeometryInfo<3>::child_cell_on_face</tt>).
- *
- * For anisotropic refinement, the child cells can not be numbered according to
- * adjacent vertices, thus the following conventions are used:
+ * You can get these numbers using the GeometryInfo<3>::child_cell_on_face()
+ * function. As each child is adjacent to the vertex with the same number
+ * these numbers are also given by the
+ * GeometryInfo<3>::face_to_cell_vertices() function.
+ *
+ * Note that, again, the above list only holds for faces in their standard
+ * orientation. If a face is not in standard orientation, then the children at
+ * positions 1 and 2 (counting from 0 to 3) would be swapped. In fact, this is
+ * what the child_cell_on_face and the face_to_cell_vertices functions of
+ * GeometryInfo<3> do, when invoked with a <tt>face_orientation=false</tt>
+ * argument.
+ *
+ * The information which child cell is at which position of which face is most
+ * often used when computing jump terms across faces with hanging nodes, using
+ * objects of type FESubfaceValues. Sitting on one cell, you would look at a
+ * face and figure out which child of the neighbor is sitting on a given
+ * subface between the present and the neighboring cell. To avoid having to
+ * query the standard orientation of the faces of the two cells every time in
+ * such cases, you should use a function call like
+ * <tt>cell->neighbor_child_on_subface(face_no,subface_no)</tt>, which returns
+ * the correct result both in 2d (where face orientations are immaterial) and
+ * 3d (where it is necessary to use the face orientation as additional
+ * argument to <tt>GeometryInfo<3>::child_cell_on_face</tt>).
+ *
+ * For anisotropic refinement, the child cells can not be numbered according
+ * to adjacent vertices, thus the following conventions are used:
* @verbatim
* RefinementCase<3>::cut_x
*
* By the convention laid down as above, the vertices have the following
* coordinates (lexicographic, with x running fastest):
* <ul>
- * <li> Vertex 0: <tt>(0,0,0)</tt>;
- * <li> Vertex 1: <tt>(1,0,0)</tt>;
- * <li> Vertex 2: <tt>(0,1,0)</tt>;
- * <li> Vertex 3: <tt>(1,1,0)</tt>;
- * <li> Vertex 4: <tt>(0,0,1)</tt>;
- * <li> Vertex 5: <tt>(1,0,1)</tt>;
- * <li> Vertex 6: <tt>(0,1,1)</tt>;
- * <li> Vertex 7: <tt>(1,1,1)</tt>.
+ * <li> Vertex 0: <tt>(0,0,0)</tt>;
+ * <li> Vertex 1: <tt>(1,0,0)</tt>;
+ * <li> Vertex 2: <tt>(0,1,0)</tt>;
+ * <li> Vertex 3: <tt>(1,1,0)</tt>;
+ * <li> Vertex 4: <tt>(0,0,1)</tt>;
+ * <li> Vertex 5: <tt>(1,0,1)</tt>;
+ * <li> Vertex 6: <tt>(0,1,1)</tt>;
+ * <li> Vertex 7: <tt>(1,1,1)</tt>.
* </ul>
*
*
{
/**
- * Maximum number of children of
- * a refined cell, i.e. the
- * number of children of an
- * isotropically refined cell.
+ * Maximum number of children of a refined cell, i.e. the number of children
+ * of an isotropically refined cell.
*
- * If a cell is refined
- * anisotropically, the actual
- * number of children may be less
- * than the value given here.
+ * If a cell is refined anisotropically, the actual number of children may
+ * be less than the value given here.
*/
static const unsigned int max_children_per_cell = 1 << dim;
static const unsigned int faces_per_cell = 2 * dim;
/**
- * Maximum number of children of
- * a refined face, i.e. the
- * number of children of an
- * isotropically refined face.
+ * Maximum number of children of a refined face, i.e. the number of children
+ * of an isotropically refined face.
*
- * If a cell is refined
- * anisotropically, the actual
- * number of children may be less
- * than the value given here.
+ * If a cell is refined anisotropically, the actual number of children may
+ * be less than the value given here.
*/
static const unsigned int max_children_per_face = GeometryInfo<dim-1>::max_children_per_cell;
static const unsigned int vertices_per_cell = 1 << dim;
/**
- * Number of vertices on each
- * face.
+ * Number of vertices on each face.
*/
static const unsigned int vertices_per_face = GeometryInfo<dim-1>::vertices_per_cell;
/**
* Number of lines of a cell.
*
- * The formula to compute this makes use
- * of the fact that when going from one
- * dimension to the next, the object of
- * the lower dimension is copied once
- * (thus twice the old number of lines)
- * and then a new line is inserted
- * between each vertex of the old object
- * and the corresponding one in the copy.
+ * The formula to compute this makes use of the fact that when going from
+ * one dimension to the next, the object of the lower dimension is copied
+ * once (thus twice the old number of lines) and then a new line is inserted
+ * between each vertex of the old object and the corresponding one in the
+ * copy.
*/
static const unsigned int lines_per_cell
= (2*GeometryInfo<dim-1>::lines_per_cell +
GeometryInfo<dim-1>::vertices_per_cell);
/**
- * Number of quadrilaterals of a
- * cell.
+ * Number of quadrilaterals of a cell.
*
- * This number is computed recursively
- * just as the previous one, with the
- * exception that new quads result from
- * connecting an original line and its
+ * This number is computed recursively just as the previous one, with the
+ * exception that new quads result from connecting an original line and its
* copy.
*/
static const unsigned int quads_per_cell
GeometryInfo<dim-1>::lines_per_cell);
/**
- * Number of hexahedra of a
- * cell.
+ * Number of hexahedra of a cell.
*/
static const unsigned int hexes_per_cell
= (2*GeometryInfo<dim-1>::hexes_per_cell +
GeometryInfo<dim-1>::quads_per_cell);
/**
- * Rearrange vertices for UCD
- * output. For a cell being
- * written in UCD format, each
- * entry in this field contains
- * the number of a vertex in
- * <tt>deal.II</tt> that corresponds
- * to the UCD numbering at this
- * location.
+ * Rearrange vertices for UCD output. For a cell being written in UCD
+ * format, each entry in this field contains the number of a vertex in
+ * <tt>deal.II</tt> that corresponds to the UCD numbering at this location.
*
- * Typical example: write a cell
- * and arrange the vertices, such
- * that UCD understands them.
+ * Typical example: write a cell and arrange the vertices, such that UCD
+ * understands them.
*
* @code
* for (i=0; i< n_vertices; ++i)
* out << cell->vertex(ucd_to_deal[i]);
* @endcode
*
- * As the vertex numbering in
- * deal.II versions <= 5.1
- * happened to coincide with the
- * UCD numbering, this field can
- * also be used like a
+ * As the vertex numbering in deal.II versions <= 5.1 happened to coincide
+ * with the UCD numbering, this field can also be used like a
* old_to_lexicographic mapping.
*/
static const unsigned int ucd_to_deal[vertices_per_cell];
/**
- * Rearrange vertices for OpenDX
- * output. For a cell being
- * written in OpenDX format, each
- * entry in this field contains
- * the number of a vertex in
- * <tt>deal.II</tt> that corresponds
- * to the DX numbering at this
- * location.
+ * Rearrange vertices for OpenDX output. For a cell being written in OpenDX
+ * format, each entry in this field contains the number of a vertex in
+ * <tt>deal.II</tt> that corresponds to the DX numbering at this location.
*
- * Typical example: write a cell
- * and arrange the vertices, such
- * that OpenDX understands them.
+ * Typical example: write a cell and arrange the vertices, such that OpenDX
+ * understands them.
*
* @code
* for (i=0; i< n_vertices; ++i)
static const unsigned int dx_to_deal[vertices_per_cell];
/**
- * This field stores for each vertex
- * to which faces it belongs. In any
- * given dimension, the number of
- * faces is equal to the dimension.
- * The first index in this 2D-array
- * runs over all vertices, the second
- * index over @p dim faces to which
- * the vertex belongs.
- *
- * The order of the faces for
- * each vertex is such that the
- * first listed face bounds the
- * reference cell in <i>x</i>
- * direction, the second in
- * <i>y</i> direction, and so on.
+ * This field stores for each vertex to which faces it belongs. In any given
+ * dimension, the number of faces is equal to the dimension. The first index
+ * in this 2D-array runs over all vertices, the second index over @p dim
+ * faces to which the vertex belongs.
+ *
+ * The order of the faces for each vertex is such that the first listed face
+ * bounds the reference cell in <i>x</i> direction, the second in <i>y</i>
+ * direction, and so on.
*/
static const unsigned int vertex_to_face[vertices_per_cell][dim];
/**
- * Return the number of children
- * of a cell (or face) refined
- * with <tt>ref_case</tt>.
+ * Return the number of children of a cell (or face) refined with
+ * <tt>ref_case</tt>.
*/
static
unsigned int
n_children(const RefinementCase<dim> &refinement_case);
/**
- * Return the number of subfaces
- * of a face refined according to
- * internal::SubfaceCase
- * @p face_ref_case.
+ * Return the number of subfaces of a face refined according to
+ * internal::SubfaceCase @p face_ref_case.
*/
static
unsigned int
n_subfaces(const internal::SubfaceCase<dim> &subface_case);
/**
- * Given a face on the reference
- * element with a
- * <code>internal::SubfaceCase@<dim@></code>
- * @p face_refinement_case this
- * function returns the ratio
- * between the area of the @p
- * subface_no th subface and the
- * area(=1) of the face.
+ * Given a face on the reference element with a
+ * <code>internal::SubfaceCase@<dim@></code> @p face_refinement_case this
+ * function returns the ratio between the area of the @p subface_no th
+ * subface and the area(=1) of the face.
*
- * E.g. for
- * internal::SubfaceCase::cut_xy
- * the ratio is 1/4 for each of
- * the subfaces.
+ * E.g. for internal::SubfaceCase::cut_xy the ratio is 1/4 for each of the
+ * subfaces.
*/
static
double
const unsigned int subface_no);
/**
- * Given a cell refined with the
- * <code>RefinementCase</code>
- * @p cell_refinement_case
- * return the
- * <code>SubfaceCase</code> of
- * the @p face_no th face.
+ * Given a cell refined with the <code>RefinementCase</code> @p
+ * cell_refinement_case return the <code>SubfaceCase</code> of the @p
+ * face_no th face.
*/
static
RefinementCase<dim-1>
const bool face_rotation = false);
/**
- * Given the SubfaceCase @p
- * face_refinement_case of the @p
- * face_no th face, return the
- * smallest RefinementCase of the
- * cell, which corresponds to
- * that refinement of the face.
+ * Given the SubfaceCase @p face_refinement_case of the @p face_no th face,
+ * return the smallest RefinementCase of the cell, which corresponds to that
+ * refinement of the face.
*/
static
RefinementCase<dim>
const bool face_rotation = false);
/**
- * Given a cell refined with the
- * RefinementCase @p
- * cell_refinement_case return
- * the RefinementCase of the @p
- * line_no th face.
+ * Given a cell refined with the RefinementCase @p cell_refinement_case
+ * return the RefinementCase of the @p line_no th face.
*/
static
RefinementCase<1>
const unsigned int line_no);
/**
- * Return the minimal / smallest
- * RefinementCase of the cell, which
- * ensures refinement of line
- * @p line_no.
+ * Return the minimal / smallest RefinementCase of the cell, which ensures
+ * refinement of line @p line_no.
*/
static
RefinementCase<dim>
min_cell_refinement_case_for_line_refinement(const unsigned int line_no);
/**
- * This field stores which child
- * cells are adjacent to a
- * certain face of the mother
- * cell.
+ * This field stores which child cells are adjacent to a certain face of the
+ * mother cell.
*
- * For example, in 2D the layout of
- * a cell is as follows:
+ * For example, in 2D the layout of a cell is as follows:
* @verbatim
* . 3
* . 2-->--3
* . 0-->--1
* . 2
* @endverbatim
- * Vertices and faces are indicated
- * with their numbers, faces also with
+ * Vertices and faces are indicated with their numbers, faces also with
* their directions.
*
- * Now, when refined, the layout is
- * like this:
+ * Now, when refined, the layout is like this:
* @verbatim
* *--*--*
* | 2|3 |
* *--*--*
* @endverbatim
*
- * Thus, the child cells on face
- * 0 are (ordered in the
- * direction of the face) 0 and
- * 2, on face 3 they are 2 and 3,
- * etc.
+ * Thus, the child cells on face 0 are (ordered in the direction of the
+ * face) 0 and 2, on face 3 they are 2 and 3, etc.
*
- * For three spatial dimensions, the exact
- * order of the children is laid down in
- * the general documentation of this
- * class.
+ * For three spatial dimensions, the exact order of the children is laid
+ * down in the general documentation of this class.
*
- * Through the <tt>face_orientation</tt>,
- * <tt>face_flip</tt> and
- * <tt>face_rotation</tt> arguments this
- * function handles faces oriented in the
- * standard and non-standard orientation.
- * <tt>face_orientation</tt> defaults to
- * <tt>true</tt>, <tt>face_flip</tt> and
- * <tt>face_rotation</tt> default to
- * <tt>false</tt> (standard orientation)
- * and has no effect in 2d. The concept of
- * face orientations is explained in this
- * @ref GlossFaceOrientation "glossary"
- * entry.
- *
- * In the case of anisotropically refined
- * cells and faces, the @p RefinementCase of
- * the face, <tt>face_ref_case</tt>,
- * might have an influence on
- * which child is behind which given
- * subface, thus this is an additional
- * argument, defaulting to isotropic
- * refinement of the face.
+ * Through the <tt>face_orientation</tt>, <tt>face_flip</tt> and
+ * <tt>face_rotation</tt> arguments this function handles faces oriented in
+ * the standard and non-standard orientation. <tt>face_orientation</tt>
+ * defaults to <tt>true</tt>, <tt>face_flip</tt> and <tt>face_rotation</tt>
+ * default to <tt>false</tt> (standard orientation) and has no effect in 2d.
+ * The concept of face orientations is explained in this @ref
+ * GlossFaceOrientation "glossary" entry.
+ *
+ * In the case of anisotropically refined cells and faces, the @p
+ * RefinementCase of the face, <tt>face_ref_case</tt>, might have an
+ * influence on which child is behind which given subface, thus this is an
+ * additional argument, defaulting to isotropic refinement of the face.
*/
static
unsigned int
= RefinementCase<dim-1>::isotropic_refinement);
/**
- * Map line vertex number to cell
- * vertex number, i.e. give the
- * cell vertex number of the
- * <tt>vertex</tt>th vertex of
- * line <tt>line</tt>, e.g.
+ * Map line vertex number to cell vertex number, i.e. give the cell vertex
+ * number of the <tt>vertex</tt>th vertex of line <tt>line</tt>, e.g.
* <tt>GeometryInfo<2>::line_to_cell_vertices(3,0)=2</tt>.
*
- * The order of the lines, as well as
- * their direction (which in turn
- * determines which is the first and
- * which the second vertex on a line) is
- * the canonical one in deal.II, as
- * described in the general documentation
+ * The order of the lines, as well as their direction (which in turn
+ * determines which is the first and which the second vertex on a line) is
+ * the canonical one in deal.II, as described in the general documentation
* of this class.
*
- * For <tt>dim=2</tt> this call
- * is simply passed down to the
- * face_to_cell_vertices()
- * function.
+ * For <tt>dim=2</tt> this call is simply passed down to the
+ * face_to_cell_vertices() function.
*/
static
unsigned int
const unsigned int vertex);
/**
- * Map face vertex number to cell
- * vertex number, i.e. give the
- * cell vertex number of the
- * <tt>vertex</tt>th vertex of
- * face <tt>face</tt>, e.g.
- * <tt>GeometryInfo<2>::face_to_cell_vertices(3,0)=2</tt>,
- * see the image under point N4
- * in the 2d section of this
- * class's documentation.
- *
- * Through the <tt>face_orientation</tt>,
- * <tt>face_flip</tt> and
- * <tt>face_rotation</tt> arguments this
- * function handles faces oriented in the
- * standard and non-standard orientation.
- * <tt>face_orientation</tt> defaults to
- * <tt>true</tt>, <tt>face_flip</tt> and
- * <tt>face_rotation</tt> default to
- * <tt>false</tt> (standard orientation).
- * In 2d only <tt>face_flip</tt> is considered.
- * See this @ref GlossFaceOrientation "glossary"
- * article for more information.
- *
- * As the children of a cell are
- * ordered according to the
- * vertices of the cell, this
- * call is passed down to the
- * child_cell_on_face() function.
- * Hence this function is simply
- * a wrapper of
- * child_cell_on_face() giving it
+ * Map face vertex number to cell vertex number, i.e. give the cell vertex
+ * number of the <tt>vertex</tt>th vertex of face <tt>face</tt>, e.g.
+ * <tt>GeometryInfo<2>::face_to_cell_vertices(3,0)=2</tt>, see the image
+ * under point N4 in the 2d section of this class's documentation.
+ *
+ * Through the <tt>face_orientation</tt>, <tt>face_flip</tt> and
+ * <tt>face_rotation</tt> arguments this function handles faces oriented in
+ * the standard and non-standard orientation. <tt>face_orientation</tt>
+ * defaults to <tt>true</tt>, <tt>face_flip</tt> and <tt>face_rotation</tt>
+ * default to <tt>false</tt> (standard orientation). In 2d only
+ * <tt>face_flip</tt> is considered. See this @ref GlossFaceOrientation
+ * "glossary" article for more information.
+ *
+ * As the children of a cell are ordered according to the vertices of the
+ * cell, this call is passed down to the child_cell_on_face() function.
+ * Hence this function is simply a wrapper of child_cell_on_face() giving it
* a suggestive name.
*/
static
const bool face_rotation = false);
/**
- * Map face line number to cell
- * line number, i.e. give the
- * cell line number of the
- * <tt>line</tt>th line of face
- * <tt>face</tt>, e.g.
+ * Map face line number to cell line number, i.e. give the cell line number
+ * of the <tt>line</tt>th line of face <tt>face</tt>, e.g.
* <tt>GeometryInfo<3>::face_to_cell_lines(5,0)=4</tt>.
*
- * Through the <tt>face_orientation</tt>,
- * <tt>face_flip</tt> and
- * <tt>face_rotation</tt> arguments this
- * function handles faces oriented in the
- * standard and non-standard orientation.
- * <tt>face_orientation</tt> defaults to
- * <tt>true</tt>, <tt>face_flip</tt> and
- * <tt>face_rotation</tt> default to
- * <tt>false</tt> (standard orientation)
- * and has no effect in 2d.
+ * Through the <tt>face_orientation</tt>, <tt>face_flip</tt> and
+ * <tt>face_rotation</tt> arguments this function handles faces oriented in
+ * the standard and non-standard orientation. <tt>face_orientation</tt>
+ * defaults to <tt>true</tt>, <tt>face_flip</tt> and <tt>face_rotation</tt>
+ * default to <tt>false</tt> (standard orientation) and has no effect in 2d.
*/
static
unsigned int
const bool face_rotation = false);
/**
- * Map the vertex index @p vertex of a face
- * in standard orientation to one of a face
- * with arbitrary @p face_orientation, @p
- * face_flip and @p face_rotation. The
- * values of these three flags default to
- * <tt>true</tt>, <tt>false</tt> and
- * <tt>false</tt>, respectively. this
- * combination describes a face in standard
- * orientation.
+ * Map the vertex index @p vertex of a face in standard orientation to one
+ * of a face with arbitrary @p face_orientation, @p face_flip and @p
+ * face_rotation. The values of these three flags default to <tt>true</tt>,
+ * <tt>false</tt> and <tt>false</tt>, respectively. this combination
+ * describes a face in standard orientation.
*
* This function is only implemented in 3D.
*/
const bool face_rotation = false);
/**
- * Map the vertex index @p vertex of a face
- * with arbitrary @p face_orientation, @p
- * face_flip and @p face_rotation to a face
- * in standard orientation. The values of
- * these three flags default to
- * <tt>true</tt>, <tt>false</tt> and
- * <tt>false</tt>, respectively. this
- * combination describes a face in standard
- * orientation.
+ * Map the vertex index @p vertex of a face with arbitrary @p
+ * face_orientation, @p face_flip and @p face_rotation to a face in standard
+ * orientation. The values of these three flags default to <tt>true</tt>,
+ * <tt>false</tt> and <tt>false</tt>, respectively. this combination
+ * describes a face in standard orientation.
*
* This function is only implemented in 3D.
*/
const bool face_rotation = false);
/**
- * Map the line index @p line of a face
- * in standard orientation to one of a face
- * with arbitrary @p face_orientation, @p
- * face_flip and @p face_rotation. The
- * values of these three flags default to
- * <tt>true</tt>, <tt>false</tt> and
- * <tt>false</tt>, respectively. this
- * combination describes a face in standard
- * orientation.
+ * Map the line index @p line of a face in standard orientation to one of a
+ * face with arbitrary @p face_orientation, @p face_flip and @p
+ * face_rotation. The values of these three flags default to <tt>true</tt>,
+ * <tt>false</tt> and <tt>false</tt>, respectively. this combination
+ * describes a face in standard orientation.
*
* This function is only implemented in 3D.
*/
const bool face_rotation = false);
/**
- * Map the line index @p line of a face
- * with arbitrary @p face_orientation, @p
- * face_flip and @p face_rotation to a face
- * in standard orientation. The values of
- * these three flags default to
- * <tt>true</tt>, <tt>false</tt> and
- * <tt>false</tt>, respectively. this
- * combination describes a face in standard
- * orientation.
+ * Map the line index @p line of a face with arbitrary @p face_orientation,
+ * @p face_flip and @p face_rotation to a face in standard orientation. The
+ * values of these three flags default to <tt>true</tt>, <tt>false</tt> and
+ * <tt>false</tt>, respectively. this combination describes a face in
+ * standard orientation.
*
* This function is only implemented in 3D.
*/
const bool face_rotation = false);
/**
- * Return the position of the @p ith
- * vertex on the unit cell. The order of
- * vertices is the canonical one in
- * deal.II, as described in the general
+ * Return the position of the @p ith vertex on the unit cell. The order of
+ * vertices is the canonical one in deal.II, as described in the general
* documentation of this class.
*/
static
unit_cell_vertex (const unsigned int vertex);
/**
- * Given a point @p p in unit
- * coordinates, return the number
- * of the child cell in which it
- * would lie in. If the point
- * lies on the interface of two
- * children, return any one of
- * their indices. The result is
- * always less than
+ * Given a point @p p in unit coordinates, return the number of the child
+ * cell in which it would lie in. If the point lies on the interface of two
+ * children, return any one of their indices. The result is always less than
* GeometryInfo<dimension>::max_children_per_cell.
*
- * The order of child cells is described
- * the general documentation of this
+ * The order of child cells is described the general documentation of this
* class.
*/
static
child_cell_from_point (const Point<dim> &p);
/**
- * Given coordinates @p p on the
- * unit cell, return the values
- * of the coordinates of this
- * point in the coordinate system
- * of the given child. Neither
- * original nor returned
- * coordinates need actually be
- * inside the cell, we simply
- * perform a scale-and-shift
- * operation with a shift that
- * depends on the number of the
- * child.
+ * Given coordinates @p p on the unit cell, return the values of the
+ * coordinates of this point in the coordinate system of the given child.
+ * Neither original nor returned coordinates need actually be inside the
+ * cell, we simply perform a scale-and-shift operation with a shift that
+ * depends on the number of the child.
*/
static
Point<dim>
= RefinementCase<dim>::isotropic_refinement);
/**
- * The reverse function to the
- * one above: take a point in the
- * coordinate system of the
- * child, and transform it to the
- * coordinate system of the
+ * The reverse function to the one above: take a point in the coordinate
+ * system of the child, and transform it to the coordinate system of the
* mother cell.
*/
static
= RefinementCase<dim>::isotropic_refinement);
/**
- * Return true if the given point
- * is inside the unit cell of the
- * present space dimension.
+ * Return true if the given point is inside the unit cell of the present
+ * space dimension.
*/
static
bool
is_inside_unit_cell (const Point<dim> &p);
/**
- * Return true if the given point
- * is inside the unit cell of the
- * present space dimension. This
- * * function accepts an
- * additional * parameter which
- * specifies how * much the point
- * position may * actually be
- * outside the true * unit
- * cell. This is useful because
- * in practice we may often not
- * be able to compute the
- * coordinates of a point in
- * reference coordinates exactly,
- * but only up to numerical
- * roundoff.
- *
- * The tolerance parameter may be
- * less than zero, indicating
- * that the point should be
- * safely inside the cell.
+ * Return true if the given point is inside the unit cell of the present
+ * space dimension. This * function accepts an additional * parameter which
+ * specifies how * much the point position may * actually be outside the
+ * true * unit cell. This is useful because in practice we may often not be
+ * able to compute the coordinates of a point in reference coordinates
+ * exactly, but only up to numerical roundoff.
+ *
+ * The tolerance parameter may be less than zero, indicating that the point
+ * should be safely inside the cell.
*/
static
bool
const double eps);
/**
- * Projects a given point onto the
- * unit cell, i.e. each coordinate
- * outside [0..1] is modified
- * to lie within that interval.
+ * Projects a given point onto the unit cell, i.e. each coordinate outside
+ * [0..1] is modified to lie within that interval.
*/
static
Point<dim>
project_to_unit_cell (const Point<dim> &p);
/**
- * Returns the infinity norm of
- * the vector between a given point @p p
- * outside the unit cell to the closest
- * unit cell boundary.
- * For points inside the cell, this is
- * defined as zero.
+ * Returns the infinity norm of the vector between a given point @p p
+ * outside the unit cell to the closest unit cell boundary. For points
+ * inside the cell, this is defined as zero.
*/
static
double
distance_to_unit_cell (const Point<dim> &p);
/**
- * Compute the value of the $i$-th
- * $d$-linear (i.e. (bi-,tri-)linear)
- * shape function at location $\xi$.
+ * Compute the value of the $i$-th $d$-linear (i.e. (bi-,tri-)linear) shape
+ * function at location $\xi$.
*/
static
double
const unsigned int i);
/**
- * Compute the gradient of the $i$-th
- * $d$-linear (i.e. (bi-,tri-)linear)
+ * Compute the gradient of the $i$-th $d$-linear (i.e. (bi-,tri-)linear)
* shape function at location $\xi$.
*/
static
const unsigned int i);
/**
- * For a (bi-, tri-)linear
- * mapping from the reference
- * cell, face, or edge to the
- * object specified by the given
- * vertices, compute the
- * alternating form of the
- * transformed unit vectors
- * vertices. For an object of
- * dimensionality @p dim, there
- * are @p dim vectors with @p
- * spacedim components each, and
- * the alternating form is a
- * tensor of rank spacedim-dim
- * that corresponds to the wedge
- * product of the @p dim unit
- * vectors, and it corresponds to
- * the volume and normal vectors
- * of the mapping from reference
- * element to the element
- * described by the vertices.
- *
- * For example, if dim==spacedim==2, then
- * the alternating form is a scalar
- * (because spacedim-dim=0) and its value
- * equals $\mathbf v_1\wedge \mathbf
- * v_2=\mathbf v_1^\perp \cdot\mathbf
- * v_2$, where $\mathbf v_1^\perp$ is a
- * vector that is rotated to the right by
- * 90 degrees from $\mathbf v_1$. If
- * dim==spacedim==3, then the result is
- * again a scalar with value $\mathbf
- * v_1\wedge \mathbf v_2 \wedge \mathbf
- * v_3 = (\mathbf v_1\times \mathbf
- * v_2)\cdot \mathbf v_3$, where $\mathbf
- * v_1, \mathbf v_2, \mathbf v_3$ are the
- * images of the unit vectors at a vertex
- * of the unit dim-dimensional cell under
- * transformation to the dim-dimensional
- * cell in spacedim-dimensional space. In
- * both cases, i.e. for dim==2 or 3, the
- * result happens to equal the
- * determinant of the Jacobian of the
- * mapping from reference cell to cell in
- * real space. Note that it is the actual
- * determinant, not its absolute value as
- * often used in transforming integrals
- * from one coordinate system to
- * another. In particular, if the object
- * specified by the vertices is a
- * parallelogram (i.e. a linear
- * transformation of the reference cell)
- * then the computed values are the same
- * at all vertices and equal the (signed)
- * area of the cell; similarly, for
- * parallel-epipeds, it is the volume of
- * the cell.
- *
- * Likewise, if we have dim==spacedim-1
- * (e.g. we have a quad in 3d space, or a
- * line in 2d), then the alternating
- * product denotes the normal vector
- * (i.e. a rank-1 tensor, since
- * spacedim-dim=1) to the object at each
- * vertex, where the normal vector's
- * magnitude denotes the area element of
- * the transformation from the reference
- * object to the object given by the
- * vertices. In particular, if again the
- * mapping from reference object to the
- * object under consideration here is
- * linear (not bi- or trilinear), then
- * the returned vectors are all
- * %parallel, perpendicular to the mapped
- * object described by the vertices, and
- * have a magnitude equal to the
- * area/volume of the mapped object. If
- * dim=1, spacedim=2, then the returned
- * value is $\mathbf v_1^\perp$, where
- * $\mathbf v_1$ is the image of the sole
- * unit vector of a line mapped to the
- * line in 2d given by the vertices; if
- * dim=2, spacedim=3, then the returned
- * values are $\mathbf v_1 \wedge \mathbf
- * v_2=\mathbf v_1 \times \mathbf v_2$
- * where $\mathbf v_1,\mathbf v_2$ are
- * the two three-dimensional vectors that
- * are tangential to the quad mapped into
- * three-dimensional space.
- *
- * This function is used in order to
- * determine how distorted a cell is (see
- * the entry on
- * @ref GlossDistorted "distorted cells"
- * in the glossary).
+ * For a (bi-, tri-)linear mapping from the reference cell, face, or edge to
+ * the object specified by the given vertices, compute the alternating form
+ * of the transformed unit vectors vertices. For an object of dimensionality
+ * @p dim, there are @p dim vectors with @p spacedim components each, and
+ * the alternating form is a tensor of rank spacedim-dim that corresponds to
+ * the wedge product of the @p dim unit vectors, and it corresponds to the
+ * volume and normal vectors of the mapping from reference element to the
+ * element described by the vertices.
+ *
+ * For example, if dim==spacedim==2, then the alternating form is a scalar
+ * (because spacedim-dim=0) and its value equals $\mathbf v_1\wedge \mathbf
+ * v_2=\mathbf v_1^\perp \cdot\mathbf v_2$, where $\mathbf v_1^\perp$ is a
+ * vector that is rotated to the right by 90 degrees from $\mathbf v_1$. If
+ * dim==spacedim==3, then the result is again a scalar with value $\mathbf
+ * v_1\wedge \mathbf v_2 \wedge \mathbf v_3 = (\mathbf v_1\times \mathbf
+ * v_2)\cdot \mathbf v_3$, where $\mathbf v_1, \mathbf v_2, \mathbf v_3$ are
+ * the images of the unit vectors at a vertex of the unit dim-dimensional
+ * cell under transformation to the dim-dimensional cell in spacedim-
+ * dimensional space. In both cases, i.e. for dim==2 or 3, the result
+ * happens to equal the determinant of the Jacobian of the mapping from
+ * reference cell to cell in real space. Note that it is the actual
+ * determinant, not its absolute value as often used in transforming
+ * integrals from one coordinate system to another. In particular, if the
+ * object specified by the vertices is a parallelogram (i.e. a linear
+ * transformation of the reference cell) then the computed values are the
+ * same at all vertices and equal the (signed) area of the cell; similarly,
+ * for parallel-epipeds, it is the volume of the cell.
+ *
+ * Likewise, if we have dim==spacedim-1 (e.g. we have a quad in 3d space, or
+ * a line in 2d), then the alternating product denotes the normal vector
+ * (i.e. a rank-1 tensor, since spacedim-dim=1) to the object at each
+ * vertex, where the normal vector's magnitude denotes the area element of
+ * the transformation from the reference object to the object given by the
+ * vertices. In particular, if again the mapping from reference object to
+ * the object under consideration here is linear (not bi- or trilinear),
+ * then the returned vectors are all %parallel, perpendicular to the mapped
+ * object described by the vertices, and have a magnitude equal to the
+ * area/volume of the mapped object. If dim=1, spacedim=2, then the returned
+ * value is $\mathbf v_1^\perp$, where $\mathbf v_1$ is the image of the
+ * sole unit vector of a line mapped to the line in 2d given by the
+ * vertices; if dim=2, spacedim=3, then the returned values are $\mathbf v_1
+ * \wedge \mathbf v_2=\mathbf v_1 \times \mathbf v_2$ where $\mathbf
+ * v_1,\mathbf v_2$ are the two three-dimensional vectors that are
+ * tangential to the quad mapped into three-dimensional space.
+ *
+ * This function is used in order to determine how distorted a cell is (see
+ * the entry on @ref GlossDistorted "distorted cells" in the glossary).
*/
template <int spacedim>
static void
#endif
/**
- * For each face of the reference
- * cell, this field stores the
- * coordinate direction in which
- * its normal vector points. In
- * <tt>dim</tt> dimension these
- * are the <tt>2*dim</tt> first
- * entries of
- * <tt>{0,0,1,1,2,2,3,3}</tt>.
+ * For each face of the reference cell, this field stores the coordinate
+ * direction in which its normal vector points. In <tt>dim</tt> dimension
+ * these are the <tt>2*dim</tt> first entries of <tt>{0,0,1,1,2,2,3,3}</tt>.
*
- * Note that this is only the
- * coordinate number. The actual
- * direction of the normal vector
- * is obtained by multiplying the
- * unit vector in this direction
- * with #unit_normal_orientation.
+ * Note that this is only the coordinate number. The actual direction of the
+ * normal vector is obtained by multiplying the unit vector in this
+ * direction with #unit_normal_orientation.
*/
static const unsigned int unit_normal_direction[faces_per_cell];
/**
- * Orientation of the unit normal
- * vector of a face of the
- * reference cell. In
- * <tt>dim</tt> dimension these
- * are the <tt>2*dim</tt> first
- * entries of
+ * Orientation of the unit normal vector of a face of the reference cell. In
+ * <tt>dim</tt> dimension these are the <tt>2*dim</tt> first entries of
* <tt>{-1,1,-1,1,-1,1,-1,1}</tt>.
*
- * Each value is either
- * <tt>1</tt> or <tt>-1</tt>,
- * corresponding to a normal
- * vector pointing in the
- * positive or negative
- * coordinate direction,
+ * Each value is either <tt>1</tt> or <tt>-1</tt>, corresponding to a normal
+ * vector pointing in the positive or negative coordinate direction,
* respectively.
*
- * Note that this is only the
- * <em>standard orientation</em>
- * of faces. At least in 3d,
- * actual faces of cells in a
- * triangulation can also have
- * the opposite orientation,
- * depending on a flag that one
- * can query from the cell it
- * belongs to. For more
- * information, see the
- * @ref GlossFaceOrientation "glossary"
- * entry on
- * face orientation.
+ * Note that this is only the <em>standard orientation</em> of faces. At
+ * least in 3d, actual faces of cells in a triangulation can also have the
+ * opposite orientation, depending on a flag that one can query from the
+ * cell it belongs to. For more information, see the @ref
+ * GlossFaceOrientation "glossary" entry on face orientation.
*/
static const int unit_normal_orientation[faces_per_cell];
/**
- * List of numbers which denotes which
- * face is opposite to a given face. Its
- * entries are the first <tt>2*dim</tt>
- * entries of
- * <tt>{ 1, 0, 3, 2, 5, 4, 7, 6}</tt>.
+ * List of numbers which denotes which face is opposite to a given face. Its
+ * entries are the first <tt>2*dim</tt> entries of <tt>{ 1, 0, 3, 2, 5, 4,
+ * 7, 6}</tt>.
*/
static const unsigned int opposite_face[faces_per_cell];
{
/**
* Given two sets of indices that are assumed to be sorted, determine
- * whether they will have a nonempty intersection. The actual intersection is
- * not computed.
+ * whether they will have a nonempty intersection. The actual intersection
+ * is not computed.
* @param indices1 A set of indices, assumed sorted.
- * @param indices2 A set of indices, assumed sorted.
- * @return Whether the two sets of indices do have a nonempty intersection.
+ * @param indices2 A set of indices, assumed sorted. @return Whether the
+ * two sets of indices do have a nonempty intersection.
*/
inline
bool
/**
- * Create a partitioning of the given range of iterators using a simplified
- * version of the Cuthill-McKee algorithm (Breadth First Search algorithm).
- * The function creates partitions that contain "zones" of iterators
- * where the first partition contains the first iterator, the second
- * zone contains all those iterators that have conflicts with the single
- * element in the first zone, the third zone contains those iterators that
- * have conflicts with the iterators of the second zone and have not previously
- * been assigned to a zone, etc. If the iterators represent cells, then this
- * generates partitions that are like onion shells around the very first
- * cell. Note that elements in each zone may conflict with other elements in
- * the same zone.
+ * Create a partitioning of the given range of iterators using a
+ * simplified version of the Cuthill-McKee algorithm (Breadth First Search
+ * algorithm). The function creates partitions that contain "zones" of
+ * iterators where the first partition contains the first iterator, the
+ * second zone contains all those iterators that have conflicts with the
+ * single element in the first zone, the third zone contains those
+ * iterators that have conflicts with the iterators of the second zone and
+ * have not previously been assigned to a zone, etc. If the iterators
+ * represent cells, then this generates partitions that are like onion
+ * shells around the very first cell. Note that elements in each zone may
+ * conflict with other elements in the same zone.
*
- * The question whether two iterators conflict is determined by a user-provided
- * function. The meaning of this function is discussed in the documentation of
- * the GraphColoring::make_graph_coloring() function.
+ * The question whether two iterators conflict is determined by a user-
+ * provided function. The meaning of this function is discussed in the
+ * documentation of the GraphColoring::make_graph_coloring() function.
*
* @param[in] begin The first element of a range of iterators for which a
- * partitioning is sought.
+ * partitioning is sought.
* @param[in] end The element past the end of the range of iterators.
- * @param[in] get_conflict_indices A user defined function object returning
- * a set of indicators that are descriptive of what represents a
- * conflict. See above for a more thorough discussion.
- * @return A set of sets of iterators (where sets are represented by
- * std::vector for efficiency). Each element of the outermost set
- * corresponds to the iterators pointing to objects that are in the
- * same partition (i.e., the same zone).
+ * @param[in] get_conflict_indices A user defined function object
+ * returning a set of indicators that are descriptive of what represents a
+ * conflict. See above for a more thorough discussion. @return A set of
+ * sets of iterators (where sets are represented by std::vector for
+ * efficiency). Each element of the outermost set corresponds to the
+ * iterators pointing to objects that are in the same partition (i.e., the
+ * same zone).
*
* @author Martin Kronbichler, Bruno Turcksin
*/
/**
* This function uses DSATUR (Degree SATURation) to color the elements of
- * a set. DSATUR works as follows:
- * -# Arrange the vertices by decreasing order of degrees.
- * -# Color a vertex of maximal degree with color 1.
- * -# Choose a vertex with a maximal saturation degree. If there is equality,
- * choose any vertex of maximal degree in the uncolored subgraph.
- * -# Color the chosen vertex with the least possible (lowest numbered) color.
- * -# If all the vertices are colored, stop. Otherwise, return to 3.
+ * a set. DSATUR works as follows: -# Arrange the vertices by decreasing
+ * order of degrees. -# Color a vertex of maximal degree with color 1. -#
+ * Choose a vertex with a maximal saturation degree. If there is equality,
+ * choose any vertex of maximal degree in the uncolored subgraph. -# Color
+ * the chosen vertex with the least possible (lowest numbered) color. -#
+ * If all the vertices are colored, stop. Otherwise, return to 3.
*
* @param[in] partition The set of iterators that should be colored.
- * @param[in] get_conflict_indices A user defined function object returning
- * a set of indicators that are descriptive of what represents a
- * conflict. See above for a more thorough discussion.
- * @param[out] partition_coloring A set of sets of iterators (where sets are represented by
- * std::vector for efficiency). Each element of the outermost set
- * corresponds to the iterators pointing to objects that are in the
- * same partition (have the same color) and consequently do not
- * conflict. The elements of different sets may conflict.
+ * @param[in] get_conflict_indices A user defined function object
+ * returning a set of indicators that are descriptive of what represents a
+ * conflict. See above for a more thorough discussion.
+ * @param[out] partition_coloring A set of sets of iterators (where sets
+ * are represented by std::vector for efficiency). Each element of the
+ * outermost set corresponds to the iterators pointing to objects that are
+ * in the same partition (have the same color) and consequently do not
+ * conflict. The elements of different sets may conflict.
*/
template <typename Iterator>
void
/**
- * Given a partition-coloring graph, i.e., a set of zones (partitions) each
- * of which is colored, produce a combined coloring for the entire set of
- * iterators. This is possible because any color on an
- * even (resp. odd) zone does not conflict with any color of any other even
- * (resp. odd) zone. Consequently, we can combine colors from all even and all
- * odd zones. This function tries to create colors of similar number of elements.
+ * Given a partition-coloring graph, i.e., a set of zones (partitions)
+ * each of which is colored, produce a combined coloring for the entire
+ * set of iterators. This is possible because any color on an even (resp.
+ * odd) zone does not conflict with any color of any other even (resp.
+ * odd) zone. Consequently, we can combine colors from all even and all
+ * odd zones. This function tries to create colors of similar number of
+ * elements.
*/
template <typename Iterator>
std::vector<std::vector<Iterator> >
/**
- * Create a partitioning of the given range of iterators so that
- * iterators that point to conflicting objects will be placed
- * into different partitions, where the question whether two objects conflict
- * is determined by a user-provided function.
+ * Create a partitioning of the given range of iterators so that iterators
+ * that point to conflicting objects will be placed into different
+ * partitions, where the question whether two objects conflict is determined
+ * by a user-provided function.
*
* This function can also be considered as a graph coloring: each object
- * pointed to by an iterator is considered to be a node and there is an
- * edge between each two nodes that conflict. The graph coloring algorithm
- * then assigns a color to each node in such a way that two nodes connected
- * by an edge do not have the same color.
+ * pointed to by an iterator is considered to be a node and there is an edge
+ * between each two nodes that conflict. The graph coloring algorithm then
+ * assigns a color to each node in such a way that two nodes connected by an
+ * edge do not have the same color.
*
- * A typical use case for this function is in assembling a matrix in parallel.
- * There, one would like to assemble local contributions on different cells
- * at the same time (an operation that is purely local and so requires
- * no synchronization) but then we need to add these local contributions
- * to the global matrix. In general, the contributions from different cells
- * may be to the same matrix entries if the cells share degrees of freedom
- * and, consequently, can not happen at the same time unless we want to
- * risk a race condition (see http://en.wikipedia.org/wiki/Race_condition ).
- * Thus, we call these two cells in conflict, and we can only allow operations
- * in parallel from cells that do not conflict. In other words, two cells
- * are in conflict if the set of matrix entries (for example characterized
- * by the rows) have a nonempty intersection.
+ * A typical use case for this function is in assembling a matrix in
+ * parallel. There, one would like to assemble local contributions on
+ * different cells at the same time (an operation that is purely local and
+ * so requires no synchronization) but then we need to add these local
+ * contributions to the global matrix. In general, the contributions from
+ * different cells may be to the same matrix entries if the cells share
+ * degrees of freedom and, consequently, can not happen at the same time
+ * unless we want to risk a race condition (see
+ * http://en.wikipedia.org/wiki/Race_condition ). Thus, we call these two
+ * cells in conflict, and we can only allow operations in parallel from
+ * cells that do not conflict. In other words, two cells are in conflict if
+ * the set of matrix entries (for example characterized by the rows) have a
+ * nonempty intersection.
*
- * In this generality, computing the graph of conflicts would require calling
- * a function that determines whether two iterators (or the two objects they
- * represent) conflict, and calling it for every pair of iterators, i.e.,
- * $\frac 12 N (N-1)$ times. This is too expensive in general. A better
- * approach is to require a user-defined function that returns for every
- * iterator it is called for a set of indicators of some kind that characterize
- * a conflict; two iterators are in conflict if their conflict indicator sets
- * have a nonempty intersection. In the example of assembling a matrix,
- * the conflict indicator set would contain the indices of all degrees of
- * freedom on the cell pointed to (in the case of continuous Galerkin methods)
- * or the union of indices of degree of freedom on the current cell and all
- * cells adjacent to the faces of the current cell (in the case of
- * discontinuous Galerkin methods, because there one computes face integrals
- * coupling the degrees of freedom connected by a common face -- see step-12).
+ * In this generality, computing the graph of conflicts would require
+ * calling a function that determines whether two iterators (or the two
+ * objects they represent) conflict, and calling it for every pair of
+ * iterators, i.e., $\frac 12 N (N-1)$ times. This is too expensive in
+ * general. A better approach is to require a user-defined function that
+ * returns for every iterator it is called for a set of indicators of some
+ * kind that characterize a conflict; two iterators are in conflict if their
+ * conflict indicator sets have a nonempty intersection. In the example of
+ * assembling a matrix, the conflict indicator set would contain the indices
+ * of all degrees of freedom on the cell pointed to (in the case of
+ * continuous Galerkin methods) or the union of indices of degree of freedom
+ * on the current cell and all cells adjacent to the faces of the current
+ * cell (in the case of discontinuous Galerkin methods, because there one
+ * computes face integrals coupling the degrees of freedom connected by a
+ * common face -- see step-12).
*
* @note The conflict set returned by the user defined function passed as
- * third argument needs to accurately describe <i>all</i> degrees of
- * freedom for which anything is written into the matrix or right hand side.
- * In other words, if the writing happens through a function like
- * ConstraintMatrix::copy_local_to_global(), then the set of conflict indices
- * must actually contain not only the degrees of freedom on the current
- * cell, but also those they are linked to by constraints such as hanging
- * nodes.
+ * third argument needs to accurately describe <i>all</i> degrees of freedom
+ * for which anything is written into the matrix or right hand side. In
+ * other words, if the writing happens through a function like
+ * ConstraintMatrix::copy_local_to_global(), then the set of conflict
+ * indices must actually contain not only the degrees of freedom on the
+ * current cell, but also those they are linked to by constraints such as
+ * hanging nodes.
*
- * In other situations, the conflict indicator sets may represent
- * something different altogether -- it is up to the caller of this function
- * to describe what it means for two iterators to conflict. Given this,
+ * In other situations, the conflict indicator sets may represent something
+ * different altogether -- it is up to the caller of this function to
+ * describe what it means for two iterators to conflict. Given this,
* computing conflict graph edges can be done significantly more cheaply
* than with ${\cal O}(N^2)$ operations.
*
* Turcksin, Kronbichler and Bangerth, see @ref workstream_paper .
*
* @param[in] begin The first element of a range of iterators for which a
- * coloring is sought.
+ * coloring is sought.
* @param[in] end The element past the end of the range of iterators.
* @param[in] get_conflict_indices A user defined function object returning
- * a set of indicators that are descriptive of what represents a
- * conflict. See above for a more thorough discussion.
- * @return A set of sets of iterators (where sets are represented by
- * std::vector for efficiency). Each element of the outermost set
- * corresponds to the iterators pointing to objects that are in the
- * same partition (have the same color) and consequently do not
- * conflict. The elements of different sets may conflict.
+ * a set of indicators that are descriptive of what represents a conflict.
+ * See above for a more thorough discussion. @return A set of sets of
+ * iterators (where sets are represented by std::vector for efficiency).
+ * Each element of the outermost set corresponds to the iterators pointing
+ * to objects that are in the same partition (have the same color) and
+ * consequently do not conflict. The elements of different sets may
+ * conflict.
*
* @author Martin Kronbichler, Bruno Turcksin
*/
/**
* A class that represents a subset of indices among a larger set. For
- * example, it can be used to denote the set of degrees of freedom
- * within the range $[0,\text{dof\_handler.n\_dofs})$ that belongs to
- * a particular subdomain, or those among all degrees of freedom that
- * are stored on a particular processor in a distributed parallel
- * computation.
+ * example, it can be used to denote the set of degrees of freedom within the
+ * range $[0,\text{dof\_handler.n\_dofs})$ that belongs to a particular
+ * subdomain, or those among all degrees of freedom that are stored on a
+ * particular processor in a distributed parallel computation.
*
- * This class can represent a collection of half-open ranges of
- * indices as well as individual elements. For practical purposes it
- * also stores the overall range these indices can assume. In other
- * words, you need to specify the size of the index space
- * $[0,\text{size})$ of which objects of this class are a subset.
+ * This class can represent a collection of half-open ranges of indices as
+ * well as individual elements. For practical purposes it also stores the
+ * overall range these indices can assume. In other words, you need to specify
+ * the size of the index space $[0,\text{size})$ of which objects of this
+ * class are a subset.
*
* The data structures used in this class along with a rationale can be found
* in the @ref distributed_paper "Distributed Computing paper".
<< " is not an element of this set.");
/**
- * Write or read the data of this object to or
- * from a stream for the purpose of serialization
+ * Write or read the data of this object to or from a stream for the purpose
+ * of serialization
*/
template <class Archive>
void serialize (Archive &ar, const unsigned int version);
types::global_dof_index nth_index_in_set;
/**
- * Default constructor. Since there is no useful choice for
- * a default constructed interval, this constructor simply
- * creates something that resembles an invalid range. We
- * need this constructor for serialization purposes, but the
- * invalid range should be filled with something read from
- * the archive before it is used, so we should hopefully
- * never get to see an invalid range in the wild.
- **/
+ * Default constructor. Since there is no useful choice for a default
+ * constructed interval, this constructor simply creates something that
+ * resembles an invalid range. We need this constructor for serialization
+ * purposes, but the invalid range should be filled with something read
+ * from the archive before it is used, so we should hopefully never get to
+ * see an invalid range in the wild.
+ */
Range ();
/**
* Constructor. Create a half-open interval with the given indices.
*
* @param i1 Left end point of the interval.
- * @param i2 First index greater than the last index of the indicated range.
- **/
+ * @param i2 First index greater than the last index of the indicated
+ * range.
+ */
Range (const types::global_dof_index i1,
const types::global_dof_index i2);
* This integer caches the index of the largest range in @p ranges. This
* gives <tt>O(1)</tt> access to the range with most elements, while general
* access costs <tt>O(log(n_ranges))</tt>. The largest range is needed for
- * the methods @p is_element(), @p index_within_set(), @p
- * nth_index_in_set. In many applications, the largest range contains most
- * elements (the locally owned range), whereas there are only a few other
- * elements (ghosts).
+ * the methods @p is_element(), @p index_within_set(), @p nth_index_in_set.
+ * In many applications, the largest range contains most elements (the
+ * locally owned range), whereas there are only a few other elements
+ * (ghosts).
*/
mutable types::global_dof_index largest_range;
/**
- * Create and return an index set of size $N$ that contains every
- * single index within this range. In essence, this function
- * returns an index set created by
+ * Create and return an index set of size $N$ that contains every single index
+ * within this range. In essence, this function returns an index set created
+ * by
* @code
* IndexSet is (N);
* is.add_range(0, N);
* @endcode
- * This function exists so that one can create and initialize
- * index sets that are complete in one step, or so one can write
- * code like
+ * This function exists so that one can create and initialize index sets that
+ * are complete in one step, or so one can write code like
* @code
* if (my_index_set == complete_index_set(my_index_set.size())
* ...
/**
- * A class that is used to denote a collection of iterators that can
- * be expressed in terms of a range of iterators characterized by a begin
- * and an end iterator. As is common in C++, these ranges are specified as
- * half open intervals defined by a begin iterator and a one-past-the-end
- * iterator.
+ * A class that is used to denote a collection of iterators that can be
+ * expressed in terms of a range of iterators characterized by a begin and an
+ * end iterator. As is common in C++, these ranges are specified as half open
+ * intervals defined by a begin iterator and a one-past-the-end iterator.
*
* The purpose of this class is so that classes such as Triangulation and
* DoFHandler can return ranges of cell iterators using an object of the
* object can then be used in a range-based for loop as supported by C++11,
* see also @ref CPP11 "C++11 standard".
*
- * For example, such a loop could look like this if the goal is to set
- * the user flag on every active cell:
+ * For example, such a loop could look like this if the goal is to set the
+ * user flag on every active cell:
* @code
* Triangulation<dim> triangulation;
* ...
* for (auto cell : triangulation.active_cell_iterators())
* cell->set_user_flag();
* @endcode
- * In other words, the <code>cell</code> objects are iterators, and the
- * range object returned by Triangulation::active_cell_iterators() and
- * similar functions are conceptually thought of as <i>collections of
- * iterators</i>.
+ * In other words, the <code>cell</code> objects are iterators, and the range
+ * object returned by Triangulation::active_cell_iterators() and similar
+ * functions are conceptually thought of as <i>collections of iterators</i>.
*
- * Of course, the class may also be used to denote other iterator
- * ranges using different kinds of iterators into other containers.
+ * Of course, the class may also be used to denote other iterator ranges using
+ * different kinds of iterators into other containers.
*
*
* <h3>Class design: Motivation</h3>
*
- * Informally, the way the C++11 standard describes
- * <a href="http://en.wikipedia.org/wiki/C%2B%2B11#Range-based_for_loop">range-based
- * for loops</a> works as follows: A <i>range-based for loop</i> of the form
+ * Informally, the way the C++11 standard describes <a
+ * href="http://en.wikipedia.org/wiki/C%2B%2B11#Range-based_for_loop">range-
+ * based for loops</a> works as follows: A <i>range-based for loop</i> of the
+ * form
* @code
* Container c;
* for (auto v : c)
* statement;
* @endcode
- * where <code>c</code> is a container or collection, is equivalent to the following
- * loop:
+ * where <code>c</code> is a container or collection, is equivalent to the
+ * following loop:
* @code
* Container c;
* for (auto tmp=c.begin(); tmp!=c.end(); ++tmp)
* statement;
* }
* @endcode
- * In other words, the compiler introduces a temporary variable that <i>iterates</i>
- * over the elements of the container or collection, and the original variable
- * <code>v</code> that appeared in the range-based for loop represents the
- * <i>dereferenced</i> state of these iterators -- in other words, the
- * <i>elements</i> of the collection.
+ * In other words, the compiler introduces a temporary variable that
+ * <i>iterates</i> over the elements of the container or collection, and the
+ * original variable <code>v</code> that appeared in the range-based for loop
+ * represents the <i>dereferenced</i> state of these iterators -- in other
+ * words, the <i>elements</i> of the collection.
*
- * In the context of loops over cells, we typically want to retain the fact that
- * the loop variable is an iterator, not a value. This is because in deal.II,
- * we never actually use the <i>dereferenced state</i> of a cell iterator:
- * conceptually, it would represent a cell, and technically it is implemented
- * by classes such as CellAccessor and DoFCellAccessor, but these classes are
- * never used explicitly. Consequently, what we would like is that a call
- * such as Triangulation::active_cell_iterators() returns an object that
- * represents a <i>collection of iterators</i> of the kind
- * <code>{begin, begin+1, ..., end-1}</code>. This is conveniently expressed
- * as the half open interval <code>[begin,end)</code>. The loop variable in the
- * range-based for loop would then take on each of these iterators in turn.
+ * In the context of loops over cells, we typically want to retain the fact
+ * that the loop variable is an iterator, not a value. This is because in
+ * deal.II, we never actually use the <i>dereferenced state</i> of a cell
+ * iterator: conceptually, it would represent a cell, and technically it is
+ * implemented by classes such as CellAccessor and DoFCellAccessor, but these
+ * classes are never used explicitly. Consequently, what we would like is that
+ * a call such as Triangulation::active_cell_iterators() returns an object
+ * that represents a <i>collection of iterators</i> of the kind <code>{begin,
+ * begin+1, ..., end-1}</code>. This is conveniently expressed as the half
+ * open interval <code>[begin,end)</code>. The loop variable in the range-
+ * based for loop would then take on each of these iterators in turn.
*
*
* <h3>Class design: Implementation</h3>
*
- * To represent the desired semantics as outlined above, this class
- * stores a half-open range of iterators <code>[b,e)</code> of
- * the given template type. Secondly, the class needs to provide begin()
- * and end() functions in such a way that if you <i>dereference</i> the
- * result of IteratorRange::begin(), you get the <code>b</code> iterator.
- * Furthermore, you must be able to increment the object returned by
- * IteratorRange::begin() so that <code>*(++begin()) == b+1</code>.
- * In other words, IteratorRange::begin() must return an iterator that
- * when dereferenced returns an iterator of the template type
- * <code>Iterator</code>: It is an iterator over iterators in the same
- * sense as if you had a pointer into an array of pointers.
+ * To represent the desired semantics as outlined above, this class stores a
+ * half-open range of iterators <code>[b,e)</code> of the given template type.
+ * Secondly, the class needs to provide begin() and end() functions in such a
+ * way that if you <i>dereference</i> the result of IteratorRange::begin(),
+ * you get the <code>b</code> iterator. Furthermore, you must be able to
+ * increment the object returned by IteratorRange::begin() so that
+ * <code>*(++begin()) == b+1</code>. In other words, IteratorRange::begin()
+ * must return an iterator that when dereferenced returns an iterator of the
+ * template type <code>Iterator</code>: It is an iterator over iterators in
+ * the same sense as if you had a pointer into an array of pointers.
*
* This is implemented in the form of the IteratorRange::IteratorOverIterators
* class.
{
public:
/**
- * A class that implements the semantics of iterators over iterators
- * as discussed in the design sections of the IteratorRange class.
+ * A class that implements the semantics of iterators over iterators as
+ * discussed in the design sections of the IteratorRange class.
*/
class IteratorOverIterators : public std::iterator<std::forward_iterator_tag, Iterator,
typename Iterator::difference_type>
{
public:
/**
- * Typedef the elements of the collection to give them a name that is
- * more distinct.
+ * Typedef the elements of the collection to give them a name that is more
+ * distinct.
*/
typedef Iterator BaseIterator;
/**
- * Constructor. Initialize this iterator-over-iterator in
- * such a way that it points to the given argument.
+ * Constructor. Initialize this iterator-over-iterator in such a way that
+ * it points to the given argument.
*
- * @param iterator An iterator to which this object
- * is supposed to point.
+ * @param iterator An iterator to which this object is supposed to point.
*/
IteratorOverIterators (const BaseIterator &iterator);
/**
- * Dereferencing operator.
- * @return The iterator within the collection currently pointed to.
+ * Dereferencing operator. @return The iterator within the collection
+ * currently pointed to.
*/
BaseIterator operator* () const;
/**
- * Dereferencing operator.
- * @return The iterator within the collection currently pointed to.
+ * Dereferencing operator. @return The iterator within the collection
+ * currently pointed to.
*/
const BaseIterator *operator-> () const;
/**
* Comparison operator
- * @param i_o_i Another iterator over iterators.
- * @return Returns whether the current iterator points to a
- * different object than the iterator represented by the
- * argument.
+ * @param i_o_i Another iterator over iterators. @return Returns whether
+ * the current iterator points to a different object than the iterator
+ * represented by the argument.
*/
bool operator != (const IteratorOverIterators &i_o_i);
typedef Iterator iterator;
/**
- * Default constructor. Create a range represented by two
- * default constructed iterators. This range is likely (depending
- * on the type of the iterators) empty.
+ * Default constructor. Create a range represented by two default
+ * constructed iterators. This range is likely (depending on the type of the
+ * iterators) empty.
*/
IteratorRange();
*
* @param[in] begin An iterator pointing to the first element of the range
* @param[in] end An iterator pointing past the last element represented
- * by this range.
+ * by this range.
*/
IteratorRange (const iterator begin,
const iterator end);
IteratorOverIterators begin();
/**
- * Return the iterator pointing to the element past the last
- * element of this range.
+ * Return the iterator pointing to the element past the last element of this
+ * range.
*/
IteratorOverIterators end();
DEAL_II_NAMESPACE_OPEN
/**
* Identification of a program run. <tt>JobIdentifier</tt> determines the
- * start time of a program run and stores it as a program
- * identifier. There exists a library object <tt>dealjobid</tt> of this
- * class. This object can be accessed by all output functions to
- * provide an id for the current job.
+ * start time of a program run and stores it as a program identifier. There
+ * exists a library object <tt>dealjobid</tt> of this class. This object can
+ * be accessed by all output functions to provide an id for the current job.
*
* @ingroup utilities
*/
{
public:
/**
- * Constructor. Set program
- * identifier to value of
- * <tt>program_id</tt> concatenated
- * with the present time.
+ * Constructor. Set program identifier to value of <tt>program_id</tt>
+ * concatenated with the present time.
*/
JobIdentifier();
/**
- * This function returns an
- * identifier for the running
- * program. Currently, the
- * library provides a function
- * returning "JobID".
+ * This function returns an identifier for the running program. Currently,
+ * the library provides a function returning "JobID".
*
- * The user may define a
- * replacement of this function
- * in his source code and avoid
- * linking the library
- * version. Unfortunately, this
- * mechanism does not work with
- * shared libraries.
+ * The user may define a replacement of this function in his source code and
+ * avoid linking the library version. Unfortunately, this mechanism does not
+ * work with shared libraries.
*/
static const char *program_id();
/**
- * Obtain the base name of the
- * file currently being
- * compiled. That is, if the file
- * is <tt>mypath/file.cc</tt>
- * return just
- * <tt>file</tt>. Typically, this
- * can be called from a program
- * with the argument
- * <tt>__FILE__</tt> and is used
- * in the deal.II test suite.
+ * Obtain the base name of the file currently being compiled. That is, if
+ * the file is <tt>mypath/file.cc</tt> return just <tt>file</tt>. Typically,
+ * this can be called from a program with the argument <tt>__FILE__</tt> and
+ * is used in the deal.II test suite.
*/
static std::string base_name(const char *filename);
private:
/**
- * String holding the identifier
- * of the presently running
- * program.
+ * String holding the identifier of the presently running program.
*/
std::string id;
};
* providing
* <ul>
* <li> a push and pop mechanism for prefixes, and
- * <li> the possibility of distributing information to files and the
- * console.
+ * <li> the possibility of distributing information to files and the console.
* </ul>
*
* The usual usage of this class is through the pregenerated object
* <tt>deallog</tt>. Typical setup steps are:
* <ul>
- * <li> <tt>deallog.depth_console(n)</tt>: restrict output on screen to outer loops.
- * <li> <tt>deallog.attach(std::ostream)</tt>: write logging information into a file.
- * <li> <tt>deallog.depth_file(n)</tt>: restrict output to file to outer loops.
+ * <li> <tt>deallog.depth_console(n)</tt>: restrict output on screen to outer
+ * loops.
+ * <li> <tt>deallog.attach(std::ostream)</tt>: write logging information into
+ * a file.
+ * <li> <tt>deallog.depth_file(n)</tt>: restrict output to file to outer
+ * loops.
* </ul>
*
- * Before entering a new phase of your program, e.g. a new loop,
- * a new prefix can be set via <tt>LogStream::Prefix p("loopname");</tt>.
- * The destructor of the prefix will pop the prefix text from the stack.
+ * Before entering a new phase of your program, e.g. a new loop, a new prefix
+ * can be set via <tt>LogStream::Prefix p("loopname");</tt>. The destructor of
+ * the prefix will pop the prefix text from the stack.
*
- * Writes via the <tt><<</tt> operator,
- * <tt> deallog << "This is a log notice";</tt> will be buffered thread
- * locally until a <tt>std::flush</tt> or <tt>std::endl</tt> is
- * encountered, which will trigger a writeout to the console and, if set
- * up, the log file.
+ * Writes via the <tt><<</tt> operator, <tt> deallog << "This is a log
+ * notice";</tt> will be buffered thread locally until a <tt>std::flush</tt>
+ * or <tt>std::endl</tt> is encountered, which will trigger a writeout to the
+ * console and, if set up, the log file.
*
* <h3>LogStream and thread safety</h3>
*
- * In the vicinity of concurrent threads, LogStream behaves in the
- * following manner:
+ * In the vicinity of concurrent threads, LogStream behaves in the following
+ * manner:
* <ul>
* <li> Every write to a Logstream with operator <tt><<</tt> (or with
- * one of the special member functions) is buffered in a thread-local
- * storage.
- * <li> An <tt>std::flush</tt> or <tt>std::endl</tt> will trigger a
- * writeout to the console and (if attached) to the file stream. This
- * writeout is sequentialized so that output from concurrent threads don't
- * interleave.
+ * one of the special member functions) is buffered in a thread-local storage.
+ * <li> An <tt>std::flush</tt> or <tt>std::endl</tt> will trigger a writeout
+ * to the console and (if attached) to the file stream. This writeout is
+ * sequentialized so that output from concurrent threads don't interleave.
* <li> On a new thread, invoking a writeout, as well as a call to #push or
- * #pop will copy the current prefix of the "blessed" thread that created
- * the LogStream instance to a thread-local storage. After that prefixes
- * are thread-local.
+ * #pop will copy the current prefix of the "blessed" thread that created the
+ * LogStream instance to a thread-local storage. After that prefixes are
+ * thread-local.
* </ul>
*
* <h3>LogStream and reproducible regression test output</h3>
*
- * Generating reproducible floating point output for regression tests
- * is mildly put a nightmare. In order to make life a little easier,
- * LogStream implements a few features that try to achieve such a
- * goal. These features are turned on by calling test_mode(), and it
- * is not recommended to use them in any other environment. Right now,
- * LogStream implements the following:
+ * Generating reproducible floating point output for regression tests is
+ * mildly put a nightmare. In order to make life a little easier, LogStream
+ * implements a few features that try to achieve such a goal. These features
+ * are turned on by calling test_mode(), and it is not recommended to use them
+ * in any other environment. Right now, LogStream implements the following:
*
* <ol>
* <li> A double number very close to zero will end up being output in
- * exponential format, although it has no significant digits. The
- * parameter #double_threshold determines which numbers are too close
- * to zero to be considered nonzero.
+ * exponential format, although it has no significant digits. The parameter
+ * #double_threshold determines which numbers are too close to zero to be
+ * considered nonzero.
* <li> For float numbers holds the same, but with a typically larger
* #float_threshold.
- * <li> Rounded numbers become unreliable with inexact
- * arithmetics. Therefore, adding a small number before rounding makes
- * results more reproducible, assuming that numbers like 0.5 are more
- * likely than 0.49997.
+ * <li> Rounded numbers become unreliable with inexact arithmetics. Therefore,
+ * adding a small number before rounding makes results more reproducible,
+ * assuming that numbers like 0.5 are more likely than 0.49997.
* </ol>
- * It should be pointed out that all of these measures distort the
- * output and make it less accurate. Therefore, they are only
- * recommended if the output needs to be reproducible.
+ * It should be pointed out that all of these measures distort the output and
+ * make it less accurate. Therefore, they are only recommended if the output
+ * needs to be reproducible.
*
* @ingroup textoutput
* @author Guido Kanschat, Wolfgang Bangerth, 1999, 2003, 2011
/**
* A subclass allowing for the safe generation and removal of prefices.
*
- * Somewhere at the beginning of a block, create one of these objects,
- * and it will appear as a prefix in LogStream output like @p deallog. At
- * the end of the block, the prefix will automatically be removed, when
- * this object is destroyed.
+ * Somewhere at the beginning of a block, create one of these objects, and
+ * it will appear as a prefix in LogStream output like @p deallog. At the
+ * end of the block, the prefix will automatically be removed, when this
+ * object is destroyed.
*
* In other words, the scope of the object so created determines the
- * lifetime of the prefix. The advantage of using such an object is that
- * the prefix is removed whichever way you exit the scope -- by
+ * lifetime of the prefix. The advantage of using such an object is that the
+ * prefix is removed whichever way you exit the scope -- by
* <code>continue</code>, <code>break</code>, <code>return</code>,
* <code>throw</code>, or by simply reaching the closing brace. In all of
- * these cases, it is not necessary to remember to pop the prefix
- * manually using LogStream::pop. In this, it works just like the better
- * known Threads::Mutex::ScopedLock class.
+ * these cases, it is not necessary to remember to pop the prefix manually
+ * using LogStream::pop. In this, it works just like the better known
+ * Threads::Mutex::ScopedLock class.
*/
class Prefix
{
Prefix(const std::string &text);
/**
- * Set a new prefix for the given stream, which will be removed when
- * the variable is destroyed.
+ * Set a new prefix for the given stream, which will be removed when the
+ * variable is destroyed.
*/
Prefix(const std::string &text,
LogStream &stream);
/**
- * Disable output to the second stream. You may want to call
- * <tt>close</tt> on the stream that was previously attached to this
- * object.
+ * Disable output to the second stream. You may want to call <tt>close</tt>
+ * on the stream that was previously attached to this object.
*/
void detach ();
/**
* Setup the logstream for regression test mode.
*
- * This sets the parameters #double_threshold, #float_threshold, and
- * #offset to nonzero values. The exact values being used have been
- * determined experimentally and can be found in the source code.
+ * This sets the parameters #double_threshold, #float_threshold, and #offset
+ * to nonzero values. The exact values being used have been determined
+ * experimentally and can be found in the source code.
*
- * Called with an argument <tt>false</tt>, switches off test mode and
- * sets all involved parameters to zero.
+ * Called with an argument <tt>false</tt>, switches off test mode and sets
+ * all involved parameters to zero.
*/
void test_mode (bool on=true);
/**
- * Push another prefix on the stack. Prefixes are automatically separated
- * by a colon and there is a double colon after the last prefix.
+ * Push another prefix on the stack. Prefixes are automatically separated by
+ * a colon and there is a double colon after the last prefix.
*
* A simpler way to add a prefix (without the manual need to add the
* corresponding pop()) is to use the Prefix class.
/**
- * Maximum number of levels to be written to the log file. The
- * functionality is the same as <tt>depth_console</tt>, nevertheless,
- * this function should be used with care, since it may spoile the value
- * of a log file.
+ * Maximum number of levels to be written to the log file. The functionality
+ * is the same as <tt>depth_console</tt>, nevertheless, this function should
+ * be used with care, since it may spoile the value of a log file.
*
* The previous value of this parameter is returned.
*/
/**
* Output time differences between consecutive logs. If this function is
- * invoked with <tt>true</tt>, the time difference between the previous
- * log line and the recent one is printed. If it is invoked with
- * <tt>false</tt>, the accumulated time since start of the program is
- * printed (default behavior).
+ * invoked with <tt>true</tt>, the time difference between the previous log
+ * line and the recent one is printed. If it is invoked with <tt>false</tt>,
+ * the accumulated time since start of the program is printed (default
+ * behavior).
*
* The measurement of times is not changed by this function, just the
* output.
* The default value for this threshold is zero, i.e. numbers are printed
* according to their real value.
*
- * This feature is mostly useful for automated tests: there, one would
- * like to reproduce the exact same solution in each run of a testsuite.
- * However, subtle difference in processor, operating system, or compiler
- * version can lead to differences in the last few digits of numbers, due
- * to different rounding. While one can avoid trouble for most numbers
- * when comparing with stored results by simply limiting the accuracy of
- * output, this does not hold for numbers very close to zero, i.e. zero
- * plus accumulated round-off. For these numbers, already the first digit
- * is tainted by round-off. Using the present function, it is possible to
- * eliminate this source of problems, by simply writing zero to the
- * output in this case.
+ * This feature is mostly useful for automated tests: there, one would like
+ * to reproduce the exact same solution in each run of a testsuite. However,
+ * subtle difference in processor, operating system, or compiler version can
+ * lead to differences in the last few digits of numbers, due to different
+ * rounding. While one can avoid trouble for most numbers when comparing
+ * with stored results by simply limiting the accuracy of output, this does
+ * not hold for numbers very close to zero, i.e. zero plus accumulated
+ * round-off. For these numbers, already the first digit is tainted by
+ * round-off. Using the present function, it is possible to eliminate this
+ * source of problems, by simply writing zero to the output in this case.
*/
void threshold_double(const double t);
/**
- * set the precision for the underlying stream and returns the
- * previous stream precision. This fuction mimics
+ * set the precision for the underlying stream and returns the previous
+ * stream precision. This fuction mimics
* http://www.cplusplus.com/reference/ios/ios_base/precision/
*/
std::streamsize precision (const std::streamsize prec);
/**
- * set the width for the underlying stream and returns the
- * previous stream width. This fuction mimics
+ * set the width for the underlying stream and returns the previous stream
+ * width. This fuction mimics
* http://www.cplusplus.com/reference/ios/ios_base/width/
*/
std::streamsize width (const std::streamsize wide);
/**
- * set the flags for the underlying stream and returns the
- * previous stream flags. This fuction mimics
+ * set the flags for the underlying stream and returns the previous stream
+ * flags. This fuction mimics
* http://www.cplusplus.com/reference/ios/ios_base/flags/
*/
std::ios::fmtflags flags(const std::ios::fmtflags f);
/**
* Treat ostream manipulators. This passes on the whole thing to the
* template function with the exception of the <tt>std::endl</tt>
- * manipulator, for which special action is performed: write the
- * temporary stream buffer including a header to the file and
- * <tt>std::cout</tt> and empty the buffer.
+ * manipulator, for which special action is performed: write the temporary
+ * stream buffer including a header to the file and <tt>std::cout</tt> and
+ * empty the buffer.
*
- * An overload of this function is needed anyway, since the compiler
- * can't bind manipulators like @p std::endl directly to template
- * arguments @p T like in the previous general template. This is due to
- * the fact that @p std::endl is actually an overloaded set of functions
- * for @p std::ostream, @p std::wostream, and potentially more of this
- * kind. This function is therefore necessary to pick one element from
- * this overload set.
+ * An overload of this function is needed anyway, since the compiler can't
+ * bind manipulators like @p std::endl directly to template arguments @p T
+ * like in the previous general template. This is due to the fact that @p
+ * std::endl is actually an overloaded set of functions for @p std::ostream,
+ * @p std::wostream, and potentially more of this kind. This function is
+ * therefore necessary to pick one element from this overload set.
*/
LogStream &operator<< (std::ostream& (*p) (std::ostream &));
/**
* Determine an estimate for the memory consumption (in bytes) of this
- * object. Since sometimes the size of objects can not be determined
- * exactly (for example: what is the memory consumption of an STL
- * <tt>std::map</tt> type with a certain number of elements?), this is
- * only an estimate. however often quite close to the true value.
+ * object. Since sometimes the size of objects can not be determined exactly
+ * (for example: what is the memory consumption of an STL <tt>std::map</tt>
+ * type with a certain number of elements?), this is only an estimate.
+ * however often quite close to the true value.
*/
std::size_t memory_consumption () const;
/**
- * Internal wrapper around thread-local prefixes. This private
- * function will return the correct internal prefix stack. More
- * important, a new thread-local stack will be copied from the current
- * stack of the "blessed" thread that created this LogStream instance
- * (usually, in the case of deallog, the "main" thread).
+ * Internal wrapper around thread-local prefixes. This private function will
+ * return the correct internal prefix stack. More important, a new thread-
+ * local stack will be copied from the current stack of the "blessed" thread
+ * that created this LogStream instance (usually, in the case of deallog,
+ * the "main" thread).
*/
std::stack<std::string> &get_prefixes() const;
/**
- * Stack of strings which are printed at the beginning of each line to
- * allow identification where the output was generated.
+ * Stack of strings which are printed at the beginning of each line to allow
+ * identification where the output was generated.
*/
mutable Threads::ThreadLocalStorage<std::stack<std::string> > prefixes;
/**
* Value denoting the number of prefixes to be printed to the standard
- * output. If more than this number of prefixes is pushed to the stack,
- * then no output will be generated until the number of prefixes shrinks
- * back below this number.
+ * output. If more than this number of prefixes is pushed to the stack, then
+ * no output will be generated until the number of prefixes shrinks back
+ * below this number.
*/
unsigned int std_depth;
float float_threshold;
/**
- * An offset added to every float or double number upon output. This is
- * done after the number is compared to #double_threshold or
- * #float_threshold, but before rounding.
+ * An offset added to every float or double number upon output. This is done
+ * after the number is compared to #double_threshold or #float_threshold,
+ * but before rounding.
*
- * This functionality was introduced to produce more reproducible
- * floating point output for regression tests. The rationale is, that an
- * exact output value is much more likely to be 1/8 than 0.124997. If we
- * round to two digits though, 1/8 becomes unreliably either .12 or .13
- * due to machine accuracy. On the other hand, if we add a something
- * above machine accuracy first, we will always get .13.
+ * This functionality was introduced to produce more reproducible floating
+ * point output for regression tests. The rationale is, that an exact output
+ * value is much more likely to be 1/8 than 0.124997. If we round to two
+ * digits though, 1/8 becomes unreliably either .12 or .13 due to machine
+ * accuracy. On the other hand, if we add a something above machine accuracy
+ * first, we will always get .13.
*
- * It is safe to leave this value equal to zero. For regression tests,
- * the function test_mode() sets it to a reasonable value.
+ * It is safe to leave this value equal to zero. For regression tests, the
+ * function test_mode() sets it to a reasonable value.
*
* The offset is relative to the magnitude of the number.
*/
/**
* Original buffer of <tt>std::cerr</tt>. We store the address of that
- * buffer when #log_cerr is called, and reset it to this value if
- * #log_cerr is called a second time, or when the destructor of this
- * class is run.
+ * buffer when #log_cerr is called, and reset it to this value if #log_cerr
+ * is called a second time, or when the destructor of this class is run.
*/
std::streambuf *old_cerr;
void print_line_head ();
/**
- * Internal wrapper around "thread local" outstreams. This private
- * function will return the correct internal ostringstream buffer for
- * operater<<.
+ * Internal wrapper around "thread local" outstreams. This private function
+ * will return the correct internal ostringstream buffer for operater<<.
*/
std::ostringstream &get_stream();
/**
- * We use tbb's thread local storage facility to generate a stringstream
- * for every thread that sends log messages.
+ * We use tbb's thread local storage facility to generate a stringstream for
+ * every thread that sends log messages.
*/
Threads::ThreadLocalStorage<std_cxx11::shared_ptr<std::ostringstream> > outstreams;
/**
- * This namespace provides functions helping to determine the amount
- * of memory used by objects. The goal is not necessarily to give the
- * amount of memory used up to the last bit (what is the memory used
- * by an STL <tt>std::map<></tt> object?), but rather to aid in the search for
- * memory bottlenecks.
+ * This namespace provides functions helping to determine the amount of memory
+ * used by objects. The goal is not necessarily to give the amount of memory
+ * used up to the last bit (what is the memory used by an STL
+ * <tt>std::map<></tt> object?), but rather to aid in the search for memory
+ * bottlenecks.
*
- * This namespace has a single member function memory_consumption()
- * and a lot of specializations. Depending on the argument type of the
- * function, there are several modes of operation:
+ * This namespace has a single member function memory_consumption() and a lot
+ * of specializations. Depending on the argument type of the function, there
+ * are several modes of operation:
*
* <ol>
- * <li> The argument is a standard C++ data type, namely,
- * <tt>bool</tt>, <tt>float</tt>, <tt>double</tt> or any of the
- * integer types. In that case, memory_consumption() simple returns
- * <tt>sizeof</tt> of its argument. The library also provides an
- * estimate for the amount of memory occupied by a
+ * <li> The argument is a standard C++ data type, namely, <tt>bool</tt>,
+ * <tt>float</tt>, <tt>double</tt> or any of the integer types. In that case,
+ * memory_consumption() simple returns <tt>sizeof</tt> of its argument. The
+ * library also provides an estimate for the amount of memory occupied by a
* <tt>std::string</tt> this way.
*
* <li> For objects, which are neither standard types, nor vectors,
- * memory_consumption() will simply call the member function of same
- * name. It is up to the implementation of the data type to provide a
- * good estimate of the amount of memory used. Inside this function,
- * the use of MemoryConsumpton::memory_consumption() for compounds of
- * the class helps to obtain this estimate. Most classes in the
- * deal.II library have such a member function.
+ * memory_consumption() will simply call the member function of same name. It
+ * is up to the implementation of the data type to provide a good estimate of
+ * the amount of memory used. Inside this function, the use of
+ * MemoryConsumpton::memory_consumption() for compounds of the class helps to
+ * obtain this estimate. Most classes in the deal.II library have such a
+ * member function.
*
* <li> For vectors and C++ arrays of objects, memory_consumption()
- * recursively calls itself for all entries and adds the results to
- * the size of the object itself. Some optimized specializations for
- * standard data types exist.
+ * recursively calls itself for all entries and adds the results to the size
+ * of the object itself. Some optimized specializations for standard data
+ * types exist.
*
- * <li> For vectors of regular pointers, memory_consumption(T*)
- * returns the size of the vector of pointers, ignoring the size of
- * the objects.
+ * <li> For vectors of regular pointers, memory_consumption(T*) returns the
+ * size of the vector of pointers, ignoring the size of the objects.
*
* </ol>
*
* <h3>Extending this namespace</h3>
*
- * The function in this namespace and the functionality provided by
- * it relies on the assumption that there is either a specialized function
- * <tt>memory_consumption(T)</tt> in this namespace determining the amount
- * of memory used by objects of type <tt>T</tt>, or that the class <tt>T</tt> has
- * a member function of that name. While the latter is
- * true for almost all classes in deal.II, we have only implemented the
- * first kind of functions for the most common data types, such as
- * atomic types, strings, C++ vectors, C-style arrays, and C++
- * pairs. These functions therefore do not cover, for example, C++
- * maps, lists, etc. If you need such functions feel free to implement
- * them and send them to us for inclusion.
+ * The function in this namespace and the functionality provided by it relies
+ * on the assumption that there is either a specialized function
+ * <tt>memory_consumption(T)</tt> in this namespace determining the amount of
+ * memory used by objects of type <tt>T</tt>, or that the class <tt>T</tt> has
+ * a member function of that name. While the latter is true for almost all
+ * classes in deal.II, we have only implemented the first kind of functions
+ * for the most common data types, such as atomic types, strings, C++ vectors,
+ * C-style arrays, and C++ pairs. These functions therefore do not cover, for
+ * example, C++ 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, documentation updated by Guido Kanschat
{
/**
- * This function is the generic
- * interface for determining the
- * memory used by an object. If no
- * specialization for the type
- * <tt>T</tt> is specified, it will
- * call the member function
- * <tt>t.memory_consumption()</tt>.
+ * This function is the generic interface for determining the memory used by
+ * an object. If no specialization for the type <tt>T</tt> is specified, it
+ * will call the member function <tt>t.memory_consumption()</tt>.
*
- * The library provides
- * specializations for all basic
- * C++ data types. Every additional
- * type needs to have a member
- * function memory_consumption()
- * callable for constant objects to
- * be used in this framework.
+ * The library provides specializations for all basic C++ data types. Every
+ * additional type needs to have a member function memory_consumption()
+ * callable for constant objects to be used in this framework.
*/
template <typename T>
inline
std::size_t memory_consumption (const T &t);
/**
- * Determine the amount of memory
- * in bytes consumed by a <tt>bool</tt>
+ * Determine the amount of memory in bytes consumed by a <tt>bool</tt>
* variable.
*/
inline
std::size_t memory_consumption (const bool);
/**
- * Determine the amount of memory
- * in bytes consumed by a <tt>char</tt>
+ * Determine the amount of memory in bytes consumed by a <tt>char</tt>
* variable.
*/
inline
std::size_t memory_consumption (const char);
/**
- * Determine the amount of memory
- * in bytes consumed by a
- * <tt>short int</tt> variable.
+ * Determine the amount of memory in bytes consumed by a <tt>short int</tt>
+ * variable.
*/
inline
std::size_t memory_consumption (const short int);
/**
- * Determine the amount of memory
- * in bytes consumed by a
- * <tt>short unsigned int</tt> variable.
+ * Determine the amount of memory in bytes consumed by a <tt>short unsigned
+ * int</tt> variable.
*/
inline
std::size_t memory_consumption (const short unsigned int);
/**
- * Determine the amount of memory
- * in bytes consumed by a <tt>int</tt>
+ * Determine the amount of memory in bytes consumed by a <tt>int</tt>
* variable.
*/
inline
std::size_t memory_consumption (const int);
/**
- * Determine the amount of memory
- * in bytes consumed by a <tt>unsigned int</tt>
- * variable.
+ * Determine the amount of memory in bytes consumed by a <tt>unsigned
+ * int</tt> variable.
*/
inline
std::size_t memory_consumption (const unsigned int);
/**
- * Determine the amount of memory
- * in bytes consumed by a <tt>unsigned long long int</tt>
- * variable.
+ * Determine the amount of memory in bytes consumed by a <tt>unsigned long
+ * long int</tt> variable.
*/
inline
std::size_t memory_consumption (const unsigned long long int);
/**
- * Determine the amount of memory
- * in bytes consumed by a <tt>float</tt>
+ * Determine the amount of memory in bytes consumed by a <tt>float</tt>
* variable.
*/
inline
std::size_t memory_consumption (const float);
/**
- * Determine the amount of memory
- * in bytes consumed by a <tt>double</tt>
+ * Determine the amount of memory in bytes consumed by a <tt>double</tt>
* variable.
*/
inline
std::size_t memory_consumption (const double);
/**
- * Determine the amount of memory
- * in bytes consumed by a <tt>long double</tt>
- * variable.
+ * Determine the amount of memory in bytes consumed by a <tt>long
+ * double</tt> variable.
*/
inline
std::size_t memory_consumption (const long double);
/**
- * Determine the amount of memory
- * in bytes consumed by a <tt>std::complex</tt>
- * variable.
+ * Determine the amount of memory in bytes consumed by a
+ * <tt>std::complex</tt> variable.
*/
template <typename T>
inline
std::size_t memory_consumption (const VectorizedArray<T> &);
/**
- * Determine an estimate of the
- * amount of memory in bytes
- * consumed by a <tt>std::string</tt>
- * variable.
+ * Determine an estimate of the amount of memory in bytes consumed by a
+ * <tt>std::string</tt> variable.
*/
inline
std::size_t memory_consumption (const std::string &s);
/**
- * Determine the amount of memory
- * in bytes consumed by a
- * <tt>std::vector</tt> of elements
- * of type <tt>T</tt> by
- * recursively calling
- * memory_consumption() for each entry.
+ * Determine the amount of memory in bytes consumed by a
+ * <tt>std::vector</tt> of elements of type <tt>T</tt> by recursively
+ * calling memory_consumption() for each entry.
*
- * This function loops over all
- * entries of the vector and
- * determines their sizes using
- * memory_consumption() for each
- * <tt>v[i]</tt>. If the entries
- * are of constant size, there
- * might be another global function
- * memory_consumption() for this
- * data type or if there is a
- * member function of that class of
- * that names that returns a
- * constant value and the compiler
- * will unroll this loop so that
- * the operation is fast. If the
- * size of the data elements is
- * variable, for example if they do
- * memory allocation themselves,
- * then the operation will
- * necessarily be more expensive.
+ * This function loops over all entries of the vector and determines their
+ * sizes using memory_consumption() for each <tt>v[i]</tt>. If the entries
+ * are of constant size, there might be another global function
+ * memory_consumption() for this data type or if there is a member function
+ * of that class of that names that returns a constant value and the
+ * compiler will unroll this loop so that the operation is fast. If the size
+ * of the data elements is variable, for example if they do memory
+ * allocation themselves, then the operation will necessarily be more
+ * expensive.
*
- * Using the algorithm, in
- * particular the loop over all
- * elements, it is possible to also
- * compute the memory consumption
- * of vectors of vectors, vectors
- * of strings, etc, where the
- * individual elements may have
- * vastly different sizes.
+ * Using the algorithm, in particular the loop over all elements, it is
+ * possible to also compute the memory consumption of vectors of vectors,
+ * vectors of strings, etc, where the individual elements may have vastly
+ * different sizes.
*
- * Note that this algorithm also
- * takes into account the size of
- * elements that are allocated by
- * this vector but not currently
- * used.
+ * Note that this algorithm also takes into account the size of elements
+ * that are allocated by this vector but not currently used.
*
- * For the most commonly used
- * vectors, there are special
- * functions that compute the size
- * without a loop. This also
- * applies for the special case of
- * vectors of bools.
+ * For the most commonly used vectors, there are special functions that
+ * compute the size without a loop. This also applies for the special case
+ * of vectors of bools.
*/
template <typename T>
inline
std::size_t memory_consumption (const std::vector<T> &v);
/**
- * Estimate the amount of memory
- * (in bytes) occupied by a
- * C-style array. Since in this
- * library we do not usually
- * store simple data elements
- * like <tt>double</tt>s in such
- * arrays (but rather use STL
- * <tt>std::vector</tt>s or deal.II
- * <tt>Vector</tt> objects), we do not
- * provide specializations like
- * for the <tt>std::vector</tt> arrays, but
- * always use the loop over all
- * elements.
+ * Estimate the amount of memory (in bytes) occupied by a C-style array.
+ * Since in this library we do not usually store simple data elements like
+ * <tt>double</tt>s in such arrays (but rather use STL <tt>std::vector</tt>s
+ * or deal.II <tt>Vector</tt> objects), we do not provide specializations
+ * like for the <tt>std::vector</tt> arrays, but always use the loop over
+ * all elements.
*/
template <typename T, int N>
inline
std::size_t memory_consumption (const T (&v)[N]);
/**
- * Specialization of the
- * determination of the memory
- * consumption of a vector, here
- * for a vector of <tt>bool</tt>s.
+ * Specialization of the determination of the memory consumption of a
+ * vector, here for a vector of <tt>bool</tt>s.
*
- * This is a special case, as the
- * bools are not stored
- * one-by-one, but as a bit
- * field.
+ * This is a special case, as the bools are not stored one-by-one, but as a
+ * bit field.
*/
inline
std::size_t memory_consumption (const std::vector<bool> &v);
/**
- * Specialization of the
- * determination of the memory
- * consumption of a vector, here
- * for a vector of <tt>int</tt>s.
+ * Specialization of the determination of the memory consumption of a
+ * vector, here for a vector of <tt>int</tt>s.
*/
inline
std::size_t memory_consumption (const std::vector<int> &v);
/**
- * Specialization of the
- * determination of the memory
- * consumption of a vector, here
- * for a vector of <tt>double</tt>s.
+ * Specialization of the determination of the memory consumption of a
+ * vector, here for a vector of <tt>double</tt>s.
*/
inline
std::size_t memory_consumption (const std::vector<double> &v);
/**
- * Specialization of the
- * determination of the memory
- * consumption of a vector, here
- * for a vector of <tt>float</tt>s.
+ * Specialization of the determination of the memory consumption of a
+ * vector, here for a vector of <tt>float</tt>s.
*/
inline
std::size_t memory_consumption (const std::vector<float> &v);
/**
- * Specialization of the
- * determination of the memory
- * consumption of a vector, here
- * for a vector of <tt>char</tt>s.
+ * Specialization of the determination of the memory consumption of a
+ * vector, here for a vector of <tt>char</tt>s.
*/
inline
std::size_t memory_consumption (const std::vector<char> &v);
/**
- * Specialization of the
- * determination of the memory
- * consumption of a vector, here
- * for a vector of <tt>unsigned char</tt>s.
+ * Specialization of the determination of the memory consumption of a
+ * vector, here for a vector of <tt>unsigned char</tt>s.
*/
inline
std::size_t memory_consumption (const std::vector<unsigned char> &v);
/**
- * Specialization of the
- * determination of the memory
- * consumption of a vector, here
- * for a vector of pointers.
+ * Specialization of the determination of the memory consumption of a
+ * vector, here for a vector of pointers.
*/
template <typename T>
inline
std::size_t memory_consumption (const std::vector<T *> &v);
/**
- * Specialization of the
- * determination of the memory
- * consumption of a vector, here
- * for a vector of strings. This
- * function is not necessary from a
- * strict C++ viewpoint, since it
- * could be generated, but is
- * necessary for compatibility with
- * IBM's xlC 5.0 compiler, and
- * doesn't harm for other compilers
- * as well.
+ * Specialization of the determination of the memory consumption of a
+ * vector, here for a vector of strings. This function is not necessary from
+ * a strict C++ viewpoint, since it could be generated, but is necessary for
+ * compatibility with IBM's xlC 5.0 compiler, and doesn't harm for other
+ * compilers as well.
*/
std::size_t memory_consumption (const std::vector<std::string> &v);
/**
- * Determine an estimate of the
- * amount of memory in bytes
- * consumed by a pair of values.
+ * Determine an estimate of the amount of memory in bytes consumed by a pair
+ * of values.
*/
template <typename A, typename B>
inline
std::size_t memory_consumption (const std::pair<A,B> &p);
/**
- * Return the amount of memory
- * used by a pointer.
+ * Return the amount of memory used by a pointer.
*
- * @note This returns the size of
- * the pointer, not of the object
- * pointed to.
+ * @note This returns the size of the pointer, not of the object pointed to.
*/
template <typename T>
inline
std::size_t memory_consumption (const T *const);
/**
- * Return the amount of memory
- * used by a pointer.
+ * Return the amount of memory used by a pointer.
*
- * @note This returns the size of
- * the pointer, not of the object
- * pointed to.
+ * @note This returns the size of the pointer, not of the object pointed to.
*/
template <typename T>
inline
std::size_t memory_consumption (T *const);
/**
- * Return the amount of memory
- * used by a void pointer.
+ * Return the amount of memory used by a void pointer.
*
- * Note that we needed this
- * function since <tt>void</tt> is no
- * type and a <tt>void*</tt> is thus
- * not caught by the general
- * <tt>T*</tt> template function
- * above.
+ * Note that we needed this function since <tt>void</tt> is no type and a
+ * <tt>void*</tt> is thus not caught by the general <tt>T*</tt> template
+ * function above.
*
- * @note This returns the size of
- * the pointer, not of the object
- * pointed to.
+ * @note This returns the size of the pointer, not of the object pointed to.
*/
inline
std::size_t memory_consumption (void *const);
/**
- * Return the amount of memory used
- * by a shared pointer.
+ * Return the amount of memory used by a shared pointer.
*
- * @note This returns the size of
- * the pointer, not of the object
- * pointed to.
+ * @note This returns the size of the pointer, not of the object pointed to.
*/
template <typename T>
inline
/**
- * An array with an object for each level. The purpose of this class
- * is mostly to store objects and allow access by level number, even
- * if the lower levels are not used and therefore have no object at
- * all; this is done by simply shifting the given index by the minimum
- * level we have stored.
+ * An array with an object for each level. The purpose of this class is
+ * mostly to store objects and allow access by level number, even if the lower
+ * levels are not used and therefore have no object at all; this is done by
+ * simply shifting the given index by the minimum level we have stored.
*
- * In most cases, the objects which are stored on each levels, are
- * either matrices or vectors.
+ * In most cases, the objects which are stored on each levels, are either
+ * matrices or vectors.
*
* @ingroup mg
* @ingroup data
{
public:
/**
- * Constructor allowing to
- * initialize the number of
- * levels. By default, the object
- * is created empty.
+ * Constructor allowing to initialize the number of levels. By default, the
+ * object is created empty.
*/
MGLevelObject (const unsigned int minlevel = 0,
const unsigned int maxlevel = 0);
Object &operator[] (const unsigned int level);
/**
- * Access object on level
- * @p level. Constant version.
+ * Access object on level @p level. Constant version.
*/
const Object &operator[] (const unsigned int level) const;
/**
- * Delete all previous contents
- * of this object and reset its
- * size according to the values
- * of @p new_minlevel and
- * @p new_maxlevel.
+ * Delete all previous contents of this object and reset its size according
+ * to the values of @p new_minlevel and @p new_maxlevel.
*/
void resize (const unsigned int new_minlevel,
const unsigned int new_maxlevel);
/**
- * Call <tt>operator = (s)</tt>
- * on all objects stored by this
- * object. This is particularly
- * useful for
- * e.g. <tt>Object==Vector@<T@></tt>
+ * Call <tt>operator = (s)</tt> on all objects stored by this object. This
+ * is particularly useful for e.g. <tt>Object==Vector@<T@></tt>
*/
MGLevelObject<Object> &operator = (const double d);
/**
- * Call @p clear on all objects
- * stored by this object. This
- * function is only implemented
- * for some @p Object classes,
- * e.g. the PreconditionBlockSOR
- * and similar classes.
+ * Call @p clear on all objects stored by this object. This function is only
+ * implemented for some @p Object classes, e.g. the PreconditionBlockSOR and
+ * similar classes.
*/
void clear();
char ** &argv) /*DEAL_II_DEPRECATED*/;
/**
- * Initialize MPI (and, if deal.II was configured to use it, PETSc)
- * and set the number of threads used by deal.II (via the underlying
+ * Initialize MPI (and, if deal.II was configured to use it, PETSc) and
+ * set the number of threads used by deal.II (via the underlying
* Threading Building Blocks library) to the given parameter.
*
- * @param[in,out] argc A reference to the 'argc' argument passed to main. This
- * argument is used to initialize MPI (and, possibly, PETSc) as they
- * read arguments from the command line.
- * @param[in,out] argv A reference to the 'argv' argument passed to main.
- * @param[in] max_num_threads The maximal number of threads this MPI process
- * should utilize. If this argument is set to
- * numbers::invalid_unsigned_int, the number of threads is determined by
- * automatically in the following way: the number of
- * threads to run on this MPI process is set in such a way that all of
- * the cores in your node are spoken for. In other words, if you
- * have started one MPI process per node, setting this argument is
- * equivalent to setting it to the number of cores present in the node
- * this MPI process runs on. If you have started as many MPI
- * processes per node as there are cores on each node, then
- * this is equivalent to passing 1 as the argument. On the
- * other hand, if, for example, you start 4 MPI processes
- * on each 16-core node, then this option will start 4 worker
- * threads for each node. If you start 3 processes on an 8 core
- * node, then they will start 3, 3 and 2 threads, respectively.
+ * @param[in,out] argc A reference to the 'argc' argument passed to
+ * main. This argument is used to initialize MPI (and, possibly, PETSc)
+ * as they read arguments from the command line.
+ * @param[in,out] argv A reference to the 'argv' argument passed to
+ * main.
+ * @param[in] max_num_threads The maximal number of threads this MPI
+ * process should utilize. If this argument is set to
+ * numbers::invalid_unsigned_int, the number of threads is determined by
+ * automatically in the following way: the number of threads to run on
+ * this MPI process is set in such a way that all of the cores in your
+ * node are spoken for. In other words, if you have started one MPI
+ * process per node, setting this argument is equivalent to setting it
+ * to the number of cores present in the node this MPI process runs on.
+ * If you have started as many MPI processes per node as there are cores
+ * on each node, then this is equivalent to passing 1 as the argument.
+ * On the other hand, if, for example, you start 4 MPI processes on each
+ * 16-core node, then this option will start 4 worker threads for each
+ * node. If you start 3 processes on an 8 core node, then they will
+ * start 3, 3 and 2 threads, respectively.
*
- * @note This function calls MultithreadInfo::set_thread_limit()
- * with either @p max_num_threads or, following the discussion above, a
- * number of threads equal to the number of cores allocated to this
- * MPI process. However, MultithreadInfo::set_thread_limit() in turn also
- * evaluates the environment variable DEAL_II_NUM_THREADS. Finally, the worker
- * threads can only be created on cores to which the current MPI process has
- * access to; some MPI implementations limit the number of cores each process
- * has access to to one or a subset of cores in order to ensure better cache
- * behavior. Consequently, the number of threads that will really be created
- * will be the minimum of the argument passed here, the environment variable
- * (if set), and the number of cores accessible to the thread.
+ * @note This function calls MultithreadInfo::set_thread_limit() with
+ * either @p max_num_threads or, following the discussion above, a
+ * number of threads equal to the number of cores allocated to this MPI
+ * process. However, MultithreadInfo::set_thread_limit() in turn also
+ * evaluates the environment variable DEAL_II_NUM_THREADS. Finally, the
+ * worker threads can only be created on cores to which the current MPI
+ * process has access to; some MPI implementations limit the number of
+ * cores each process has access to to one or a subset of cores in order
+ * to ensure better cache behavior. Consequently, the number of threads
+ * that will really be created will be the minimum of the argument
+ * passed here, the environment variable (if set), and the number of
+ * cores accessible to the thread.
*/
MPI_InitFinalize (int &argc,
char ** &argv,
* parallel methods is selected automatically by the Threading Building Blocks
* library. See @ref threads for more information on this. Thread-based
* parallel methods need to explicitly created threads and may want to use a
- * number of threads that is related to the number of CPUs in your
- * system. This can be queried using the variable
- * <code>
- * multithread_info.n_cpus;
- * </code>
- * of a global variable <code>multithread_info</code> of this class that, or using
- * <code>
- * multithread_info.n_threads();
- * </code>
+ * number of threads that is related to the number of CPUs in your system.
+ * This can be queried using the variable <code> multithread_info.n_cpus;
+ * </code> of a global variable <code>multithread_info</code> of this class
+ * that, or using <code> multithread_info.n_threads(); </code>
*
* @ingroup threads
* @author Thomas Richter, Wolfgang Bangerth, 2000
{
public:
/**
- * The constructor determines the
- * number of CPUs in the system.
- * At the moment detection of
- * CPUs is only implemented on
- * Linux computers with the /proc
- * filesystem and on Sun
- * machines. The number of CPUs
- * present is set to one if
- * detection failed or if
- * detection is not supported.
+ * The constructor determines the number of CPUs in the system. At the
+ * moment detection of CPUs is only implemented on Linux computers with the
+ * /proc filesystem and on Sun machines. The number of CPUs present is set
+ * to one if detection failed or if detection is not supported.
*/
MultithreadInfo ();
/**
- * The number of CPUs in the
- * system. It is one if
- * detection is not implemented
- * or failed.
+ * The number of CPUs in the system. It is one if detection is not
+ * implemented or failed.
*
- * If it is one, although you
- * are on a multi-processor
- * machine, please refer to the
- * documentation in
- * <tt>multithread_info.cc</tt>
- * near to the <tt>error</tt> directive.
+ * If it is one, although you are on a multi-processor machine, please refer
+ * to the documentation in <tt>multithread_info.cc</tt> near to the
+ * <tt>error</tt> directive.
*/
const unsigned int n_cpus;
* determined how many threads to use, for example when assembling matrices
* in MatrixCreator or generating output in DataOut. To this end,
* n_default_threads is set to n_cpus at the start of the program, but used
- * programs could set it to a different value in their main()
- * function. However, since almost all of deal.II has now been converted to
- * a task-based parallelism model, this variable is no longer used in the
- * library. Instead, the task scheduling methods use the n_threads()
- * function as a guide to how many threads to use, and the current variable
- * is now deprecated.
+ * programs could set it to a different value in their main() function.
+ * However, since almost all of deal.II has now been converted to a task-
+ * based parallelism model, this variable is no longer used in the library.
+ * Instead, the task scheduling methods use the n_threads() function as a
+ * guide to how many threads to use, and the current variable is now
+ * deprecated.
*
* @deprecated: Use n_threads() to query the number of threads to use (if
* you wanted to read this variable), and set_thread_limit() to limit it (if
unsigned int n_threads() const;
/**
- * Determine an estimate for
- * the memory consumption (in
- * bytes) of this
- * object. Since sometimes
- * the size of objects can
- * not be determined exactly
- * (for example: what is the
- * memory consumption of an
- * STL <tt>std::map</tt> type with a
- * certain number of
- * elements?), this is only
- * an estimate. however often
- * quite close to the true
- * value.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object. Since sometimes the size of objects can not be determined exactly
+ * (for example: what is the memory consumption of an STL <tt>std::map</tt>
+ * type with a certain number of elements?), this is only an estimate.
+ * however often quite close to the true value.
*/
static std::size_t memory_consumption ();
/**
- * Sets the maximum number of threads to be used
- * to the minimum of the environment variable DEAL_II_NUM_THREADS
- * and the given parameter (if not the default value). This
- * affects the initialization of the TBB. If neither is given, the
- * default from TBB is used (based on the number of cores in the system).
+ * Sets the maximum number of threads to be used to the minimum of the
+ * environment variable DEAL_II_NUM_THREADS and the given parameter (if not
+ * the default value). This affects the initialization of the TBB. If
+ * neither is given, the default from TBB is used (based on the number of
+ * cores in the system).
*
* This routine is called automatically by MPI_InitFinalize. Due to
* limitations in the way TBB can be controlled, only the first call to this
- * method will have any effect. Use the parameter of the MPI_InitFinalize
- * if you have an MPI based code.
+ * method will have any effect. Use the parameter of the MPI_InitFinalize if
+ * you have an MPI based code.
*/
void set_thread_limit(const unsigned int max_threads = numbers::invalid_unsigned_int);
/**
- * Returns if the TBB is running using a single thread either
- * because of thread affinity or because it is set via a call
- * to set_thread_limit. This is used in the PETScWrappers to
- * avoid using the interface that is not thread-safe.
+ * Returns if the TBB is running using a single thread either because of
+ * thread affinity or because it is set via a call to set_thread_limit. This
+ * is used in the PETScWrappers to avoid using the interface that is not
+ * thread-safe.
*/
bool is_running_single_threaded();
/**
private:
/**
- * Private function to determine
- * the number of CPUs.
- * Implementation for Linux, OSF,
- * SGI, and Sun machines; if no
- * detection of the number of CPUs is
- * supported, or if detection
- * fails, this function returns
- * one.
+ * Private function to determine the number of CPUs. Implementation for
+ * Linux, OSF, SGI, and Sun machines; if no detection of the number of CPUs
+ * is supported, or if detection fails, this function returns one.
*/
static unsigned int get_n_cpus();
/**
* Global variable of type <tt>MultithreadInfo</tt> which you may ask for the
- * number of CPUs in your system, as well as for the default number of
- * threads that multithreaded functions shall use.
+ * number of CPUs in your system, as well as for the default number of threads
+ * that multithreaded functions shall use.
*
* @ingroup threads
*/
class AnyData;
/**
- * @deprecated The use of this class is deprecated and AnyData should
- * be used instead. It is not only more flexible, the way constness
- * was assured in this class never worked the way it was
- * intended. Therefore, the according checks have been disabled.
+ * @deprecated The use of this class is deprecated and AnyData should be used
+ * instead. It is not only more flexible, the way constness was assured in
+ * this class never worked the way it was intended. Therefore, the according
+ * checks have been disabled.
*
- * This class is a collection of DATA objects. Each of the pointers
- * has a name associated, enabling identification by this name rather
- * than the index in the vector only.
+ * This class is a collection of DATA objects. Each of the pointers has a name
+ * associated, enabling identification by this name rather than the index in
+ * the vector only.
*
- * Note that it is the actual data stored in this object. Therefore,
- * for storing vectors and other large objects, it should be
- * considered to use SmartPointer or boost::shared_ptr for DATA.
+ * Note that it is the actual data stored in this object. Therefore, for
+ * storing vectors and other large objects, it should be considered to use
+ * SmartPointer or boost::shared_ptr for DATA.
*
- * Objects of this kind have a smart way of treating constness: if a
- * const data object is added or a const NamedData is supplied with
- * merge(), the object will henceforth consider itself as const
- * (#is_constant will be true). Thus, any subsequent modification will
- * be illegal and ExcConstantObject will be raised in debug mode.
+ * Objects of this kind have a smart way of treating constness: if a const
+ * data object is added or a const NamedData is supplied with merge(), the
+ * object will henceforth consider itself as const (#is_constant will be
+ * true). Thus, any subsequent modification will be illegal and
+ * ExcConstantObject will be raised in debug mode.
*
* @author Guido Kanschat, 2007, 2008, 2009
*/
class NamedData : public Subscriptor
{
public:
- /** Standard constructor creating
- * an empty object.
+ /**
+ * Standard constructor creating an empty object.
*/
NamedData();
/**
- * Assignment operator, copying
- * conversible data from another
- * object.
+ * Assignment operator, copying conversible data from another object.
*/
template <typename DATA2>
NamedData<DATA> &operator = (const NamedData<DATA2> &other);
*/
//@{
/**
- * Add a new data item to the end
- * of the collection.
+ * Add a new data item to the end of the collection.
*/
void add(DATA &v, const std::string &name);
/**
- * Add a new constant data item
- * to the end of the collection
- * and make the collection
- * constant.
+ * Add a new constant data item to the end of the collection and make the
+ * collection constant.
*/
void add(const DATA &v, const std::string &name);
/**
- * Merge the data of another
- * NamedData to the end of this
- * object.
+ * Merge the data of another NamedData to the end of this object.
*
- * If the other object had
- * #is_constant set, so will have
- * this object after merge.
+ * If the other object had #is_constant set, so will have this object after
+ * merge.
*/
template <typename DATA2>
void merge(NamedData<DATA2> &);
/**
- * Merge the data of another
- * NamedData to the end of this
- * object.
+ * Merge the data of another NamedData to the end of this object.
*
- * After this operation, all
- * data in this object will be
- * treated as const.
+ * After this operation, all data in this object will be treated as const.
*/
template <typename DATA2>
void merge(const NamedData<DATA2> &);
//@}
/**
- * \name Accessing and querying
- * contents
+ * \name Accessing and querying contents
*/
//@{
/// Number of stored data objects.
unsigned int size() const;
/**
- * @brief Access to stored data
- * object by index.
+ * @brief Access to stored data object by index.
*
- * @note This function throws an
- * exception, if is_const()
- * returns <tt>true</tt>. In such
- * a case, either cast the
- * NamedData object to a const
- * reference, or use the function
- * read() instead of this operator.
+ * @note This function throws an exception, if is_const() returns
+ * <tt>true</tt>. In such a case, either cast the NamedData object to a
+ * const reference, or use the function read() instead of this operator.
*/
DATA &operator() (unsigned int i);
void print(OUT &o) const;
//@}
/**
- * Exception indicating that a
- * function expected a vector
- * to have a certain name, but
- * NamedData had a different
- * name in that position.
+ * Exception indicating that a function expected a vector to have a certain
+ * name, but NamedData had a different name in that position.
*/
DeclException2(ExcNameMismatch, int, std::string,
<< "Name at position " << arg1 << " is not equal to " << arg2);
/**
- * Exception indicating that read
- * access to stored data was
- * attempted although the
- * NamedData object contains
- * const data and #is_constant
- * was true.
+ * Exception indicating that read access to stored data was attempted
+ * although the NamedData object contains const data and #is_constant was
+ * true.
*/
DeclException0(ExcConstantObject);
/**
* Select data from NamedData corresponding to the attached name.
*
- * Given a list of names to search for (provided by add()), objects of
- * this class provide an index list of the selected data.
+ * Given a list of names to search for (provided by add()), objects of this
+ * class provide an index list of the selected data.
*
* @author Guido Kanschat, 2009
*/
{
public:
/**
- * Add a new name to be searched
- * for in NamedData.
+ * Add a new name to be searched for in NamedData.
*
- * @note Names will be added to
- * the end of the current list.
+ * @note Names will be added to the end of the current list.
*/
void add (const std::string &name);
/**
- * Create the index vector
- * pointing into the NamedData
- * object.
+ * Create the index vector pointing into the NamedData object.
*/
template <typename DATA>
void initialize(const NamedData<DATA> &data);
/**
- * Create the index vector
- * pointing into the AnyData
- * object.
+ * Create the index vector pointing into the AnyData object.
*/
void initialize(const AnyData &data);
/**
- * The number of names in this
- * object. This function may be
- * used whether initialize() was
- * called before or not.
+ * The number of names in this object. This function may be used whether
+ * initialize() was called before or not.
*/
unsigned int size() const;
/**
- * Return the corresponding index
- * in the NamedData object
- * supplied to the last
- * initialize(). It is an error
- * if initialize() has not been
- * called before.
+ * Return the corresponding index in the NamedData object supplied to the
+ * last initialize(). It is an error if initialize() has not been called
+ * before.
*
- * Indices are in the same order
- * as the calls to add().
+ * Indices are in the same order as the calls to add().
*/
unsigned int operator() (unsigned int i) const;
*/
std::vector<std::string> names;
/**
- * The index map generated by
- * initialize() and accessed by
- * operator().
+ * The index map generated by initialize() and accessed by operator().
*/
std::vector<unsigned int> indices;
};
/**
* Namespace for the declaration of universal constants. Since the
- * availability in <tt>math.h</tt> is not always guaranteed, we put
- * them here. Since this file is included by <tt>base/config.h</tt>,
- * they are available to the whole library.
+ * availability in <tt>math.h</tt> is not always guaranteed, we put them here.
+ * Since this file is included by <tt>base/config.h</tt>, they are available
+ * to the whole library.
*
* The constants defined here are a subset of the <tt>M_XXX</tt> constants
* sometimes declared in the system include file <tt>math.h</tt>, but without
* the prefix <tt>M_</tt>.
*
* In addition to that, we declare <tt>invalid_unsigned_int</tt> to be the
- * largest unsigned integer representable; this value is widely used in
- * the library as a marker for an invalid index, an invalid size of an
- * array, and similar purposes.
+ * largest unsigned integer representable; this value is widely used in the
+ * library as a marker for an invalid index, an invalid size of an array, and
+ * similar purposes.
*/
namespace numbers
{
static const double SQRT1_2 = 0.70710678118654752440;
/**
- * Return @p true if the given
- * value is a finite floating
- * point number, i.e. is neither
- * plus or minus infinity nor NaN
- * (not a number).
+ * Return @p true if the given value is a finite floating point number, i.e.
+ * is neither plus or minus infinity nor NaN (not a number).
*
- * Note that the argument type of
- * this function is
- * <code>double</code>. In other
- * words, if you give a very
- * large number of type
- * <code>long double</code>, this
- * function may return
- * <code>false</code> even if the
- * number is finite with respect
- * to type <code>long
- * double</code>.
+ * Note that the argument type of this function is <code>double</code>. In
+ * other words, if you give a very large number of type <code>long
+ * double</code>, this function may return <code>false</code> even if the
+ * number is finite with respect to type <code>long double</code>.
*/
bool is_finite (const double x);
/**
- * Return @p true if real and
- * imaginary parts of the given
- * complex number are finite.
+ * Return @p true if real and imaginary parts of the given complex number
+ * are finite.
*/
bool is_finite (const std::complex<double> &x);
/**
- * Return @p true if real and
- * imaginary parts of the given
- * complex number are finite.
+ * Return @p true if real and imaginary parts of the given complex number
+ * are finite.
*/
bool is_finite (const std::complex<float> &x);
/**
- * Return @p true if real and
- * imaginary parts of the given
- * complex number are finite.
+ * Return @p true if real and imaginary parts of the given complex number
+ * are finite.
*
- * Again may not work correctly if
- * real or imaginary parts are very
- * large numbers that are infinite in
- * terms of <code>double</code>, but
- * finite with respect to
- * <code>long double</code>.
+ * Again may not work correctly if real or imaginary parts are very large
+ * numbers that are infinite in terms of <code>double</code>, but finite
+ * with respect to <code>long double</code>.
*/
bool is_finite (const std::complex<long double> &x);
/**
- * A structure that, together with
- * its partial specializations
- * NumberTraits<std::complex<number> >,
- * provides traits and member
- * functions that make it possible
- * to write templates that work on
- * both real number types and
- * complex number types. This
- * template is mostly used to
- * implement linear algebra classes
- * such as vectors and matrices
- * that work for both real and
- * complex numbers.
+ * A structure that, together with its partial specializations
+ * NumberTraits<std::complex<number> >, provides traits and member functions
+ * that make it possible to write templates that work on both real number
+ * types and complex number types. This template is mostly used to implement
+ * linear algebra classes such as vectors and matrices that work for both
+ * real and complex numbers.
*
* @author Wolfgang Bangerth, 2007
*/
struct NumberTraits
{
/**
- * A flag that specifies whether the
- * template type given to this class is
- * complex or real. Since the general
- * template is selected for non-complex
- * types, the answer is
- * <code>false</code>.
+ * A flag that specifies whether the template type given to this class is
+ * complex or real. Since the general template is selected for non-complex
+ * types, the answer is <code>false</code>.
*/
static const bool is_complex = false;
/**
- * For this data type, typedef the
- * corresponding real type. Since the
- * general template is selected for all
- * data types that are not
- * specializations of std::complex<T>,
- * the underlying type must be
- * real-values, so the real_type is
- * equal to the underlying type.
+ * For this data type, typedef the corresponding real type. Since the
+ * general template is selected for all data types that are not
+ * specializations of std::complex<T>, the underlying type must be real-
+ * values, so the real_type is equal to the underlying type.
*/
typedef number real_type;
/**
- * Return the complex-conjugate of the
- * given number. Since the general
- * template is selected if number is
- * not a complex data type, this
- * function simply returns the given
- * number.
+ * Return the complex-conjugate of the given number. Since the general
+ * template is selected if number is not a complex data type, this
+ * function simply returns the given number.
*/
static
const number &conjugate (const number &x);
/**
- * Return the square of the absolute
- * value of the given number. Since the
- * general template is chosen for types
- * not equal to std::complex, this
- * function simply returns the square
- * of the given number.
+ * Return the square of the absolute value of the given number. Since the
+ * general template is chosen for types not equal to std::complex, this
+ * function simply returns the square of the given number.
*/
static
real_type abs_square (const number &x);
/**
- * Return the absolute value of a
- * number.
+ * Return the absolute value of a number.
*/
static
real_type abs (const number &x);
/**
- * Specialization of the general
- * NumberTraits class that provides the
- * relevant information if the underlying
- * data type is std::complex<T>.
+ * Specialization of the general NumberTraits class that provides the
+ * relevant information if the underlying data type is std::complex<T>.
*
* @author Wolfgang Bangerth, 2007
*/
struct NumberTraits<std::complex<number> >
{
/**
- * A flag that specifies whether the
- * template type given to this class is
- * complex or real. Since this
- * specialization of the general
- * template is selected for complex
- * types, the answer is
- * <code>true</code>.
+ * A flag that specifies whether the template type given to this class is
+ * complex or real. Since this specialization of the general template is
+ * selected for complex types, the answer is <code>true</code>.
*/
static const bool is_complex = true;
/**
- * For this data type, typedef the
- * corresponding real type. Since this
- * specialization of the template is
- * selected for number types
- * std::complex<T>, the real type is
- * equal to the type used to store the
- * two components of the complex
- * number.
+ * For this data type, typedef the corresponding real type. Since this
+ * specialization of the template is selected for number types
+ * std::complex<T>, the real type is equal to the type used to store the
+ * two components of the complex number.
*/
typedef number real_type;
/**
- * Return the complex-conjugate of the
- * given number.
+ * Return the complex-conjugate of the given number.
*/
static
std::complex<number> conjugate (const std::complex<number> &x);
/**
- * Return the square of the absolute
- * value of the given number. Since
- * this specialization of the general
- * template is chosen for types equal
- * to std::complex, this function
- * returns the product of a number and
- * its complex conjugate.
+ * Return the square of the absolute value of the given number. Since this
+ * specialization of the general template is chosen for types equal to
+ * std::complex, this function returns the product of a number and its
+ * complex conjugate.
*/
static
real_type abs_square (const std::complex<number> &x);
/**
- * Return the absolute value of a
- * complex number.
+ * Return the absolute value of a complex number.
*/
static
real_type abs (const std::complex<number> &x);
namespace internal
{
/**
- * Convert a function object of type F
- * into an object that can be applied to
- * all elements of a range of synchronous
- * iterators.
+ * Convert a function object of type F into an object that can be applied
+ * to all elements of a range of synchronous iterators.
*/
template <typename F>
struct Body
{
/**
- * Constructor. Take and package the
- * given function object.
+ * Constructor. Take and package the given function object.
*/
Body (const F &f)
:
const F f;
/**
- * Apply F to a set of iterators with
- * two elements.
+ * Apply F to a set of iterators with two elements.
*/
template <typename I1, typename I2>
static
}
/**
- * Apply F to a set of iterators with
- * three elements.
+ * Apply F to a set of iterators with three elements.
*/
template <typename I1, typename I2, typename I3>
static
}
/**
- * Apply F to a set of iterators with
- * three elements.
+ * Apply F to a set of iterators with three elements.
*/
template <typename I1, typename I2,
typename I3, typename I4>
/**
- * Take a function object and create a
- * Body object from it. We do this in
- * this helper function since
- * alternatively we would have to specify
- * the actual data type of F -- which for
- * function objects is often
+ * Take a function object and create a Body object from it. We do this in
+ * this helper function since alternatively we would have to specify the
+ * actual data type of F -- which for function objects is often
* extraordinarily complicated.
*/
template <typename F>
}
/**
- * An algorithm that performs the action
- * <code>*out++ = predicate(*in++)</code>
- * where the <code>in</code> iterator
- * ranges over the given input range.
+ * An algorithm that performs the action <code>*out++ =
+ * predicate(*in++)</code> where the <code>in</code> iterator ranges over
+ * the given input range.
*
- * This algorithm does pretty much what
- * std::transform does. The difference is
- * that the function can run in parallel
- * when deal.II is configured to use
- * multiple threads.
+ * This algorithm does pretty much what std::transform does. The difference
+ * is that the function can run in parallel when deal.II is configured to
+ * use multiple threads.
*
- * If running in parallel, the iterator range
- * is split into several chunks that are
- * each packaged up as a task and given to
- * the Threading Building Blocks scheduler
- * to work on as compute resources are
- * available. The function returns once all
- * chunks have been worked on. The last
- * argument denotes the minimum number of
- * elements of the iterator range per
- * task; the number must be
- * large enough to amortize the startup
- * cost of new tasks, and small enough to
- * ensure that tasks can be
- * reasonably load balanced.
+ * If running in parallel, the iterator range is split into several chunks
+ * that are each packaged up as a task and given to the Threading Building
+ * Blocks scheduler to work on as compute resources are available. The
+ * function returns once all chunks have been worked on. The last argument
+ * denotes the minimum number of elements of the iterator range per task;
+ * the number must be large enough to amortize the startup cost of new
+ * tasks, and small enough to ensure that tasks can be reasonably load
+ * balanced.
*
- * For a discussion of the kind of
- * problems to which this function
- * is applicable, see the
- * @ref threads "Parallel computing with multiple processors"
- * module.
+ * For a discussion of the kind of problems to which this function is
+ * applicable, see the @ref threads "Parallel computing with multiple
+ * processors" module.
*/
template <typename InputIterator,
typename OutputIterator,
/**
- * An algorithm that performs the action
- * <code>*out++ = predicate(*in1++, *in2++)</code>
- * where the <code>in1</code> iterator
- * ranges over the given input
- * range, using the parallel for
- * operator of tbb.
+ * An algorithm that performs the action <code>*out++ = predicate(*in1++,
+ * *in2++)</code> where the <code>in1</code> iterator ranges over the given
+ * input range, using the parallel for operator of tbb.
*
- * This algorithm does pretty much what
- * std::transform does. The difference is
- * that the function can run in parallel
- * when deal.II is configured to use
- * multiple threads.
+ * This algorithm does pretty much what std::transform does. The difference
+ * is that the function can run in parallel when deal.II is configured to
+ * use multiple threads.
*
- * If running in parallel, the iterator range
- * is split into several chunks that are
- * each packaged up as a task and given to
- * the Threading Building Blocks scheduler
- * to work on as compute resources are
- * available. The function returns once all
- * chunks have been worked on. The last
- * argument denotes the minimum number of
- * elements of the iterator range per
- * task; the number must be
- * large enough to amortize the startup
- * cost of new tasks, and small enough to
- * ensure that tasks can be
- * reasonably load balanced.
+ * If running in parallel, the iterator range is split into several chunks
+ * that are each packaged up as a task and given to the Threading Building
+ * Blocks scheduler to work on as compute resources are available. The
+ * function returns once all chunks have been worked on. The last argument
+ * denotes the minimum number of elements of the iterator range per task;
+ * the number must be large enough to amortize the startup cost of new
+ * tasks, and small enough to ensure that tasks can be reasonably load
+ * balanced.
*
- * For a discussion of the kind of
- * problems to which this function
- * is applicable, see the
- * @ref threads "Parallel computing with multiple processors"
- * module.
+ * For a discussion of the kind of problems to which this function is
+ * applicable, see the @ref threads "Parallel computing with multiple
+ * processors" module.
*/
template <typename InputIterator1,
typename InputIterator2,
/**
- * An algorithm that performs the action
- * <code>*out++ = predicate(*in1++, *in2++, *in3++)</code>
- * where the <code>in1</code> iterator
- * ranges over the given input range.
+ * An algorithm that performs the action <code>*out++ = predicate(*in1++,
+ * *in2++, *in3++)</code> where the <code>in1</code> iterator ranges over
+ * the given input range.
*
- * This algorithm does pretty much what
- * std::transform does. The difference is
- * that the function can run in parallel
- * when deal.II is configured to use
- * multiple threads.
+ * This algorithm does pretty much what std::transform does. The difference
+ * is that the function can run in parallel when deal.II is configured to
+ * use multiple threads.
*
- * If running in parallel, the iterator range
- * is split into several chunks that are
- * each packaged up as a task and given to
- * the Threading Building Blocks scheduler
- * to work on as compute resources are
- * available. The function returns once all
- * chunks have been worked on. The last
- * argument denotes the minimum number of
- * elements of the iterator range per
- * task; the number must be
- * large enough to amortize the startup
- * cost of new tasks, and small enough to
- * ensure that tasks can be
- * reasonably load balanced.
+ * If running in parallel, the iterator range is split into several chunks
+ * that are each packaged up as a task and given to the Threading Building
+ * Blocks scheduler to work on as compute resources are available. The
+ * function returns once all chunks have been worked on. The last argument
+ * denotes the minimum number of elements of the iterator range per task;
+ * the number must be large enough to amortize the startup cost of new
+ * tasks, and small enough to ensure that tasks can be reasonably load
+ * balanced.
*
- * For a discussion of the kind of
- * problems to which this function
- * is applicable, see the
- * @ref threads "Parallel computing with multiple processors"
- * module.
+ * For a discussion of the kind of problems to which this function is
+ * applicable, see the @ref threads "Parallel computing with multiple
+ * processors" module.
*/
template <typename InputIterator1,
typename InputIterator2,
{
#ifdef DEAL_II_WITH_THREADS
/**
- * Take a range argument and call the
- * given function with its begin and end.
+ * Take a range argument and call the given function with its begin and
+ * end.
*/
template <typename RangeType, typename Function>
void apply_to_subranges (const tbb::blocked_range<RangeType> &range,
/**
- * This function applies the given function
- * argument @p f to all elements in the range
- * <code>[begin,end)</code> and may do so
- * in parallel.
+ * This function applies the given function argument @p f to all elements in
+ * the range <code>[begin,end)</code> and may do so in parallel.
*
- * However, in many cases it is not
- * efficient to call a function on each
- * element, so this function calls the
- * given function object on sub-ranges. In
- * other words: if the given range
- * <code>[begin,end)</code> is smaller than
- * grainsize or if multithreading is not
- * enabled, then we call
- * <code>f(begin,end)</code>; otherwise, we
- * may execute, possibly in %parallel, a
- * sequence of calls <code>f(b,e)</code>
- * where <code>[b,e)</code> are
- * subintervals of <code>[begin,end)</code>
- * and the collection of calls we do to
- * <code>f(.,.)</code> will happen on
- * disjoint subintervals that collectively
- * cover the original interval
+ * However, in many cases it is not efficient to call a function on each
+ * element, so this function calls the given function object on sub-ranges.
+ * In other words: if the given range <code>[begin,end)</code> is smaller
+ * than grainsize or if multithreading is not enabled, then we call
+ * <code>f(begin,end)</code>; otherwise, we may execute, possibly in
+ * %parallel, a sequence of calls <code>f(b,e)</code> where
+ * <code>[b,e)</code> are subintervals of <code>[begin,end)</code> and the
+ * collection of calls we do to <code>f(.,.)</code> will happen on disjoint
+ * subintervals that collectively cover the original interval
* <code>[begin,end)</code>.
*
- * Oftentimes, the called function will of
- * course have to get additional
- * information, such as the object to work
- * on for a given value of the iterator
- * argument. This can be achieved by
- * <i>binding</i> certain arguments. For
- * example, here is an implementation of a
- * matrix-vector multiplication $y=Ax$ for
- * a full matrix $A$ and vectors $x,y$:
+ * Oftentimes, the called function will of course have to get additional
+ * information, such as the object to work on for a given value of the
+ * iterator argument. This can be achieved by <i>binding</i> certain
+ * arguments. For example, here is an implementation of a matrix-vector
+ * multiplication $y=Ax$ for a full matrix $A$ and vectors $x,y$:
* @code
* void matrix_vector_product (const FullMatrix &A,
* const Vector &x,
* }
* @endcode
*
- * Note how we use the
- * <code>std_cxx11::bind</code> function to
- * convert
- * <code>mat_vec_on_subranged</code> from a
- * function that takes 5 arguments to one
- * taking 2 by binding the remaining
- * arguments (the modifiers
- * <code>std_cxx11::ref</code> and
- * <code>std_cxx11::cref</code> make sure
- * that the enclosed variables are actually
- * passed by reference and constant
- * reference, rather than by value). The
- * resulting function object requires only
- * two arguments, begin_row and end_row,
- * with all other arguments fixed.
+ * Note how we use the <code>std_cxx11::bind</code> function to convert
+ * <code>mat_vec_on_subranged</code> from a function that takes 5 arguments
+ * to one taking 2 by binding the remaining arguments (the modifiers
+ * <code>std_cxx11::ref</code> and <code>std_cxx11::cref</code> make sure
+ * that the enclosed variables are actually passed by reference and constant
+ * reference, rather than by value). The resulting function object requires
+ * only two arguments, begin_row and end_row, with all other arguments
+ * fixed.
*
- * The code, if in single-thread mode, will
- * call <code>mat_vec_on_subranges</code>
- * on the entire range
- * <code>[0,n_rows)</code> exactly once. In
- * multi-threaded mode, however, it may be
- * called multiple times on subranges of
- * this interval, possibly allowing more
- * than one CPU core to take care of part
- * of the work.
+ * The code, if in single-thread mode, will call
+ * <code>mat_vec_on_subranges</code> on the entire range
+ * <code>[0,n_rows)</code> exactly once. In multi-threaded mode, however, it
+ * may be called multiple times on subranges of this interval, possibly
+ * allowing more than one CPU core to take care of part of the work.
*
- * The @p grainsize argument (50 in the
- * example above) makes sure that subranges
- * do not become too small, to avoid
- * spending more time on scheduling
- * subranges to CPU resources than on doing
- * actual work.
+ * The @p grainsize argument (50 in the example above) makes sure that
+ * subranges do not become too small, to avoid spending more time on
+ * scheduling subranges to CPU resources than on doing actual work.
*
- * For a discussion of the kind of
- * problems to which this function
- * is applicable, see also the
- * @ref threads "Parallel computing with multiple processors"
- * module.
+ * For a discussion of the kind of problems to which this function is
+ * applicable, see also the @ref threads "Parallel computing with multiple
+ * processors" module.
*/
template <typename RangeType, typename Function>
void apply_to_subranges (const RangeType &begin,
struct ParallelForInteger
{
/**
- * Destructor. Made virtual to ensure that derived classes also
- * have virtual destructors.
+ * Destructor. Made virtual to ensure that derived classes also have
+ * virtual destructors.
*/
virtual ~ParallelForInteger ();
/**
- * This function runs the for loop over the
- * given range <tt>[lower,upper)</tt>,
- * possibly in parallel when end-begin is
- * larger than the minimum parallel grain
- * size. This function is marked const because
- * it any operation that changes the data of a
- * derived class will inherently not be
- * thread-safe when several threads work with
- * the same data simultaneously.
+ * This function runs the for loop over the given range
+ * <tt>[lower,upper)</tt>, possibly in parallel when end-begin is larger
+ * than the minimum parallel grain size. This function is marked const
+ * because it any operation that changes the data of a derived class will
+ * inherently not be thread-safe when several threads work with the same
+ * data simultaneously.
*/
void apply_parallel (const std::size_t begin,
const std::size_t end,
const std::size_t minimum_parallel_grain_size) const;
/**
- * Virtual function for working on subrange to
- * be defined in a derived class. This
- * function is marked const because it any
- * operation that changes the data of a
- * derived class will inherently not be
- * thread-safe when several threads work with
- * the same data simultaneously.
+ * Virtual function for working on subrange to be defined in a derived
+ * class. This function is marked const because it any operation that
+ * changes the data of a derived class will inherently not be thread-safe
+ * when several threads work with the same data simultaneously.
*/
virtual void apply_to_subrange (const std::size_t,
const std::size_t) const = 0;
{
#ifdef DEAL_II_WITH_THREADS
/**
- * A class that conforms to the Body
- * requirements of the TBB
- * parallel_reduce function. The first
- * template argument denotes the type on
- * which the reduction is to be done. The
- * second denotes the type of the
- * function object that shall be called
- * for each subrange.
+ * A class that conforms to the Body requirements of the TBB
+ * parallel_reduce function. The first template argument denotes the type
+ * on which the reduction is to be done. The second denotes the type of
+ * the function object that shall be called for each subrange.
*/
template <typename ResultType,
typename Function>
struct ReductionOnSubranges
{
/**
- * A variable that will hold the
- * result of the reduction.
+ * A variable that will hold the result of the reduction.
*/
ResultType result;
/**
- * Constructor. Take the function
- * object to call on each sub-range
- * as well as the neutral element
- * with respect to the reduction
- * operation.
+ * Constructor. Take the function object to call on each sub-range as
+ * well as the neutral element with respect to the reduction operation.
*
- * The second argument denotes a
- * function object that will be used
- * to reduce the result of two
- * computations into one number. An
- * example if we want to simply
- * accumulate integer results would
- * be std::plus<int>().
+ * The second argument denotes a function object that will be used to
+ * reduce the result of two computations into one number. An example if
+ * we want to simply accumulate integer results would be
+ * std::plus<int>().
*/
template <typename Reductor>
ReductionOnSubranges (const Function &f,
{}
/**
- * Splitting constructor. See the TBB
- * book for more details about this.
+ * Splitting constructor. See the TBB book for more details about this.
*/
ReductionOnSubranges (const ReductionOnSubranges &r,
tbb::split)
{}
/**
- * Join operation: merge the results
- * from computations on different
- * sub-intervals.
+ * Join operation: merge the results from computations on different sub-
+ * intervals.
*/
void join (const ReductionOnSubranges &r)
{
}
/**
- * Execute the given function on the
- * specified range.
+ * Execute the given function on the specified range.
*/
template <typename RangeType>
void operator () (const tbb::blocked_range<RangeType> &range)
private:
/**
- * The function object to call on
- * every sub-range.
+ * The function object to call on every sub-range.
*/
const Function f;
/**
- * The neutral element with respect
- * to the reduction operation. This
- * is needed when calling the
- * splitting constructor since we
- * have to re-set the result variable
- * in this case.
+ * The neutral element with respect to the reduction operation. This is
+ * needed when calling the splitting constructor since we have to re-set
+ * the result variable in this case.
*/
const ResultType neutral_element;
/**
- * The function object to be used to
- * reduce the result of two calls
- * into one number.
+ * The function object to be used to reduce the result of two calls into
+ * one number.
*/
const std_cxx11::function<ResultType (ResultType, ResultType)> reductor;
};
/**
- * This function works a lot like the
- * apply_to_subranges(), but it allows to
- * accumulate numerical results computed on
- * each subrange into one number. The type
- * of this number is given by the
- * ResultType template argument that needs
- * to be explicitly specified.
+ * This function works a lot like the apply_to_subranges(), but it allows to
+ * accumulate numerical results computed on each subrange into one number.
+ * The type of this number is given by the ResultType template argument that
+ * needs to be explicitly specified.
*
- * An example of use of this function is to
- * compute the value of the expression $x^T
- * A x$ for a square matrix $A$ and a
- * vector $x$. The sum over rows can be
- * parallelized and the whole code might
- * look like this:
+ * An example of use of this function is to compute the value of the
+ * expression $x^T A x$ for a square matrix $A$ and a vector $x$. The sum
+ * over rows can be parallelized and the whole code might look like this:
* @code
* void matrix_norm (const FullMatrix &A,
* const Vector &x)
* }
* @endcode
*
- * Here,
- * <code>mat_norm_sqr_on_subranges</code>
- * is called on the entire range
- * <code>[0,A.n_rows())</code> if this
- * range is less than the minimum grainsize
- * (above chosen as 50) or if deal.II is
- * configured to not use
- * multithreading. Otherwise, it may be
- * called on subsets of the given range,
- * with results from the individual
- * subranges accumulated internally.
+ * Here, <code>mat_norm_sqr_on_subranges</code> is called on the entire
+ * range <code>[0,A.n_rows())</code> if this range is less than the minimum
+ * grainsize (above chosen as 50) or if deal.II is configured to not use
+ * multithreading. Otherwise, it may be called on subsets of the given
+ * range, with results from the individual subranges accumulated internally.
*
- * @warning If ResultType is a floating point
- * type, then accumulation is not an
- * associative operation. In other words,
- * if the given function object is called
- * three times on three subranges,
- * returning values $a,b,c$, then the
- * returned result of this function is
- * $(a+b)+c$. However, depending on how the
- * three sub-tasks are distributed on
- * available CPU resources, the result may
- * also be $(a+c)+b$ or any other
- * permutation; because floating point
- * addition is not associative (as opposed, of
- * course, to addition of real %numbers),
- * the result of invoking this function
- * several times may differ on the order of
- * round-off.
+ * @warning If ResultType is a floating point type, then accumulation is not
+ * an associative operation. In other words, if the given function object is
+ * called three times on three subranges, returning values $a,b,c$, then the
+ * returned result of this function is $(a+b)+c$. However, depending on how
+ * the three sub-tasks are distributed on available CPU resources, the
+ * result may also be $(a+c)+b$ or any other permutation; because floating
+ * point addition is not associative (as opposed, of course, to addition of
+ * real %numbers), the result of invoking this function several times may
+ * differ on the order of round-off.
*
- * For a discussion of the kind of
- * problems to which this function
- * is applicable, see also the
- * @ref threads "Parallel computing with multiple processors"
- * module.
+ * For a discussion of the kind of problems to which this function is
+ * applicable, see also the @ref threads "Parallel computing with multiple
+ * processors" module.
*/
template <typename ResultType, typename RangeType, typename Function>
ResultType accumulate_from_subranges (const Function &f,
namespace Vector
{
/**
- * If we do computations on vectors in
- * parallel (say, we add two vectors to
- * get a third, and we do the loop over
- * all elements in parallel), then this
- * variable determines the minimum number
- * of elements for which it is profitable
- * to split a range of elements any
- * further to distribute to different
- * threads.
+ * If we do computations on vectors in parallel (say, we add two vectors
+ * to get a third, and we do the loop over all elements in parallel), then
+ * this variable determines the minimum number of elements for which it is
+ * profitable to split a range of elements any further to distribute to
+ * different threads.
*
- * This variable is available as
- * a global writable variable in
- * order to allow the testsuite
- * to also test the parallel
- * case. By default, it is set to
- * several thousand elements,
- * which is a case that the
- * testsuite would not normally
- * encounter. As a consequence,
- * in the testsuite we set it to
- * one -- a value that's hugely
- * unprofitable but definitely
- * tests parallel operations.
+ * This variable is available as a global writable variable in order to
+ * allow the testsuite to also test the parallel case. By default, it is
+ * set to several thousand elements, which is a case that the testsuite
+ * would not normally encounter. As a consequence, in the testsuite we set
+ * it to one -- a value that's hugely unprofitable but definitely tests
+ * parallel operations.
*/
extern unsigned int minimum_parallel_grain_size;
}
namespace SparseMatrix
{
/**
- * Like
- * internal::Vector::minimum_parallel_grain_size,
- * but now denoting the number of rows of
- * a matrix that should be worked on as a
- * minimum.
+ * Like internal::Vector::minimum_parallel_grain_size, but now denoting
+ * the number of rows of a matrix that should be worked on as a minimum.
*/
extern unsigned int minimum_parallel_grain_size;
}
/**
* Base class to declare common interface. The purpose of this class is
- * mostly to define the interface of patterns, and to force derived
- * classes to have a <tt>clone</tt> function. It is thus, in the
- * languages of the "Design Patterns" book (Gamma et al.), a "prototype".
+ * mostly to define the interface of patterns, and to force derived classes
+ * to have a <tt>clone</tt> function. It is thus, in the languages of the
+ * "Design Patterns" book (Gamma et al.), a "prototype".
*/
class PatternBase
{
/**
* Return a pointer to an exact copy of the object. This is necessary
- * since we want to store objects of this type in containers, were we
- * need to copy objects without knowledge of their actual data type (we
- * only have pointers to the base class).
+ * since we want to store objects of this type in containers, were we need
+ * to copy objects without knowledge of their actual data type (we only
+ * have pointers to the base class).
*
* Ownership of the objects returned by this function is passed to the
* caller of this function.
/**
* Determine an estimate for the memory consumption (in bytes) of this
- * object. To avoid unnecessary overhead, we do not force derived
- * classes to provide this function as a virtual overloaded one, but
- * rather try to cast the present object to one of the known derived
- * classes and if that fails then take the size of this base class
- * instead and add 32 byte (this value is arbitrary, it should account
- * for virtual function tables, and some possible data elements). Since
- * there are usually not many thousands of objects of this type around,
- * and since the memory_consumption mechanism is used to find out where
- * memory in the range of many megabytes is, this seems like a
- * reasonable approximation.
+ * object. To avoid unnecessary overhead, we do not force derived classes
+ * to provide this function as a virtual overloaded one, but rather try to
+ * cast the present object to one of the known derived classes and if that
+ * fails then take the size of this base class instead and add 32 byte
+ * (this value is arbitrary, it should account for virtual function
+ * tables, and some possible data elements). Since there are usually not
+ * many thousands of objects of this type around, and since the
+ * memory_consumption mechanism is used to find out where memory in the
+ * range of many megabytes is, this seems like a reasonable approximation.
*
* On the other hand, if you know that your class deviates from this
* assumption significantly, you can still overload this function.
};
/**
- * Returns pointer to the correct derived class based on description.
- */
+ * Returns pointer to the correct derived class based on description.
+ */
PatternBase *pattern_factory (const std::string &description);
/**
* Test for the string being an integer. If bounds are given to the
- * constructor, then the integer given also needs to be within the
- * interval specified by these bounds. Note that unlike common convention
- * in the C++ standard library, both bounds of this interval are
- * inclusive; the reason is that in practice in most cases, one needs
- * closed intervals, but these can only be realized with inclusive bounds
- * for non-integer values. We thus stay consistent by always using closed
- * intervals.
+ * constructor, then the integer given also needs to be within the interval
+ * specified by these bounds. Note that unlike common convention in the C++
+ * standard library, both bounds of this interval are inclusive; the reason
+ * is that in practice in most cases, one needs closed intervals, but these
+ * can only be realized with inclusive bounds for non-integer values. We
+ * thus stay consistent by always using closed intervals.
*
* If the upper bound given to the constructor is smaller than the lower
* bound, then the infinite interval is implied, i.e. every integer is
* allowed.
*
- * Giving bounds may be useful if for example a value can only be
- * positive and less than a reasonable upper bound (for example the
- * number of refinement steps to be performed), or in many other cases.
+ * Giving bounds may be useful if for example a value can only be positive
+ * and less than a reasonable upper bound (for example the number of
+ * refinement steps to be performed), or in many other cases.
*/
class Integer : public PatternBase
{
static const int max_int_value;
/**
- * Constructor. Bounds can be specified within which a valid parameter
- * has to be. If the upper bound is smaller than the lower bound, then
- * the infinite interval is meant. The default values are chosen such
- * that no bounds are enforced on parameters.
+ * Constructor. Bounds can be specified within which a valid parameter has
+ * to be. If the upper bound is smaller than the lower bound, then the
+ * infinite interval is meant. The default values are chosen such that no
+ * bounds are enforced on parameters.
*/
Integer (const int lower_bound = min_int_value,
const int upper_bound = max_int_value);
virtual bool match (const std::string &test_string) const;
/**
- * Return a description of the pattern that valid strings are expected
- * to match. If bounds were specified to the constructor, then include
- * them into this description.
+ * Return a description of the pattern that valid strings are expected to
+ * match. If bounds were specified to the constructor, then include them
+ * into this description.
*/
virtual std::string description () const;
private:
/**
* Value of the lower bound. A number that satisfies the @ref match
- * operation of this class must be equal to this value or larger, if
- * the bounds of the interval for a valid range.
+ * operation of this class must be equal to this value or larger, if the
+ * bounds of the interval for a valid range.
*/
const int lower_bound;
};
/**
- * Test for the string being a <tt>double</tt>. If bounds are given to
- * the constructor, then the integer given also needs to be within the
- * interval specified by these bounds. Note that unlike common convention
- * in the C++ standard library, both bounds of this interval are
- * inclusive; the reason is that in practice in most cases, one needs
- * closed intervals, but these can only be realized with inclusive bounds
- * for non-integer values. We thus stay consistent by always using closed
- * intervals.
+ * Test for the string being a <tt>double</tt>. If bounds are given to the
+ * constructor, then the integer given also needs to be within the interval
+ * specified by these bounds. Note that unlike common convention in the C++
+ * standard library, both bounds of this interval are inclusive; the reason
+ * is that in practice in most cases, one needs closed intervals, but these
+ * can only be realized with inclusive bounds for non-integer values. We
+ * thus stay consistent by always using closed intervals.
*
* If the upper bound given to the constructor is smaller than the lower
* bound, then the infinite interval is implied, i.e. every integer is
* allowed.
*
- * Giving bounds may be useful if for example a value can only be
- * positive and less than a reasonable upper bound (for example damping
- * parameters are frequently only reasonable if between zero and one), or
- * in many other cases.
+ * Giving bounds may be useful if for example a value can only be positive
+ * and less than a reasonable upper bound (for example damping parameters
+ * are frequently only reasonable if between zero and one), or in many other
+ * cases.
*/
class Double : public PatternBase
{
public:
/**
* Minimal double value. If the <tt>std::numeric_limits</tt> class is
- * available use this information to obtain the extremal values,
- * otherwise set it so that this class understands that all values are
- * allowed.
+ * available use this information to obtain the extremal values, otherwise
+ * set it so that this class understands that all values are allowed.
*/
static const double min_double_value;
/**
- * Maximal double value. If the numeric_limits class is available use
- * this information to obtain the extremal values, otherwise set it so
- * that this class understands that all values are allowed.
+ * Maximal double value. If the numeric_limits class is available use this
+ * information to obtain the extremal values, otherwise set it so that
+ * this class understands that all values are allowed.
*/
static const double max_double_value;
/**
- * Constructor. Bounds can be specified within which a valid parameter
- * has to be. If the upper bound is smaller than the lower bound, then
- * the infinite interval is meant. The default values are chosen such
- * that no bounds are enforced on parameters.
+ * Constructor. Bounds can be specified within which a valid parameter has
+ * to be. If the upper bound is smaller than the lower bound, then the
+ * infinite interval is meant. The default values are chosen such that no
+ * bounds are enforced on parameters.
*/
Double (const double lower_bound = min_double_value,
const double upper_bound = max_double_value);
/**
- * Return <tt>true</tt> if the string is a number and its value is
- * within the specified range.
+ * Return <tt>true</tt> if the string is a number and its value is within
+ * the specified range.
*/
virtual bool match (const std::string &test_string) const;
/**
- * Return a description of the pattern that valid strings are expected
- * to match. If bounds were specified to the constructor, then include
- * them into this description.
+ * Return a description of the pattern that valid strings are expected to
+ * match. If bounds were specified to the constructor, then include them
+ * into this description.
*/
virtual std::string description () const;
private:
/**
* Value of the lower bound. A number that satisfies the @ref match
- * operation of this class must be equal to this value or larger, if
- * the bounds of the interval for a valid range.
+ * operation of this class must be equal to this value or larger, if the
+ * bounds of the interval for a valid range.
*/
const double lower_bound;
/**
* Test for the string being one of a sequence of values given like a
- * regular expression. For example, if the string given to the
- * constructor is <tt>"red|blue|black"</tt>, then the @ref match function
- * returns <tt>true</tt> exactly if the string is either "red" or "blue"
- * or "black". Spaces around the pipe signs do not matter and are
- * eliminated.
+ * regular expression. For example, if the string given to the constructor
+ * is <tt>"red|blue|black"</tt>, then the @ref match function returns
+ * <tt>true</tt> exactly if the string is either "red" or "blue" or "black".
+ * Spaces around the pipe signs do not matter and are eliminated.
*/
class Selection : public PatternBase
{
virtual bool match (const std::string &test_string) const;
/**
- * Return a description of the pattern that valid strings are expected
- * to match. Here, this is the list of valid strings passed to the
+ * Return a description of the pattern that valid strings are expected to
+ * match. Here, this is the list of valid strings passed to the
* constructor.
*/
virtual std::string description () const;
private:
/**
- * List of valid strings as passed to the constructor. We don't make
- * this string constant, as we process it somewhat in the constructor.
+ * List of valid strings as passed to the constructor. We don't make this
+ * string constant, as we process it somewhat in the constructor.
*/
std::string sequence;
/**
* This pattern matches a list of values separated by commas (or another
- * string), each of which
- * have to match a pattern given to the constructor. With two additional
- * parameters, the number of elements this list has to have can be
- * specified. If none is specified, the list may have zero or more
- * entries.
+ * string), each of which have to match a pattern given to the constructor.
+ * With two additional parameters, the number of elements this list has to
+ * have can be specified. If none is specified, the list may have zero or
+ * more entries.
*/
class List : public PatternBase
{
virtual ~List ();
/**
- * Return <tt>true</tt> if the
- * string is a comma-separated list of strings each of which match the
- * pattern given to the constructor.
+ * Return <tt>true</tt> if the string is a comma-separated list of strings
+ * each of which match the pattern given to the constructor.
*/
virtual bool match (const std::string &test_string) const;
/**
- * Return a description of the pattern that valid strings are expected
- * to match.
+ * Return a description of the pattern that valid strings are expected to
+ * match.
*/
virtual std::string description () const;
*/
std::size_t memory_consumption () const;
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception.
/**
* This pattern matches a list of comma-separated values each of which
* denotes a pair of key and value. Both key and value have to match a
- * pattern given to the constructor. For each entry of the map,
- * parameters have to be entered in the form <code>key: value</code>. In
- * other words, a map is described in the form
- * <code>key1: value1, key2: value2, key3: value3, ...</code>. A constructor
- * argument allows to choose a delimiter between pairs other than the comma.
+ * pattern given to the constructor. For each entry of the map, parameters
+ * have to be entered in the form <code>key: value</code>. In other words, a
+ * map is described in the form <code>key1: value1, key2: value2, key3:
+ * value3, ...</code>. A constructor argument allows to choose a delimiter
+ * between pairs other than the comma.
*
- * With two additional parameters, the number of elements this list has
- * to have can be specified. If none is specified, the map may have zero
- * or more entries.
+ * With two additional parameters, the number of elements this list has to
+ * have can be specified. If none is specified, the map may have zero or
+ * more entries.
*/
class Map : public PatternBase
{
virtual ~Map ();
/**
- * Return <tt>true</tt> if the string is a comma-separated list of
- * strings each of which match the pattern given to the constructor.
+ * Return <tt>true</tt> if the string is a comma-separated list of strings
+ * each of which match the pattern given to the constructor.
*/
virtual bool match (const std::string &test_string) const;
/**
- * Return a description of the pattern that valid strings are expected
- * to match.
+ * Return a description of the pattern that valid strings are expected to
+ * match.
*/
virtual std::string description () const;
*/
std::size_t memory_consumption () const;
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception.
/**
- * This class is much like the Selection class, but it allows the input
- * to be a comma-separated list of values which each have to be given in
- * the constructor argument. Alternatively, it could be viewed as a
+ * This class is much like the Selection class, but it allows the input to
+ * be a comma-separated list of values which each have to be given in the
+ * constructor argument. Alternatively, it could be viewed as a
* specialization of the List class. For example, if the string to the
- * constructor was <tt>"ucd|gmv|eps"</tt>, then the following would be
- * legal input: <tt>eps</tt>, <tt>gmv</tt>. You may give an arbitrarily
- * long list of values, where there may be as many spaces around commas
- * as you like. However, commas are not allowed inside the values given
- * to the constructor.
+ * constructor was <tt>"ucd|gmv|eps"</tt>, then the following would be legal
+ * input: <tt>eps</tt>, <tt>gmv</tt>. You may give an arbitrarily long list
+ * of values, where there may be as many spaces around commas as you like.
+ * However, commas are not allowed inside the values given to the
+ * constructor.
*/
class MultipleSelection : public PatternBase
{
virtual bool match (const std::string &test_string) const;
/**
- * Return a description of the pattern that valid strings are expected
- * to match. Here, this is the list of valid strings passed to the
+ * Return a description of the pattern that valid strings are expected to
+ * match. Here, this is the list of valid strings passed to the
* constructor.
*/
virtual std::string description () const;
*/
std::size_t memory_consumption () const;
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception.
//@}
private:
/**
- * List of valid strings as passed to the constructor. We don't make
- * this string constant, as we process it somewhat in the constructor.
+ * List of valid strings as passed to the constructor. We don't make this
+ * string constant, as we process it somewhat in the constructor.
*/
std::string sequence;
};
/**
- * Test for the string being either "true" or "false". This is mapped to
- * the Selection class.
+ * Test for the string being either "true" or "false". This is mapped to the
+ * Selection class.
*/
class Bool : public Selection
{
Bool ();
/**
- * Return a description of the pattern that valid strings are expected
- * to match.
+ * Return a description of the pattern that valid strings are expected to
+ * match.
*/
virtual std::string description () const;
virtual bool match (const std::string &test_string) const;
/**
- * Return a description of the pattern that valid strings are expected
- * to match. Here, this is the string <tt>"[Anything]"</tt>.
+ * Return a description of the pattern that valid strings are expected to
+ * match. Here, this is the string <tt>"[Anything]"</tt>.
*/
virtual std::string description () const;
/**
- * A pattern that can be used to indicate when a parameter is intended to
- * be the name of a file. By itself, this class does not check whether
- * the string that is given in a parameter file actually corresponds to
- * an existing file (it could, for example, be the name of a file to
- * which you want to write output). Functionally, the class is therefore
- * equivalent to the Anything class. However, it allows to specify the
- * <i>intent</i> of a parameter. The flag given to the constructor also
- * allows to specify whether the file is supposed to be an input or
- * output file.
+ * A pattern that can be used to indicate when a parameter is intended to be
+ * the name of a file. By itself, this class does not check whether the
+ * string that is given in a parameter file actually corresponds to an
+ * existing file (it could, for example, be the name of a file to which you
+ * want to write output). Functionally, the class is therefore equivalent to
+ * the Anything class. However, it allows to specify the <i>intent</i> of a
+ * parameter. The flag given to the constructor also allows to specify
+ * whether the file is supposed to be an input or output file.
*
- * The reason for the existence of this class is to support graphical
- * user interfaces for editing parameter files. These may open a file
- * selection dialog if the filename is supposed to represent an input
- * file.
+ * The reason for the existence of this class is to support graphical user
+ * interfaces for editing parameter files. These may open a file selection
+ * dialog if the filename is supposed to represent an input file.
*/
class FileName : public PatternBase
{
virtual bool match (const std::string &test_string) const;
/**
- * Return a description of the pattern that valid strings are expected
- * to match. Here, this is the string <tt>"[Filename]"</tt>.
+ * Return a description of the pattern that valid strings are expected to
+ * match. Here, this is the string <tt>"[Filename]"</tt>.
*/
virtual std::string description () const;
/**
- * A pattern that can be used to indicate when a parameter is intended to
- * be the name of a directory. By itself, this class does not check
- * whether the string that is given in a parameter file actually
- * corresponds to an existing directory. Functionally, the class is
- * therefore equivalent to the Anything class. However, it allows to
- * specify the <i>intent</i> of a parameter.
+ * A pattern that can be used to indicate when a parameter is intended to be
+ * the name of a directory. By itself, this class does not check whether the
+ * string that is given in a parameter file actually corresponds to an
+ * existing directory. Functionally, the class is therefore equivalent to
+ * the Anything class. However, it allows to specify the <i>intent</i> of a
+ * parameter.
*
- * The reason for the existence of this class is to support graphical
- * user interfaces for editing parameter files. These may open a file
- * selection dialog to select or create a directory.
+ * The reason for the existence of this class is to support graphical user
+ * interfaces for editing parameter files. These may open a file selection
+ * dialog to select or create a directory.
*/
class DirectoryName : public PatternBase
{
virtual bool match (const std::string &test_string) const;
/**
- * Return a description of the pattern that valid strings are expected
- * to match. Here, this is the string <tt>"[Filename]"</tt>.
+ * Return a description of the pattern that valid strings are expected to
+ * match. Here, this is the string <tt>"[Filename]"</tt>.
*/
virtual std::string description () const;
/**
- * The ParameterHandler class provides a standard interface to an input
- * file which provides at run-time for program parameters such as time
- * step sizes, geometries, right hand sides etc. The input for the
- * program is given in files, streams or strings in memory using text
- * like
+ * The ParameterHandler class provides a standard interface to an input file
+ * which provides at run-time for program parameters such as time step sizes,
+ * geometries, right hand sides etc. The input for the program is given in
+ * files, streams or strings in memory using text like
* @code
* set Time step size = 0.3
* set Geometry = [0,1]x[0,3]
* @endcode
- * Input may be sorted into subsection trees in order to give the input a
- * logical structure, and input files may include other files.
+ * Input may be sorted into subsection trees in order to give the input a
+ * logical structure, and input files may include other files.
*
- * The ParameterHandler class is discussed in detail in the @ref step_19
- * "step-19" example program, and is used in more realistic situations in
- * step-29, step-33 and step-34.
+ * The ParameterHandler class is discussed in detail in the @ref step_19
+ * "step-19" example program, and is used in more realistic situations in
+ * step-29, step-33 and step-34.
*
- * <h3>Declaring entries</h3>
+ * <h3>Declaring entries</h3>
*
- * In order to use the facilities of a ParameterHandler object, one first
- * has to make known the different entries the input file may or may not
- * contain. This is done in the following way:
+ * In order to use the facilities of a ParameterHandler object, one first has
+ * to make known the different entries the input file may or may not contain.
+ * This is done in the following way:
*
* @code
* ...
* Patterns::Anything());
* ...
* @endcode
- * Each entry is declared using the function declare_entry(). The first
- * parameter is the name of the entry (in short: the entry). The second
- * is the default answer to be taken in case the entry is not specified
- * in the input file. The third parameter is a regular expression which
- * the input (and the default answer) has to match. Several such regular
- * expressions are defined in Patterns. This parameter can be omitted, in
- * which case it will default to Patterns::Anything, i.e. a pattern that
- * matches every input string. The fourth parameter can be used to
- * document the intent or expected format of an entry; its value is
- * printed as a comment when writing all entries of a ParameterHandler
- * object using the print_parameters() function to allow for easier
- * understanding of a parameter file. It can be omitted as well, in which
- * case no such documentation will be printed.
- *
- * Entries may be located in subsections which form a kind of input tree.
- * For example input parameters for linear solver routines should be
- * classified in a subsection named <tt>Linear solver</tt> or any other
- * suitable name. This is accomplished in the following way:
+ * Each entry is declared using the function declare_entry(). The first
+ * parameter is the name of the entry (in short: the entry). The second is the
+ * default answer to be taken in case the entry is not specified in the input
+ * file. The third parameter is a regular expression which the input (and the
+ * default answer) has to match. Several such regular expressions are defined
+ * in Patterns. This parameter can be omitted, in which case it will default
+ * to Patterns::Anything, i.e. a pattern that matches every input string. The
+ * fourth parameter can be used to document the intent or expected format of
+ * an entry; its value is printed as a comment when writing all entries of a
+ * ParameterHandler object using the print_parameters() function to allow for
+ * easier understanding of a parameter file. It can be omitted as well, in
+ * which case no such documentation will be printed.
+ *
+ * Entries may be located in subsections which form a kind of input tree. For
+ * example input parameters for linear solver routines should be classified in
+ * a subsection named <tt>Linear solver</tt> or any other suitable name. This
+ * is accomplished in the following way:
* @code
* ...
* LinEq eq;
* }
* @endcode
*
- * Subsections may be nested. For example a nonlinear solver may have a
- * linear solver as member object. Then the function call tree would be
- * something like (if the class <tt>NonLinEq</tt> has a member variables
- * <tt>eq</tt> of type <tt>LinEq</tt>):
+ * Subsections may be nested. For example a nonlinear solver may have a linear
+ * solver as member object. Then the function call tree would be something
+ * like (if the class <tt>NonLinEq</tt> has a member variables <tt>eq</tt> of
+ * type <tt>LinEq</tt>):
* @code
* void NonLinEq::declare_parameters (ParameterHandler &prm) {
* prm.enter_subsection ("Nonlinear solver");
* }
* @endcode
*
- * For class member functions which declare the different entries we
- * propose to use the common name <tt>declare_parameters</tt>. In normal
- * cases this method can be <tt>static</tt> since the entries will not
- * depend on any previous knowledge. Classes for which entries should
- * logically be grouped into subsections should declare these subsections
- * themselves. If a class has two or more member variables of the same
- * type both of which should have their own parameters, this parent
- * class' method <tt>declare_parameters</tt> is responsible to group them
- * into different subsections:
+ * For class member functions which declare the different entries we propose
+ * to use the common name <tt>declare_parameters</tt>. In normal cases this
+ * method can be <tt>static</tt> since the entries will not depend on any
+ * previous knowledge. Classes for which entries should logically be grouped
+ * into subsections should declare these subsections themselves. If a class
+ * has two or more member variables of the same type both of which should have
+ * their own parameters, this parent class' method <tt>declare_parameters</tt>
+ * is responsible to group them into different subsections:
* @code
* void NonLinEq::declare_parameters (ParameterHandler &prm) {
* prm.enter_subsection ("Nonlinear solver");
* @endcode
*
*
- * <h3>Input files and special characters</h3>
+ * <h3>Input files and special characters</h3>
*
- * For the first example above the input file would look like the following:
+ * For the first example above the input file would look like the following:
* @code
* ...
* subsection Nonlinear solver
* end
* ... # other stuff
* @endcode
- * The words <tt>subsection</tt>, <tt>set</tt> and <tt>end</tt> may be
- * either written in lowercase or uppercase letters. Leading and trailing
- * whitespace is removed, multiple whitespace is condensed into only one.
- * Since the latter applies also to the name of an entry, an entry name
- * will not be recognized if in the declaration multiple whitespace is
- * used.
+ * The words <tt>subsection</tt>, <tt>set</tt> and <tt>end</tt> may be either
+ * written in lowercase or uppercase letters. Leading and trailing whitespace
+ * is removed, multiple whitespace is condensed into only one. Since the
+ * latter applies also to the name of an entry, an entry name will not be
+ * recognized if in the declaration multiple whitespace is used.
*
- * In entry names and values the following characters are not allowed:
- * <tt>\#</tt>, <tt>{</tt>, <tt>}</tt>, <tt>|</tt>. Their use is reserved
- * for the MultipleParameterLoop class.
+ * In entry names and values the following characters are not allowed:
+ * <tt>\#</tt>, <tt>{</tt>, <tt>}</tt>, <tt>|</tt>. Their use is reserved for
+ * the MultipleParameterLoop class.
*
- * Comments starting with \# are skipped.
+ * Comments starting with \# are skipped.
*
- * We propose to use the following scheme to name entries: start the
- * first word with a capital letter and use lowercase letters further on.
- * The same applies to the possible entry values to the right of the
- * <tt>=</tt> sign.
+ * We propose to use the following scheme to name entries: start the first
+ * word with a capital letter and use lowercase letters further on. The same
+ * applies to the possible entry values to the right of the <tt>=</tt> sign.
*
*
- * <h3>Including other input files</h3>
+ * <h3>Including other input files</h3>
*
- * An input file can include other include files using the syntax
+ * An input file can include other include files using the syntax
* @code
* ...
* include some_other_file.prm
* ...
* @endcode
- * The file so referenced is searched for relative to the current
- * directory (not relative to the directory in which the including
- * parameter file is located, since this is not known to all three
- * versions of the read_input() function).
+ * The file so referenced is searched for relative to the current directory
+ * (not relative to the directory in which the including parameter file is
+ * located, since this is not known to all three versions of the read_input()
+ * function).
*
*
- * <h3>Reading data from input sources</h3>
+ * <h3>Reading data from input sources</h3>
*
- * In order to read input there are three possibilities: reading from
- * an <tt>std::istream</tt> object, reading from a file of which the name
- * is given and reading from a string in memory in which the lines are
- * separated by <tt>@\n</tt> characters. These possibilities are used as
- * follows:
+ * In order to read input there are three possibilities: reading from an
+ * <tt>std::istream</tt> object, reading from a file of which the name is
+ * given and reading from a string in memory in which the lines are separated
+ * by <tt>@\n</tt> characters. These possibilities are used as follows:
* @code
* ParameterHandler prm;
* ...
* prm.read_input_from_string (in);
* ...
* @endcode
- * You can use several sources of input successively. Entries which are
- * changed more than once will be overwritten every time they are used.
- *
- * You should not try to declare entries using declare_entry() and
- * enter_subsection() with as yet unknown subsection names after
- * using read_input(). The results in this case are unspecified.
- *
- * If an error occurs upon reading the input, error messages are written
- * to <tt>std::cerr</tt> and the reader function returns with a return
- * value of <code>false</code>. This is opposed to almost all other
- * functions in deal.II, which would normally throw an exception if an
- * error occurs; this difference in behavior is a relic of the fact that
- * this class predates deal.II and had previously been written for a
- * different project.
- *
- *
- * <h3>Using the %ParameterHandler Graphical User Interface</h3>
- *
- * An alternative to using the hand-written input files shown above is to
- * use the graphical user interface (GUI) that accompanies this class.
- * For this, you first need to write a description of all the parameters,
- * their default values, patterns and documentation strings into a file
- * in a format that the GUI can understand; this is done using the
- * ParameterHandler::print_parameters() function with
- * ParameterHandler::XML as second argument, as discussed in more detail
- * below in the <i>Representation of Parameters</i> section. This file
- * can then be loaded using the executable for the GUI, which should be
- * located in <code>lib/bin/dealii_parameter_gui</code> of your deal.II
- * installation, assuming that you have a sufficiently recent version of
- * the <a href="http://qt.nokia.com/">Qt toolkit</a> installed.
- *
- * Once loaded, the GUI displays subsections and individual parameters in
- * tree form (see also the discussion in the <i>Representation of
- * Parameters</i> section below). Here is a screen shot
- * with some sub-sections expanded and one parameter selected for
- * editing:
- *
- * @image html parameter_gui.png "Parameter GUI"
- *
- * Using the GUI, you can edit the values of individual parameters and
- * save the result in the same format as before. It can then be read in
- * using the ParameterHandler::read_input_from_xml() function.
- *
- *
- * <h3>Getting entry values out of a %ParameterHandler object</h3>
- *
- * Each class gets its data out of a ParameterHandler object by
- * calling the get() member functions like this:
+ * You can use several sources of input successively. Entries which are
+ * changed more than once will be overwritten every time they are used.
+ *
+ * You should not try to declare entries using declare_entry() and
+ * enter_subsection() with as yet unknown subsection names after using
+ * read_input(). The results in this case are unspecified.
+ *
+ * If an error occurs upon reading the input, error messages are written to
+ * <tt>std::cerr</tt> and the reader function returns with a return value of
+ * <code>false</code>. This is opposed to almost all other functions in
+ * deal.II, which would normally throw an exception if an error occurs; this
+ * difference in behavior is a relic of the fact that this class predates
+ * deal.II and had previously been written for a different project.
+ *
+ *
+ * <h3>Using the %ParameterHandler Graphical User Interface</h3>
+ *
+ * An alternative to using the hand-written input files shown above is to use
+ * the graphical user interface (GUI) that accompanies this class. For this,
+ * you first need to write a description of all the parameters, their default
+ * values, patterns and documentation strings into a file in a format that the
+ * GUI can understand; this is done using the
+ * ParameterHandler::print_parameters() function with ParameterHandler::XML as
+ * second argument, as discussed in more detail below in the <i>Representation
+ * of Parameters</i> section. This file can then be loaded using the
+ * executable for the GUI, which should be located in
+ * <code>lib/bin/dealii_parameter_gui</code> of your deal.II installation,
+ * assuming that you have a sufficiently recent version of the <a
+ * href="http://qt.nokia.com/">Qt toolkit</a> installed.
+ *
+ * Once loaded, the GUI displays subsections and individual parameters in tree
+ * form (see also the discussion in the <i>Representation of Parameters</i>
+ * section below). Here is a screen shot with some sub-sections expanded and
+ * one parameter selected for editing:
+ *
+ * @image html parameter_gui.png "Parameter GUI"
+ *
+ * Using the GUI, you can edit the values of individual parameters and save
+ * the result in the same format as before. It can then be read in using the
+ * ParameterHandler::read_input_from_xml() function.
+ *
+ *
+ * <h3>Getting entry values out of a %ParameterHandler object</h3>
+ *
+ * Each class gets its data out of a ParameterHandler object by calling the
+ * get() member functions like this:
* @code
* void NonLinEq::get_parameters (ParameterHandler &prm) {
* prm.enter_subsection ("Nonlinear solver");
* prm.leave_subsection ();
* }
* @endcode
- * get() returns the value of the given entry. If the entry was not
- * specified in the input source(s), the default value is returned. You
- * have to enter and leave subsections exactly as you did when declaring
- * subsection. You may chose the order in which to transverse the
- * subsection tree.
- *
- * It is guaranteed that only entries matching the given regular
- * expression are returned, i.e. an input entry value which does not
- * match the regular expression is not stored.
- *
- * You can use get() to retrieve the parameter in text form,
- * get_integer() to get an integer or get_double() to get a double. You
- * can also use get_bool(). It will cause an internal error if the string
- * could not be converted to an integer, double or a bool. This should,
- * though, not happen if you correctly specified the regular expression
- * for this entry; you should not try to get out an integer or a double
- * from an entry for which no according regular expression was set. The
- * internal error is raised through the Assert() macro family which only
- * works in debug mode.
- *
- * If you want to print out all user selectable features, use the
- * print_parameters() function. It is generally a good idea to print all
- * parameters at the beginning of a log file, since this way input and
- * output are together in one file which makes matching at a later time
- * easier. Additionally, the function also print those entries which have
- * not been modified in the input file und are thus set to default
- * values; since default values may change in the process of program
- * development, you cannot know the values of parameters not specified in
- * the input file.
- *
- *
- * <h3>Style guide for data retrieval</h3>
- *
- * We propose that every class which gets data out of a ParameterHandler
- * object provides a function named <tt>get_parameters</tt>. This should
- * be declared <tt>virtual</tt>. <tt>get_parameters</tt> functions in
- * derived classes should call the <tt>BaseClass::get_parameters</tt>
- * function.
- *
- *
- * <h3>Experience with large parameter lists</h3>
- *
- * Experience has shown that in programs defining larger numbers of
- * parameters (more than, say, fifty) it is advantageous to define an
- * additional class holding these parameters. This class is more like a
- * C-style structure, having a large number of variables, usually public.
- * It then has at least two functions, which declare and parse the
- * parameters. In the main program, the main class has an object of this
- * parameter class and delegates declaration and parsing of parameters to
- * this object.
- *
- * The advantage of this approach is that you can keep out the technical
- * details (declaration and parsing) out of the main class and
- * additionally don't clutter up your main class with dozens or more
- * variables denoting the parameters.
- *
- *
- *
- * <h3>Worked Example</h3>
- *
- * This is the code:
+ * get() returns the value of the given entry. If the entry was not specified
+ * in the input source(s), the default value is returned. You have to enter
+ * and leave subsections exactly as you did when declaring subsection. You may
+ * chose the order in which to transverse the subsection tree.
+ *
+ * It is guaranteed that only entries matching the given regular expression
+ * are returned, i.e. an input entry value which does not match the regular
+ * expression is not stored.
+ *
+ * You can use get() to retrieve the parameter in text form, get_integer() to
+ * get an integer or get_double() to get a double. You can also use
+ * get_bool(). It will cause an internal error if the string could not be
+ * converted to an integer, double or a bool. This should, though, not happen
+ * if you correctly specified the regular expression for this entry; you
+ * should not try to get out an integer or a double from an entry for which no
+ * according regular expression was set. The internal error is raised through
+ * the Assert() macro family which only works in debug mode.
+ *
+ * If you want to print out all user selectable features, use the
+ * print_parameters() function. It is generally a good idea to print all
+ * parameters at the beginning of a log file, since this way input and output
+ * are together in one file which makes matching at a later time easier.
+ * Additionally, the function also print those entries which have not been
+ * modified in the input file und are thus set to default values; since
+ * default values may change in the process of program development, you cannot
+ * know the values of parameters not specified in the input file.
+ *
+ *
+ * <h3>Style guide for data retrieval</h3>
+ *
+ * We propose that every class which gets data out of a ParameterHandler
+ * object provides a function named <tt>get_parameters</tt>. This should be
+ * declared <tt>virtual</tt>. <tt>get_parameters</tt> functions in derived
+ * classes should call the <tt>BaseClass::get_parameters</tt> function.
+ *
+ *
+ * <h3>Experience with large parameter lists</h3>
+ *
+ * Experience has shown that in programs defining larger numbers of parameters
+ * (more than, say, fifty) it is advantageous to define an additional class
+ * holding these parameters. This class is more like a C-style structure,
+ * having a large number of variables, usually public. It then has at least
+ * two functions, which declare and parse the parameters. In the main program,
+ * the main class has an object of this parameter class and delegates
+ * declaration and parsing of parameters to this object.
+ *
+ * The advantage of this approach is that you can keep out the technical
+ * details (declaration and parsing) out of the main class and additionally
+ * don't clutter up your main class with dozens or more variables denoting the
+ * parameters.
+ *
+ *
+ *
+ * <h3>Worked Example</h3>
+ *
+ * This is the code:
* @code
* #include <iostream>
* #include "../include/parameter_handler.h"
* @endcode
*
*
- * This is the input file (named "prmtest.prm"):
+ * This is the input file (named "prmtest.prm"):
* @code
* # first declare the types of equations
* set Equation 1 = Poisson
* end
* @endcode
*
- * And here is the output of the program:
+ * And here is the output of the program:
* @code
* Line 8:
* The entry value
*
*
*
- * <h3>Representation of Parameters</h3>
+ * <h3>Representation of Parameters</h3>
*
- * Here is some more internal information about the repesentation of
- * parameters:
+ * Here is some more internal information about the repesentation of
+ * parameters:
*
- * Logically, parameters and the nested sections they are arranged in can be
- * thought of as a hierarchical directory structure, or a tree. Take, for
- * example, the following code declaring a set of parameters and sections
- * they live in:
+ * Logically, parameters and the nested sections they are arranged in can be
+ * thought of as a hierarchical directory structure, or a tree. Take, for
+ * example, the following code declaring a set of parameters and sections they
+ * live in:
* @code
* ParameterHandler prm;
*
* prm.leave_subsection ();
* @endcode
*
- * We can think of the parameters so arranged as a file system in which
- * every parameter is a directory. The name of this directory is the name
- * of the parameter, and in this directory lie files that describe the
- * parameter. These files are:
- * - <code>value</code>: The content of this file is the current value of this
- * parameter; initially, the content of the file equals the default value of
- * the parameter.
- * - <code>default_value</code>: The content of this file is the default value
- * value of the parameter.
- * - <code>pattern</code>: A textual representation of the pattern that describes
- * the parameter's possible values.
- * - <code>pattern_index</code>: A number that indexes the Patterns::PatternBase
- * object that is used to describe the parameter.
- * - <code>documentation</code>: The content of this file is the documentation
- * given for a parameter as the last argument of the
- * ParameterHandler::declare_entry call.
- * With the exception of the <code>value</code> file, the contents of files
- * are never changed after declaration of a parameter.
- *
- * Alternatively, a directory in this file system may not have a file
- * called <code>value</code> in it. In that case, the directory
- * represents a subsection as declared above, and the directory's name
- * will correspond to the name of the subsection. It will then have no
- * files in it at all, but it may have further directories in it: some of
- * these directories will be parameters (indicates by the presence of
- * files) or further nested subsections.
- *
- * Given this explanation, the code above will lead to a hierarchical
- * representation of data that looks like this (the content of files is
- * indicated at the right in a different font):
- * @image html parameter_handler.png
- * Once parameters have been read in, the contents of the <code>value</code>
- * "files" may be different while the other files remain untouched.
- *
- * Using the ParameterHandler::print_parameters() function with
- * ParameterHandler::XML as second argument, we can get a complete
- * representation of this data structure in XML. It will look like
- * this:
+ * We can think of the parameters so arranged as a file system in which every
+ * parameter is a directory. The name of this directory is the name of the
+ * parameter, and in this directory lie files that describe the parameter.
+ * These files are: - <code>value</code>: The content of this file is the
+ * current value of this parameter; initially, the content of the file equals
+ * the default value of the parameter. - <code>default_value</code>: The
+ * content of this file is the default value value of the parameter. -
+ * <code>pattern</code>: A textual representation of the pattern that
+ * describes the parameter's possible values. - <code>pattern_index</code>: A
+ * number that indexes the Patterns::PatternBase object that is used to
+ * describe the parameter. - <code>documentation</code>: The content of this
+ * file is the documentation given for a parameter as the last argument of the
+ * ParameterHandler::declare_entry call. With the exception of the
+ * <code>value</code> file, the contents of files are never changed after
+ * declaration of a parameter.
+ *
+ * Alternatively, a directory in this file system may not have a file called
+ * <code>value</code> in it. In that case, the directory represents a
+ * subsection as declared above, and the directory's name will correspond to
+ * the name of the subsection. It will then have no files in it at all, but it
+ * may have further directories in it: some of these directories will be
+ * parameters (indicates by the presence of files) or further nested
+ * subsections.
+ *
+ * Given this explanation, the code above will lead to a hierarchical
+ * representation of data that looks like this (the content of files is
+ * indicated at the right in a different font): @image html
+ * parameter_handler.png Once parameters have been read in, the contents of
+ * the <code>value</code> "files" may be different while the other files
+ * remain untouched.
+ *
+ * Using the ParameterHandler::print_parameters() function with
+ * ParameterHandler::XML as second argument, we can get a complete
+ * representation of this data structure in XML. It will look like this:
* @code
* <?xml version="1.0" encoding="utf-8"?>
* <ParameterHandler>
* </Preconditioner>
* <ParameterHandler>
* @endcode
- * This representation closely resembles the directory/file structure
- * discussed above. The only difference is that directory and file
- * names are mangled: since they should only contain letters and
- * numbers, every character in their names that is not a letter or number
- * is replaced
- * by an underscore followed by its two-digit hexadecimal representation.
- * In addition, the special name "value" is mangled when used as the
- * name of a parameter, given that this name is also used to name
- * special files in the hierarchy structure.
- * Finally, the entire tree is wrapped into a tag
- * <code>%ParameterHandler</code> to satisfy the XML requirement that there
- * be only a single top-level construct in each file.
- *
- * The tree structure (and its XML representation) is what the graphical
- * user interface (see above) uses to represent parameters like a
- * directory/file collection.
- *
- *
- * @ingroup input
- * @author Wolfgang Bangerth, October 1997, revised February 1998, 2010, 2011
+ * This representation closely resembles the directory/file structure
+ * discussed above. The only difference is that directory and file names are
+ * mangled: since they should only contain letters and numbers, every
+ * character in their names that is not a letter or number is replaced by an
+ * underscore followed by its two-digit hexadecimal representation. In
+ * addition, the special name "value" is mangled when used as the name of a
+ * parameter, given that this name is also used to name special files in the
+ * hierarchy structure. Finally, the entire tree is wrapped into a tag
+ * <code>%ParameterHandler</code> to satisfy the XML requirement that there be
+ * only a single top-level construct in each file.
+ *
+ * The tree structure (and its XML representation) is what the graphical user
+ * interface (see above) uses to represent parameters like a directory/file
+ * collection.
+ *
+ *
+ * @ingroup input
+ * @author Wolfgang Bangerth, October 1997, revised February 1998, 2010, 2011
*/
class ParameterHandler : public Subscriptor
{
/**
* List of possible output formats.
*
- * The formats down the list with prefix <em>Short</em> and bit 6 and 7
- * set reproduce the old behavior of not writing comments or original
- * values to the files.
+ * The formats down the list with prefix <em>Short</em> and bit 6 and 7 set
+ * reproduce the old behavior of not writing comments or original values to
+ * the files.
*/
enum OutputStyle
{
* Write out everything as an <a
* href="http://en.wikipedia.org/wiki/XML">XML</a> file.
*
- * See the general documentation of this class for an example of
- * output.
+ * See the general documentation of this class for an example of output.
*/
XML = 4,
virtual ~ParameterHandler ();
/**
- * Read input from a stream until the stream returns the <tt>eof</tt> condition
- * or error. The second argument can be used to denote the name of the file
- * (if that's what the input stream represents) we are reading from; this
- * is only used when creating output for error messages.
+ * Read input from a stream until the stream returns the <tt>eof</tt>
+ * condition or error. The second argument can be used to denote the name of
+ * the file (if that's what the input stream represents) we are reading
+ * from; this is only used when creating output for error messages.
*
* Return whether the read was successful.
*/
const std::string &filename = "input file");
/**
- * Read input from a file the name of which is given. The PathSearch
- * class "PARAMETERS" is used to find the file.
+ * Read input from a file the name of which is given. The PathSearch class
+ * "PARAMETERS" is used to find the file.
*
* Return whether the read was successful.
*
* Unless <tt>optional</tt> is <tt>true</tt>, this function will
- * automatically generate the requested file with default values if the
- * file did not exist. This file will not contain additional comments if
+ * automatically generate the requested file with default values if the file
+ * did not exist. This file will not contain additional comments if
* <tt>write_stripped_file</tt> is <tt>true</tt>.
*/
virtual bool read_input (const std::string &filename,
virtual bool read_input_from_string (const char *s);
/**
- * Read a parameter file in XML format. This could be from a file
- * originally written by the print_parameters() function using the XML
- * output style and then modified by hand as necessary; or from a file
- * written using this method and then modified by the graphical parameter
- * GUI (see the general documentation of this class).
+ * Read a parameter file in XML format. This could be from a file originally
+ * written by the print_parameters() function using the XML output style and
+ * then modified by hand as necessary; or from a file written using this
+ * method and then modified by the graphical parameter GUI (see the general
+ * documentation of this class).
*
* Return whether the read was successful.
*/
/**
- * Declare a new entry with name <tt>entry</tt>, default and for which
- * any input has to match the <tt>pattern</tt> (default: any pattern).
+ * Declare a new entry with name <tt>entry</tt>, default and for which any
+ * input has to match the <tt>pattern</tt> (default: any pattern).
*
* The last parameter defaulting to an empty string is used to add a
* documenting text to each entry which will be printed as a comment when
- * this class is asked to write out all declarations to a stream using
- * the print_parameters() function.
+ * this class is asked to write out all declarations to a stream using the
+ * print_parameters() function.
*
* The function generates an exception of type ExcValueDoesNotMatchPattern
- * if the default value doesn't match the given pattern, using the C++
- * throw mechanism. However, this exception is only generated <i>after</i>
- * the entry has been created; if you have code where no sensible default
- * value for a parameter is possible, you can then catch and ignore this
+ * if the default value doesn't match the given pattern, using the C++ throw
+ * mechanism. However, this exception is only generated <i>after</i> the
+ * entry has been created; if you have code where no sensible default value
+ * for a parameter is possible, you can then catch and ignore this
* exception.
*
- * @note An entry can be declared more than once without
- * generating an error, for example to override an earlier default value.
+ * @note An entry can be declared more than once without generating an
+ * error, for example to override an earlier default value.
*/
void declare_entry (const std::string &entry,
const std::string &default_value,
void enter_subsection (const std::string &subsection);
/**
- * Leave present subsection. Return <tt>false</tt> if there is no
- * subsection to leave; <tt>true</tt> otherwise.
+ * Leave present subsection. Return <tt>false</tt> if there is no subsection
+ * to leave; <tt>true</tt> otherwise.
*/
bool leave_subsection ();
/**
- * Return value of entry <tt>entry_string</tt>. If the entry was
- * changed, then the changed value is returned, otherwise the default
- * value. If the value of an undeclared entry is required, an exception
- * will be thrown.
+ * Return value of entry <tt>entry_string</tt>. If the entry was changed,
+ * then the changed value is returned, otherwise the default value. If the
+ * value of an undeclared entry is required, an exception will be thrown.
*/
std::string get (const std::string &entry_string) const;
/**
- * Return value of entry <tt>entry_string</tt> as <tt>long int</tt>. (A
- * long int is chosen so that even very large unsigned values can be
- * returned by this function).
+ * Return value of entry <tt>entry_string</tt> as <tt>long int</tt>. (A long
+ * int is chosen so that even very large unsigned values can be returned by
+ * this function).
*/
long int get_integer (const std::string &entry_string) const;
double get_double (const std::string &entry_name) const;
/**
- * Return value of entry <tt>entry_name</tt> as <tt>bool</tt>. The entry
- * may be "true" or "yes" for <tt>true</tt>, "false" or "no" for
- * <tt>false</tt> respectively.
+ * Return value of entry <tt>entry_name</tt> as <tt>bool</tt>. The entry may
+ * be "true" or "yes" for <tt>true</tt>, "false" or "no" for <tt>false</tt>
+ * respectively.
*/
bool get_bool (const std::string &entry_name) const;
*
* The parameter must already exist in the present subsection.
*
- * The function throws an exception of type ExcValueDoesNotMatchPattern
- * if the new value does not conform to the pattern for this entry.
+ * The function throws an exception of type ExcValueDoesNotMatchPattern if
+ * the new value does not conform to the pattern for this entry.
*/
void set (const std::string &entry_name,
const std::string &new_value);
/**
- * Same as above, but an overload where the second argument is a
- * character pointer. This is necessary, since otherwise the call to
+ * Same as above, but an overload where the second argument is a character
+ * pointer. This is necessary, since otherwise the call to
* <tt>set("abc","def")</code> will be mapped to the function taking one
- * string and a bool as arguments, which is certainly not what is most
- * often intended.
+ * string and a bool as arguments, which is certainly not what is most often
+ * intended.
*
- * The function throws an exception of type ExcValueDoesNotMatchPattern
- * if the new value does not conform to the pattern for this entry.
+ * The function throws an exception of type ExcValueDoesNotMatchPattern if
+ * the new value does not conform to the pattern for this entry.
*/
void set (const std::string &entry_name,
const char *new_value);
*
* The parameter must already exist in the present subsection.
*
- * The function throws an exception of type ExcValueDoesNotMatchPattern
- * if the new value does not conform to the pattern for this entry.
+ * The function throws an exception of type ExcValueDoesNotMatchPattern if
+ * the new value does not conform to the pattern for this entry.
*/
void set (const std::string &entry_name,
const long int &new_value);
*
* The parameter must already exist in the present subsection.
*
- * For internal purposes, the new value needs to be converted to a
- * string. This is done using 16 digits of accuracy, so the set value and
- * the one you can get back out using get_double() may differ in the 16th
- * digit.
+ * For internal purposes, the new value needs to be converted to a string.
+ * This is done using 16 digits of accuracy, so the set value and the one
+ * you can get back out using get_double() may differ in the 16th digit.
*
- * The function throws an exception of type ExcValueDoesNotMatchPattern
- * if the new value does not conform to the pattern for this entry.
+ * The function throws an exception of type ExcValueDoesNotMatchPattern if
+ * the new value does not conform to the pattern for this entry.
*/
void set (const std::string &entry_name,
const double &new_value);
*
* The parameter must already exist in the present subsection.
*
- * The function throws an exception of type ExcValueDoesNotMatchPattern
- * if the new value does not conform to the pattern for this entry.
+ * The function throws an exception of type ExcValueDoesNotMatchPattern if
+ * the new value does not conform to the pattern for this entry.
*/
void set (const std::string &entry_name,
const bool &new_value);
/**
- * Print all parameters with the given style to <tt>out</tt>. Presently
- * only <tt>Text</tt>, <tt>LaTeX</tt> and <tt>XML</tt> are implemented.
+ * Print all parameters with the given style to <tt>out</tt>. Presently only
+ * <tt>Text</tt>, <tt>LaTeX</tt> and <tt>XML</tt> are implemented.
*
- * In <tt>Text</tt> format, the output is formatted in such a way that it
- * is possible to use it for later input again. This is most useful to
- * record the parameters for a specific run, since if you output the
- * parameters using this function into a log file, you can always recover
- * the results by simply copying the output to your input file.
+ * In <tt>Text</tt> format, the output is formatted in such a way that it is
+ * possible to use it for later input again. This is most useful to record
+ * the parameters for a specific run, since if you output the parameters
+ * using this function into a log file, you can always recover the results
+ * by simply copying the output to your input file.
*
* Besides the name and value of each entry, the output also contains the
* default value of entries if it is different from the actual value, as
- * well as the documenting string given to the declare_entry() function
- * if available.
+ * well as the documenting string given to the declare_entry() function if
+ * available.
*
* In <tt>XML</tt> format, the output starts with one root element
- * <tt>ParameterHandler</tt> in order to get a valid XML document
- * and all subsections under it.
+ * <tt>ParameterHandler</tt> in order to get a valid XML document and all
+ * subsections under it.
*
- * In <tt>Text</tt> format, the output contains the same information but
- * in a format so that the resulting file can be input into a latex
- * document such as a manual for the code for which this object handles
- * run-time parameters. The various sections of parameters are then
- * represented by latex section and subsection commands as well as by
- * nested enumerations.
+ * In <tt>Text</tt> format, the output contains the same information but in
+ * a format so that the resulting file can be input into a latex document
+ * such as a manual for the code for which this object handles run-time
+ * parameters. The various sections of parameters are then represented by
+ * latex section and subsection commands as well as by nested enumerations.
*
* In addition, all parameter names are listed with <code>@\index</code>
- * statements in two indices called <code>prmindex</code> (where the name
- * of each parameter is listed in the index) and
- * <code>prmindexfull</code> where parameter names are listed sorted by
- * the section in which they exist. By default, the LaTeX program ignores
- * these <code>@\index</code> commands, but they can be used to generate
- * an index by using the following commands in the preamble of the latex
- * file:
+ * statements in two indices called <code>prmindex</code> (where the name of
+ * each parameter is listed in the index) and <code>prmindexfull</code>
+ * where parameter names are listed sorted by the section in which they
+ * exist. By default, the LaTeX program ignores these <code>@\index</code>
+ * commands, but they can be used to generate an index by using the
+ * following commands in the preamble of the latex file:
* @code
* \usepackage{imakeidx}
* \makeindex[name=prmindex, title=Index of run-time parameter entries]
/**
* Print out the parameters of the present subsection as given by the
- * <tt>subsection_path</tt> member variable. This variable is controlled
- * by entering and leaving subsections through the enter_subsection() and
+ * <tt>subsection_path</tt> member variable. This variable is controlled by
+ * entering and leaving subsections through the enter_subsection() and
* leave_subsection() functions.
*
- * If <tt>include_top_level_elements</tt> is <tt>true</tt>, also
- * the higher subsection elements are printed. In <tt>XML</tt> format
- * this is required to get a valid XML document and output starts
- * with one root element <tt>ParameterHandler</tt>.
+ * If <tt>include_top_level_elements</tt> is <tt>true</tt>, also the higher
+ * subsection elements are printed. In <tt>XML</tt> format this is required
+ * to get a valid XML document and output starts with one root element
+ * <tt>ParameterHandler</tt>.
*
- * In most cases, you will not want to use this function directly, but
- * have it called recursively by the previous function.
+ * In most cases, you will not want to use this function directly, but have
+ * it called recursively by the previous function.
*/
void print_parameters_section (std::ostream &out,
const OutputStyle style,
/**
* Print parameters to a logstream. This function allows to print all
- * parameters into a log-file. Sections will be indented in the usual
- * log-file style.
+ * parameters into a log-file. Sections will be indented in the usual log-
+ * file style.
*/
void log_parameters (LogStream &out);
/**
- * Log parameters in the present subsection. The subsection is determined
- * by the <tt>subsection_path</tt> member variable. This variable is
- * controlled by entering and leaving subsections through the
- * enter_subsection() and leave_subsection() functions.
+ * Log parameters in the present subsection. The subsection is determined by
+ * the <tt>subsection_path</tt> member variable. This variable is controlled
+ * by entering and leaving subsections through the enter_subsection() and
+ * leave_subsection() functions.
*
- * In most cases, you will not want to use this function directly, but
- * have it called recursively by the previous function.
+ * In most cases, you will not want to use this function directly, but have
+ * it called recursively by the previous function.
*/
void log_parameters_section (LogStream &out);
*/
bool operator == (const ParameterHandler &prm2) const;
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
//@}
private:
/**
- * The separator used when accessing elements of a path into the
- * parameter tree.
+ * The separator used when accessing elements of a path into the parameter
+ * tree.
*/
static const char path_separator = '.';
/**
- * The complete tree of sections and entries. See the general
- * documentation of this class for a description how data is stored in
- * this variable.
+ * The complete tree of sections and entries. See the general documentation
+ * of this class for a description how data is stored in this variable.
*
- * The variable is a pointer so that we can use an incomplete type,
- * rather than having to include all of the property_tree stuff from
- * boost. This works around a problem with gcc 4.5.
+ * The variable is a pointer so that we can use an incomplete type, rather
+ * than having to include all of the property_tree stuff from boost. This
+ * works around a problem with gcc 4.5.
*/
std::auto_ptr<boost::property_tree::ptree> entries;
std::string get_current_path () const;
/**
- * Given the name of an entry as argument, the function computes a full
- * path into the parameter tree using the current subsection.
+ * Given the name of an entry as argument, the function computes a full path
+ * into the parameter tree using the current subsection.
*/
std::string get_current_full_path (const std::string &name) const;
/**
- * Scan one line of input. <tt>input_filename</tt> and <tt>lineno</tt>
- * are the name of the input file and the current number of the line
- * presently scanned (for the logs if there are messages). Return
- * <tt>false</tt> if line contained stuff that could not be understood,
- * the uppermost subsection was to be left by an <tt>END</tt> or
- * <tt>end</tt> statement, a value for a non-declared entry was given or
- * the entry value did not match the regular expression. <tt>true</tt>
- * otherwise.
+ * Scan one line of input. <tt>input_filename</tt> and <tt>lineno</tt> are
+ * the name of the input file and the current number of the line presently
+ * scanned (for the logs if there are messages). Return <tt>false</tt> if
+ * line contained stuff that could not be understood, the uppermost
+ * subsection was to be left by an <tt>END</tt> or <tt>end</tt> statement, a
+ * value for a non-declared entry was given or the entry value did not match
+ * the regular expression. <tt>true</tt> otherwise.
*
* The function modifies its argument, but also takes it by value, so the
* caller's variable is not changed.
/**
- * The class MultipleParameterLoop offers an easy possibility to test
- * several parameter sets during one run of the program. For this it uses
- * the ParameterHandler class to read in data in a standardized form,
- * searches for variant entry values and performs a loop over all
- * combinations of parameters.
+ * The class MultipleParameterLoop offers an easy possibility to test several
+ * parameter sets during one run of the program. For this it uses the
+ * ParameterHandler class to read in data in a standardized form, searches for
+ * variant entry values and performs a loop over all combinations of
+ * parameters.
*
- * Variant entry values are given like this:
+ * Variant entry values are given like this:
* @verbatim
* set Time step size = { 0.1 | 0.2 | 0.3 }
* @endverbatim
- * The loop will then perform three runs of the program, one for each
- * value of <tt>Time step size</tt>, while all other parameters are as
- * specified or with their default value. If there are several variant
- * entry values in the input, a loop is performed for each combination of
- * variant values:
+ * The loop will then perform three runs of the program, one for each value of
+ * <tt>Time step size</tt>, while all other parameters are as specified or
+ * with their default value. If there are several variant entry values in the
+ * input, a loop is performed for each combination of variant values:
* @verbatim
* set Time step size = { 0.1 | 0.2 }
* set Solver = { CG | GMRES }
* @endverbatim
- * will result in four runs of the programs, with time step 0.1 and 0.2
- * for each of the two solvers.
+ * will result in four runs of the programs, with time step 0.1 and 0.2 for
+ * each of the two solvers.
*
- * In addition to variant entries, this class also supports <i>array
- * entries</i> that look like this:
+ * In addition to variant entries, this class also supports <i>array
+ * entries</i> that look like this:
* @verbatim
* set Output file = ofile.{{ 1 | 2 | 3 | 4 }}
* @endverbatim
- * This indicates that if there are variant entries producing a total of
- * four different runs, then we will write their results to the files
- * <tt>ofile.1</tt>, <tt>ofile.2</tt>, <tt>ofile.3</tt> and
- * <tt>ofile.4</tt>, respectively. Array entries do not generate multiple
- * runs of the main loop themselves, but if there are variant entries,
- * then in the <i>n</i>th run of the main loop, also the <i>n</i>th value
- * of an array is returned.
- *
- * Since the different variants are constructed in the order of
- * declaration, not in the order in which the variant entries appear in
- * the input file, it may be difficult to guess the mapping between the
- * different variants and the appropriate entry in an array. You will
- * have to check the order of declaration, or use only one variant entry.
- *
- * It is guaranteed that only selections which match the regular
- * expression (pattern) given upon declaration of an entry are given back
- * to the program. If a variant value does not match the regular
- * expression, the default value is stored and an error is issued. Before
- * the first run of the loop, all possible values are checked for their
- * conformance, so that the error is issued at the very beginning of the
- * program.
- *
- *
- * <h3>Usage</h3>
- *
- * The usage of this class is similar to the ParameterHandler class.
- * First the entries and subsections have to be declared, then a loop is
- * performed in which the different parameter sets are set, a new
- * instance of a user class is created which is then called. Taking the
- * classes of the example for the ParameterHandler class, the extended
- * program would look like this:
+ * This indicates that if there are variant entries producing a total of four
+ * different runs, then we will write their results to the files
+ * <tt>ofile.1</tt>, <tt>ofile.2</tt>, <tt>ofile.3</tt> and <tt>ofile.4</tt>,
+ * respectively. Array entries do not generate multiple runs of the main loop
+ * themselves, but if there are variant entries, then in the <i>n</i>th run of
+ * the main loop, also the <i>n</i>th value of an array is returned.
+ *
+ * Since the different variants are constructed in the order of declaration,
+ * not in the order in which the variant entries appear in the input file, it
+ * may be difficult to guess the mapping between the different variants and
+ * the appropriate entry in an array. You will have to check the order of
+ * declaration, or use only one variant entry.
+ *
+ * It is guaranteed that only selections which match the regular expression
+ * (pattern) given upon declaration of an entry are given back to the program.
+ * If a variant value does not match the regular expression, the default value
+ * is stored and an error is issued. Before the first run of the loop, all
+ * possible values are checked for their conformance, so that the error is
+ * issued at the very beginning of the program.
+ *
+ *
+ * <h3>Usage</h3>
+ *
+ * The usage of this class is similar to the ParameterHandler class. First the
+ * entries and subsections have to be declared, then a loop is performed in
+ * which the different parameter sets are set, a new instance of a user class
+ * is created which is then called. Taking the classes of the example for the
+ * ParameterHandler class, the extended program would look like this:
* @code
* class HelperClass : public MultipleParameterLoop::UserClass {
* public:
* }
* @endcode
*
- * As can be seen, first a new helper class has to be set up. This must
- * contain a virtual constructor for a problem class. You can also derive
- * your problem class from MultipleParameterLoop::UserClass and let
- * <tt>create_new</tt> clear all member variables. If you have access to
- * all inherited member variables in some way this is the recommended
- * procedure. A third possibility is to use multiple inheritance and
- * derive a helper class from both the MultipleParameterLoop::UserClass
- * and the problem class. In any case, <tt>create_new</tt> has to provide
- * a clean problem object which is the problem in the second and third
- * possibility.
- *
- * The derived class also has to provide for member functions which
- * declare the entries and which run the program. Running the program
- * includes getting the parameters out of the ParameterHandler object.
- *
- * After defining an object of this helper class and an object of the
- * MultipleParameterLoop class, the entries have to be declared in the
- * same way as for the ParameterHandler class. Then the input has to be
- * read. Finally the loop is called. This executes the following steps:
+ * As can be seen, first a new helper class has to be set up. This must
+ * contain a virtual constructor for a problem class. You can also derive your
+ * problem class from MultipleParameterLoop::UserClass and let
+ * <tt>create_new</tt> clear all member variables. If you have access to all
+ * inherited member variables in some way this is the recommended procedure. A
+ * third possibility is to use multiple inheritance and derive a helper class
+ * from both the MultipleParameterLoop::UserClass and the problem class. In
+ * any case, <tt>create_new</tt> has to provide a clean problem object which
+ * is the problem in the second and third possibility.
+ *
+ * The derived class also has to provide for member functions which declare
+ * the entries and which run the program. Running the program includes getting
+ * the parameters out of the ParameterHandler object.
+ *
+ * After defining an object of this helper class and an object of the
+ * MultipleParameterLoop class, the entries have to be declared in the same
+ * way as for the ParameterHandler class. Then the input has to be read.
+ * Finally the loop is called. This executes the following steps:
* @code
* for (each combination)
* {
* UserObject.run (*this);
* }
* @endcode
- * <tt>UserObject</tt> is the parameter to the <tt>loop</tt> function.
- * <tt>create_new</tt> is given the number of the run (starting from one)
- * to enable naming output files differently for each run.
+ * <tt>UserObject</tt> is the parameter to the <tt>loop</tt> function.
+ * <tt>create_new</tt> is given the number of the run (starting from one) to
+ * enable naming output files differently for each run.
*
*
- * <h3>Syntax for variant and array entry values</h3>
+ * <h3>Syntax for variant and array entry values</h3>
*
- * Variant values are specified like <tt>prefix{ v1 | v2 | v3 | ... }postfix</tt>. Whitespace
- * to the right of the opening brace <tt>{</tt> is ignored as well as to the left of the
- * closing brace <tt>}</tt> while whitespace on the respectively other side is not ignored.
- * Whitespace around the mid symbols <tt>|</tt> is also ignored. The empty selection
- * <tt>prefix{ v1 | }postfix</tt> is also allowed and produces the strings <tt>prefixv1postfix</tt> and
- * <tt>prefixpostfix</tt>.
+ * Variant values are specified like <tt>prefix{ v1 | v2 | v3 | ...
+ * }postfix</tt>. Whitespace to the right of the opening brace <tt>{</tt> is
+ * ignored as well as to the left of the closing brace <tt>}</tt> while
+ * whitespace on the respectively other side is not ignored. Whitespace around
+ * the mid symbols <tt>|</tt> is also ignored. The empty selection <tt>prefix{
+ * v1 | }postfix</tt> is also allowed and produces the strings
+ * <tt>prefixv1postfix</tt> and <tt>prefixpostfix</tt>.
*
- * The syntax for array values is equal, apart from the double braces:
- * <tt>prefix{{ v1 | v2 | v3 }}postfix</tt>.
+ * The syntax for array values is equal, apart from the double braces:
+ * <tt>prefix{{ v1 | v2 | v3 }}postfix</tt>.
*
*
- * <h3>Worked example</h3>
+ * <h3>Worked example</h3>
*
- * Given the above extensions to the example program for the
- * ParameterHandler and the following input file
+ * Given the above extensions to the example program for the ParameterHandler
+ * and the following input file
* @verbatim
* set Equation 1 = Poisson
* set Equation 2 = Navier-Stokes
* end
* end
* @endverbatim
- * this is the output:
+ * this is the output:
* @verbatim
* LinEq: Method=CG, MaxIterations=10
* LinEq: Method=BiCGStab, MaxIterations=100
* eq1=Poisson, eq2=Navier-Stokes
* Matrix1=Sparse, Matrix2=Full
* @endverbatim
- * Since <tt>create_new</tt> gets the number of the run it would also be
- * possible to output the number of the run.
+ * Since <tt>create_new</tt> gets the number of the run it would also be
+ * possible to output the number of the run.
*
*
- * @ingroup input
- * @author Wolfgang Bangerth, October 1997, 2010
+ * @ingroup input
+ * @author Wolfgang Bangerth, October 1997, 2010
*/
class MultipleParameterLoop : public ParameterHandler
{
public:
/**
- * This is the class the helper class or the problem class has to be
- * derived of.
+ * This is the class the helper class or the problem class has to be derived
+ * of.
*/
class UserClass
{
public:
/**
- * Destructor. It doesn't actually do anything, but is declared to
- * force derived classes to have a virtual destructor.
+ * Destructor. It doesn't actually do anything, but is declared to force
+ * derived classes to have a virtual destructor.
*/
virtual ~UserClass ();
/**
- * <tt>create_new</tt> must provide a clean object, either by creating
- * a new one or by cleaning an old one.
+ * <tt>create_new</tt> must provide a clean object, either by creating a
+ * new one or by cleaning an old one.
*/
virtual void create_new (const unsigned int run_no) = 0;
/**
- * This should declare parameters and call the
- * <tt>declare_parameters</tt> function of the problem class.
+ * This should declare parameters and call the <tt>declare_parameters</tt>
+ * function of the problem class.
*/
virtual void declare_parameters (ParameterHandler &prm) = 0;
/**
* Destructor. Declare this only to have a virtual destructor, which is
- * safer as we have virtual functions. It actually does nothing
- * spectacular.
+ * safer as we have virtual functions. It actually does nothing spectacular.
*/
virtual ~MultipleParameterLoop ();
/**
- * Read input from a stream until the stream returns the <tt>eof</tt> condition
- * or error. The second argument can be used to denote the name of the file
- * (if that's what the input stream represents) we are reading from; this
- * is only used when creating output for error messages.
+ * Read input from a stream until the stream returns the <tt>eof</tt>
+ * condition or error. The second argument can be used to denote the name of
+ * the file (if that's what the input stream represents) we are reading
+ * from; this is only used when creating output for error messages.
*
* Return whether the read was successful.
*/
const std::string &filename = "input file");
/**
- * Read input from a file the name of which is given. The PathSearch
- * class "PARAMETERS" is used to find the file.
+ * Read input from a file the name of which is given. The PathSearch class
+ * "PARAMETERS" is used to find the file.
*
* Return whether the read was successful.
*
* Unless <tt>optional</tt> is <tt>true</tt>, this function will
- * automatically generate the requested file with default values if the
- * file did not exist. This file will not contain additional comments if
+ * automatically generate the requested file with default values if the file
+ * did not exist. This file will not contain additional comments if
* <tt>write_stripped_file</tt> is <tt>true</tt>.
*/
virtual bool read_input (const std::string &FileName,
namespace Functions
{
/**
- * Friendly interface to the FunctionParser class. This class is
- * meant as a wrapper for the FunctionParser class. It is used in the
- * step-34 tutorial program.
+ * Friendly interface to the FunctionParser class. This class is meant as a
+ * wrapper for the FunctionParser class. It is used in the step-34 tutorial
+ * program.
*
- * It provides two
- * methods to declare and parse a ParameterHandler object and creates
- * the Function object declared in the parameter file. This class is
- * derived from the AutoDerivativeFunction class, so you don't need
- * to specify derivatives. An example of usage of this class is as follows:
+ * It provides two methods to declare and parse a ParameterHandler object
+ * and creates the Function object declared in the parameter file. This
+ * class is derived from the AutoDerivativeFunction class, so you don't need
+ * to specify derivatives. An example of usage of this class is as follows:
*
* @code
* // A parameter handler
*
* @endcode
*
- * And here is an example of how the input parameter could look like
- * (see the documentation of the FunctionParser class for a detailed
- * description of the syntax of the function definition):
+ * And here is an example of how the input parameter could look like (see
+ * the documentation of the FunctionParser class for a detailed description
+ * of the syntax of the function definition):
*
* @code
*
*
* @endcode
*
- * @ingroup functions
- * @author Luca Heltai, 2006
+ * @ingroup functions
+ * @author Luca Heltai, 2006
*/
template <int dim>
class ParsedFunction : public AutoDerivativeFunction<dim>
{
public:
/**
- * Construct a vector
- * function. The vector
- * function which is generated
- * has @p n_components
- * components (defaults to
- * 1). The parameter @p h is
- * used to initialize the
- * AutoDerivativeFunction class
- * from which this class is
+ * Construct a vector function. The vector function which is generated has
+ * @p n_components components (defaults to 1). The parameter @p h is used
+ * to initialize the AutoDerivativeFunction class from which this class is
* derived.
*/
ParsedFunction (const unsigned int n_components = 1, const double h=1e-8);
/**
- * Declare parameters needed by
- * this class. The additional
- * parameter @p n_components is
- * used to generate the right
- * code according to the number
- * of components of the
- * function that will parse
- * this ParameterHandler. If
- * the number of components
- * which is parsed does not
- * match the number of
- * components of this object,
- * an assertion is thrown and
- * the program is aborted. The
- * default behavior for this
- * class is to declare the
+ * Declare parameters needed by this class. The additional parameter @p
+ * n_components is used to generate the right code according to the number
+ * of components of the function that will parse this ParameterHandler. If
+ * the number of components which is parsed does not match the number of
+ * components of this object, an assertion is thrown and the program is
+ * aborted. The default behavior for this class is to declare the
* following entries:
*
* @code
const unsigned int n_components = 1);
/**
- * Parse parameters needed by
- * this class. If the number
- * of components which is
- * parsed does not match the
- * number of components of this
- * object, an assertion is
- * thrown and the program is
- * aborted. In order for the
- * class to function properly,
- * we follow the same
- * convenctions declared in the
- * FunctionParser class (look
- * there for a detailed
- * description of the syntax
- * for function declarations).
+ * Parse parameters needed by this class. If the number of components
+ * which is parsed does not match the number of components of this object,
+ * an assertion is thrown and the program is aborted. In order for the
+ * class to function properly, we follow the same convenctions declared in
+ * the FunctionParser class (look there for a detailed description of the
+ * syntax for function declarations).
*
- * The three variables that can
- * be parsed from a parameter
- * file are the following:
+ * The three variables that can be parsed from a parameter file are the
+ * following:
*
* @code
*
*
* @endcode
*
- * Function constants is a
- * collection of pairs in the
- * form name=value, separated
- * by commas, for example:
+ * Function constants is a collection of pairs in the form name=value,
+ * separated by commas, for example:
*
* @code
*
*
* @endcode
*
- * These constants can be used
- * in the declaration of the
- * function expression, which
- * follows the convention of
- * the FunctionParser
- * class. In order to specify
- * vector functions,
- * semicolons have to be used
- * to separate the different
- * components, e.g.:
+ * These constants can be used in the declaration of the function
+ * expression, which follows the convention of the FunctionParser class.
+ * In order to specify vector functions, semicolons have to be used to
+ * separate the different components, e.g.:
*
* @code
*
*
* @endcode
*
- * The variable names entry
- * can be used to customize
- * the name of the variables
- * used in the Function. It
- * defaults to
+ * The variable names entry can be used to customize the name of the
+ * variables used in the Function. It defaults to
*
* @code
*
*
* @endcode
*
- * for one dimensional problems,
+ * for one dimensional problems,
*
* @code
*
*
* @endcode
*
- * for two dimensional problems and
+ * for two dimensional problems and
*
* @code
*
*
* @endcode
*
- * for three dimensional problems.
+ * for three dimensional problems.
*
- * The time variable can be
- * set according to
- * specifications in the
- * FunctionTime base class.
+ * The time variable can be set according to specifications in the
+ * FunctionTime base class.
*/
void parse_parameters(ParameterHandler &prm);
/**
- * Return all components of a
- * vector-valued function at the
- * given point @p p.
+ * Return all components of a vector-valued function at the given point @p
+ * p.
*/
virtual void vector_value (const Point<dim> &p,
Vector<double> &values) const;
/**
- * Return the value of the
- * function at the given
- * point. Unless there is only
- * one component (i.e. the
- * function is scalar), you
- * should state the component
- * you want to have evaluated;
- * it defaults to zero,
- * i.e. the first component.
+ * Return the value of the function at the given point. Unless there is
+ * only one component (i.e. the function is scalar), you should state the
+ * component you want to have evaluated; it defaults to zero, i.e. the
+ * first component.
*/
virtual double value (const Point< dim > &p,
const unsigned int component = 0) const;
/**
- * Set the time to a specific
- * value for time-dependent
- * functions.
+ * Set the time to a specific value for time-dependent functions.
*
- * We need to overwrite this to
- * set the time also in the
- * accessor
+ * We need to overwrite this to set the time also in the accessor
* FunctionParser<dim>.
*/
virtual void set_time(const double newtime);
private:
/**
- * The object with which we do
- * computations.
+ * The object with which we do computations.
*/
FunctionParser<dim> function_object;
};
namespace MPI
{
/**
- * This class defines a model for the partitioning of a vector (or,
- * in fact, any linear data structure) among processors using
- * MPI.
+ * This class defines a model for the partitioning of a vector (or, in
+ * fact, any linear data structure) among processors using MPI.
*
- * The partitioner stores the global vector size and the locally
- * owned range as a half-open interval [@p lower, @p
- * upper). Furthermore, it includes a structure for the
- * point-to-point communication patterns. It allows the inclusion of
- * ghost indices (i.e. indices that a current processor needs to
- * have access to, but are owned by another process) through an
- * IndexSet. In addition, it also stores the other processors' ghost
- * indices belonging to the current processor, which are the indices
- * where other processors might require information from. In a
- * sense, these import indices form the dual of the ghost
- * indices. This information is gathered once when constructing the
- * partitioner, which obviates subsequent global communication steps
- * when exchanging data.
+ * The partitioner stores the global vector size and the locally owned
+ * range as a half-open interval [@p lower, @p upper). Furthermore, it
+ * includes a structure for the point-to-point communication patterns. It
+ * allows the inclusion of ghost indices (i.e. indices that a current
+ * processor needs to have access to, but are owned by another process)
+ * through an IndexSet. In addition, it also stores the other processors'
+ * ghost indices belonging to the current processor, which are the indices
+ * where other processors might require information from. In a sense,
+ * these import indices form the dual of the ghost indices. This
+ * information is gathered once when constructing the partitioner, which
+ * obviates subsequent global communication steps when exchanging data.
*
* The partitioner includes a mechanism for converting global to local and
* local to global indices. Internally, this class stores vector elements
* using the convention as follows: The local range is associated with
* local indices [0,@p local_size), and ghost indices are stored
- * consecutively in [@p local_size, @p local_size + @p
- * n_ghost_indices). The ghost indices are sorted according to their
- * global index.
+ * consecutively in [@p local_size, @p local_size + @p n_ghost_indices).
+ * The ghost indices are sorted according to their global index.
*
*
* @author Katharina Kormann, Martin Kronbichler, 2010, 2011
Partitioner ();
/**
- * Constructor with size argument. Creates an
- * MPI_COMM_SELF structure where there is no
- * real parallel layout.
+ * Constructor with size argument. Creates an MPI_COMM_SELF structure
+ * where there is no real parallel layout.
*/
Partitioner (const unsigned int size);
/**
- * Constructor with index set arguments. This
- * constructor creates a distributed layout
- * based on a given communicators, an
- * IndexSet describing the locally owned
- * range and another one for describing ghost
- * indices that are owned by other
- * processors, but we need to have read or
- * write access to.
+ * Constructor with index set arguments. This constructor creates a
+ * distributed layout based on a given communicators, an IndexSet
+ * describing the locally owned range and another one for describing
+ * ghost indices that are owned by other processors, but we need to have
+ * read or write access to.
*/
Partitioner (const IndexSet &locally_owned_indices,
const IndexSet &ghost_indices_in,
const MPI_Comm communicator_in);
/**
- * Constructor with one index set argument. This
- * constructor creates a distributed layout
- * based on a given communicator, and an IndexSet
- * describing the locally owned range. It
- * allows to set the ghost indices at a later
- * time. Apart from this, it is similar to the
- * other constructor with two index sets.
+ * Constructor with one index set argument. This constructor creates a
+ * distributed layout based on a given communicator, and an IndexSet
+ * describing the locally owned range. It allows to set the ghost
+ * indices at a later time. Apart from this, it is similar to the other
+ * constructor with two index sets.
*/
Partitioner (const IndexSet &locally_owned_indices,
const MPI_Comm communicator_in);
/**
- * Sets the locally owned indices. Used in the
- * constructor.
+ * Sets the locally owned indices. Used in the constructor.
*/
void set_owned_indices (const IndexSet &locally_owned_indices);
/**
- * Allows to set the ghost indices after the
- * constructor has been called.
+ * Allows to set the ghost indices after the constructor has been
+ * called.
*/
void set_ghost_indices (const IndexSet &ghost_indices);
types::global_dof_index size() const;
/**
- * Returns the local size, i.e.
- * local_range().second minus
+ * Returns the local size, i.e. local_range().second minus
* local_range().first.
*/
unsigned int local_size() const;
/**
- * Returns an IndexSet representation of the
- * local range. This class only supports
- * contiguous local ranges, so the IndexSet
- * actually only consists of one single range
- * of data, and is equivalent to the result of
- * local_range().
+ * Returns an IndexSet representation of the local range. This class
+ * only supports contiguous local ranges, so the IndexSet actually only
+ * consists of one single range of data, and is equivalent to the result
+ * of local_range().
*/
const IndexSet &locally_owned_range() const;
/**
- * Returns the local range. The returned pair
- * consists of the index of the first element
- * and the index of the element one past the
- * last locally owned one.
+ * Returns the local range. The returned pair consists of the index of
+ * the first element and the index of the element one past the last
+ * locally owned one.
*/
std::pair<types::global_dof_index,types::global_dof_index>
local_range() const;
/**
- * Returns true if the given global index is
- * in the local range of this processor.
+ * Returns true if the given global index is in the local range of this
+ * processor.
*/
bool in_local_range (const types::global_dof_index global_index) const;
/**
- * Returns the local index corresponding to
- * the given global index. If the given global
- * index is neither locally owned nor a ghost,
- * an exception is thrown.
+ * Returns the local index corresponding to the given global index. If
+ * the given global index is neither locally owned nor a ghost, an
+ * exception is thrown.
*
- * Note that the local index for locally owned
- * indices is between 0 and local_size()-1,
- * and the local index for ghosts is between
- * local_size() and
- * local_size()+n_ghost_indices()-1.
+ * Note that the local index for locally owned indices is between 0 and
+ * local_size()-1, and the local index for ghosts is between
+ * local_size() and local_size()+n_ghost_indices()-1.
*/
unsigned int
global_to_local (const types::global_dof_index global_index) const;
/**
- * Returns the global index corresponding to
- * the given local index.
+ * Returns the global index corresponding to the given local index.
*
- * Note that the local index for locally owned
- * indices is between 0 and local_size()-1,
- * and the local index for ghosts is between
- * local_size() and
- * local_size()+n_ghost_indices()-1.
+ * Note that the local index for locally owned indices is between 0 and
+ * local_size()-1, and the local index for ghosts is between
+ * local_size() and local_size()+n_ghost_indices()-1.
*/
types::global_dof_index
local_to_global (const unsigned int local_index) const;
/**
- * Returns whether the given global index is a
- * ghost index on the present
- * processor. Returns false for indices that
- * are owned locally and for indices not
- * present at all.
+ * Returns whether the given global index is a ghost index on the
+ * present processor. Returns false for indices that are owned locally
+ * and for indices not present at all.
*/
bool is_ghost_entry (const types::global_dof_index global_index) const;
/**
- * Returns an IndexSet representation of all
- * ghost indices.
+ * Returns an IndexSet representation of all ghost indices.
*/
const IndexSet &ghost_indices() const;
/**
- * Returns the number of ghost indices. Same
- * as ghost_indices().n_elements(), but cached
- * for simpler access.
+ * Returns the number of ghost indices. Same as
+ * ghost_indices().n_elements(), but cached for simpler access.
*/
unsigned int n_ghost_indices() const;
/**
- * Returns a list of processors (first entry)
- * and the number of degrees of freedom for
- * the individual processor on the ghost
- * elements present (second entry).
+ * Returns a list of processors (first entry) and the number of degrees
+ * of freedom for the individual processor on the ghost elements present
+ * (second entry).
*/
const std::vector<std::pair<unsigned int, types::global_dof_index> > &
ghost_targets() const;
/**
- * The set of (local) indices that we are
- * importing during compress(), i.e., others'
- * ghosts that belong to the local
- * range. Similar structure as in an IndexSet,
- * but tailored to be iterated over, and some
- * indices may be duplicates.
+ * The set of (local) indices that we are importing during compress(),
+ * i.e., others' ghosts that belong to the local range. Similar
+ * structure as in an IndexSet, but tailored to be iterated over, and
+ * some indices may be duplicates.
*/
const std::vector<std::pair<types::global_dof_index, types::global_dof_index> > &
import_indices() const;
/**
- * Number of import indices, i.e., indices
- * that are ghosts on other processors and we
- * will receive data from.
+ * Number of import indices, i.e., indices that are ghosts on other
+ * processors and we will receive data from.
*/
unsigned int n_import_indices() const;
/**
- * Returns a list of processors (first entry)
- * and the number of degrees of freedom for
- * all the processors that data is obtained
- * from (second entry), i.e., locally owned
- * indices that are ghosts on other
+ * Returns a list of processors (first entry) and the number of degrees
+ * of freedom for all the processors that data is obtained from (second
+ * entry), i.e., locally owned indices that are ghosts on other
* processors.
*/
const std::vector<std::pair<unsigned int, types::global_dof_index> > &
import_targets() const;
/**
- * Checks whether the given
- * partitioner is compatible with the
- * partitioner used for this
- * vector. Two partitioners are
- * compatible if the have the same
- * local size and the same ghost
- * indices. They do not necessarily
- * need to be the same data
- * field. This is a local operation
- * only, i.e., if only some
- * processors decide that the
- * partitioning is not compatible,
- * only these processors will return
- * @p false, whereas the other
- * processors will return @p true.
+ * Checks whether the given partitioner is compatible with the
+ * partitioner used for this vector. Two partitioners are compatible if
+ * the have the same local size and the same ghost indices. They do not
+ * necessarily need to be the same data field. This is a local operation
+ * only, i.e., if only some processors decide that the partitioning is
+ * not compatible, only these processors will return @p false, whereas
+ * the other processors will return @p true.
*/
bool is_compatible (const Partitioner &part) const;
/**
- * Returns the MPI ID of the calling
- * processor. Cached to have simple access.
+ * Returns the MPI ID of the calling processor. Cached to have simple
+ * access.
*/
unsigned int this_mpi_process () const;
/**
- * Returns the total number of MPI processor
- * participating in the given
+ * Returns the total number of MPI processor participating in the given
* partitioner. Cached to have simple access.
*/
unsigned int n_mpi_processes () const;
/**
- * Returns the MPI communicator underlying the
- * partitioner object.
+ * Returns the MPI communicator underlying the partitioner object.
*/
const MPI_Comm &get_communicator() const;
/**
- * Computes the memory consumption of this
- * structure.
+ * Computes the memory consumption of this structure.
*/
std::size_t memory_consumption() const;
const types::global_dof_index global_size;
/**
- * The range of the vector that is stored
- * locally.
+ * The range of the vector that is stored locally.
*/
IndexSet locally_owned_range_data;
/**
- * The range of the vector that is stored
- * locally. Extracted from locally_owned_range
- * for performance reasons.
+ * The range of the vector that is stored locally. Extracted from
+ * locally_owned_range for performance reasons.
*/
std::pair<types::global_dof_index,types::global_dof_index> local_range_data;
/**
- * The set of indices to which we need to have
- * read access but that are not locally owned
+ * The set of indices to which we need to have read access but that are
+ * not locally owned
*/
IndexSet ghost_indices_data;
/**
- * Caches the number of ghost indices. It
- * would be expensive to use @p
+ * Caches the number of ghost indices. It would be expensive to use @p
* ghost_indices.n_elements() to compute this.
*/
unsigned int n_ghost_indices_data;
/**
- * Contains information which processors my
- * ghost indices belong to and how many those
- * indices are
+ * Contains information which processors my ghost indices belong to and
+ * how many those indices are
*/
std::vector<std::pair<unsigned int, types::global_dof_index> > ghost_targets_data;
/**
- * The set of (local) indices that we are
- * importing during compress(), i.e., others'
- * ghosts that belong to the local
- * range. Similar structure as in an IndexSet,
- * but tailored to be iterated over, and some
- * indices may be duplicates.
+ * The set of (local) indices that we are importing during compress(),
+ * i.e., others' ghosts that belong to the local range. Similar
+ * structure as in an IndexSet, but tailored to be iterated over, and
+ * some indices may be duplicates.
*/
std::vector<std::pair<types::global_dof_index, types::global_dof_index> > import_indices_data;
/**
- * Caches the number of ghost indices. It
- * would be expensive to compute it by
- * iterating over the import indices and
- * accumulate them.
+ * Caches the number of ghost indices. It would be expensive to compute
+ * it by iterating over the import indices and accumulate them.
*/
unsigned int n_import_indices_data;
/**
- * The set of processors and length of data
- * field which send us their ghost data
+ * The set of processors and length of data field which send us their
+ * ghost data
*/
std::vector<std::pair<unsigned int,types::global_dof_index> > import_targets_data;
/**
- * The ID of the current processor in the MPI
- * network
+ * The ID of the current processor in the MPI network
*/
unsigned int my_pid;
/**
- * The total number of processors active in
- * the problem
+ * The total number of processors active in the problem
*/
unsigned int n_procs;
/**
- * The MPI communicator involved in the
- * problem
+ * The MPI communicator involved in the problem
*/
const MPI_Comm communicator;
};
DEAL_II_NAMESPACE_OPEN
/**
- * Support for searching files in a list of paths and with a list of
- * suffixes.
+ * Support for searching files in a list of paths and with a list of suffixes.
*
- * A list of search paths is maintained for each file class supported.
- * A file class is defined by a unique string. The classes provided are
- * <dl>
- * <dt> MESH <dd> mesh input files in various formats (see GridIn)
- * <dt> PARAMETER <dd> Parameter files (<tt>.prm</tt>)
- * </dl>
+ * A list of search paths is maintained for each file class supported. A file
+ * class is defined by a unique string. The classes provided are <dl> <dt>
+ * MESH <dd> mesh input files in various formats (see GridIn) <dt> PARAMETER
+ * <dd> Parameter files (<tt>.prm</tt>) </dl>
*
* Additional file classes can be added easily by using add_class().
*
* Usage: First, you construct a PathSearch object for a certain file class,
- * e.g. meshes. Then, you use the find() method to obtain a full path
- * name and you can open the file.
+ * e.g. meshes. Then, you use the find() method to obtain a full path name and
+ * you can open the file.
* @code
* #include <deal.II/base/path_search.h>
*
* ...
* @endcode
*
- * This piece of code will first traverse all paths in the list set up
- * for file class <TT>MESH</tt>. If it manages to open a file, it
- * returns the <tt>istream</tt> object. If not, it will try to append
- * the first suffix of the suffix list and do the same. And so on. If
- * no file is found in the end, an exception is thrown.
+ * This piece of code will first traverse all paths in the list set up for
+ * file class <TT>MESH</tt>. If it manages to open a file, it returns the
+ * <tt>istream</tt> object. If not, it will try to append the first suffix of
+ * the suffix list and do the same. And so on. If no file is found in the end,
+ * an exception is thrown.
*
- * If you want to restrict your search to a certain mesh format,
- * <tt>.inp</tt> for instance, then either use <tt>"grid.inp"</tt> in
- * the code above or use the alternative find(const std::string&,const
- * std::string&,const char*) function
+ * If you want to restrict your search to a certain mesh format, <tt>.inp</tt>
+ * for instance, then either use <tt>"grid.inp"</tt> in the code above or use
+ * the alternative find(const std::string&,const std::string&,const char*)
+ * function
* @code
* std::string full_name = search.find("grid", ".inp");
* @endcode
*
* Path lists are by default starting with the current directory
- * (<tt>"./"</tt>), followed optionally by a standard directory of
- * deal.II. Use show() to find out the path list
- * for a given class. Paths and suffixes can be added using the
- * functions add_path() and add_suffix(), respectively.
+ * (<tt>"./"</tt>), followed optionally by a standard directory of deal.II.
+ * Use show() to find out the path list for a given class. Paths and suffixes
+ * can be added using the functions add_path() and add_suffix(), respectively.
*
- * @note Directories in the path list should always end with a
- * trailing <tt>"/"</tt>, while suffixes should always start with a
- * dot. These characters are not added automatically (allowing you to
- * do some real file name editing).
+ * @note Directories in the path list should always end with a trailing
+ * <tt>"/"</tt>, while suffixes should always start with a dot. These
+ * characters are not added automatically (allowing you to do some real file
+ * name editing).
*
* @todo Add support for environment variables like in kpathsea.
*
{
public:
/**
- * Position for adding a new item
- * to a list.
+ * Position for adding a new item to a list.
*/
enum Position
{
};
/**
- * Constructor. The first argument is a
- * string identifying the class of files
- * to be searched for.
+ * Constructor. The first argument is a string identifying the class of
+ * files to be searched for.
*
- * The debug argument determines
- * the verbosity of this class.
+ * The debug argument determines the verbosity of this class.
*/
PathSearch (const std::string &cls,
const unsigned int debug=0);
/**
- * Find a file in the class
- * specified by the constructor
- * and return its complete path
- * name (including a possible
- * suffix).
+ * Find a file in the class specified by the constructor and return its
+ * complete path name (including a possible suffix).
*
- * File search works by actually
- * trying to open the file. If @p
- * fopen is successful with the
- * provided @p open_mode, then
- * the file is found, otherwise
- * the search continues.
+ * File search works by actually trying to open the file. If @p fopen is
+ * successful with the provided @p open_mode, then the file is found,
+ * otherwise the search continues.
*
- * @warning Be careful with @p
- * open_mode! In particular, use
- * <tt>"w"</tt> with great care!
- * If the file does not exist, it
- * cannot be found. If it does
- * exist, the @p fopen function
- * will truncate it to zero
- * length.
+ * @warning Be careful with @p open_mode! In particular, use <tt>"w"</tt>
+ * with great care! If the file does not exist, it cannot be found. If it
+ * does exist, the @p fopen function will truncate it to zero length.
*
- * @param filename The base
- * name of the file to be found,
- * without path components and
- * suffix.
- * @param open_mode The mode
- * handed over to the @p fopen
- * function.
+ * @param filename The base name of the file to be found, without path
+ * components and suffix.
+ * @param open_mode The mode handed over to the @p fopen function.
*/
std::string find (const std::string &filename,
const char *open_mode = "r");
/**
- * Find a file in the class
- * specified by the constructor
- * and return its complete path
- * name. Do not use the standard
- * suffix list, but only try to
+ * Find a file in the class specified by the constructor and return its
+ * complete path name. Do not use the standard suffix list, but only try to
* apply the suffix given.
*
- * File search works by actually
- * trying to open the file. If @p
- * fopen is successful with the
- * provided @p open_mode, then
- * the file is found, otherwise
- * the search continues.
+ * File search works by actually trying to open the file. If @p fopen is
+ * successful with the provided @p open_mode, then the file is found,
+ * otherwise the search continues.
*
- * @warning Be careful with @p
- * open_mode! In particular, use
- * <tt>"w"</tt> with great care!
- * If the file does not exist, it
- * cannot be found. If it does
- * exist, the @p fopen function
- * will truncate it to zero
- * length.
+ * @warning Be careful with @p open_mode! In particular, use <tt>"w"</tt>
+ * with great care! If the file does not exist, it cannot be found. If it
+ * does exist, the @p fopen function will truncate it to zero length.
*
- * @param filename The base
- * name of the file to be found,
- * without path components and
- * suffix.
- * @param suffix The suffix to be
- * used for opening.
- * @param open_mode The mode
- * handed over to the @p fopen
- * function.
+ * @param filename The base name of the file to be found, without path
+ * components and suffix.
+ * @param suffix The suffix to be used for opening.
+ * @param open_mode The mode handed over to the @p fopen function.
*/
std::string find (const std::string &filename,
const std::string &suffix,
const char *open_mode = "r");
/**
- * Show the paths and suffixes
- * used for this object.
+ * Show the paths and suffixes used for this object.
*/
template <class STREAM>
void show(STREAM &stream) const;
static void add_class (const std::string &cls);
/**
- * Add a path to the current
- * class. See
- * PathSearch::Position for
- * possible position arguments.
+ * Add a path to the current class. See PathSearch::Position for possible
+ * position arguments.
*/
void add_path (const std::string &path, Position pos = back);
/**
- * Add a path to the current
- * class. See
- * PathSearch::Position for
- * possible position arguments.
+ * Add a path to the current class. See PathSearch::Position for possible
+ * position arguments.
*/
void add_suffix (const std::string &suffix, Position pos = back);
/**
- * This class was not
- * registered in the path
- * search mechanism.
+ * This class was not registered in the path search mechanism.
* @ingroup Exceptions
*/
DeclException1(ExcNoClass,
<< arg1
<< " must be registered before referring it in PathSearch");
/**
- * The PathSearch class could not
- * find a file with this name in
- * its path list.
+ * The PathSearch class could not find a file with this name in its path
+ * list.
* @ingroup Exceptions
*/
DeclException2(ExcFileNotFound,
private:
/**
- * Type of values in the class
- * maps.
+ * Type of values in the class maps.
*/
typedef std::map<std::string, std::vector<std::string> >::value_type map_type;
/**
- * Initialize the static list
- * objects for further use.
+ * Initialize the static list objects for further use.
*/
static void initialize_classes();
/**
- * Get path list for a certain
- * class. Used to set up
- * #my_path_list in constructor.
+ * Get path list for a certain class. Used to set up #my_path_list in
+ * constructor.
*/
static std::vector<std::string> &get_path_list(const std::string &cls);
/**
- * Get suffix list for a certain
- * class. Used to set up
- * #my_suffix_list in constructor.
+ * Get suffix list for a certain class. Used to set up #my_suffix_list in
+ * constructor.
*/
static std::vector<std::string> &get_suffix_list(const std::string &cls);
const std::string cls;
/**
- * All path lists for all
- * classes, such that we can
- * build them only once.
+ * All path lists for all classes, such that we can build them only once.
*/
static std::map<std::string, std::vector<std::string> > path_lists;
/**
- * List of suffixes for each
- * class.
+ * List of suffixes for each class.
*/
static std::map<std::string, std::vector<std::string> > suffix_lists;
/**
- * Path list for the class this
- * object belongs to.
+ * Path list for the class this object belongs to.
*/
std::vector<std::string> &my_path_list;
/**
- * Suffix list for the class this
- * object belongs to.
+ * Suffix list for the class this object belongs to.
*/
std::vector<std::string> &my_suffix_list;
{
public:
/**
- * Standard constructor. Creates
- * an object that corresponds to the origin, i.e., all coordinates
- * are set to zero.
+ * Standard constructor. Creates an object that corresponds to the origin,
+ * i.e., all coordinates are set to zero.
*/
Point ();
/**
- * Constructor. Initialize all
- * entries to zero if
- * <tt>initialize==true</tt> (in which case it is equivalent to the default
- * constructor) or leaves the elements uninitialized if
- * <tt>initialize==false</tt>.
+ * Constructor. Initialize all entries to zero if <tt>initialize==true</tt>
+ * (in which case it is equivalent to the default constructor) or leaves the
+ * elements uninitialized if <tt>initialize==false</tt>.
*/
explicit Point (const bool initialize);
Point (const Tensor<1,dim,Number> &);
/**
- * Constructor for one dimensional
- * points. This function is only
- * implemented for <tt>dim==1</tt> since
- * the usage is considered unsafe for
- * points with <tt>dim!=1</tt> as it would leave some components
- * of the point coordinates uninitialized.
+ * Constructor for one dimensional points. This function is only implemented
+ * for <tt>dim==1</tt> since the usage is considered unsafe for points with
+ * <tt>dim!=1</tt> as it would leave some components of the point
+ * coordinates uninitialized.
*/
explicit Point (const Number x);
/**
- * Constructor for two dimensional
- * points. This function is only
- * implemented for <tt>dim==2</tt> since
- * the usage is considered unsafe for
- * points with <tt>dim!=2</tt> as it would leave some components
- * of the point coordinates uninitialized (if dim>2) or would
- * not use some arguments (if dim<2).
+ * Constructor for two dimensional points. This function is only implemented
+ * for <tt>dim==2</tt> since the usage is considered unsafe for points with
+ * <tt>dim!=2</tt> as it would leave some components of the point
+ * coordinates uninitialized (if dim>2) or would not use some arguments (if
+ * dim<2).
*/
Point (const Number x,
const Number y);
/**
- * Constructor for three dimensional
- * points. This function is only
- * implemented for <tt>dim==3</tt> since
- * the usage is considered unsafe for
- * points with <tt>dim!=3</tt> as it would leave some components
- * of the point coordinates uninitialized (if dim>3) or would
- * not use some arguments (if dim<3).
+ * Constructor for three dimensional points. This function is only
+ * implemented for <tt>dim==3</tt> since the usage is considered unsafe for
+ * points with <tt>dim!=3</tt> as it would leave some components of the
+ * point coordinates uninitialized (if dim>3) or would not use some
+ * arguments (if dim<3).
*/
Point (const Number x,
const Number y,
const Number z);
/**
- * Return a unit vector in
- * coordinate direction <tt>i</tt>.
+ * Return a unit vector in coordinate direction <tt>i</tt>.
*/
static Point<dim,Number> unit_vector(const unsigned int i);
/**
- * Read access to the <tt>index</tt>th
- * coordinate.
+ * Read access to the <tt>index</tt>th coordinate.
*/
Number operator () (const unsigned int index) const;
/**
- * Read and write access to the
- * <tt>index</tt>th coordinate.
+ * Read and write access to the <tt>index</tt>th coordinate.
*/
Number &operator () (const unsigned int index);
*/
/**
- * Add two point vectors. If possible,
- * use <tt>operator +=</tt> instead
- * since this does not need to copy a
- * point at least once.
+ * Add two point vectors. If possible, use <tt>operator +=</tt> instead
+ * since this does not need to copy a point at least once.
*/
Point<dim,Number> operator + (const Tensor<1,dim,Number> &) const;
/**
- * Subtract two point vectors. If
- * possible, use <tt>operator +=</tt>
- * instead since this does not need to
- * copy a point at least once.
+ * Subtract two point vectors. If possible, use <tt>operator +=</tt> instead
+ * since this does not need to copy a point at least once.
*/
Point<dim,Number> operator - (const Tensor<1,dim,Number> &) const;
Point<dim,Number> operator - () const;
/**
- * Multiply by a factor. If possible,
- * use <tt>operator *=</tt> instead
- * since this does not need to copy a
- * point at least once.
+ * Multiply by a factor. If possible, use <tt>operator *=</tt> instead since
+ * this does not need to copy a point at least once.
*
- * There is a commutative complement to this
- * function also
+ * There is a commutative complement to this function also
*/
Point<dim,Number> operator * (const Number) const;
/**
- * Returns the scalar product of two
- * vectors.
+ * Returns the scalar product of two vectors.
*/
Number operator * (const Tensor<1,dim,Number> &) const;
/**
- * Divide by a factor. If possible, use
- * <tt>operator /=</tt> instead since
- * this does not need to copy a point at
- * least once.
+ * Divide by a factor. If possible, use <tt>operator /=</tt> instead since
+ * this does not need to copy a point at least once.
*/
Point<dim,Number> operator / (const Number) const;
/**
- * Returns the scalar product of this
- * point vector with itself, i.e. the
- * square, or the square of the norm.
+ * Returns the scalar product of this point vector with itself, i.e. the
+ * square, or the square of the norm.
*/
Number square () const;
/**
- * Returns the Euclidian distance of
- * <tt>this</tt> point to the point
- * <tt>p</tt>, i.e. the <tt>l_2</tt> norm
- * of the difference between the vectors
- * representing the two points.
+ * Returns the Euclidian distance of <tt>this</tt> point to the point
+ * <tt>p</tt>, i.e. the <tt>l_2</tt> norm of the difference between the
+ * vectors representing the two points.
*/
Number distance (const Point<dim,Number> &p) const;
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the purpose
+ * of serialization
*/
template <class Archive>
void serialize(Archive &ar, const unsigned int version);
/**
- * Global operator scaling a point vector by a scalar.
- * @relates Point
+ * Global operator scaling a point vector by a scalar. @relates Point
*/
template <int dim, typename Number>
inline
/**
- * Global operator scaling a point vector by a scalar.
- * @relates Point
+ * Global operator scaling a point vector by a scalar. @relates Point
*/
template <int dim>
inline
/**
- * Output operator for points. Print the elements consecutively,
- * with a space in between.
- * @relates Point
+ * Output operator for points. Print the elements consecutively, with a space
+ * in between. @relates Point
*/
template <int dim, typename Number>
inline
/**
- * Output operator for points. Print the elements consecutively,
- * with a space in between.
- * @relates Point
+ * Output operator for points. Print the elements consecutively, with a space
+ * in between. @relates Point
*/
template <int dim, typename Number>
inline
#ifndef DOXYGEN
/**
- * Output operator for points of dimension 1. This is implemented
- * specialized from the general template in order to avoid a compiler
- * warning that the loop is empty.
+ * Output operator for points of dimension 1. This is implemented specialized
+ * from the general template in order to avoid a compiler warning that the
+ * loop is empty.
*/
template <typename Number>
inline
{
/**
- * Base class for all 1D polynomials. A polynomial is represented in
- * this class by its coefficients, which are set through the
- * constructor or by derived classes. Evaluation of a polynomial
- * happens through the Horner scheme which provides both numerical
- * stability and a minimal number of numerical operations.
+ * Base class for all 1D polynomials. A polynomial is represented in this
+ * class by its coefficients, which are set through the constructor or by
+ * derived classes. Evaluation of a polynomial happens through the Horner
+ * scheme which provides both numerical stability and a minimal number of
+ * numerical operations.
*
* @author Ralf Hartmann, Guido Kanschat, 2000, 2006
*/
Polynomial<number> &operator -= (const Polynomial<number> &p);
/**
- * Test for equality of two polynomials.
+ * Test for equality of two polynomials.
*/
bool operator == (const Polynomial<number> &p) const;
/**
- * Class generates Polynomial objects representing a monomial of
- * degree n, that is, the function $x^n$.
+ * Class generates Polynomial objects representing a monomial of degree n,
+ * that is, the function $x^n$.
*
* @author Guido Kanschat, 2004
*/
{
public:
/**
- * Constructor, taking the
- * degree of the monomial and
- * an optional coefficient as
- * arguments.
+ * Constructor, taking the degree of the monomial and an optional
+ * coefficient as arguments.
*/
Monomial(const unsigned int n,
const double coefficient = 1.);
/**
- * Return a vector of Monomial
- * objects of degree zero
- * through <tt>degree</tt>, which
- * then spans the full space of
- * polynomials up to the given
- * degree. This function may be
- * used to initialize the
- * TensorProductPolynomials
- * and PolynomialSpace
- * classes.
+ * Return a vector of Monomial objects of degree zero through
+ * <tt>degree</tt>, which then spans the full space of polynomials up to
+ * the given degree. This function may be used to initialize the
+ * TensorProductPolynomials and PolynomialSpace classes.
*/
static
std::vector<Polynomial<number> >
/**
- * Lagrange polynomials with equidistant interpolation points in
- * [0,1]. The polynomial of degree <tt>n</tt> has got <tt>n+1</tt> interpolation
- * points. The interpolation points are sorted in ascending
- * order. This order gives an index to each interpolation point. A
- * Lagrangian polynomial equals to 1 at its `support point', and 0 at
- * all other interpolation points. For example, if the degree is 3,
- * and the support point is 1, then the polynomial represented by this
- * object is cubic and its value is 1 at the point <tt>x=1/3</tt>, and zero
- * at the point <tt>x=0</tt>, <tt>x=2/3</tt>, and <tt>x=1</tt>. All the polynomials
- * have polynomial degree equal to <tt>degree</tt>, but together they span
- * the entire space of polynomials of degree less than or equal
- * <tt>degree</tt>.
+ * Lagrange polynomials with equidistant interpolation points in [0,1]. The
+ * polynomial of degree <tt>n</tt> has got <tt>n+1</tt> interpolation
+ * points. The interpolation points are sorted in ascending order. This
+ * order gives an index to each interpolation point. A Lagrangian
+ * polynomial equals to 1 at its `support point', and 0 at all other
+ * interpolation points. For example, if the degree is 3, and the support
+ * point is 1, then the polynomial represented by this object is cubic and
+ * its value is 1 at the point <tt>x=1/3</tt>, and zero at the point
+ * <tt>x=0</tt>, <tt>x=2/3</tt>, and <tt>x=1</tt>. All the polynomials have
+ * polynomial degree equal to <tt>degree</tt>, but together they span the
+ * entire space of polynomials of degree less than or equal <tt>degree</tt>.
*
* The Lagrange polynomials are implemented up to degree 10.
*
* Return a vector of polynomial objects of degree <tt>degree</tt>, which
* then spans the full space of polynomials up to the given degree. The
* polynomials are generated by calling the constructor of this class with
- * the same degree but support point running from zero to
- * <tt>degree</tt>. This function may be used to initialize the
- * TensorProductPolynomials and PolynomialSpace classes.
+ * the same degree but support point running from zero to <tt>degree</tt>.
+ * This function may be used to initialize the TensorProductPolynomials
+ * and PolynomialSpace classes.
*/
static
std::vector<Polynomial<double> >
/**
- * Legendre polynomials of arbitrary degree.
- * Constructing a Legendre polynomial of degree <tt>p</tt>, the coefficients
- * will be computed by the three-term recursion formula.
+ * Legendre polynomials of arbitrary degree. Constructing a Legendre
+ * polynomial of degree <tt>p</tt>, the coefficients will be computed by the
+ * three-term recursion formula.
*
* @note The polynomials defined by this class differ in two aspects by what
* is usually referred to as Legendre polynomials: (i) This classes defines
* them on the reference interval $[0,1]$, rather than the commonly used
- * interval $[-1,1]$. (ii) The polynomials have been scaled in such a way that
- * they are orthonormal, not just orthogonal; consequently, the polynomials do
- * not necessarily have boundary values equal to one.
+ * interval $[-1,1]$. (ii) The polynomials have been scaled in such a way
+ * that they are orthonormal, not just orthogonal; consequently, the
+ * polynomials do not necessarily have boundary values equal to one.
*
* @author Guido Kanschat, 2000
*/
{
public:
/**
- * Constructor for polynomial of
- * degree <tt>p</tt>.
+ * Constructor for polynomial of degree <tt>p</tt>.
*/
Legendre (const unsigned int p);
/**
- * Return a vector of Legendre
- * polynomial objects of degrees
- * zero through <tt>degree</tt>, which
- * then spans the full space of
- * polynomials up to the given
- * degree. This function may be
- * used to initialize the
- * TensorProductPolynomials
- * and PolynomialSpace
- * classes.
+ * Return a vector of Legendre polynomial objects of degrees zero through
+ * <tt>degree</tt>, which then spans the full space of polynomials up to
+ * the given degree. This function may be used to initialize the
+ * TensorProductPolynomials and PolynomialSpace classes.
*/
static
std::vector<Polynomial<double> >
static std::vector<std_cxx11::shared_ptr<const std::vector<double> > > shifted_coefficients;
/**
- * Vector with already computed
- * coefficients. For each degree of the
- * polynomial, we keep one pointer to
- * the list of coefficients; we do so
- * rather than keeping a vector of
- * vectors in order to simplify
- * programming multithread-safe. In
- * order to avoid memory leak, we use a
- * shared_ptr in order to correctly
- * free the memory of the vectors when
+ * Vector with already computed coefficients. For each degree of the
+ * polynomial, we keep one pointer to the list of coefficients; we do so
+ * rather than keeping a vector of vectors in order to simplify
+ * programming multithread-safe. In order to avoid memory leak, we use a
+ * shared_ptr in order to correctly free the memory of the vectors when
* the global destructor is called.
*/
static std::vector<std_cxx11::shared_ptr<const std::vector<double> > > recursive_coefficients;
/**
- * Compute coefficients recursively.
- * The coefficients are stored in a
- * static data vector to be available
- * when needed next time. Since the
- * recursion is performed for the
- * interval $[-1,1]$, the polynomials
- * are shifted to $[0,1]$ by the
- * <tt>scale</tt> and <tt>shift</tt>
- * functions of <tt>Polynomial</tt>,
- * afterwards.
+ * Compute coefficients recursively. The coefficients are stored in a
+ * static data vector to be available when needed next time. Since the
+ * recursion is performed for the interval $[-1,1]$, the polynomials are
+ * shifted to $[0,1]$ by the <tt>scale</tt> and <tt>shift</tt> functions
+ * of <tt>Polynomial</tt>, afterwards.
*/
static void compute_coefficients (const unsigned int p);
/**
- * Get coefficients for
- * constructor. This way, it can
- * use the non-standard
- * constructor of
- * Polynomial.
+ * Get coefficients for constructor. This way, it can use the non-
+ * standard constructor of Polynomial.
*/
static const std::vector<double> &
get_coefficients (const unsigned int k);
*
* These polynomials are the integrated Legendre polynomials on [0,1]. The
* first two polynomials are the standard linear shape functions given by
- * $l_0(x) = 1-x$ and $l_1(x) = x$. For $i\geq2$ we use the definition $l_i(x)
- * = \frac{1}{\Vert L_{i-1}\Vert_2}\int_0^x L_{i-1}(t)\,dt$, where $L_i$
- * denotes the $i$-th Legendre polynomial on $[0,1]$. The Lobatto polynomials
- * $l_0,\ldots,l_k$ form a complete basis of the polynomials space of degree
- * $k$.
+ * $l_0(x) = 1-x$ and $l_1(x) = x$. For $i\geq2$ we use the definition
+ * $l_i(x) = \frac{1}{\Vert L_{i-1}\Vert_2}\int_0^x L_{i-1}(t)\,dt$, where
+ * $L_i$ denotes the $i$-th Legendre polynomial on $[0,1]$. The Lobatto
+ * polynomials $l_0,\ldots,l_k$ form a complete basis of the polynomials
+ * space of degree $k$.
*
* Calling the constructor with a given index <tt>k</tt> will generate the
* polynomial with index <tt>k</tt>. But only for $k\geq 1$ the index equals
- * the degree of the polynomial. For <tt>k==0</tt> also a polynomial of degree
- * 1 is generated.
+ * the degree of the polynomial. For <tt>k==0</tt> also a polynomial of
+ * degree 1 is generated.
*
* These polynomials are used for the construction of the shape functions of
* Nédélec elements of arbitrary order.
{
public:
/**
- * Constructor for polynomial of degree
- * <tt>p</tt>. There is an exception
- * for <tt>p==0</tt>, see the general
- * documentation.
+ * Constructor for polynomial of degree <tt>p</tt>. There is an exception
+ * for <tt>p==0</tt>, see the general documentation.
*/
Lobatto (const unsigned int p = 0);
/**
- * Return the polynomials with index
- * <tt>0</tt> up to
- * <tt>degree</tt>. There is an
- * exception for <tt>p==0</tt>, see the
- * general documentation.
+ * Return the polynomials with index <tt>0</tt> up to <tt>degree</tt>.
+ * There is an exception for <tt>p==0</tt>, see the general documentation.
*/
static std::vector<Polynomial<double> >
generate_complete_basis (const unsigned int p);
/**
* Hierarchical polynomials of arbitrary degree on <tt>[0,1]</tt>.
*
- * When Constructing a Hierarchical polynomial of degree <tt>p</tt>,
- * the coefficients will be computed by a recursion formula. The
- * coefficients are stored in a static data vector to be available
- * when needed next time.
+ * When Constructing a Hierarchical polynomial of degree <tt>p</tt>, the
+ * coefficients will be computed by a recursion formula. The coefficients
+ * are stored in a static data vector to be available when needed next time.
*
* These hierarchical polynomials are based on those of Demkowicz, Oden,
* Rachowicz, and Hardy (CMAME 77 (1989) 79-112, Sec. 4). The first two
- * polynomials are the standard linear shape functions given by
- * $\phi_{0}(x) = 1 - x$ and $\phi_{1}(x) = x$. For $l \geq 2$
- * we use the definitions $\phi_{l}(x) = (2x-1)^l - 1, l = 2,4,6,...$
- * and $\phi_{l}(x) = (2x-1)^l - (2x-1), l = 3,5,7,...$. These satisfy the
- * recursion relations $\phi_{l}(x) = (2x-1)\phi_{l-1}, l=3,5,7,...$ and
- * $\phi_{l}(x) = (2x-1)\phi_{l-1} + \phi_{2}, l=4,6,8,...$.
+ * polynomials are the standard linear shape functions given by $\phi_{0}(x)
+ * = 1 - x$ and $\phi_{1}(x) = x$. For $l \geq 2$ we use the definitions
+ * $\phi_{l}(x) = (2x-1)^l - 1, l = 2,4,6,...$ and $\phi_{l}(x) = (2x-1)^l -
+ * (2x-1), l = 3,5,7,...$. These satisfy the recursion relations
+ * $\phi_{l}(x) = (2x-1)\phi_{l-1}, l=3,5,7,...$ and $\phi_{l}(x) =
+ * (2x-1)\phi_{l-1} + \phi_{2}, l=4,6,8,...$.
*
- * The degrees of freedom are the values at the vertices and the
- * derivatives at the midpoint. Currently, we do not scale the
- * polynomials in any way, although better conditioning of the
- * element stiffness matrix could possibly be achieved with scaling.
+ * The degrees of freedom are the values at the vertices and the derivatives
+ * at the midpoint. Currently, we do not scale the polynomials in any way,
+ * although better conditioning of the element stiffness matrix could
+ * possibly be achieved with scaling.
*
* Calling the constructor with a given index <tt>p</tt> will generate the
* following: if <tt>p==0</tt>, then the resulting polynomial is the linear
* associated with the right vertex. For higher values of <tt>p</tt>, you
* get the polynomial of degree <tt>p</tt> that is orthogonal to all
* previous ones. Note that for <tt>p==0</tt> you therefore do <b>not</b>
- * get a polynomial of degree zero, but one of degree one. This is to
- * allow generating a complete basis for polynomial spaces, by just
- * iterating over the indices given to the constructor.
+ * get a polynomial of degree zero, but one of degree one. This is to allow
+ * generating a complete basis for polynomial spaces, by just iterating over
+ * the indices given to the constructor.
*
- * On the other hand, the function generate_complete_basis() creates
- * a complete basis of given degree. In order to be consistent with
- * the concept of a polynomial degree, if the given argument is zero,
- * it does <b>not</b> return the linear polynomial described above, but
- * rather a constant polynomial.
+ * On the other hand, the function generate_complete_basis() creates a
+ * complete basis of given degree. In order to be consistent with the
+ * concept of a polynomial degree, if the given argument is zero, it does
+ * <b>not</b> return the linear polynomial described above, but rather a
+ * constant polynomial.
*
* @author Brian Carnes, 2002
*/
{
public:
/**
- * Constructor for polynomial of
- * degree <tt>p</tt>. There is an
- * exception for <tt>p==0</tt>, see
- * the general documentation.
+ * Constructor for polynomial of degree <tt>p</tt>. There is an exception
+ * for <tt>p==0</tt>, see the general documentation.
*/
Hierarchical (const unsigned int p);
/**
- * Return a vector of
- * Hierarchical polynomial
- * objects of degrees zero through
- * <tt>degree</tt>, which then spans
- * the full space of polynomials
- * up to the given degree. Note
- * that there is an exception if
- * the given <tt>degree</tt> equals
- * zero, see the general
- * documentation of this class.
+ * Return a vector of Hierarchical polynomial objects of degrees zero
+ * through <tt>degree</tt>, which then spans the full space of polynomials
+ * up to the given degree. Note that there is an exception if the given
+ * <tt>degree</tt> equals zero, see the general documentation of this
+ * class.
*
- * This function may be
- * used to initialize the
- * TensorProductPolynomials,
- * AnisotropicPolynomials,
- * and PolynomialSpace
- * classes.
+ * This function may be used to initialize the TensorProductPolynomials,
+ * AnisotropicPolynomials, and PolynomialSpace classes.
*/
static
std::vector<Polynomial<double> >
static void compute_coefficients (const unsigned int p);
/**
- * Get coefficients for
- * constructor. This way, it can
- * use the non-standard
- * constructor of
- * Polynomial.
+ * Get coefficients for constructor. This way, it can use the non-
+ * standard constructor of Polynomial.
*/
static const std::vector<double> &
get_coefficients (const unsigned int p);
/**
- * Vector with already computed
- * coefficients. For each degree of the
- * polynomial, we keep one pointer to
- * the list of coefficients; we do so
- * rather than keeping a vector of
- * vectors in order to simplify
- * programming multithread-safe. In
- * order to avoid memory leak, we use a
- * shared_ptr in order to correctly
- * free the memory of the vectors when
+ * Vector with already computed coefficients. For each degree of the
+ * polynomial, we keep one pointer to the list of coefficients; we do so
+ * rather than keeping a vector of vectors in order to simplify
+ * programming multithread-safe. In order to avoid memory leak, we use a
+ * shared_ptr in order to correctly free the memory of the vectors when
* the global destructor is called.
*/
static std::vector<std_cxx11::shared_ptr<const std::vector<double> > > recursive_coefficients;
/**
* Polynomials for Hermite interpolation condition.
*
- * This is the set of polynomials of degree at least three, such that
- * the following interpolation conditions are met: the polynomials and
- * their first derivatives vanish at the values <i>x</i>=0 and
- * <i>x</i>=1, with the exceptions <i>p</i><sub>0</sub>(0)=1,
+ * This is the set of polynomials of degree at least three, such that the
+ * following interpolation conditions are met: the polynomials and their
+ * first derivatives vanish at the values <i>x</i>=0 and <i>x</i>=1, with
+ * the exceptions <i>p</i><sub>0</sub>(0)=1,
* <i>p</i><sub><i>1</i></sub>(1)=1, <i>p</i>'<sub>2</sub>(0)=1,
* <i>p'</i><sub>3</sub>(1)=1.
*
- * For degree three, we obtain the standard four Hermitian
- * interpolation polynomials, see for instance <a
+ * For degree three, we obtain the standard four Hermitian interpolation
+ * polynomials, see for instance <a
* href="http://en.wikipedia.org/wiki/Cubic_Hermite_spline">Wikipedia</a>.
- * For higher degrees, these are augmented
- * first, by the polynomial of degree four with vanishing values and
- * derivatives at <i>x</i>=0 and <i>x</i>=1, then by the product of
- * this fourth order polynomial with Legendre polynomials of
- * increasing order. The implementation is
- * @f{align*}{
- * p_0(x) &= 2x^3-3x^2+1 \\
- * p_1(x) &= -2x^2+3x^2 \\
- * p_2(x) &= x^3-2x^2+x \\
- * p_3(x) &= x^3-x^2 \\
- * p_4(x) &= 16x^2(x-1)^2 \\
- * \ldots & \ldots \\
- * p_k(x) &= x^2(x-1)^2 L_{k-4}(x)
- * @f}
+ * For higher degrees, these are augmented first, by the polynomial of
+ * degree four with vanishing values and derivatives at <i>x</i>=0 and
+ * <i>x</i>=1, then by the product of this fourth order polynomial with
+ * Legendre polynomials of increasing order. The implementation is
+ * @f{align*}{ p_0(x) &= 2x^3-3x^2+1 \\ p_1(x) &= -2x^2+3x^2 \\ p_2(x) &=
+ * x^3-2x^2+x \\ p_3(x) &= x^3-x^2 \\ p_4(x) &= 16x^2(x-1)^2 \\ \ldots &
+ * \ldots \\ p_k(x) &= x^2(x-1)^2 L_{k-4}(x) @f}
*
* @author Guido Kanschat
* @date 2012
{
public:
/**
- * Constructor for polynomial
- * with index <tt>p</tt>. See
- * the class documentation on
- * the definition of the
- * sequence of polynomials.
- */
+ * Constructor for polynomial with index <tt>p</tt>. See the class
+ * documentation on the definition of the sequence of polynomials.
+ */
HermiteInterpolation (const unsigned int p);
/**
- * Return the polynomials with index
- * <tt>0</tt> up to
- * <tt>p+1</tt> in a space of
- * degree up to
- * <tt>p</tt>. Here, <tt>p</tt>
- * has to be at least 3.
+ * Return the polynomials with index <tt>0</tt> up to <tt>p+1</tt> in a
+ * space of degree up to <tt>p</tt>. Here, <tt>p</tt> has to be at least
+ * 3.
*/
static std::vector<Polynomial<double> >
generate_complete_basis (const unsigned int p);
DEAL_II_NAMESPACE_OPEN
/**
- * Representation of the space of polynomials of degree at most n in
- * higher dimensions.
+ * Representation of the space of polynomials of degree at most n in higher
+ * dimensions.
*
- * Given a vector of <i>n</i> one-dimensional polynomials
- * <i>P<sub>0</sub></i> to <i>P<sub>n</sub></i>, where
- * <i>P<sub>i</sub></i> has degree <i>i</i>, this class generates all
- * dim-dimensional polynomials of the form <i>
+ * Given a vector of <i>n</i> one-dimensional polynomials <i>P<sub>0</sub></i>
+ * to <i>P<sub>n</sub></i>, where <i>P<sub>i</sub></i> has degree <i>i</i>,
+ * this class generates all dim-dimensional polynomials of the form <i>
* P<sub>ijk</sub>(x,y,z) =
- * P<sub>i</sub>(x)P<sub>j</sub>(y)P<sub>k</sub>(z)</i>, where the sum
- * of <i>i</i>, <i>j</i> and <i>k</i> is less than or equal <i>n</i>.
+ * P<sub>i</sub>(x)P<sub>j</sub>(y)P<sub>k</sub>(z)</i>, where the sum of
+ * <i>i</i>, <i>j</i> and <i>k</i> is less than or equal <i>n</i>.
*
- * The output_indices() function prints the ordering of the
- * polynomials, i.e. for each dim-dimensional polynomial in the
- * polynomial space it gives the indices i,j,k of the one-dimensional
- * polynomials in x,y and z direction. The ordering of the
- * dim-dimensional polynomials can be changed by using the
+ * The output_indices() function prints the ordering of the polynomials, i.e.
+ * for each dim-dimensional polynomial in the polynomial space it gives the
+ * indices i,j,k of the one-dimensional polynomials in x,y and z direction.
+ * The ordering of the dim-dimensional polynomials can be changed by using the
* set_numbering() function.
*
- * The standard ordering of polynomials is that indices for the first
- * space dimension vary fastest and the last space dimension is
- * slowest. In particular, if we take for simplicity the vector of
- * monomials <i>x<sup>0</sup>, x<sup>1</sup>, x<sup>2</sup>,...,
- * x<sup>n</sup></i>, we get
+ * The standard ordering of polynomials is that indices for the first space
+ * dimension vary fastest and the last space dimension is slowest. In
+ * particular, if we take for simplicity the vector of monomials
+ * <i>x<sup>0</sup>, x<sup>1</sup>, x<sup>2</sup>,..., x<sup>n</sup></i>, we
+ * get
*
- * <dl>
- * <dt> 1D <dd> <i> x<sup>0</sup>, x<sup>1</sup>,...,x<sup>n</sup></i>
+ * <dl> <dt> 1D <dd> <i> x<sup>0</sup>, x<sup>1</sup>,...,x<sup>n</sup></i>
* <dt> 2D: <dd> <i> x<sup>0</sup>y<sup>0</sup>,
- * x<sup>1</sup>y<sup>0</sup>,...,
- * x<sup>n</sup>y<sup>0</sup>,<br>
- * x<sup>0</sup>y<sup>1</sup>,
- * x<sup>1</sup>y<sup>1</sup>,...,
- * x<sup>n-1</sup>y<sup>1</sup>,<br>
- * x<sup>0</sup>y<sup>2</sup>,...
- * x<sup>n-2</sup>y<sup>2</sup>,<br>...<br>
- * x<sup>0</sup>y<sup>n-1</sup>,
- * x<sup>1</sup>y<sup>n-1</sup>,<br>
- * x<sup>0</sup>y<sup>n</sup>
- * </i>
- * <dt> 3D: <dd> <i> x<sup>0</sup>y<sup>0</sup>z<sup>0</sup>,...,
- * x<sup>n</sup>y<sup>0</sup>z<sup>0</sup>,<br>
- * x<sup>0</sup>y<sup>1</sup>z<sup>0</sup>,...,
- * x<sup>n-1</sup>y<sup>1</sup>z<sup>0</sup>,<br>...<br>
- * x<sup>0</sup>y<sup>n</sup>z<sup>0</sup>,<br>
- * x<sup>0</sup>y<sup>0</sup>z<sup>1</sup>,...
- * x<sup>n-1</sup>y<sup>0</sup>z<sup>1</sup>,<br>...<br>
- * x<sup>0</sup>y<sup>n-1</sup>z<sup>1</sup>,<br>
- * x<sup>0</sup>y<sup>0</sup>z<sup>2</sup>,...
- * x<sup>n-2</sup>y<sup>0</sup>z<sup>2</sup>,<br>...<br>
- * x<sup>0</sup>y<sup>0</sup>z<sup>n</sup>
- * </i>
- * </dl>
+ * x<sup>1</sup>y<sup>0</sup>,...,
+ * x<sup>n</sup>y<sup>0</sup>,<br>
+ * x<sup>0</sup>y<sup>1</sup>, x<sup>1</sup>y<sup>1</sup>,...,
+ * x<sup>n-1</sup>y<sup>1</sup>,<br>
+ * x<sup>0</sup>y<sup>2</sup>,...
+ * x<sup>n-2</sup>y<sup>2</sup>,<br>...<br>
+ * x<sup>0</sup>y<sup>n-1</sup>,
+ * x<sup>1</sup>y<sup>n-1</sup>,<br>
+ * x<sup>0</sup>y<sup>n</sup> </i> <dt> 3D: <dd> <i>
+ * x<sup>0</sup>y<sup>0</sup>z<sup>0</sup>,...,
+ * x<sup>n</sup>y<sup>0</sup>z<sup>0</sup>,<br>
+ * x<sup>0</sup>y<sup>1</sup>z<sup>0</sup>,...,
+ * x<sup>n-1</sup>y<sup>1</sup>z<sup>0</sup>,<br>...<br>
+ * x<sup>0</sup>y<sup>n</sup>z<sup>0</sup>,<br>
+ * x<sup>0</sup>y<sup>0</sup>z<sup>1</sup>,...
+ * x<sup>n-1</sup>y<sup>0</sup>z<sup>1</sup>,<br>...<br>
+ * x<sup>0</sup>y<sup>n-1</sup>z<sup>1</sup>,<br>
+ * x<sup>0</sup>y<sup>0</sup>z<sup>2</sup>,...
+ * x<sup>n-2</sup>y<sup>0</sup>z<sup>2</sup>,<br>...<br>
+ * x<sup>0</sup>y<sup>0</sup>z<sup>n</sup> </i> </dl>
*
* @ingroup Polynomials
- * @author Guido Kanschat, Wolfgang Bangerth, Ralf Hartmann 2002, 2003, 2004, 2005
+ * @author Guido Kanschat, Wolfgang Bangerth, Ralf Hartmann 2002, 2003, 2004,
+ * 2005
*/
template <int dim>
class PolynomialSpace
{
public:
/**
- * Access to the dimension of
- * this object, for checking and
- * automatic setting of dimension
- * in other classes.
+ * Access to the dimension of this object, for checking and automatic
+ * setting of dimension in other classes.
*/
static const unsigned int dimension = dim;
/**
- * Constructor. <tt>pols</tt> is a
- * vector of pointers to
- * one-dimensional polynomials
- * and will be copied into a
- * private member variable. The static
- * type of the template argument
- * <tt>pols</tt> needs to be
- * convertible to
- * Polynomials::Polynomial@<double@>,
- * i.e. should usually be a
- * derived class of
- * Polynomials::Polynomial@<double@>.
+ * Constructor. <tt>pols</tt> is a vector of pointers to one-dimensional
+ * polynomials and will be copied into a private member variable. The static
+ * type of the template argument <tt>pols</tt> needs to be convertible to
+ * Polynomials::Polynomial@<double@>, i.e. should usually be a derived class
+ * of Polynomials::Polynomial@<double@>.
*/
template <class Pol>
PolynomialSpace (const std::vector<Pol> &pols);
/**
- * Prints the list of the indices
- * to <tt>out</tt>.
+ * Prints the list of the indices to <tt>out</tt>.
*/
template <class STREAM>
void output_indices(STREAM &out) const;
/**
- * Sets the ordering of the
- * polynomials. Requires
- * <tt>renumber.size()==n()</tt>.
- * Stores a copy of
- * <tt>renumber</tt>.
+ * Sets the ordering of the polynomials. Requires
+ * <tt>renumber.size()==n()</tt>. Stores a copy of <tt>renumber</tt>.
*/
void set_numbering(const std::vector<unsigned int> &renumber);
/**
- * Computes the value and the
- * first and second derivatives
- * of each polynomial at
- * <tt>unit_point</tt>.
+ * Computes the value and the first and second derivatives of each
+ * polynomial at <tt>unit_point</tt>.
*
- * The size of the vectors must
- * either be equal 0 or equal
- * n(). In the first case,
- * the function will not compute
- * these values, i.e. you
- * indicate what you want to have
- * computed by resizing those
- * vectors which you want filled.
+ * The size of the vectors must either be equal 0 or equal n(). In the first
+ * case, the function will not compute these values, i.e. you indicate what
+ * you want to have computed by resizing those vectors which you want
+ * filled.
*
- * If you need values or
- * derivatives of all polynomials
- * then use this function, rather
- * than using any of the
- * compute_value(),
- * compute_grad() or
- * compute_grad_grad()
- * functions, see below, in a
- * loop over all polynomials.
+ * If you need values or derivatives of all polynomials then use this
+ * function, rather than using any of the compute_value(), compute_grad() or
+ * compute_grad_grad() functions, see below, in a loop over all polynomials.
*/
void compute (const Point<dim> &unit_point,
std::vector<double> &values,
std::vector<Tensor<2,dim> > &grad_grads) const;
/**
- * Computes the value of the
- * <tt>i</tt>th polynomial at
- * <tt>unit_point</tt>.
+ * Computes the value of the <tt>i</tt>th polynomial at <tt>unit_point</tt>.
*
* Consider using compute() instead.
*/
const Point<dim> &p) const;
/**
- * Computes the gradient of the
- * <tt>i</tt>th polynomial at
+ * Computes the gradient of the <tt>i</tt>th polynomial at
* <tt>unit_point</tt>.
*
* Consider using compute() instead.
const Point<dim> &p) const;
/**
- * Computes the second derivative
- * (grad_grad) of the <tt>i</tt>th
- * polynomial at
- * <tt>unit_point</tt>.
+ * Computes the second derivative (grad_grad) of the <tt>i</tt>th polynomial
+ * at <tt>unit_point</tt>.
*
* Consider using compute() instead.
*/
const Point<dim> &p) const;
/**
- * Return the number of
- * polynomials spanning the space
- * represented by this
- * class. Here, if <tt>N</tt> is the
- * number of one-dimensional
- * polynomials given, then the
- * result of this function is
- * <i>N</i> in 1d, <i>N(N+1)/2</i> in
- * 2d, and <i>N(N+1)(N+2)/6</i> in
- * 3d.
+ * Return the number of polynomials spanning the space represented by this
+ * class. Here, if <tt>N</tt> is the number of one-dimensional polynomials
+ * given, then the result of this function is <i>N</i> in 1d,
+ * <i>N(N+1)/2</i> in 2d, and <i>N(N+1)(N+2)/6</i> in 3d.
*/
unsigned int n () const;
/**
- * Degree of the space. This is
- * by definition the number of
- * polynomials given to the
- * constructor, NOT the maximal
- * degree of a polynomial in this
- * vector. The latter value is
- * never checked and therefore
- * left to the application.
+ * Degree of the space. This is by definition the number of polynomials
+ * given to the constructor, NOT the maximal degree of a polynomial in this
+ * vector. The latter value is never checked and therefore left to the
+ * application.
*/
unsigned int degree () const;
/**
- * Static function used in the
- * constructor to compute the
- * number of polynomials.
+ * Static function used in the constructor to compute the number of
+ * polynomials.
*/
static unsigned int compute_n_pols (const unsigned int n);
protected:
/**
- * Compute numbers in x, y and z
- * direction. Given an index
- * <tt>n</tt> in the d-dimensional
- * polynomial space, compute the
- * indices i,j,k such that
+ * Compute numbers in x, y and z direction. Given an index <tt>n</tt> in the
+ * d-dimensional polynomial space, compute the indices i,j,k such that
* <i>p<sub>n</sub>(x,y,z) =
* p<sub>i</sub>(x)p<sub>j</sub>(y)p<sub>k</sub>(z)</i>.
*/
private:
/**
- * Copy of the vector <tt>pols</tt> of
- * polynomials given to the
- * constructor.
+ * Copy of the vector <tt>pols</tt> of polynomials given to the constructor.
*/
const std::vector<Polynomials::Polynomial<double> > polynomials;
/**
- * Store the precomputed value
- * which the <tt>n()</tt> function
- * returns.
+ * Store the precomputed value which the <tt>n()</tt> function returns.
*/
const unsigned int n_pols;
/**
- * Index map for reordering the
- * polynomials.
+ * Index map for reordering the polynomials.
*/
std::vector<unsigned int> index_map;
/**
- * Index map for reordering the
- * polynomials.
+ * Index map for reordering the polynomials.
*/
std::vector<unsigned int> index_map_inverse;
};
DEAL_II_NAMESPACE_OPEN
/**
- * This class implements the <i>H<sup>div</sup></i>-conforming,
- * vector-valued Arnold-Boffi-Falk polynomials as described in the
- * article by Arnold-Boffi-Falk:
- * Quadrilateral H(div) finite elements, SIAM J. Numer. Anal.
- * Vol.42, No.6, pp.2429-2451
+ * This class implements the <i>H<sup>div</sup></i>-conforming, vector-valued
+ * Arnold-Boffi-Falk polynomials as described in the article by Arnold-Boffi-
+ * Falk: Quadrilateral H(div) finite elements, SIAM J. Numer. Anal. Vol.42,
+ * No.6, pp.2429-2451
*
*
- * The ABF polynomials are constructed such that the
- * divergence is in the tensor product polynomial space
- * <i>Q<sub>k</sub></i>. Therefore, the polynomial order of each
- * component must be two orders higher in the corresponding direction,
- * yielding the polynomial spaces <i>(Q<sub>k+2,k</sub>,
- * Q<sub>k,k+2</sub>)</i> and <i>(Q<sub>k+2,k,k</sub>,
+ * The ABF polynomials are constructed such that the divergence is in the
+ * tensor product polynomial space <i>Q<sub>k</sub></i>. Therefore, the
+ * polynomial order of each component must be two orders higher in the
+ * corresponding direction, yielding the polynomial spaces
+ * <i>(Q<sub>k+2,k</sub>, Q<sub>k,k+2</sub>)</i> and <i>(Q<sub>k+2,k,k</sub>,
* Q<sub>k,k+2,k</sub>, Q<sub>k,k,k+2</sub>)</i> in 2D and 3D, resp.
*
* @ingroup Polynomials
{
public:
/**
- * Constructor. Creates all basis
- * functions for Raviart-Thomas polynomials
+ * Constructor. Creates all basis functions for Raviart-Thomas polynomials
* of given degree.
*
- * @arg k: the degree of the
- * Raviart-Thomas-space, which is the degree
- * of the largest tensor product
- * polynomial space
- * <i>Q<sub>k</sub></i> contained.
+ * @arg k: the degree of the Raviart-Thomas-space, which is the degree of
+ * the largest tensor product polynomial space <i>Q<sub>k</sub></i>
+ * contained.
*/
PolynomialsABF (const unsigned int k);
~PolynomialsABF ();
/**
- * Computes the value and the
- * first and second derivatives
- * of each Raviart-Thomas
- * polynomial at @p unit_point.
+ * Computes the value and the first and second derivatives of each Raviart-
+ * Thomas polynomial at @p unit_point.
*
- * The size of the vectors must
- * either be zero or equal
- * <tt>n()</tt>. In the
- * first case, the function will
- * not compute these values.
+ * The size of the vectors must either be zero or equal <tt>n()</tt>. In
+ * the first case, the function will not compute these values.
*
- * If you need values or
- * derivatives of all tensor
- * product polynomials then use
- * this function, rather than
- * using any of the
- * <tt>compute_value</tt>,
- * <tt>compute_grad</tt> or
- * <tt>compute_grad_grad</tt>
- * functions, see below, in a
- * loop over all tensor product
- * polynomials.
+ * If you need values or derivatives of all tensor product polynomials then
+ * use this function, rather than using any of the <tt>compute_value</tt>,
+ * <tt>compute_grad</tt> or <tt>compute_grad_grad</tt> functions, see below,
+ * in a loop over all tensor product polynomials.
*/
void compute (const Point<dim> &unit_point,
std::vector<Tensor<1,dim> > &values,
unsigned int n () const;
/**
- * Returns the degree of the ABF
- * space, which is two less than
- * the highest polynomial degree.
+ * Returns the degree of the ABF space, which is two less than the highest
+ * polynomial degree.
*/
unsigned int degree () const;
/**
- * Return the name of the space,
- * which is <tt>ABF</tt>.
+ * Return the name of the space, which is <tt>ABF</tt>.
*/
std::string name () const;
/**
- * Return the number of
- * polynomials in the space
- * <TT>RT(degree)</tt> without
- * requiring to build an object
- * of PolynomialsABF. This is
- * required by the FiniteElement
- * classes.
+ * Return the number of polynomials in the space <TT>RT(degree)</tt> without
+ * requiring to build an object of PolynomialsABF. This is required by the
+ * FiniteElement classes.
*/
static unsigned int compute_n_pols(unsigned int degree);
private:
/**
- * The degree of this object as
- * given to the constructor.
+ * The degree of this object as given to the constructor.
*/
const unsigned int my_degree;
/**
- * An object representing the
- * polynomial space for a single
- * component. We can re-use it by
- * rotating the coordinates of
- * the evaluation point.
+ * An object representing the polynomial space for a single component. We
+ * can re-use it by rotating the coordinates of the evaluation point.
*/
AnisotropicPolynomials<dim> *polynomial_space;
/**
- * Number of Raviart-Thomas
- * polynomials.
+ * Number of Raviart-Thomas polynomials.
*/
unsigned int n_pols;
/**
- * A mutex that guards the
- * following scratch arrays.
+ * A mutex that guards the following scratch arrays.
*/
mutable Threads::Mutex mutex;
/**
* The cubic polynomial space for the Adini element
*
- * This space consists of the cubic space <i>P<sub>3</sub></i>
- * augmented by the functions <i>xy<sup>3</sup></i> and
- * <i>x<sup>3</sup>y</i>.
+ * This space consists of the cubic space <i>P<sub>3</sub></i> augmented by
+ * the functions <i>xy<sup>3</sup></i> and <i>x<sup>3</sup>y</i>.
*
- * The basis of the space is chosen to match the node functionals of
- * the Adini element.
+ * The basis of the space is chosen to match the node functionals of the Adini
+ * element.
*
* @todo This polynomial space is implemented in 2D only.
*
{
public:
/**
- * Constructor for
- * the polynomials of
- * the described space
+ * Constructor for the polynomials of the described space
*/
PolynomialsAdini ();
/**
- * Computes the value and the
- * first and second derivatives
- * of each polynomial at
- * <tt>unit_point</tt>.
+ * Computes the value and the first and second derivatives of each
+ * polynomial at <tt>unit_point</tt>.
*
- * The size of the vectors must
- * either be equal 0 or equal
- * n(). In the first case,
- * the function will not compute
- * these values, i.e. you
- * indicate what you want to have
- * computed by resizing those
- * vectors which you want filled.
+ * The size of the vectors must either be equal 0 or equal n(). In the first
+ * case, the function will not compute these values, i.e. you indicate what
+ * you want to have computed by resizing those vectors which you want
+ * filled.
*
- * If you need values or
- * derivatives of all polynomials
- * then use this function, rather
- * than using any of the
- * compute_value(),
- * compute_grad() or
- * compute_grad_grad()
- * functions, see below, in a
- * loop over all polynomials.
+ * If you need values or derivatives of all polynomials then use this
+ * function, rather than using any of the compute_value(), compute_grad() or
+ * compute_grad_grad() functions, see below, in a loop over all polynomials.
*/
void compute (const Point<2> &unit_point,
std::vector< Tensor<2,2> > &grad_grads) const;
/**
- * Computes the value of the
- * <tt>i</tt>th polynomial at
- * <tt>unit_point</tt>.
+ * Computes the value of the <tt>i</tt>th polynomial at <tt>unit_point</tt>.
*
* Consider using compute() instead.
*/
const Point<2> &p) const;
/**
- * Computes the gradient of the
- * <tt>i</tt>th polynomial at
+ * Computes the gradient of the <tt>i</tt>th polynomial at
* <tt>unit_point</tt>.
*
* Consider using compute() instead.
Tensor<1,2> compute_grad (const unsigned int i,
const Point<2> &p) const;
/**
- * Computes the second derivative
- * (grad_grad) of the <tt>i</tt>th
- * polynomial at
- * <tt>unit_point</tt>.
+ * Computes the second derivative (grad_grad) of the <tt>i</tt>th polynomial
+ * at <tt>unit_point</tt>.
*
* Consider using compute() instead.
*/
private:
/**
- * Store the coefficients of the
- * polynominals in the order
+ * Store the coefficients of the polynominals in the order
* $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
*/
Table<2, double> coef;
/**
- * Store the coefficients of the x-derivative
- * of the polynominals in the order
- * $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
+ * Store the coefficients of the x-derivative of the polynominals in the
+ * order $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
*/
Table<2, double> dx;
/**
- * Store the coefficients of the y-derivative
- * of the polynominals in the order
- * $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
+ * Store the coefficients of the y-derivative of the polynominals in the
+ * order $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
*/
Table<2, double> dy;
/**
- * Store the coefficients of the second x-derivative
- * of the polynominals in the order
- * $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
+ * Store the coefficients of the second x-derivative of the polynominals in
+ * the order $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
*/
Table<2, double> dxx;
/**
- * Store the coefficients of the second y-derivative
- * of the polynominals in the order
- * $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
+ * Store the coefficients of the second y-derivative of the polynominals in
+ * the order $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
*/
Table<2, double> dyy;
/**
- * Store the coefficients of the second mixed derivative
- * of the polynominals in the order
- * $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
+ * Store the coefficients of the second mixed derivative of the polynominals
+ * in the order $1,x,y,x^2,y^2,xy,x^3,y^3,xy^2,x^2y,x^3y,xy^3$
*/
Table<2, double> dxy;
DEAL_II_NAMESPACE_OPEN
/**
- * This class implements the <i>H<sup>div</sup></i>-conforming,
- * vector-valued Brezzi-Douglas-Marini polynomials as described in the
- * book by Brezzi and Fortin.
+ * This class implements the <i>H<sup>div</sup></i>-conforming, vector-valued
+ * Brezzi-Douglas-Marini polynomials as described in the book by Brezzi and
+ * Fortin.
*
- * These polynomial spaces are based on the space
- * <i>P<sub>k</sub></i>, realized by a PolynomialSpace constructed
- * with Legendre polynomials. Since these shape functions are not
- * sufficient, additional functions are added. These are the following
- * vector valued polynomials:
+ * These polynomial spaces are based on the space <i>P<sub>k</sub></i>,
+ * realized by a PolynomialSpace constructed with Legendre polynomials. Since
+ * these shape functions are not sufficient, additional functions are added.
+ * These are the following vector valued polynomials:
*
- * <dl>
- * <dt> In 2D:
- * <dd> The 2D-curl of the functions <i>x<sup>k+1</sup>y</i>
- * and <i>xy<sup>k+1</sup></i>.
- * <dt>In 3D:
- * <dd> For any <i>i=0,...,k</i> the curls of
- * <i>(0,0,xy<sup>i+1</sup>z<sup>k-i</sup>)</i>,
+ * <dl> <dt> In 2D: <dd> The 2D-curl of the functions <i>x<sup>k+1</sup>y</i>
+ * and <i>xy<sup>k+1</sup></i>. <dt>In 3D: <dd> For any <i>i=0,...,k</i> the
+ * curls of <i>(0,0,xy<sup>i+1</sup>z<sup>k-i</sup>)</i>,
* <i>(x<sup>k-i</sup>yz<sup>i+1</sup>,0,0)</i> and
- * <i>(0,x<sup>i+1</sup>y<sup>k-i</sup>z,0)</i>
- * </dl>
+ * <i>(0,x<sup>i+1</sup>y<sup>k-i</sup>z,0)</i> </dl>
*
* @todo Second derivatives in 3D are missing.
*
{
public:
/**
- * Constructor. Creates all basis
- * functions for BDM polynomials
- * of given degree.
+ * Constructor. Creates all basis functions for BDM polynomials of given
+ * degree.
*
- * @arg k: the degree of the
- * BDM-space, which is the degree
- * of the largest complete
- * polynomial space
- * <i>P<sub>k</sub></i> contained
- * in the BDM-space.
+ * @arg k: the degree of the BDM-space, which is the degree of the largest
+ * complete polynomial space <i>P<sub>k</sub></i> contained in the BDM-
+ * space.
*/
PolynomialsBDM (const unsigned int k);
/**
- * Computes the value and the
- * first and second derivatives
- * of each BDM
+ * Computes the value and the first and second derivatives of each BDM
* polynomial at @p unit_point.
*
- * The size of the vectors must
- * either be zero or equal
- * <tt>n()</tt>. In the
- * first case, the function will
- * not compute these values.
+ * The size of the vectors must either be zero or equal <tt>n()</tt>. In
+ * the first case, the function will not compute these values.
*
- * If you need values or
- * derivatives of all tensor
- * product polynomials then use
- * this function, rather than
- * using any of the
- * <tt>compute_value</tt>,
- * <tt>compute_grad</tt> or
- * <tt>compute_grad_grad</tt>
- * functions, see below, in a
- * loop over all tensor product
- * polynomials.
+ * If you need values or derivatives of all tensor product polynomials then
+ * use this function, rather than using any of the <tt>compute_value</tt>,
+ * <tt>compute_grad</tt> or <tt>compute_grad_grad</tt> functions, see below,
+ * in a loop over all tensor product polynomials.
*/
void compute (const Point<dim> &unit_point,
std::vector<Tensor<1,dim> > &values,
unsigned int n () const;
/**
- * Returns the degree of the BDM
- * space, which is one less than
- * the highest polynomial degree.
+ * Returns the degree of the BDM space, which is one less than the highest
+ * polynomial degree.
*/
unsigned int degree () const;
/**
- * Return the name of the space,
- * which is <tt>BDM</tt>.
+ * Return the name of the space, which is <tt>BDM</tt>.
*/
std::string name () const;
/**
- * Return the number of
- * polynomials in the space
- * <TT>BDM(degree)</tt> without
- * requiring to build an object
- * of PolynomialsBDM. This is
- * required by the FiniteElement
- * classes.
+ * Return the number of polynomials in the space <TT>BDM(degree)</tt>
+ * without requiring to build an object of PolynomialsBDM. This is required
+ * by the FiniteElement classes.
*/
static unsigned int compute_n_pols(unsigned int degree);
private:
/**
- * An object representing the
- * polynomial space used
- * here. The constructor fills
- * this with the monomial basis.
+ * An object representing the polynomial space used here. The constructor
+ * fills this with the monomial basis.
*/
const PolynomialSpace<dim> polynomial_space;
/**
- * Storage for monomials. In 2D,
- * this is just the polynomial of
- * order <i>k</i>. In 3D, we
- * need all polynomials from
- * degree zero to <i>k</i>.
+ * Storage for monomials. In 2D, this is just the polynomial of order
+ * <i>k</i>. In 3D, we need all polynomials from degree zero to <i>k</i>.
*/
std::vector<Polynomials::Polynomial<double> > monomials;
/**
- * Number of BDM
- * polynomials.
+ * Number of BDM polynomials.
*/
unsigned int n_pols;
/**
- * A mutex that guards the
- * following scratch arrays.
+ * A mutex that guards the following scratch arrays.
*/
mutable Threads::Mutex mutex;
/**
* This class implements the first family <i>H<sup>curl</sup></i>-conforming,
- * vector-valued polynomials, proposed by J.-C. Nédélec in 1980
- * (Numer. Math. 35).
+ * vector-valued polynomials, proposed by J.-C. Nédélec in 1980 (Numer.
+ * Math. 35).
*
- * The Nédélec polynomials are constructed such that the curl
- * is in the tensor product polynomial space <i>Q<sub>k</sub></i>.
- * Therefore, the polynomial order of each component must be one
- * order higher in the corresponding two directions,
- * yielding the polynomial spaces <i>(Q<sub>k,k+1</sub>,
- * Q<sub>k+1,k</sub>)</i> and <i>(Q<sub>k,k+1,k+1</sub>,
- * Q<sub>k+1,k,k+1</sub>, Q<sub>k+1,k+1,k</sub>)</i> in 2D and 3D, resp.
+ * The Nédélec polynomials are constructed such that the curl is in the
+ * tensor product polynomial space <i>Q<sub>k</sub></i>. Therefore, the
+ * polynomial order of each component must be one order higher in the
+ * corresponding two directions, yielding the polynomial spaces
+ * <i>(Q<sub>k,k+1</sub>, Q<sub>k+1,k</sub>)</i> and
+ * <i>(Q<sub>k,k+1,k+1</sub>, Q<sub>k+1,k,k+1</sub>,
+ * Q<sub>k+1,k+1,k</sub>)</i> in 2D and 3D, resp.
*
* @ingroup Polynomials
* @author Markus Bürg
{
public:
/**
- * Constructor. Creates all basis
- * functions for Nédélec polynomials
- * of given degree.
+ * Constructor. Creates all basis functions for Nédélec polynomials of
+ * given degree.
*
- * @arg k: the degree of the
- * Nédélec space, which is the degree
- * of the largest tensor product
- * polynomial space
- * <i>Q<sub>k</sub></i> contained.
+ * @arg k: the degree of the Nédélec space, which is the degree of the
+ * largest tensor product polynomial space <i>Q<sub>k</sub></i> contained.
*/
PolynomialsNedelec (const unsigned int k);
/**
- * Computes the value and the
- * first and second derivatives
- * of each Nédélec
+ * Computes the value and the first and second derivatives of each Nédélec
* polynomial at @p unit_point.
*
- * The size of the vectors must
- * either be zero or equal
- * <tt>n()</tt>. In the
- * first case, the function will
- * not compute these values.
+ * The size of the vectors must either be zero or equal <tt>n()</tt>. In
+ * the first case, the function will not compute these values.
*
- * If you need values or
- * derivatives of all tensor
- * product polynomials then use
- * this function, rather than
- * using any of the
- * <tt>compute_value</tt>,
- * <tt>compute_grad</tt> or
- * <tt>compute_grad_grad</tt>
- * functions, see below, in a
- * loop over all tensor product
- * polynomials.
+ * If you need values or derivatives of all tensor product polynomials then
+ * use this function, rather than using any of the <tt>compute_value</tt>,
+ * <tt>compute_grad</tt> or <tt>compute_grad_grad</tt> functions, see below,
+ * in a loop over all tensor product polynomials.
*/
void compute (const Point<dim> &unit_point, std::vector<Tensor<1, dim> > &values, std::vector<Tensor<2, dim> > &grads, std::vector<Tensor<3, dim> > &grad_grads) const;
/**
- * Returns the number of Nédélec
- * polynomials.
+ * Returns the number of Nédélec polynomials.
*/
unsigned int n () const;
/**
- * Returns the degree of the Nédélec
- * space, which is one less than
- * the highest polynomial degree.
+ * Returns the degree of the Nédélec space, which is one less than the
+ * highest polynomial degree.
*/
unsigned int degree () const;
/**
- * Return the name of the space,
- * which is <tt>Nedelec</tt>.
+ * Return the name of the space, which is <tt>Nedelec</tt>.
*/
std::string name () const;
/**
- * Return the number of
- * polynomials in the space
- * <TT>N(degree)</tt> without
- * requiring to build an object
- * of PolynomialsNedelec. This is
- * required by the FiniteElement
- * classes.
+ * Return the number of polynomials in the space <TT>N(degree)</tt> without
+ * requiring to build an object of PolynomialsNedelec. This is required by
+ * the FiniteElement classes.
*/
static unsigned int compute_n_pols (unsigned int degree);
private:
/**
- * The degree of this object as
- * given to the constructor.
+ * The degree of this object as given to the constructor.
*/
const unsigned int my_degree;
/**
- * An object representing the
- * polynomial space for a single
- * component. We can re-use it by
- * rotating the coordinates of
- * the evaluation point.
+ * An object representing the polynomial space for a single component. We
+ * can re-use it by rotating the coordinates of the evaluation point.
*/
const AnisotropicPolynomials<dim> polynomial_space;
const unsigned int n_pols;
/**
- * A static member function that
- * creates the polynomial space
- * we use to initialize the
- * #polynomial_space member
- * variable.
+ * A static member function that creates the polynomial space we use to
+ * initialize the #polynomial_space member variable.
*/
static std::vector<std::vector< Polynomials::Polynomial< double > > > create_polynomials (const unsigned int k);
};
*/
/**
- * This class implements the polynomial space of degree <tt>p</tt>
- * based on the monomials ${1,x,x^2,...}$. I.e. in <tt>d</tt>
- * dimensions it constructs all polynomials of the form $\prod_{i=1}^d
- * x_i^{n_i}$, where $\sum_i n_i\leq p$. The base polynomials are
- * given a specific ordering, e.g. in 2 dimensions:
- * ${1,x,y,xy,x^2,y^2,x^2y,xy^2,x^3,y^3,...}$. The ordering of the
- * monomials in $P_k1$ matches the ordering of the monomials in $P_k2$
- * for $k2>k1$.
+ * This class implements the polynomial space of degree <tt>p</tt> based on
+ * the monomials ${1,x,x^2,...}$. I.e. in <tt>d</tt> dimensions it constructs
+ * all polynomials of the form $\prod_{i=1}^d x_i^{n_i}$, where $\sum_i
+ * n_i\leq p$. The base polynomials are given a specific ordering, e.g. in 2
+ * dimensions: ${1,x,y,xy,x^2,y^2,x^2y,xy^2,x^3,y^3,...}$. The ordering of the
+ * monomials in $P_k1$ matches the ordering of the monomials in $P_k2$ for
+ * $k2>k1$.
*
* @author Ralf Hartmann, 2004
*/
{
public:
/**
- * Access to the dimension of
- * this object, for checking and
- * automatic setting of dimension
- * in other classes.
+ * Access to the dimension of this object, for checking and automatic
+ * setting of dimension in other classes.
*/
static const unsigned int dimension = dim;
/**
- * Constructor. Creates all basis
- * functions of $P_p$.
- * @arg p: the degree of the
- * polynomial space
+ * Constructor. Creates all basis functions of $P_p$. @arg p: the degree of
+ * the polynomial space
*/
PolynomialsP (const unsigned int p);
/**
- * Returns the degree <tt>p</tt>
- * of the polynomial space
- * <tt>P_p</tt>.
+ * Returns the degree <tt>p</tt> of the polynomial space <tt>P_p</tt>.
*
- * Note, that this number is
- * <tt>PolynomialSpace::degree()-1</tt>,
- * compare definition in
- * PolynomialSpace.
+ * Note, that this number is <tt>PolynomialSpace::degree()-1</tt>, compare
+ * definition in PolynomialSpace.
*/
unsigned int degree() const;
/**
- * For the <tt>n</tt>th
- * polynomial $p_n(x,y,z)=x^i y^j
- * z^k$ this function gives the
- * degrees i,j,k in the x,y,z
- * directions.
+ * For the <tt>n</tt>th polynomial $p_n(x,y,z)=x^i y^j z^k$ this function
+ * gives the degrees i,j,k in the x,y,z directions.
*/
void directional_degrees(unsigned int n,
unsigned int (°rees)[dim]) const;
void create_polynomial_ordering(std::vector<unsigned int> &index_map) const;
/**
- * Degree <tt>p</tt> of the
- * polynomial space $P_p$,
- * i.e. the number <tt>p</tt>
- * which was given to the
- * constructor.
+ * Degree <tt>p</tt> of the polynomial space $P_p$, i.e. the number
+ * <tt>p</tt> which was given to the constructor.
*/
const unsigned int p;
};
unsigned int n_intervals;
/**
- * Stores the index of the current polynomial in the range of
- * intervals.
+ * Stores the index of the current polynomial in the range of intervals.
*/
unsigned int interval;
DEAL_II_NAMESPACE_OPEN
/**
- * This class implements the <i>H<sup>div</sup></i>-conforming,
- * vector-valued Raviart-Thomas polynomials as described in the
- * book by Brezzi and Fortin.
+ * This class implements the <i>H<sup>div</sup></i>-conforming, vector-valued
+ * Raviart-Thomas polynomials as described in the book by Brezzi and Fortin.
*
- * The Raviart-Thomas polynomials are constructed such that the
- * divergence is in the tensor product polynomial space
- * <i>Q<sub>k</sub></i>. Therefore, the polynomial order of each
- * component must be one order higher in the corresponding direction,
- * yielding the polynomial spaces <i>(Q<sub>k+1,k</sub>,
- * Q<sub>k,k+1</sub>)</i> and <i>(Q<sub>k+1,k,k</sub>,
+ * The Raviart-Thomas polynomials are constructed such that the divergence is
+ * in the tensor product polynomial space <i>Q<sub>k</sub></i>. Therefore, the
+ * polynomial order of each component must be one order higher in the
+ * corresponding direction, yielding the polynomial spaces
+ * <i>(Q<sub>k+1,k</sub>, Q<sub>k,k+1</sub>)</i> and <i>(Q<sub>k+1,k,k</sub>,
* Q<sub>k,k+1,k</sub>, Q<sub>k,k,k+1</sub>)</i> in 2D and 3D, resp.
*
* @ingroup Polynomials
{
public:
/**
- * Constructor. Creates all basis
- * functions for Raviart-Thomas polynomials
+ * Constructor. Creates all basis functions for Raviart-Thomas polynomials
* of given degree.
*
- * @arg k: the degree of the
- * Raviart-Thomas-space, which is the degree
- * of the largest tensor product
- * polynomial space
- * <i>Q<sub>k</sub></i> contains.
+ * @arg k: the degree of the Raviart-Thomas-space, which is the degree of
+ * the largest tensor product polynomial space <i>Q<sub>k</sub></i>
+ * contains.
*/
PolynomialsRaviartThomas (const unsigned int k);
/**
- * Computes the value and the
- * first and second derivatives
- * of each Raviart-Thomas
- * polynomial at @p unit_point.
+ * Computes the value and the first and second derivatives of each Raviart-
+ * Thomas polynomial at @p unit_point.
*
- * The size of the vectors must
- * either be zero or equal
- * <tt>n()</tt>. In the
- * first case, the function will
- * not compute these values.
+ * The size of the vectors must either be zero or equal <tt>n()</tt>. In
+ * the first case, the function will not compute these values.
*
- * If you need values or
- * derivatives of all tensor
- * product polynomials then use
- * this function, rather than
- * using any of the
- * <tt>compute_value</tt>,
- * <tt>compute_grad</tt> or
- * <tt>compute_grad_grad</tt>
- * functions, see below, in a
- * loop over all tensor product
- * polynomials.
+ * If you need values or derivatives of all tensor product polynomials then
+ * use this function, rather than using any of the <tt>compute_value</tt>,
+ * <tt>compute_grad</tt> or <tt>compute_grad_grad</tt> functions, see below,
+ * in a loop over all tensor product polynomials.
*/
void compute (const Point<dim> &unit_point,
std::vector<Tensor<1,dim> > &values,
unsigned int n () const;
/**
- * Returns the degree of the Raviart-Thomas
- * space, which is one less than
+ * Returns the degree of the Raviart-Thomas space, which is one less than
* the highest polynomial degree.
*/
unsigned int degree () const;
/**
- * Return the name of the space,
- * which is <tt>RaviartThomas</tt>.
+ * Return the name of the space, which is <tt>RaviartThomas</tt>.
*/
std::string name () const;
/**
- * Return the number of
- * polynomials in the space
- * <TT>RT(degree)</tt> without
- * requiring to build an object
- * of PolynomialsRaviartThomas. This is
- * required by the FiniteElement
- * classes.
+ * Return the number of polynomials in the space <TT>RT(degree)</tt> without
+ * requiring to build an object of PolynomialsRaviartThomas. This is
+ * required by the FiniteElement classes.
*/
static unsigned int compute_n_pols(unsigned int degree);
private:
/**
- * The degree of this object as
- * given to the constructor.
+ * The degree of this object as given to the constructor.
*/
const unsigned int my_degree;
/**
- * An object representing the
- * polynomial space for a single
- * component. We can re-use it by
- * rotating the coordinates of
- * the evaluation point.
+ * An object representing the polynomial space for a single component. We
+ * can re-use it by rotating the coordinates of the evaluation point.
*/
const AnisotropicPolynomials<dim> polynomial_space;
/**
- * Number of Raviart-Thomas
- * polynomials.
+ * Number of Raviart-Thomas polynomials.
*/
const unsigned int n_pols;
/**
- * A static member function that
- * creates the polynomial space
- * we use to initialize the
- * #polynomial_space member
- * variable.
+ * A static member function that creates the polynomial space we use to
+ * initialize the #polynomial_space member variable.
*/
static
std::vector<std::vector< Polynomials::Polynomial< double > > >
/**
- * This class is a helper class to facilitate the usage of quadrature formulae
- * on faces or subfaces of cells. It computes the locations of quadrature
- * points on the unit cell from a quadrature object for a manifold of
- * one dimension less than that of the cell and the number of the face.
- * For example, giving the Simpson rule in one dimension and using the
- * project_to_face() function with face number 1, the returned points will
- * be (1,0), (1,0.5) and (1,1). Note that faces have an orientation,
- * so when projecting to face 3, you will get (0,0), (0,0.5) and (0,1),
- * which is in clockwise sense, while for face 1 the points were in
- * counterclockwise sense.
+ * This class is a helper class to facilitate the usage of quadrature formulae
+ * on faces or subfaces of cells. It computes the locations of quadrature
+ * points on the unit cell from a quadrature object for a manifold of one
+ * dimension less than that of the cell and the number of the face. For
+ * example, giving the Simpson rule in one dimension and using the
+ * project_to_face() function with face number 1, the returned points will be
+ * (1,0), (1,0.5) and (1,1). Note that faces have an orientation, so when
+ * projecting to face 3, you will get (0,0), (0,0.5) and (0,1), which is in
+ * clockwise sense, while for face 1 the points were in counterclockwise
+ * sense.
*
- * For the projection to subfaces (i.e. to the children of a face of the
- * unit cell), the same applies as above. Note the order in which the
- * children of a face are numbered, which in two dimensions coincides
- * with the orientation of the face.
+ * For the projection to subfaces (i.e. to the children of a face of the unit
+ * cell), the same applies as above. Note the order in which the children of a
+ * face are numbered, which in two dimensions coincides with the orientation
+ * of the face.
*
- * The second set of functions generates a quadrature formula by
- * projecting a given quadrature rule on <b>all</b> faces and
- * subfaces. This is used in the FEFaceValues and
- * FESubfaceValues classes. Since we now have the quadrature
- * points of all faces and subfaces in one array, we need to have a
- * way to find the starting index of the points and weights
- * corresponding to one face or subface within this array. This is
- * done through the DataSetDescriptor member class.
+ * The second set of functions generates a quadrature formula by projecting a
+ * given quadrature rule on <b>all</b> faces and subfaces. This is used in the
+ * FEFaceValues and FESubfaceValues classes. Since we now have the quadrature
+ * points of all faces and subfaces in one array, we need to have a way to
+ * find the starting index of the points and weights corresponding to one face
+ * or subface within this array. This is done through the DataSetDescriptor
+ * member class.
*
- * The different functions are grouped into a common class to avoid
- * putting them into global namespace. However, since they have no
- * local data, all functions are declared <tt>static</tt> and can be
- * called without creating an object of this class.
+ * The different functions are grouped into a common class to avoid putting
+ * them into global namespace. However, since they have no local data, all
+ * functions are declared <tt>static</tt> and can be called without creating
+ * an object of this class.
*
- * For the 3d case, you should note that the orientation of faces is
- * even more intricate than for two dimensions. Quadrature formulae
- * are projected upon the faces in their standard orientation, not to
- * the inside or outside of the hexahedron. To make things more
- * complicated, in 3d we allow faces in two orientations (which can
- * be identified using <tt>cell->face_orientation(face)</tt>), so we
- * have to project quadrature formula onto faces and subfaces in two
- * orientations. (Refer to the documentation of the Triangulation
- * class for a description of the orientation of the different faces,
- * as well as to
- * @ref GlossFaceOrientation "the glossary entry on face orientation"
- * for more information on this.) The
- * DataSetDescriptor member class is used to identify where each
- * dataset starts.
+ * For the 3d case, you should note that the orientation of faces is even more
+ * intricate than for two dimensions. Quadrature formulae are projected upon
+ * the faces in their standard orientation, not to the inside or outside of
+ * the hexahedron. To make things more complicated, in 3d we allow faces in
+ * two orientations (which can be identified using
+ * <tt>cell->face_orientation(face)</tt>), so we have to project quadrature
+ * formula onto faces and subfaces in two orientations. (Refer to the
+ * documentation of the Triangulation class for a description of the
+ * orientation of the different faces, as well as to @ref GlossFaceOrientation
+ * "the glossary entry on face orientation" for more information on this.) The
+ * DataSetDescriptor member class is used to identify where each dataset
+ * starts.
*
- * @author Wolfgang Bangerth, Guido Kanschat, 1998, 1999, 2003, 2005
+ * @author Wolfgang Bangerth, Guido Kanschat, 1998, 1999, 2003, 2005
*/
template <int dim>
class QProjector
{
public:
/**
- * Define a typedef for a
- * quadrature that acts on an
- * object of one dimension
- * less. For cells, this would
- * then be a face quadrature.
+ * Define a typedef for a quadrature that acts on an object of one dimension
+ * less. For cells, this would then be a face quadrature.
*/
typedef Quadrature<dim-1> SubQuadrature;
/**
- * Compute the quadrature points
- * on the cell if the given
- * quadrature formula is used on
- * face <tt>face_no</tt>. For further
- * details, see the general doc
- * for this class.
+ * Compute the quadrature points on the cell if the given quadrature formula
+ * is used on face <tt>face_no</tt>. For further details, see the general
+ * doc for this class.
*/
static void project_to_face (const SubQuadrature &quadrature,
const unsigned int face_no,
std::vector<Point<dim> > &q_points);
/**
- * Compute the cell quadrature
- * formula corresponding to using
- * <tt>quadrature</tt> on face
- * <tt>face_no</tt>. For further
- * details, see the general doc
- * for this class.
+ * Compute the cell quadrature formula corresponding to using
+ * <tt>quadrature</tt> on face <tt>face_no</tt>. For further details, see
+ * the general doc for this class.
*/
static Quadrature<dim>
project_to_face (const SubQuadrature &quadrature,
const unsigned int face_no);
/**
- * Compute the quadrature points on the
- * cell if the given quadrature formula is
- * used on face <tt>face_no</tt>, subface
- * number <tt>subface_no</tt> corresponding
- * to RefineCase::Type
- * <tt>ref_case</tt>. The last argument is
+ * Compute the quadrature points on the cell if the given quadrature formula
+ * is used on face <tt>face_no</tt>, subface number <tt>subface_no</tt>
+ * corresponding to RefineCase::Type <tt>ref_case</tt>. The last argument is
* only used in 3D.
*
- * @note Only the points are
- * transformed. The quadrature
- * weights are the same as those
- * of the original rule.
+ * @note Only the points are transformed. The quadrature weights are the
+ * same as those of the original rule.
*/
static void project_to_subface (const SubQuadrature &quadrature,
const unsigned int face_no,
const RefinementCase<dim-1> &ref_case=RefinementCase<dim-1>::isotropic_refinement);
/**
- * Compute the cell quadrature formula
- * corresponding to using
- * <tt>quadrature</tt> on subface
- * <tt>subface_no</tt> of face
- * <tt>face_no</tt> with
- * RefinementCase<dim-1>
- * <tt>ref_case</tt>. The last argument is
- * only used in 3D.
+ * Compute the cell quadrature formula corresponding to using
+ * <tt>quadrature</tt> on subface <tt>subface_no</tt> of face
+ * <tt>face_no</tt> with RefinementCase<dim-1> <tt>ref_case</tt>. The last
+ * argument is only used in 3D.
*
- * @note Only the points are
- * transformed. The quadrature
- * weights are the same as those
- * of the original rule.
+ * @note Only the points are transformed. The quadrature weights are the
+ * same as those of the original rule.
*/
static Quadrature<dim>
project_to_subface (const SubQuadrature &quadrature,
const RefinementCase<dim-1> &ref_case=RefinementCase<dim-1>::isotropic_refinement);
/**
- * Take a face quadrature formula
- * and generate a cell quadrature
- * formula from it where the
- * quadrature points of the given
- * argument are projected on all
- * faces.
+ * Take a face quadrature formula and generate a cell quadrature formula
+ * from it where the quadrature points of the given argument are projected
+ * on all faces.
*
- * The weights of the new rule
- * are replications of the
- * original weights. Thus, the
- * sum of the weights is not one,
- * but the number of faces, which
- * is the surface of the
- * reference cell.
+ * The weights of the new rule are replications of the original weights.
+ * Thus, the sum of the weights is not one, but the number of faces, which
+ * is the surface of the reference cell.
*
- * This in particular allows us
- * to extract a subset of points
- * corresponding to a single face
- * and use it as a quadrature on
- * this face, as is done in
+ * This in particular allows us to extract a subset of points corresponding
+ * to a single face and use it as a quadrature on this face, as is done in
* FEFaceValues.
*
- * @note In 3D, this function
- * produces eight sets of
- * quadrature points for each
- * face, in order to cope
- * possibly different
- * orientations of the mesh.
+ * @note In 3D, this function produces eight sets of quadrature points for
+ * each face, in order to cope possibly different orientations of the mesh.
*/
static Quadrature<dim>
project_to_all_faces (const SubQuadrature &quadrature);
/**
- * Take a face quadrature formula
- * and generate a cell quadrature
- * formula from it where the
- * quadrature points of the given
- * argument are projected on all
- * subfaces.
+ * Take a face quadrature formula and generate a cell quadrature formula
+ * from it where the quadrature points of the given argument are projected
+ * on all subfaces.
*
- * Like in project_to_all_faces(),
- * the weights of the new rule
- * sum up to the number of faces
- * (not subfaces), which
- * is the surface of the
- * reference cell.
+ * Like in project_to_all_faces(), the weights of the new rule sum up to the
+ * number of faces (not subfaces), which is the surface of the reference
+ * cell.
*
- * This in particular allows us
- * to extract a subset of points
- * corresponding to a single subface
- * and use it as a quadrature on
- * this face, as is done in
- * FESubfaceValues.
+ * This in particular allows us to extract a subset of points corresponding
+ * to a single subface and use it as a quadrature on this face, as is done
+ * in FESubfaceValues.
*/
static Quadrature<dim>
project_to_all_subfaces (const SubQuadrature &quadrature);
/**
- * Project a given quadrature
- * formula to a child of a
- * cell. You may want to use this
- * function in case you want to
- * extend an integral only over
- * the area which a potential
- * child would occupy. The child
- * numbering is the same as the
- * children would be numbered
- * upon refinement of the cell.
+ * Project a given quadrature formula to a child of a cell. You may want to
+ * use this function in case you want to extend an integral only over the
+ * area which a potential child would occupy. The child numbering is the
+ * same as the children would be numbered upon refinement of the cell.
*
- * As integration using this
- * quadrature formula now only
- * extends over a fraction of the
- * cell, the weights of the
- * resulting object are divided by
+ * As integration using this quadrature formula now only extends over a
+ * fraction of the cell, the weights of the resulting object are divided by
* GeometryInfo<dim>::children_per_cell.
*/
static
const unsigned int child_no);
/**
- * Project a quadrature rule to
- * all children of a
- * cell. Similarly to
- * project_to_all_subfaces(),
- * this function replicates the
- * formula generated by
- * project_to_child() for all
- * children, such that the
- * weights sum up to one, the
- * volume of the total cell
- * again.
+ * Project a quadrature rule to all children of a cell. Similarly to
+ * project_to_all_subfaces(), this function replicates the formula generated
+ * by project_to_child() for all children, such that the weights sum up to
+ * one, the volume of the total cell again.
*
- * The child
- * numbering is the same as the
- * children would be numbered
- * upon refinement of the cell.
+ * The child numbering is the same as the children would be numbered upon
+ * refinement of the cell.
*/
static
Quadrature<dim>
project_to_all_children (const Quadrature<dim> &quadrature);
/**
- * Project the onedimensional
- * rule <tt>quadrature</tt> to
- * the straight line connecting
- * the points <tt>p1</tt> and
- * <tt>p2</tt>.
+ * Project the onedimensional rule <tt>quadrature</tt> to the straight line
+ * connecting the points <tt>p1</tt> and <tt>p2</tt>.
*/
static
Quadrature<dim>
const Point<dim> &p2);
/**
- * Since the
- * project_to_all_faces() and
- * project_to_all_subfaces()
- * functions chain together the
- * quadrature points and weights
- * of all projections of a face
- * quadrature formula to the
- * faces or subfaces of a cell,
- * we need a way to identify
- * where the starting index of
- * the points and weights for a
- * particular face or subface
- * is. This class provides this:
- * there are static member
- * functions that generate
- * objects of this type, given
- * face or subface indices, and
- * you can then use the generated
- * object in place of an integer
- * that denotes the offset of a
- * given dataset.
+ * Since the project_to_all_faces() and project_to_all_subfaces() functions
+ * chain together the quadrature points and weights of all projections of a
+ * face quadrature formula to the faces or subfaces of a cell, we need a way
+ * to identify where the starting index of the points and weights for a
+ * particular face or subface is. This class provides this: there are static
+ * member functions that generate objects of this type, given face or
+ * subface indices, and you can then use the generated object in place of an
+ * integer that denotes the offset of a given dataset.
*
* @author Wolfgang Bangerth, 2003
*/
{
public:
/**
- * Default constructor. This
- * doesn't do much except
- * generating an invalid
- * index, since you didn't
- * give a valid descriptor of
- * the cell, face, or subface
- * you wanted.
+ * Default constructor. This doesn't do much except generating an invalid
+ * index, since you didn't give a valid descriptor of the cell, face, or
+ * subface you wanted.
*/
DataSetDescriptor ();
/**
- * Static function to
- * generate the offset of a
- * cell. Since we only have
- * one cell per quadrature
- * object, this offset is of
- * course zero, but we carry
- * this function around for
- * consistency with the other
- * static functions.
+ * Static function to generate the offset of a cell. Since we only have
+ * one cell per quadrature object, this offset is of course zero, but we
+ * carry this function around for consistency with the other static
+ * functions.
*/
static DataSetDescriptor cell ();
/**
- * Static function to generate an
- * offset object for a given face of a
- * cell with the given face
- * orientation, flip and rotation. This
- * function of course is only allowed
- * if <tt>dim>=2</tt>, and the face
- * orientation, flip and rotation are
- * ignored if the space dimension
- * equals 2.
+ * Static function to generate an offset object for a given face of a cell
+ * with the given face orientation, flip and rotation. This function of
+ * course is only allowed if <tt>dim>=2</tt>, and the face orientation,
+ * flip and rotation are ignored if the space dimension equals 2.
*
- * The last argument denotes
- * the number of quadrature
- * points the
- * lower-dimensional face
- * quadrature formula (the
- * one that has been
- * projected onto the faces)
- * has.
+ * The last argument denotes the number of quadrature points the lower-
+ * dimensional face quadrature formula (the one that has been projected
+ * onto the faces) has.
*/
static
DataSetDescriptor
const unsigned int n_quadrature_points);
/**
- * Static function to generate an
- * offset object for a given subface of
- * a cell with the given face
- * orientation, flip and rotation. This
- * function of course is only allowed
- * if <tt>dim>=2</tt>, and the face
- * orientation, flip and rotation are
- * ignored if the space dimension
- * equals 2.
+ * Static function to generate an offset object for a given subface of a
+ * cell with the given face orientation, flip and rotation. This function
+ * of course is only allowed if <tt>dim>=2</tt>, and the face orientation,
+ * flip and rotation are ignored if the space dimension equals 2.
*
- * The last but one argument denotes
- * the number of quadrature
- * points the
- * lower-dimensional face
- * quadrature formula (the
- * one that has been
- * projected onto the faces)
- * has.
+ * The last but one argument denotes the number of quadrature points the
+ * lower-dimensional face quadrature formula (the one that has been
+ * projected onto the faces) has.
*
- * Through the last argument
- * anisotropic refinement can be
- * respected.
+ * Through the last argument anisotropic refinement can be respected.
*/
static
DataSetDescriptor
const internal::SubfaceCase<dim> ref_case=internal::SubfaceCase<dim>::case_isotropic);
/**
- * Conversion operator to an
- * integer denoting the
- * offset of the first
- * element of this dataset in
- * the set of quadrature
- * formulas all projected
- * onto faces and
- * subfaces. This conversion
- * operator allows us to use
- * offset descriptor objects
- * in place of integer
- * offsets.
+ * Conversion operator to an integer denoting the offset of the first
+ * element of this dataset in the set of quadrature formulas all projected
+ * onto faces and subfaces. This conversion operator allows us to use
+ * offset descriptor objects in place of integer offsets.
*/
operator unsigned int () const;
private:
/**
- * Store the integer offset
- * for a given cell, face, or
- * subface.
+ * Store the integer offset for a given cell, face, or subface.
*/
const unsigned int dataset_offset;
/**
- * This is the real
- * constructor, but it is
- * private and thus only
- * available to the static
- * member functions above.
+ * This is the real constructor, but it is private and thus only available
+ * to the static member functions above.
*/
DataSetDescriptor (const unsigned int dataset_offset);
};
private:
/**
- * Given a quadrature object in
- * 2d, reflect all quadrature
- * points at the main diagonal
- * and return them with their
- * original weights.
+ * Given a quadrature object in 2d, reflect all quadrature points at the
+ * main diagonal and return them with their original weights.
*
- * This function is necessary for
- * projecting a 2d quadrature
- * rule onto the faces of a 3d
- * cube, since there we need both
- * orientations.
+ * This function is necessary for projecting a 2d quadrature rule onto the
+ * faces of a 3d cube, since there we need both orientations.
*/
static Quadrature<2> reflect (const Quadrature<2> &q);
/**
- * Given a quadrature object in
- * 2d, rotate all quadrature
- * points by @p n_times * 90 degrees
- * counterclockwise
- * and return them with their
- * original weights.
+ * Given a quadrature object in 2d, rotate all quadrature points by @p
+ * n_times * 90 degrees counterclockwise and return them with their original
+ * weights.
*
- * This function is necessary for
- * projecting a 2d quadrature
- * rule onto the faces of a 3d
- * cube, since there we need all
- * rotations to account for
- * face_flip and face_rotation
- * of non-standard faces.
+ * This function is necessary for projecting a 2d quadrature rule onto the
+ * faces of a 3d cube, since there we need all rotations to account for
+ * face_flip and face_rotation of non-standard faces.
*/
static Quadrature<2> rotate (const Quadrature<2> &q,
const unsigned int n_times);
/**
* Base class for quadrature formulæ in arbitrary dimensions. This class
- * stores quadrature points and weights on the unit line [0,1], unit
- * square [0,1]x[0,1], etc.
+ * stores quadrature points and weights on the unit line [0,1], unit square
+ * [0,1]x[0,1], etc.
*
- * There are a number of derived classes, denoting concrete
- * integration formulæ. Their names names prefixed by
- * <tt>Q</tt>. Refer to the list of derived classes for more details.
+ * There are a number of derived classes, denoting concrete integration
+ * formulæ. Their names names prefixed by <tt>Q</tt>. Refer to the list of
+ * derived classes for more details.
*
- * The schemes for higher dimensions are typically tensor products of the
- * one-dimensional formulæ, but refer to the section on implementation
- * detail below.
+ * The schemes for higher dimensions are typically tensor products of the one-
+ * dimensional formulæ, but refer to the section on implementation detail
+ * below.
*
- * In order to allow for dimension independent programming, a
- * quadrature formula of dimension zero exists. Since an integral over
- * zero dimensions is the evaluation at a single point, any
- * constructor of such a formula initializes to a single quadrature
- * point with weight one. Access to the weight is possible, while
- * access to the quadrature point is not permitted, since a Point of
- * dimension zero contains no information. The main purpose of these
- * formulæ is their use in QProjector, which will create a useful
+ * In order to allow for dimension independent programming, a quadrature
+ * formula of dimension zero exists. Since an integral over zero dimensions is
+ * the evaluation at a single point, any constructor of such a formula
+ * initializes to a single quadrature point with weight one. Access to the
+ * weight is possible, while access to the quadrature point is not permitted,
+ * since a Point of dimension zero contains no information. The main purpose
+ * of these formulæ is their use in QProjector, which will create a useful
* formula of dimension one out of them.
*
* <h3>Mathematical background</h3>
*
- * For each quadrature formula we denote by <tt>m</tt>, the maximal
- * degree of polynomials integrated exactly. This number is given in
- * the documentation of each formula. The order of the integration
- * error is <tt>m+1</tt>, that is, the error is the size of the cell
- * to the <tt>m+1</tt> by the Bramble-Hilbert Lemma. The number
- * <tt>m</tt> is to be found in the documentation of each concrete
- * formula. For the optimal formulæ QGauss we have $m = 2N-1$, where
- * N is the constructor parameter to QGauss. The tensor product
- * formulæ are exact on tensor product polynomials of degree
- * <tt>m</tt> in each space direction, but they are still only of
- * <tt>m+1</tt>st order.
+ * For each quadrature formula we denote by <tt>m</tt>, the maximal degree of
+ * polynomials integrated exactly. This number is given in the documentation
+ * of each formula. The order of the integration error is <tt>m+1</tt>, that
+ * is, the error is the size of the cell to the <tt>m+1</tt> by the Bramble-
+ * Hilbert Lemma. The number <tt>m</tt> is to be found in the documentation of
+ * each concrete formula. For the optimal formulæ QGauss we have $m = 2N-1$,
+ * where N is the constructor parameter to QGauss. The tensor product formulæ
+ * are exact on tensor product polynomials of degree <tt>m</tt> in each space
+ * direction, but they are still only of <tt>m+1</tt>st order.
*
* <h3>Implementation details</h3>
*
- * Most integration formulæ in more than one space dimension are
- * tensor products of quadrature formulæ in one space dimension, or
- * more generally the tensor product of a formula in <tt>(dim-1)</tt>
- * dimensions and one in one dimension. There is a special constructor
- * to generate a quadrature formula from two others. For example, the
- * QGauss@<dim@> formulæ include <i>N<sup>dim</sup></i> quadrature
- * points in <tt>dim</tt> dimensions, where N is the constructor
- * parameter of QGauss.
+ * Most integration formulæ in more than one space dimension are tensor
+ * products of quadrature formulæ in one space dimension, or more generally
+ * the tensor product of a formula in <tt>(dim-1)</tt> dimensions and one in
+ * one dimension. There is a special constructor to generate a quadrature
+ * formula from two others. For example, the QGauss@<dim@> formulæ include
+ * <i>N<sup>dim</sup></i> quadrature points in <tt>dim</tt> dimensions, where
+ * N is the constructor parameter of QGauss.
*
- * @note Instantiations for this template are provided for dimensions
- * 0, 1, 2, and 3 (see the section on @ref Instantiations).
+ * @note Instantiations for this template are provided for dimensions 0, 1, 2,
+ * and 3 (see the section on @ref Instantiations).
*
* @author Wolfgang Bangerth, Guido Kanschat, 1998, 1999, 2000, 2005, 2009
*/
{
public:
/**
- * Define a typedef for a
- * quadrature that acts on an
- * object of one dimension
- * less. For cells, this would
- * then be a face quadrature.
+ * Define a typedef for a quadrature that acts on an object of one dimension
+ * less. For cells, this would then be a face quadrature.
*/
typedef Quadrature<dim-1> SubQuadrature;
/**
* Constructor.
*
- * This constructor is marked as
- * explicit to avoid involuntary
- * accidents like in
- * <code>hp::QCollection@<dim@>
- * q_collection(3)</code> where
- * <code>hp::QCollection@<dim@>
- * q_collection(QGauss@<dim@>(3))</code>
- * was meant.
+ * This constructor is marked as explicit to avoid involuntary accidents
+ * like in <code>hp::QCollection@<dim@> q_collection(3)</code> where
+ * <code>hp::QCollection@<dim@> q_collection(QGauss@<dim@>(3))</code> was
+ * meant.
*/
explicit Quadrature (const unsigned int n_quadrature_points = 0);
/**
- * Build this quadrature formula
- * as the tensor product of a
- * formula in a dimension one
- * less than the present and a
- * formula in one dimension.
+ * Build this quadrature formula as the tensor product of a formula in a
+ * dimension one less than the present and a formula in one dimension.
*
- * <tt>SubQuadrature<dim>::type</tt>
- * expands to
- * <tt>Quadrature<dim-1></tt>.
+ * <tt>SubQuadrature<dim>::type</tt> expands to <tt>Quadrature<dim-1></tt>.
*/
Quadrature (const SubQuadrature &,
const Quadrature<1> &);
/**
- * Build this quadrature formula
- * as the <tt>dim</tt>-fold
- * tensor product of a formula in
- * one dimension.
+ * Build this quadrature formula as the <tt>dim</tt>-fold tensor product of
+ * a formula in one dimension.
*
- * Assuming that the points in
- * the one-dimensional rule are in
- * ascending order, the points of
- * the resulting rule are ordered
- * lexicographically with
- * <i>x</i> running fastest.
+ * Assuming that the points in the one-dimensional rule are in ascending
+ * order, the points of the resulting rule are ordered lexicographically
+ * with <i>x</i> running fastest.
*
- * In order to avoid a conflict
- * with the copy constructor in
- * 1d, we let the argument be a
- * 0d quadrature formula for
- * dim==1, and a 1d quadrature
- * formula for all other space
- * dimensions.
+ * In order to avoid a conflict with the copy constructor in 1d, we let the
+ * argument be a 0d quadrature formula for dim==1, and a 1d quadrature
+ * formula for all other space dimensions.
*/
explicit Quadrature (const Quadrature<dim != 1 ? 1 : 0> &quadrature_1d);
Quadrature (const Quadrature<dim> &q);
/**
- * Construct a quadrature formula
- * from given vectors of
- * quadrature points (which
- * should really be in the unit
- * cell) and the corresponding
- * weights. You will want to have
- * the weights sum up to one, but
- * this is not checked.
+ * Construct a quadrature formula from given vectors of quadrature points
+ * (which should really be in the unit cell) and the corresponding weights.
+ * You will want to have the weights sum up to one, but this is not checked.
*/
Quadrature (const std::vector<Point<dim> > &points,
const std::vector<double> &weights);
/**
- * Construct a dummy quadrature
- * formula from a list of points,
- * with weights set to
- * infinity. The resulting object
- * is therefore not meant to
- * actually perform integrations,
- * but rather to be used with
- * FEValues objects in
- * order to find the position of
- * some points (the quadrature
- * points in this object) on the
- * transformed cell in real
- * space.
+ * Construct a dummy quadrature formula from a list of points, with weights
+ * set to infinity. The resulting object is therefore not meant to actually
+ * perform integrations, but rather to be used with FEValues objects in
+ * order to find the position of some points (the quadrature points in this
+ * object) on the transformed cell in real space.
*/
Quadrature (const std::vector<Point<dim> > &points);
/**
- * Constructor for a one-point
- * quadrature. Sets the weight of
- * this point to one.
+ * Constructor for a one-point quadrature. Sets the weight of this point to
+ * one.
*/
Quadrature (const Point<dim> &point);
virtual ~Quadrature ();
/**
- * Assignment operator. Copies
- * contents of #weights and
- * #quadrature_points as well as
- * size.
+ * Assignment operator. Copies contents of #weights and #quadrature_points
+ * as well as size.
*/
Quadrature &operator = (const Quadrature<dim> &);
/**
- * Test for equality of two quadratures.
- */
+ * Test for equality of two quadratures.
+ */
bool operator == (const Quadrature<dim> &p) const;
/**
- * Set the quadrature points and
- * weights to the values provided
- * in the arguments.
+ * Set the quadrature points and weights to the values provided in the
+ * arguments.
*/
void initialize(const std::vector<Point<dim> > &points,
const std::vector<double> &weights);
unsigned int size () const;
/**
- * Return the <tt>i</tt>th quadrature
- * point.
+ * Return the <tt>i</tt>th quadrature point.
*/
const Point<dim> &point (const unsigned int i) const;
/**
- * Return a reference to the
- * whole array of quadrature
- * points.
+ * Return a reference to the whole array of quadrature points.
*/
const std::vector<Point<dim> > &get_points () const;
/**
- * Return the weight of the <tt>i</tt>th
- * quadrature point.
+ * Return the weight of the <tt>i</tt>th quadrature point.
*/
double weight (const unsigned int i) const;
/**
- * Return a reference to the whole array
- * of weights.
+ * Return a reference to the whole array of weights.
*/
const std::vector<double> &get_weights () const;
/**
- * Determine an estimate for
- * the memory consumption (in
- * bytes) of this
+ * Determine an estimate for the memory consumption (in bytes) of this
* object.
*/
std::size_t memory_consumption () const;
/**
- * Write or read the data of this object to or
- * from a stream for the purpose of serialization.
- */
+ * Write or read the data of this object to or from a stream for the purpose
+ * of serialization.
+ */
template <class Archive>
void serialize (Archive &ar, const unsigned int version);
protected:
/**
- * List of quadrature points. To
- * be filled by the constructors
- * of derived classes.
+ * List of quadrature points. To be filled by the constructors of derived
+ * classes.
*/
std::vector<Point<dim> > quadrature_points;
/**
- * List of weights of the
- * quadrature points. To be
- * filled by the constructors of
- * derived classes.
+ * List of weights of the quadrature points. To be filled by the
+ * constructors of derived classes.
*/
std::vector<double> weights;
};
/**
- * Quadrature formula implementing anisotropic distributions of
- * quadrature points on the reference cell. To this end, the tensor
- * product of <tt>dim</tt> one-dimensional quadrature formulas is
- * generated.
+ * Quadrature formula implementing anisotropic distributions of quadrature
+ * points on the reference cell. To this end, the tensor product of
+ * <tt>dim</tt> one-dimensional quadrature formulas is generated.
*
- * @note Each constructor can only be used in the dimension matching
- * the number of arguments.
+ * @note Each constructor can only be used in the dimension matching the
+ * number of arguments.
*
* @author Guido Kanschat, 2005
*/
{
public:
/**
- * Constructor for a
- * one-dimensional formula. This
- * one just copies the given
+ * Constructor for a one-dimensional formula. This one just copies the given
* quadrature rule.
*/
QAnisotropic(const Quadrature<1> &qx);
/**
- * Constructor for a
- * two-dimensional formula.
+ * Constructor for a two-dimensional formula.
*/
QAnisotropic(const Quadrature<1> &qx,
const Quadrature<1> &qy);
/**
- * Constructor for a
- * three-dimensional formula.
+ * Constructor for a three-dimensional formula.
*/
QAnisotropic(const Quadrature<1> &qx,
const Quadrature<1> &qy,
/**
- * Quadrature formula constructed by iteration of another quadrature formula in
- * each direction. In more than one space dimension, the resulting quadrature
- * formula is constructed in the usual way by building the tensor product of
- * the respective iterated quadrature formula in one space dimension.
+ * Quadrature formula constructed by iteration of another quadrature formula
+ * in each direction. In more than one space dimension, the resulting
+ * quadrature formula is constructed in the usual way by building the tensor
+ * product of the respective iterated quadrature formula in one space
+ * dimension.
*
- * In one space dimension, the given base formula is copied and scaled onto
- * a given number of subintervals of length <tt>1/n_copies</tt>. If the quadrature
- * formula uses both end points of the unit interval, then in the interior
- * of the iterated quadrature formula there would be quadrature points which
- * are used twice; we merge them into one with a weight which is the sum
- * of the weights of the left- and the rightmost quadrature point.
+ * In one space dimension, the given base formula is copied and scaled onto a
+ * given number of subintervals of length <tt>1/n_copies</tt>. If the
+ * quadrature formula uses both end points of the unit interval, then in the
+ * interior of the iterated quadrature formula there would be quadrature
+ * points which are used twice; we merge them into one with a weight which is
+ * the sum of the weights of the left- and the rightmost quadrature point.
*
- * Since all dimensions higher than one are built up by tensor products of
- * one dimensional and <tt>dim-1</tt> dimensional quadrature formulæ, the
- * argument given to the constructor needs to be a quadrature formula in
- * one space dimension, rather than in <tt>dim</tt> dimensions.
+ * Since all dimensions higher than one are built up by tensor products of one
+ * dimensional and <tt>dim-1</tt> dimensional quadrature formulæ, the
+ * argument given to the constructor needs to be a quadrature formula in one
+ * space dimension, rather than in <tt>dim</tt> dimensions.
*
- * The aim of this class is to provide a
- * low order formula, where the error constant can be tuned by
- * increasing the number of quadrature points. This is useful in
- * integrating non-differentiable functions on cells.
+ * The aim of this class is to provide a low order formula, where the error
+ * constant can be tuned by increasing the number of quadrature points. This
+ * is useful in integrating non-differentiable functions on cells.
*
* @author Wolfgang Bangerth 1999
*/
{
public:
/**
- * Constructor. Iterate the given
- * quadrature formula <tt>n_copies</tt> times in
- * each direction.
+ * Constructor. Iterate the given quadrature formula <tt>n_copies</tt> times
+ * in each direction.
*/
QIterated (const Quadrature<1> &base_quadrature,
const unsigned int n_copies);
DeclException0 (ExcInvalidQuadratureFormula);
private:
/**
- * Check whether the given
- * quadrature formula has quadrature
- * points at the left and right end points
- * of the interval.
+ * Check whether the given quadrature formula has quadrature points at the
+ * left and right end points of the interval.
*/
static bool
uses_both_endpoints (const Quadrature<1> &base_quadrature);
/*@{*/
/**
- * The Gauss-Legendre family of quadrature rules for numerical
- * integration.
+ * The Gauss-Legendre family of quadrature rules for numerical integration.
*
* The coefficients of these quadrature rules are computed by the function
* described in <a
{
public:
/**
- * Generate a formula with
- * <tt>n</tt> quadrature points (in
- * each space direction), exact for
- * polynomials of degree
- * <tt>2n-1</tt>.
+ * Generate a formula with <tt>n</tt> quadrature points (in each space
+ * direction), exact for polynomials of degree <tt>2n-1</tt>.
*/
QGauss (const unsigned int n);
};
/**
- * The Gauss-Lobatto family of quadrature rules for numerical
- * integration.
+ * The Gauss-Lobatto family of quadrature rules for numerical integration.
*
- * This modification of the Gauss quadrature uses the two interval end
- * points as well. Being exact for polynomials of degree <i>2n-3</i>,
- * this formula is suboptimal by two degrees.
+ * This modification of the Gauss quadrature uses the two interval end points
+ * as well. Being exact for polynomials of degree <i>2n-3</i>, this formula is
+ * suboptimal by two degrees.
*
- * The quadrature points are interval end points plus the roots of
- * the derivative of the Legendre polynomial <i>P<sub>n-1</sub></i> of
- * degree <i>n-1</i>. The quadrature weights are
+ * The quadrature points are interval end points plus the roots of the
+ * derivative of the Legendre polynomial <i>P<sub>n-1</sub></i> of degree
+ * <i>n-1</i>. The quadrature weights are
* <i>2/(n(n-1)(P<sub>n-1</sub>(x<sub>i</sub>)<sup>2</sup>)</i>.
*
- * @note This implementation has not been optimized concerning
- * numerical stability and efficiency. It can be easily adapted
- * to the general case of Gauss-Lobatto-Jacobi-Bouzitat quadrature
- * with arbitrary parameters $\alpha$, $\beta$, of which
- * the Gauss-Lobatto-Legendre quadrature ($\alpha = \beta = 0$)
- * is a special case.
+ * @note This implementation has not been optimized concerning numerical
+ * stability and efficiency. It can be easily adapted to the general case of
+ * Gauss-Lobatto-Jacobi-Bouzitat quadrature with arbitrary parameters
+ * $\alpha$, $\beta$, of which the Gauss-Lobatto-Legendre quadrature ($\alpha
+ * = \beta = 0$) is a special case.
*
- * @sa http://en.wikipedia.org/wiki/Handbook_of_Mathematical_Functions
- * @sa Karniadakis, G.E. and Sherwin, S.J.:
- * Spectral/hp element methods for computational fluid dynamics.
- * Oxford: Oxford University Press, 2005
+ * @sa http://en.wikipedia.org/wiki/Handbook_of_Mathematical_Functions @sa
+ * Karniadakis, G.E. and Sherwin, S.J.: Spectral/hp element methods for
+ * computational fluid dynamics. Oxford: Oxford University Press, 2005
*
* @author Guido Kanschat, 2005, 2006; F. Prill, 2006
*/
{
public:
/**
- * Generate a formula with
- * <tt>n</tt> quadrature points
- * (in each space direction).
+ * Generate a formula with <tt>n</tt> quadrature points (in each space
+ * direction).
*/
QGaussLobatto(const unsigned int n);
protected:
/**
- * Compute Legendre-Gauss-Lobatto
- * quadrature points in the
- * interval $[-1, +1]$. They are
- * equal to the roots of the
- * corresponding Jacobi
- * polynomial (specified by @p
- * alpha, @p beta). @p q is the
- * number of points.
+ * Compute Legendre-Gauss-Lobatto quadrature points in the interval $[-1,
+ * +1]$. They are equal to the roots of the corresponding Jacobi polynomial
+ * (specified by @p alpha, @p beta). @p q is the number of points.
*
* @return Vector containing nodes.
*/
const int beta) const;
/**
- * Compute Legendre-Gauss-Lobatto quadrature
- * weights.
- * The quadrature points and weights are
- * related to Jacobi polynomial specified
- * by @p alpha, @p beta.
- * @p x denotes the quadrature points.
+ * Compute Legendre-Gauss-Lobatto quadrature weights. The quadrature points
+ * and weights are related to Jacobi polynomial specified by @p alpha, @p
+ * beta. @p x denotes the quadrature points.
*
* @return Vector containing weights.
*/
const int beta) const;
/**
- * Evaluate a Jacobi polynomial
- * $ P^{\alpha, \beta}_n(x) $
- * specified by the parameters
- * @p alpha, @p beta, @p n.
- * Note: The Jacobi polynomials are
- * not orthonormal and defined on
- * the interval $[-1, +1]$.
- * @p x is the point of evaluation.
+ * Evaluate a Jacobi polynomial $ P^{\alpha, \beta}_n(x) $ specified by the
+ * parameters @p alpha, @p beta, @p n. Note: The Jacobi polynomials are not
+ * orthonormal and defined on the interval $[-1, +1]$. @p x is the point of
+ * evaluation.
*/
long double JacobiP(const long double x,
const int alpha,
const unsigned int n) const;
/**
- * Evaluate the Gamma function
- * $ \Gamma(n) = (n-1)! $.
+ * Evaluate the Gamma function $ \Gamma(n) = (n-1)! $.
* @param n point of evaluation (integer).
*/
long double gamma(const unsigned int n) const;
/**
- * The Milne rule for numerical quadrature formula. The Milne rule is a
- * closed Newton-Cotes formula and is exact for polynomials of degree 5.
+ * The Milne rule for numerical quadrature formula. The Milne rule is a closed
+ * Newton-Cotes formula and is exact for polynomials of degree 5.
*
* @sa Stoer: Einführung in die Numerische Mathematik I, p. 102
*/
/**
- * The Weddle rule for numerical quadrature. The Weddle rule is a
- * closed Newton-Cotes formula and is exact for polynomials of degree 7.
+ * The Weddle rule for numerical quadrature. The Weddle rule is a closed
+ * Newton-Cotes formula and is exact for polynomials of degree 7.
*
* @sa Stoer: Einführung in die Numerische Mathematik I, p. 102
*/
/**
- * A class for Gauss quadrature with
- * logarithmic weighting function. This
- * formula is used to integrate $\ln|x|\;f(x)$ on the interval
- * $[0,1]$, where $f$ is a smooth function without
- * singularities. The collection of quadrature points and weights has
- * been obtained using <tt>Numerical Recipes</tt>.
+ * A class for Gauss quadrature with logarithmic weighting function. This
+ * formula is used to integrate $\ln|x|\;f(x)$ on the interval $[0,1]$, where
+ * $f$ is a smooth function without singularities. The collection of
+ * quadrature points and weights has been obtained using <tt>Numerical
+ * Recipes</tt>.
*
- * Notice that only the function $f(x)$ should be provided,
- * i.e., $\int_0^1 f(x) \ln|x| dx = \sum_{i=0}^N w_i f(q_i)$. Setting
- * the @p revert flag to true at construction time switches the weight
- * from $\ln|x|$ to $\ln|1-x|$.
+ * Notice that only the function $f(x)$ should be provided, i.e., $\int_0^1
+ * f(x) \ln|x| dx = \sum_{i=0}^N w_i f(q_i)$. Setting the @p revert flag to
+ * true at construction time switches the weight from $\ln|x|$ to $\ln|1-x|$.
*
* The weights and functions have been tabulated up to order 12.
*/
{
public:
/**
- * Generate a formula with
- * <tt>n</tt> quadrature points
+ * Generate a formula with <tt>n</tt> quadrature points
*/
QGaussLog(const unsigned int n,
const bool revert=false);
protected:
/**
- * Sets the points of the
- * quadrature formula.
+ * Sets the points of the quadrature formula.
*/
std::vector<double>
set_quadrature_points(const unsigned int n) const;
/**
- * Sets the weights of the
- * quadrature formula.
+ * Sets the weights of the quadrature formula.
*/
std::vector<double>
set_quadrature_weights(const unsigned int n) const;
/**
- * A class for Gauss quadrature with arbitrary logarithmic weighting
- * function. This formula is used to to integrate
- * $\ln(|x-x_0|/\alpha)\;f(x)$ on the interval $[0,1]$,
- * where $f$ is a smooth function without singularities, and $x_0$ and
- * $\alpha$ are given at construction time, and are the location of the
- * singularity $x_0$ and an arbitrary scaling factor in the
- * singularity.
+ * A class for Gauss quadrature with arbitrary logarithmic weighting function.
+ * This formula is used to to integrate $\ln(|x-x_0|/\alpha)\;f(x)$ on the
+ * interval $[0,1]$, where $f$ is a smooth function without singularities, and
+ * $x_0$ and $\alpha$ are given at construction time, and are the location of
+ * the singularity $x_0$ and an arbitrary scaling factor in the singularity.
*
* You have to make sure that the point $x_0$ is not one of the Gauss
- * quadrature points of order $N$, otherwise an exception is thrown,
- * since the quadrature weights cannot be computed correctly.
+ * quadrature points of order $N$, otherwise an exception is thrown, since the
+ * quadrature weights cannot be computed correctly.
*
- * This quadrature formula is rather expensive, since it uses
- * internally two Gauss quadrature formulas of order n to integrate
- * the nonsingular part of the factor, and two GaussLog quadrature
- * formulas to integrate on the separate segments $[0,x_0]$ and
- * $[x_0,1]$. If the singularity is one of the extremes and the factor
- * alpha is 1, then this quadrature is the same as QGaussLog.
+ * This quadrature formula is rather expensive, since it uses internally two
+ * Gauss quadrature formulas of order n to integrate the nonsingular part of
+ * the factor, and two GaussLog quadrature formulas to integrate on the
+ * separate segments $[0,x_0]$ and $[x_0,1]$. If the singularity is one of the
+ * extremes and the factor alpha is 1, then this quadrature is the same as
+ * QGaussLog.
*
- * The last argument from the constructor allows you to use this
- * quadrature rule in one of two possible ways:
- * \f[
- * \int_0^1 g(x) dx =
- * \int_0^1 f(x) \ln\left(\frac{|x-x_0|}{\alpha}\right) dx
- * = \sum_{i=0}^N w_i g(q_i) = \sum_{i=0}^N \bar{w}_i f(q_i)
- * \f]
+ * The last argument from the constructor allows you to use this quadrature
+ * rule in one of two possible ways: \f[ \int_0^1 g(x) dx = \int_0^1 f(x)
+ * \ln\left(\frac{|x-x_0|}{\alpha}\right) dx = \sum_{i=0}^N w_i g(q_i) =
+ * \sum_{i=0}^N \bar{w}_i f(q_i) \f]
*
- * Which one of the two sets of weights is provided, can be selected
- * by the @p factor_out_singular_weight parameter. If it is false (the
- * default), then the $\bar{w}_i$ weigths are computed, and you should
- * provide only the smooth function $f(x)$, since the singularity is
- * included inside the quadrature. If the parameter is set to true,
- * then the singularity is factored out of the quadrature formula, and
- * you should provide a function $g(x)$, which should at least be
- * similar to $\ln(|x-x_0|/\alpha)$.
+ * Which one of the two sets of weights is provided, can be selected by the @p
+ * factor_out_singular_weight parameter. If it is false (the default), then
+ * the $\bar{w}_i$ weigths are computed, and you should provide only the
+ * smooth function $f(x)$, since the singularity is included inside the
+ * quadrature. If the parameter is set to true, then the singularity is
+ * factored out of the quadrature formula, and you should provide a function
+ * $g(x)$, which should at least be similar to $\ln(|x-x_0|/\alpha)$.
*
- * Notice that this quadrature rule is worthless if you try to use it
- * for regular functions once you factored out the singularity.
+ * Notice that this quadrature rule is worthless if you try to use it for
+ * regular functions once you factored out the singularity.
*
* The weights and functions have been tabulated up to order 12.
*/
{
public:
/**
- * The constructor takes four arguments:
- * the order of the gauss formula on each
- * of the segments $[0,x_0]$ and
- * $[x_0,1]$, the actual location of the
- * singularity, the scale factor inside
- * the logarithmic function and a flag
- * that decides whether the singularity is
- * left inside the quadrature formula or
- * it is factored out, to be included in
- * the integrand.
+ * The constructor takes four arguments: the order of the gauss formula on
+ * each of the segments $[0,x_0]$ and $[x_0,1]$, the actual location of the
+ * singularity, the scale factor inside the logarithmic function and a flag
+ * that decides whether the singularity is left inside the quadrature
+ * formula or it is factored out, to be included in the integrand.
*/
QGaussLogR(const unsigned int n,
const Point<dim> x0 = Point<dim>(),
protected:
/**
- * This is the length of interval
- * $(0,origin)$, or 1 if either of the two
+ * This is the length of interval $(0,origin)$, or 1 if either of the two
* extremes have been selected.
*/
const double fraction;
/**
* A class for Gauss quadrature with $1/R$ weighting function. This formula
- * can be used to to integrate $1/R \ f(x)$ on the reference
- * element $[0,1]^2$, where $f$ is a smooth function without
- * singularities, and $R$ is the distance from the point $x$ to the vertex
- * $\xi$, given at construction time by specifying its index. Notice that
- * this distance is evaluated in the reference element.
+ * can be used to to integrate $1/R \ f(x)$ on the reference element
+ * $[0,1]^2$, where $f$ is a smooth function without singularities, and $R$ is
+ * the distance from the point $x$ to the vertex $\xi$, given at construction
+ * time by specifying its index. Notice that this distance is evaluated in the
+ * reference element.
*
- * This quadrature formula is obtained from two QGauss quadrature
- * formulas, upon transforming them into polar coordinate system
- * centered at the singularity, and then again into another reference
- * element. This allows for the singularity to be cancelled by part of
- * the Jacobian of the transformation, which contains $R$. In practice
- * the reference element is transformed into a triangle by collapsing
- * one of the sides adjacent to the singularity. The Jacobian of this
- * transformation contains $R$, which is removed before scaling the
- * original quadrature, and this process is repeated for the next half
- * element.
+ * This quadrature formula is obtained from two QGauss quadrature formulas,
+ * upon transforming them into polar coordinate system centered at the
+ * singularity, and then again into another reference element. This allows for
+ * the singularity to be cancelled by part of the Jacobian of the
+ * transformation, which contains $R$. In practice the reference element is
+ * transformed into a triangle by collapsing one of the sides adjacent to the
+ * singularity. The Jacobian of this transformation contains $R$, which is
+ * removed before scaling the original quadrature, and this process is
+ * repeated for the next half element.
*
- * Upon construction it is possible to specify whether we want the
- * singularity removed, or not. In other words, this quadrature can be
- * used to integrate $g(x) = 1/R\ f(x)$, or simply $f(x)$, with the $1/R$
- * factor already included in the quadrature weights.
+ * Upon construction it is possible to specify whether we want the singularity
+ * removed, or not. In other words, this quadrature can be used to integrate
+ * $g(x) = 1/R\ f(x)$, or simply $f(x)$, with the $1/R$ factor already
+ * included in the quadrature weights.
*/
template <int dim>
class QGaussOneOverR : public Quadrature<dim>
{
public:
/**
- * This constructor takes three arguments: the order of the Gauss
- * formula, the point of the reference element in which the
- * singularity is located, and whether we include the weighting
- * singular function inside the quadrature, or we leave it in the
- * user function to be integrated.
+ * This constructor takes three arguments: the order of the Gauss formula,
+ * the point of the reference element in which the singularity is located,
+ * and whether we include the weighting singular function inside the
+ * quadrature, or we leave it in the user function to be integrated.
*
- * Traditionally, quadrature formulas include their weighting
- * function, and the last argument is set to false by
- * default. There are cases, however, where this is undesirable
- * (for example when you only know that your singularity has the
- * same order of 1/R, but cannot be written exactly in this
- * way).
+ * Traditionally, quadrature formulas include their weighting function, and
+ * the last argument is set to false by default. There are cases, however,
+ * where this is undesirable (for example when you only know that your
+ * singularity has the same order of 1/R, but cannot be written exactly in
+ * this way).
*
- * In other words, you can use this function in either of
- * the following way, obtaining the same result:
+ * In other words, you can use this function in either of the following way,
+ * obtaining the same result:
*
* @code
* QGaussOneOverR singular_quad(order, q_point, false);
const Point<dim> singularity,
const bool factor_out_singular_weight=false);
/**
- * The constructor takes three arguments: the order of the Gauss
- * formula, the index of the vertex where the singularity is
- * located, and whether we include the weighting singular function
- * inside the quadrature, or we leave it in the user function to
- * be integrated. Notice that this is a specialized version of the
- * previous constructor which works only for the vertices of the
- * quadrilateral.
+ * The constructor takes three arguments: the order of the Gauss formula,
+ * the index of the vertex where the singularity is located, and whether we
+ * include the weighting singular function inside the quadrature, or we
+ * leave it in the user function to be integrated. Notice that this is a
+ * specialized version of the previous constructor which works only for the
+ * vertices of the quadrilateral.
*
- * Traditionally, quadrature formulas include their weighting
- * function, and the last argument is set to false by
- * default. There are cases, however, where this is undesirable
- * (for example when you only know that your singularity has the
- * same order of 1/R, but cannot be written exactly in this
- * way).
+ * Traditionally, quadrature formulas include their weighting function, and
+ * the last argument is set to false by default. There are cases, however,
+ * where this is undesirable (for example when you only know that your
+ * singularity has the same order of 1/R, but cannot be written exactly in
+ * this way).
*
- * In other words, you can use this function in either of
- * the following way, obtaining the same result:
+ * In other words, you can use this function in either of the following way,
+ * obtaining the same result:
*
* @code
* QGaussOneOverR singular_quad(order, vertex_id, false);
const bool factor_out_singular_weight=false);
private:
/**
- * Given a quadrature point and a degree n, this function returns
- * the size of the singular quadrature rule, considering whether
- * the point is inside the cell, on an edge of the cell, or on a
- * corner of the cell.
+ * Given a quadrature point and a degree n, this function returns the size
+ * of the singular quadrature rule, considering whether the point is inside
+ * the cell, on an edge of the cell, or on a corner of the cell.
*/
static unsigned int quad_size(const Point<dim> singularity,
const unsigned int n);
/**
- * Sorted Quadrature. Given an arbitrary quadrature formula, this
- * class generates a quadrature formula where the quadrature points
- * are ordered according the weights, from those with smaller
- * corresponding weight, to those with higher corresponding weights.
- * This might be necessary, for example, when integrating high order
- * polynomials, since in these cases you might sum very big numbers
- * with very small numbers, and summation is not stable if the numbers
- * to sum are not close to each other.
+ * Sorted Quadrature. Given an arbitrary quadrature formula, this class
+ * generates a quadrature formula where the quadrature points are ordered
+ * according the weights, from those with smaller corresponding weight, to
+ * those with higher corresponding weights. This might be necessary, for
+ * example, when integrating high order polynomials, since in these cases you
+ * might sum very big numbers with very small numbers, and summation is not
+ * stable if the numbers to sum are not close to each other.
*/
template <int dim>
class QSorted : public Quadrature<dim>
DEAL_II_NAMESPACE_OPEN
/**
- * This class implements the quadrature rule passed to its constructor
- * as a string. Supported quadratures are QGauss (of all
- * orders), QMidpoint, QMilne, QSimpson,
- * QTrapez and QWeddle.
+ * This class implements the quadrature rule passed to its constructor as a
+ * string. Supported quadratures are QGauss (of all orders), QMidpoint,
+ * QMilne, QSimpson, QTrapez and QWeddle.
*
- * This class is useful if you want to use flexible quadrature rules,
- * that are read from a parameter file (see ParameterHandler for
- * this).
+ * 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
{
public:
/**
- * Constructor. Takes the name of
- * the quadrature rule (one of
- * "gauss", "milne", "weddle",
- * etc) and, if it iss "gauss",
- * the order of the quadrature
- * rule as argument.
+ * Constructor. Takes the name of the quadrature rule (one of "gauss",
+ * "milne", "weddle", etc) and, if it iss "gauss", the order of the
+ * quadrature rule as argument.
*/
QuadratureSelector (const std::string &s,
const unsigned int order=0);
/**
- * This function returns all
- * possible names for quadratures
- * as a list separated by <tt>|</tt>,
- * so that you can use it for the
- * definition of parameter files
- * (see ParameterHandler for
- * details).
+ * This function returns all possible names for quadratures as a list
+ * separated by <tt>|</tt>, so that you can use it for the definition of
+ * parameter files (see ParameterHandler for details).
*/
static std::string get_quadrature_names();
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
//@}
private:
/**
- * This static function creates a
- * quadrature object according to
- * the name given as a string,
- * and the appropriate order (if
- * the name is "gauss"). It is
- * called from the constructor.
+ * This static function creates a quadrature object according to the name
+ * given as a string, and the appropriate order (if the name is "gauss"). It
+ * is called from the constructor.
*/
static
Quadrature<dim>
/**
* Smart pointers avoid destruction of an object in use. They can be used just
- * like a pointer (i.e. using the <tt>*</tt> and <tt>-></tt> operators and through casting)
- * but make sure that the object pointed to is not deleted in the course of
- * use of the pointer by signalling the pointee its use.
+ * like a pointer (i.e. using the <tt>*</tt> and <tt>-></tt> operators and
+ * through casting) but make sure that the object pointed to is not deleted in
+ * the course of use of the pointer by signalling the pointee its use.
*
- * Objects pointed to, i.e. the class T, should inherit
- * Subscriptor or must implement the same functionality. Null pointers
- * are an exception from this rule and are allowed, too.
+ * Objects pointed to, i.e. the class T, should inherit Subscriptor or must
+ * implement the same functionality. Null pointers are an exception from this
+ * rule and are allowed, too.
*
* The second template argument P only serves a single purpose: if a
- * constructor without a debug string is used, then the name of P is
- * used as the debug string.
+ * constructor without a debug string is used, then the name of P is used as
+ * the debug string.
*
- * SmartPointer does NOT implement any memory handling! Especially,
- * deleting a SmartPointer does not delete the object. Writing
+ * SmartPointer does NOT implement any memory handling! Especially, deleting a
+ * SmartPointer does not delete the object. Writing
* @code
* SmartPointer<T,P> dont_do_this = new T;
* @endcode
* @endcode
*
* Note that a smart pointer can handle <tt>const</tt>ness of an object, i.e.
- * a <tt>SmartPointer<const ABC></tt> really behaves as if it were a pointer to
- * a constant object (disallowing write access when dereferenced), while
+ * a <tt>SmartPointer<const ABC></tt> really behaves as if it were a pointer
+ * to a constant object (disallowing write access when dereferenced), while
* <tt>SmartPointer<ABC></tt> is a mutable pointer.
*
* @ingroup memory
{
public:
/**
- * Standard constructor for null
- * pointer. The id of this
- * pointer is set to the name of
- * the class P.
+ * Standard constructor for null pointer. The id of this pointer is set to
+ * the name of the class P.
*/
SmartPointer ();
/**
- * Copy constructor for
- * SmartPointer. We do now
- * copy the object subscribed to
- * from <tt>tt</tt>, but subscribe
- * ourselves to it again.
+ * Copy constructor for SmartPointer. We do now copy the object subscribed
+ * to from <tt>tt</tt>, but subscribe ourselves to it again.
*/
template <class Q>
SmartPointer (const SmartPointer<T,Q> &tt);
/**
- * Copy constructor for
- * SmartPointer. We do now
- * copy the object subscribed to
- * from <tt>tt</tt>, but subscribe
- * ourselves to it again.
+ * Copy constructor for SmartPointer. We do now copy the object subscribed
+ * to from <tt>tt</tt>, but subscribe ourselves to it again.
*/
SmartPointer (const SmartPointer<T,P> &tt);
/**
- * Constructor taking a normal
- * pointer. If possible, i.e. if
- * the pointer is not a null
- * pointer, the constructor
- * subscribes to the given object
- * to lock it, i.e. to prevent
- * its destruction before the end
- * of its use.
+ * Constructor taking a normal pointer. If possible, i.e. if the pointer is
+ * not a null pointer, the constructor subscribes to the given object to
+ * lock it, i.e. to prevent its destruction before the end of its use.
*
- * The <tt>id</tt> is used in the
- * call to
- * Subscriptor::subscribe(id) and
- * by ~SmartPointer() in the call
- * to Subscriptor::unsubscribe().
+ * The <tt>id</tt> is used in the call to Subscriptor::subscribe(id) and by
+ * ~SmartPointer() in the call to Subscriptor::unsubscribe().
*/
SmartPointer (T *t, const char *id);
/**
- * Constructor taking a normal
- * pointer. If possible, i.e. if
- * the pointer is not a null
- * pointer, the constructor
- * subscribes to the given object
- * to lock it, i.e. to prevent
- * its destruction before the end
- * of its use. The id of this
- * pointer is set to the name of
- * the class P.
+ * Constructor taking a normal pointer. If possible, i.e. if the pointer is
+ * not a null pointer, the constructor subscribes to the given object to
+ * lock it, i.e. to prevent its destruction before the end of its use. The
+ * id of this pointer is set to the name of the class P.
*/
SmartPointer (T *t);
/**
- * Destructor, removing the
- * subscription.
+ * Destructor, removing the subscription.
*/
~SmartPointer();
/**
- * Assignment operator for normal
- * pointers. The pointer
- * subscribes to the new object
- * automatically and unsubscribes
- * to an old one if it exists. It
- * will not try to subscribe to a
- * null-pointer, but still
- * delete the old subscription.
+ * Assignment operator for normal pointers. The pointer subscribes to the
+ * new object automatically and unsubscribes to an old one if it exists. It
+ * will not try to subscribe to a null-pointer, but still delete the old
+ * subscription.
*/
SmartPointer<T,P> &operator= (T *tt);
/**
- * Assignment operator for
- * SmartPointer. The pointer
- * subscribes to the new object
- * automatically and unsubscribes
- * to an old one if it exists.
+ * Assignment operator for SmartPointer. The pointer subscribes to the new
+ * object automatically and unsubscribes to an old one if it exists.
*/
template <class Q>
SmartPointer<T,P> &operator= (const SmartPointer<T,Q> &tt);
/**
- * Assignment operator for
- * SmartPointer. The pointer
- * subscribes to the new object
- * automatically and unsubscribes
- * to an old one if it exists.
+ * Assignment operator for SmartPointer. The pointer subscribes to the new
+ * object automatically and unsubscribes to an old one if it exists.
*/
SmartPointer<T,P> &operator= (const SmartPointer<T,P> &tt);
/**
- * Delete the object pointed to
- * and set the pointer to zero.
+ * Delete the object pointed to and set the pointer to zero.
*/
void clear ();
operator T *() const;
/**
- * Dereferencing operator. This
- * operator throws an
- * ExcNotInitialized if the
+ * Dereferencing operator. This operator throws an ExcNotInitialized if the
* pointer is a null pointer.
*/
T &operator * () const;
/**
- * Dereferencing operator. This
- * operator throws an
- * ExcNotInitialized if the
+ * Dereferencing operator. This operator throws an ExcNotInitialized if the
* pointer is a null pointer.
*/
T *operator -> () const;
/**
- * Exchange the pointers of this
- * object and the argument. Since
- * both the objects to which is
- * pointed are subscribed to
- * before and after, we do not
- * have to change their
- * subscription counters.
+ * Exchange the pointers of this object and the argument. Since both the
+ * objects to which is pointed are subscribed to before and after, we do not
+ * have to change their subscription counters.
*
- * Note that this function (with
- * two arguments) and the
- * respective functions where one
- * of the arguments is a pointer
- * and the other one is a C-style
- * pointer are implemented in
- * global namespace.
+ * Note that this function (with two arguments) and the respective functions
+ * where one of the arguments is a pointer and the other one is a C-style
+ * pointer are implemented in global namespace.
*/
template <class Q>
void swap (SmartPointer<T,Q> &tt);
/**
- * Swap pointers between this
- * object and the pointer
- * given. As this releases the
- * object pointed to presently,
- * we reduce its subscription
- * count by one, and increase it
- * at the object which we will
- * point to in the future.
+ * Swap pointers between this object and the pointer given. As this releases
+ * the object pointed to presently, we reduce its subscription count by one,
+ * and increase it at the object which we will point to in the future.
*
- * Note that we indeed need a
- * reference of a pointer, as we
- * want to change the pointer
- * variable which we are given.
+ * Note that we indeed need a reference of a pointer, as we want to change
+ * the pointer variable which we are given.
*/
void swap (T *&tt);
/**
- * Return an estimate of the
- * amount of memory (in bytes)
- * used by this class. Note in
- * particular, that this only
- * includes the amount of memory
- * used by <b>this</b> object, not
- * by the object pointed to.
+ * Return an estimate of the amount of memory (in bytes) used by this class.
+ * Note in particular, that this only includes the amount of memory used by
+ * <b>this</b> object, not by the object pointed to.
*/
std::size_t memory_consumption () const;
private:
/**
- * Pointer to the object we want
- * to subscribt to. Since it is
- * often necessary to follow this
- * pointer when debugging, we
- * have deliberately chosen a
- * short name.
+ * Pointer to the object we want to subscribt to. Since it is often
+ * necessary to follow this pointer when debugging, we have deliberately
+ * chosen a short name.
*/
T *t;
/**
- * The identification for the
- * subscriptor.
+ * The identification for the subscriptor.
*/
const char *const id;
};
// compiler.
#ifndef _MSC_VER
/**
- * Global function to swap the contents of two smart pointers. As both
- * objects to which the pointers point retain to be subscribed to, we
- * do not have to change their subscription count.
+ * Global function to swap the contents of two smart pointers. As both objects
+ * to which the pointers point retain to be subscribed to, we do not have to
+ * change their subscription count.
*/
template <typename T, typename P, class Q>
inline
/**
- * Global function to swap the contents of a smart pointer and a
- * C-style pointer.
+ * Global function to swap the contents of a smart pointer and a C-style
+ * pointer.
*
- * Note that we indeed need a reference of a pointer, as we want to
- * change the pointer variable which we are given.
+ * Note that we indeed need a reference of a pointer, as we want to change the
+ * pointer variable which we are given.
*/
template <typename T, typename P>
inline
/**
- * Global function to swap the contents of a C-style pointer and a
- * smart pointer.
+ * Global function to swap the contents of a C-style pointer and a smart
+ * pointer.
*
- * Note that we indeed need a reference of a pointer, as we want to
- * change the pointer variable which we are given.
+ * Note that we indeed need a reference of a pointer, as we want to change the
+ * pointer variable which we are given.
*/
template <typename T, typename P>
inline
/**
* Handling of subscriptions.
*
- * This class, as a base class, allows to keep track of other objects
- * using a specific object. It is used, when an object, given to a
- * constructor by reference, is stored. Then, the original object may
- * not be deleted before the dependent object is deleted. You can assert
- * this constraint by letting the object passed be derived from this class
- * and let the user subscribe() to this object. The destructor the used
- * object inherits from the Subscriptor class then will lead to an error
- * when destruction is attempted while there are still subscriptions.
+ * This class, as a base class, allows to keep track of other objects using a
+ * specific object. It is used, when an object, given to a constructor by
+ * reference, is stored. Then, the original object may not be deleted before
+ * the dependent object is deleted. You can assert this constraint by letting
+ * the object passed be derived from this class and let the user subscribe()
+ * to this object. The destructor the used object inherits from the
+ * Subscriptor class then will lead to an error when destruction is attempted
+ * while there are still subscriptions.
*
- * The utility of this class is even enhanced by providing identifying
- * strings to the functions subscribe() and unsubscribe(). In case of
- * a hanging subscription during destruction, this string will be
- * listed in the exception's message. For reasons of efficiency, these
- * strings are handled as <tt>const char*</tt>. Therefore, the
- * pointers provided to subscribe() and to unsubscribe() must be the
- * same. Strings with equal contents will not be recognized to be the
- * same. The handling in SmartPointer will take care of this.
+ * The utility of this class is even enhanced by providing identifying strings
+ * to the functions subscribe() and unsubscribe(). In case of a hanging
+ * subscription during destruction, this string will be listed in the
+ * exception's message. For reasons of efficiency, these strings are handled
+ * as <tt>const char*</tt>. Therefore, the pointers provided to subscribe()
+ * and to unsubscribe() must be the same. Strings with equal contents will not
+ * be recognized to be the same. The handling in SmartPointer will take care
+ * of this.
*
- * @note Due to a problem with <tt>volatile</tt> declarations, this
- * additional feature is switched off if multithreading is used.
+ * @note Due to a problem with <tt>volatile</tt> declarations, this additional
+ * feature is switched off if multithreading is used.
*
* @ingroup memory
* @author Guido Kanschat, 1998 - 2005
/**
* Copy-constructor.
*
- * The counter of the copy is zero,
- * since references point to the
- * original object.
+ * The counter of the copy is zero, since references point to the original
+ * object.
*/
Subscriptor(const Subscriptor &);
/**
- * Destructor, asserting that the counter
- * is zero.
+ * Destructor, asserting that the counter is zero.
*/
virtual ~Subscriptor();
/**
* Assignment operator.
*
- * This has to be handled with
- * care, too, because the counter
- * has to remain the same. It therefore
- * does nothing more than returning
- * <tt>*this</tt>.
+ * This has to be handled with care, too, because the counter has to remain
+ * the same. It therefore does nothing more than returning <tt>*this</tt>.
*/
Subscriptor &operator = (const Subscriptor &);
/**
- * Subscribes a user of the
- * object. The subscriber may be
- * identified by text supplied as
- * <tt>identifier</tt>.
+ * Subscribes a user of the object. The subscriber may be identified by text
+ * supplied as <tt>identifier</tt>.
*/
void subscribe (const char *identifier = 0) const;
/**
- * Unsubscribes a user from the
- * object.
+ * Unsubscribes a user from the object.
*
- * @note The <tt>identifier</tt>
- * must be the <b>same
- * pointer</b> as the one
- * supplied to subscribe(), not
- * just the same text.
+ * @note The <tt>identifier</tt> must be the <b>same pointer</b> as the one
+ * supplied to subscribe(), not just the same text.
*/
void unsubscribe (const char *identifier = 0) const;
/**
- * Return the present number of
- * subscriptions to this object.
- * This allows to use this class
- * for reference counted lifetime
- * determination where the last one
- * to unsubscribe also deletes the
- * object.
+ * Return the present number of subscriptions to this object. This allows to
+ * use this class for reference counted lifetime determination where the
+ * last one to unsubscribe also deletes the object.
*/
unsigned int n_subscriptions () const;
*/
void list_subscribers () const;
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
- * Exception:
- * Object may not be deleted, since
- * it is used.
+ * Exception: Object may not be deleted, since it is used.
*/
DeclException3(ExcInUse,
int, char *, std::string &,
<< "more information on what this error means.");
/**
- * A subscriber with the
- * identification string given to
- * Subscriptor::unsubscribe() did
- * not subscribe to the object.
+ * A subscriber with the identification string given to
+ * Subscriptor::unsubscribe() did not subscribe to the object.
*/
DeclException2(ExcNoSubscriber, char *, char *,
<< "No subscriber with identifier \"" << arg2
//@}
/**
- * Read or write the data of this
- * object to or from a stream for
- * the purpose of serialization.
+ * Read or write the data of this object to or from a stream for the purpose
+ * of serialization.
*
- * This function does not
- * actually serialize any of the
- * member variables of this
- * class. The reason is that what
- * this class stores is only who
- * subscribes to this object, but
- * who does so at the time of
- * storing the contents of this
- * object does not necessarily
- * have anything to do with who
- * subscribes to the object when
- * it is restored. Consequently,
- * we do not want to overwrite
- * the subscribers at the time of
- * restoring, and then there is
- * no reason to write the
- * subscribers out in the first
- * place.
+ * This function does not actually serialize any of the member variables of
+ * this class. The reason is that what this class stores is only who
+ * subscribes to this object, but who does so at the time of storing the
+ * contents of this object does not necessarily have anything to do with who
+ * subscribes to the object when it is restored. Consequently, we do not
+ * want to overwrite the subscribers at the time of restoring, and then
+ * there is no reason to write the subscribers out in the first place.
*/
template <class Archive>
void serialize(Archive &ar, const unsigned int version);
private:
/**
- * The data type used in
- * #counter_map.
+ * The data type used in #counter_map.
*/
typedef std::map<const char *, unsigned int>::value_type
map_value_type;
/**
- * The iterator type used in
- * #counter_map.
+ * The iterator type used in #counter_map.
*/
typedef std::map<const char *, unsigned int>::iterator
map_iterator;
/**
- * Store the number of objects
- * which subscribed to this
- * object. Initialally, this
- * number is zero, and upon
- * destruction it shall be zero
- * again (i.e. all objects which
- * subscribed should have
- * unsubscribed again).
+ * Store the number of objects which subscribed to this object. Initialally,
+ * this number is zero, and upon destruction it shall be zero again (i.e.
+ * all objects which subscribed should have unsubscribed again).
*
- * The creator (and owner) of an
- * object is counted in the map
- * below if HE manages to supply
- * identification.
+ * The creator (and owner) of an object is counted in the map below if HE
+ * manages to supply identification.
*
- * We use the <tt>mutable</tt> keyword
- * in order to allow subscription
- * to constant objects also.
+ * We use the <tt>mutable</tt> keyword in order to allow subscription to
+ * constant objects also.
*
- * In multithreaded mode, this
- * counter may be modified by
- * different threads. We thus
- * have to mark it
- * <tt>volatile</tt>. However, this is
- * counter-productive in non-MT
- * mode since it may pessimize
- * code. So use the macro
- * defined above to selectively
- * add volatility.
+ * In multithreaded mode, this counter may be modified by different threads.
+ * We thus have to mark it <tt>volatile</tt>. However, this is counter-
+ * productive in non-MT mode since it may pessimize code. So use the macro
+ * defined above to selectively add volatility.
*/
mutable DEAL_VOLATILE unsigned int counter;
/**
- * In this map, we count
- * subscriptions for each
- * different identification string
- * supplied to subscribe().
+ * In this map, we count subscriptions for each different identification
+ * string supplied to subscribe().
*/
mutable std::map<const char *, unsigned int> counter_map;
/**
- * Pointer to the typeinfo object
- * of this object, from which we
- * can later deduce the class
- * name. Since this information
- * on the derived class is
- * neither available in the
- * destructor, nor in the
- * constructor, we obtain it in
- * between and store it here.
+ * Pointer to the typeinfo object of this object, from which we can later
+ * deduce the class name. Since this information on the derived class is
+ * neither available in the destructor, nor in the constructor, we obtain it
+ * in between and store it here.
*/
mutable const std::type_info *object_info;
};
namespace internal
{
/**
- * A namespace for classes that are
- * internal to how the SymmetricTensor
+ * A namespace for classes that are internal to how the SymmetricTensor
* class works.
*/
namespace SymmetricTensorAccessors
{
/**
- * Create a TableIndices<2>
- * object where the first entries
- * up to <tt>position-1</tt> are
- * taken from previous_indices,
- * and new_index is put at
- * position
- * <tt>position</tt>. The
- * remaining indices remain in
+ * Create a TableIndices<2> object where the first entries up to
+ * <tt>position-1</tt> are taken from previous_indices, and new_index is
+ * put at position <tt>position</tt>. The remaining indices remain in
* invalid state.
*/
inline
/**
- * Create a TableIndices<4>
- * object where the first entries
- * up to <tt>position-1</tt> are
- * taken from previous_indices,
- * and new_index is put at
- * position
- * <tt>position</tt>. The
- * remaining indices remain in
+ * Create a TableIndices<4> object where the first entries up to
+ * <tt>position-1</tt> are taken from previous_indices, and new_index is
+ * put at position <tt>position</tt>. The remaining indices remain in
* invalid state.
*/
inline
/**
- * Typedef template magic
- * denoting the result of a
- * double contraction between two
- * tensors or ranks rank1 and
- * rank2. In general, this is a
- * tensor of rank
- * <tt>rank1+rank2-4</tt>, but if
- * this is zero it is a single
- * scalar Number. For this case,
- * we have a specialization.
+ * Typedef template magic denoting the result of a double contraction
+ * between two tensors or ranks rank1 and rank2. In general, this is a
+ * tensor of rank <tt>rank1+rank2-4</tt>, but if this is zero it is a
+ * single scalar Number. For this case, we have a specialization.
*
* @author Wolfgang Bangerth, 2005
*/
/**
- * Typedef template magic
- * denoting the result of a
- * double contraction between two
- * tensors or ranks rank1 and
- * rank2. In general, this is a
- * tensor of rank
- * <tt>rank1+rank2-4</tt>, but if
- * this is zero it is a single
- * scalar Number. For this case,
- * we have a specialization.
+ * Typedef template magic denoting the result of a double contraction
+ * between two tensors or ranks rank1 and rank2. In general, this is a
+ * tensor of rank <tt>rank1+rank2-4</tt>, but if this is zero it is a
+ * single scalar Number. For this case, we have a specialization.
*
* @author Wolfgang Bangerth, 2005
*/
/**
- * Declaration of typedefs for the type
- * of data structures which are used to
- * store symmetric tensors. For example,
- * for rank-2 symmetric tensors, we use a
- * flat vector to store all the
- * elements. On the other hand, symmetric
- * rank-4 tensors are mappings from
- * symmetric rank-2 tensors into
- * symmetric rank-2 tensors, so they can
- * be represented as matrices, etc.
+ * Declaration of typedefs for the type of data structures which are used
+ * to store symmetric tensors. For example, for rank-2 symmetric tensors,
+ * we use a flat vector to store all the elements. On the other hand,
+ * symmetric rank-4 tensors are mappings from symmetric rank-2 tensors
+ * into symmetric rank-2 tensors, so they can be represented as matrices,
+ * etc.
*
- * This information is probably of little
- * interest to all except the accessor
- * classes that need it. In particular,
- * you shouldn't make any assumptions
- * about the storage format in your
- * application programs.
+ * This information is probably of little interest to all except the
+ * accessor classes that need it. In particular, you shouldn't make any
+ * assumptions about the storage format in your application programs.
*/
template <int rank, int dim, typename Number>
struct StorageType;
/**
- * Specialization of StorageType for
- * rank-2 tensors.
+ * Specialization of StorageType for rank-2 tensors.
*/
template <int dim, typename Number>
struct StorageType<2,dim,Number>
{
/**
- * Number of independent components of a
- * symmetric tensor of rank 2. We store
- * only the upper right half of it.
+ * Number of independent components of a symmetric tensor of rank 2. We
+ * store only the upper right half of it.
*/
static const unsigned int
n_independent_components = (dim*dim + dim)/2;
/**
- * Declare the type in which we actually
- * store the data.
+ * Declare the type in which we actually store the data.
*/
typedef Tensor<1,n_independent_components,Number> base_tensor_type;
};
/**
- * Specialization of StorageType for
- * rank-4 tensors.
+ * Specialization of StorageType for rank-4 tensors.
*/
template <int dim, typename Number>
struct StorageType<4,dim,Number>
{
/**
- * Number of independent components
- * of a symmetric tensor of rank
- * 2. Since rank-4 tensors are
- * mappings between such objects, we
- * need this information.
+ * Number of independent components of a symmetric tensor of rank 2.
+ * Since rank-4 tensors are mappings between such objects, we need this
+ * information.
*/
static const unsigned int
n_rank2_components = (dim*dim + dim)/2;
/**
- * Number of independent components of a
- * symmetric tensor of rank 4.
+ * Number of independent components of a symmetric tensor of rank 4.
*/
static const unsigned int
n_independent_components = (n_rank2_components *
StorageType<2,dim,Number>::n_independent_components);
/**
- * Declare the type in which we
- * actually store the data. Symmetric
- * rank-4 tensors are mappings
- * between symmetric rank-2 tensors,
- * so we can represent the data as a
- * matrix if we represent the rank-2
- * tensors as vectors.
+ * Declare the type in which we actually store the data. Symmetric
+ * rank-4 tensors are mappings between symmetric rank-2 tensors, so we
+ * can represent the data as a matrix if we represent the rank-2 tensors
+ * as vectors.
*/
typedef Tensor<2,n_rank2_components,Number> base_tensor_type;
};
/**
- * Switch type to select a tensor of
- * rank 2 and dimension <tt>dim</tt>,
- * switching on whether the tensor
- * should be constant or not.
+ * Switch type to select a tensor of rank 2 and dimension <tt>dim</tt>,
+ * switching on whether the tensor should be constant or not.
*/
template <int rank, int dim, bool constness, typename Number>
struct AccessorTypes;
/**
- * Switch type to select a tensor of
- * rank 2 and dimension <tt>dim</tt>,
- * switching on whether the tensor
- * should be constant or not.
+ * Switch type to select a tensor of rank 2 and dimension <tt>dim</tt>,
+ * switching on whether the tensor should be constant or not.
*
* Specialization for constant tensors.
*/
};
/**
- * Switch type to select a tensor of
- * rank 2 and dimension <tt>dim</tt>,
- * switching on whether the tensor
- * should be constant or not.
+ * Switch type to select a tensor of rank 2 and dimension <tt>dim</tt>,
+ * switching on whether the tensor should be constant or not.
*
- * Specialization for non-constant
- * tensors.
+ * Specialization for non-constant tensors.
*/
template <int rank, int dim, typename Number>
struct AccessorTypes<rank,dim,false,Number>
/**
* @internal
*
- * Class that acts as accessor to elements of type
- * SymmetricTensor. The template parameter <tt>C</tt> may be either
- * true or false, and indicates whether the objects worked on are
- * constant or not (i.e. write access is only allowed if the value is
- * false).
+ * Class that acts as accessor to elements of type SymmetricTensor. The
+ * template parameter <tt>C</tt> may be either true or false, and
+ * indicates whether the objects worked on are constant or not (i.e. write
+ * access is only allowed if the value is false).
*
* Since with <tt>N</tt> indices, the effect of applying
* <tt>operator[]</tt> is getting access to something we <tt>N-1</tt>
- * indices, we have to implement these accessor classes recursively,
- * with stopping when we have only one index left. For the latter
- * case, a specialization of this class is declared below, where
- * calling <tt>operator[]</tt> gives you access to the objects
- * actually stored by the tensor; the tensor class also makes sure
- * that only those elements are actually accessed which we actually
- * store, i.e. it reorders indices if necessary. The template
- * parameter <tt>P</tt> indicates how many remaining indices there
- * are. For a rank-2 tensor, <tt>P</tt> may be two, and when using
- * <tt>operator[]</tt>, an object with <tt>P=1</tt> emerges.
+ * indices, we have to implement these accessor classes recursively, with
+ * stopping when we have only one index left. For the latter case, a
+ * specialization of this class is declared below, where calling
+ * <tt>operator[]</tt> gives you access to the objects actually stored by
+ * the tensor; the tensor class also makes sure that only those elements
+ * are actually accessed which we actually store, i.e. it reorders indices
+ * if necessary. The template parameter <tt>P</tt> indicates how many
+ * remaining indices there are. For a rank-2 tensor, <tt>P</tt> may be
+ * two, and when using <tt>operator[]</tt>, an object with <tt>P=1</tt>
+ * emerges.
*
* As stated for the entire namespace, you will not usually have to do
- * with these classes directly, and should not try to use their
- * interface directly as it may change without notice. In fact, since
- * the constructors are made private, you will not even be able to
- * generate objects of this class, as they are only thought as
- * temporaries for access to elements of the table class, not for
- * passing them around as arguments of functions, etc.
+ * with these classes directly, and should not try to use their interface
+ * directly as it may change without notice. In fact, since the
+ * constructors are made private, you will not even be able to generate
+ * objects of this class, as they are only thought as temporaries for
+ * access to elements of the table class, not for passing them around as
+ * arguments of functions, etc.
*
* This class is an adaptation of a similar class used for the Table
* class.
{
public:
/**
- * Import two typedefs from the
- * switch class above.
+ * Import two typedefs from the switch class above.
*/
typedef typename AccessorTypes<rank,dim,constness,Number>::reference reference;
typedef typename AccessorTypes<rank,dim,constness,Number>::tensor_type tensor_type;
private:
/**
- * Constructor. Take a
- * reference to the tensor
- * object which we will
+ * Constructor. Take a reference to the tensor object which we will
* access.
*
- * The second argument
- * denotes the values of
- * previous indices into the
- * tensor. For example, for a
- * rank-4 tensor, if P=2,
- * then we will already have
- * had two successive element
- * selections (e.g. through
- * <tt>tensor[1][2]</tt>),
- * and the two index values
- * have to be stored
- * somewhere. This class
- * therefore only makes use
- * of the first rank-P
- * elements of this array,
- * but passes it on to the
- * next level with P-1 which
- * fills the next entry, and
- * so on.
+ * The second argument denotes the values of previous indices into the
+ * tensor. For example, for a rank-4 tensor, if P=2, then we will
+ * already have had two successive element selections (e.g. through
+ * <tt>tensor[1][2]</tt>), and the two index values have to be stored
+ * somewhere. This class therefore only makes use of the first rank-P
+ * elements of this array, but passes it on to the next level with P-1
+ * which fills the next entry, and so on.
*
- * The constructor is made
- * private in order to prevent
- * you having such objects
- * around. The only way to
- * create such objects is via
- * the <tt>Table</tt> class, which
- * only generates them as
- * temporary objects. This
- * guarantees that the accessor
- * objects go out of scope
- * earlier than the mother
- * object, avoid problems with
- * data consistency.
+ * The constructor is made private in order to prevent you having such
+ * objects around. The only way to create such objects is via the
+ * <tt>Table</tt> class, which only generates them as temporary objects.
+ * This guarantees that the accessor objects go out of scope earlier
+ * than the mother object, avoid problems with data consistency.
*/
Accessor (tensor_type &tensor,
const TableIndices<rank> &previous_indices);
/**
- * Default constructor. Not
- * needed, and invisible, so
- * private.
+ * Default constructor. Not needed, and invisible, so private.
*/
Accessor ();
/**
- * Copy constructor. Not
- * needed, and invisible, so
- * private.
+ * Copy constructor. Not needed, and invisible, so private.
*/
Accessor (const Accessor &a);
private:
/**
- * Store the data given to the
- * constructor.
+ * Store the data given to the constructor.
*/
tensor_type &tensor;
const TableIndices<rank> previous_indices;
/**
- * @internal
- * Accessor class for SymmetricTensor. This is the specialization for the last
- * index, which actually allows access to the elements of the table,
- * rather than recursively returning access objects for further
- * subsets. The same holds for this specialization as for the general
- * template; see there for more information.
+ * @internal Accessor class for SymmetricTensor. This is the
+ * specialization for the last index, which actually allows access to the
+ * elements of the table, rather than recursively returning access objects
+ * for further subsets. The same holds for this specialization as for the
+ * general template; see there for more information.
*
* @author Wolfgang Bangerth, 2002, 2005
*/
{
public:
/**
- * Import two typedefs from the
- * switch class above.
+ * Import two typedefs from the switch class above.
*/
typedef typename AccessorTypes<rank,dim,constness,Number>::reference reference;
typedef typename AccessorTypes<rank,dim,constness,Number>::tensor_type tensor_type;
private:
/**
- * Constructor. Take a
- * reference to the tensor
- * object which we will
+ * Constructor. Take a reference to the tensor object which we will
* access.
*
- * The second argument
- * denotes the values of
- * previous indices into the
- * tensor. For example, for a
- * rank-4 tensor, if P=2,
- * then we will already have
- * had two successive element
- * selections (e.g. through
- * <tt>tensor[1][2]</tt>),
- * and the two index values
- * have to be stored
- * somewhere. This class
- * therefore only makes use
- * of the first rank-P
- * elements of this array,
- * but passes it on to the
- * next level with P-1 which
- * fills the next entry, and
- * so on.
+ * The second argument denotes the values of previous indices into the
+ * tensor. For example, for a rank-4 tensor, if P=2, then we will
+ * already have had two successive element selections (e.g. through
+ * <tt>tensor[1][2]</tt>), and the two index values have to be stored
+ * somewhere. This class therefore only makes use of the first rank-P
+ * elements of this array, but passes it on to the next level with P-1
+ * which fills the next entry, and so on.
*
- * For this particular
- * specialization, i.e. for
- * P==1, all but the last
+ * For this particular specialization, i.e. for P==1, all but the last
* index are already filled.
*
- * The constructor is made
- * private in order to prevent
- * you having such objects
- * around. The only way to
- * create such objects is via
- * the <tt>Table</tt> class, which
- * only generates them as
- * temporary objects. This
- * guarantees that the accessor
- * objects go out of scope
- * earlier than the mother
- * object, avoid problems with
- * data consistency.
+ * The constructor is made private in order to prevent you having such
+ * objects around. The only way to create such objects is via the
+ * <tt>Table</tt> class, which only generates them as temporary objects.
+ * This guarantees that the accessor objects go out of scope earlier
+ * than the mother object, avoid problems with data consistency.
*/
Accessor (tensor_type &tensor,
const TableIndices<rank> &previous_indices);
/**
- * Default constructor. Not
- * needed, and invisible, so
- * private.
+ * Default constructor. Not needed, and invisible, so private.
*/
Accessor ();
/**
- * Copy constructor. Not
- * needed, and invisible, so
- * private.
+ * Copy constructor. Not needed, and invisible, so private.
*/
Accessor (const Accessor &a);
private:
/**
- * Store the data given to the
- * constructor.
+ * Store the data given to the constructor.
*/
tensor_type &tensor;
const TableIndices<rank> previous_indices;
* example for the 3x3x3x3 tensors of rank 4, only 36 instead of the full 81
* entries have to be stored.
*
- * While the definition of a symmetric rank-2 tensor is obvious,
- * tensors of rank 4 are considered symmetric if they are operators
- * mapping symmetric rank-2 tensors onto symmetric rank-2
- * tensors. This entails certain symmetry properties on the elements
- * in their 4-dimensional index space, in particular that
- * <tt>C<sub>ijkl</sub>=C<sub>jikl</sub>=C<sub>ijlk</sub></tt>. However,
- * it does not imply the relation
- * <tt>C<sub>ijkl</sub>=C<sub>klij</sub></tt>. Consequently, symmetric
- * tensors of rank 4 as understood here are only tensors that map
- * symmetric tensors onto symmetric tensors, but they do not
- * necessarily induce a symmetric scalar product <tt>a:C:b=b:C:a</tt>
- * or even a positive (semi-)definite form <tt>a:C:a</tt>, where
- * <tt>a,b</tt> are symmetric rank-2 tensors and the colon indicates
- * the common double-index contraction that acts as a product for
- * symmetric tensors.
+ * While the definition of a symmetric rank-2 tensor is obvious, tensors of
+ * rank 4 are considered symmetric if they are operators mapping symmetric
+ * rank-2 tensors onto symmetric rank-2 tensors. This entails certain symmetry
+ * properties on the elements in their 4-dimensional index space, in
+ * particular that
+ * <tt>C<sub>ijkl</sub>=C<sub>jikl</sub>=C<sub>ijlk</sub></tt>. However, it
+ * does not imply the relation <tt>C<sub>ijkl</sub>=C<sub>klij</sub></tt>.
+ * Consequently, symmetric tensors of rank 4 as understood here are only
+ * tensors that map symmetric tensors onto symmetric tensors, but they do not
+ * necessarily induce a symmetric scalar product <tt>a:C:b=b:C:a</tt> or even
+ * a positive (semi-)definite form <tt>a:C:a</tt>, where <tt>a,b</tt> are
+ * symmetric rank-2 tensors and the colon indicates the common double-index
+ * contraction that acts as a product for symmetric tensors.
*
* Symmetric tensors are most often used in structural and fluid mechanics,
- * where strains and stresses are usually symmetric tensors, and the
- * stress-strain relationship is given by a symmetric rank-4 tensor.
+ * where strains and stresses are usually symmetric tensors, and the stress-
+ * strain relationship is given by a symmetric rank-4 tensor.
*
* Note that symmetric tensors only exist with even numbers of indices. In
* other words, the only objects that you can use are
*
* <h3>Accessing elements</h3>
*
- * The elements of a tensor <tt>t</tt> can be accessed using the
- * bracket operator, i.e. for a tensor of rank 4,
- * <tt>t[0][1][0][1]</tt> accesses the element
- * <tt>t<sub>0101</sub></tt>. This access can be used for both reading
- * and writing (if the tensor is non-constant at least). You may also
- * perform other operations on it, although that may lead to confusing
- * situations because several elements of the tensor are stored at the
- * same location. For example, for a rank-2 tensor that is assumed to
- * be zero at the beginning, writing <tt>t[0][1]+=1; t[1][0]+=1;</tt>
- * will lead to the same element being increased by one
- * <em>twice</em>, because even though the accesses use different
- * indices, the elements that are accessed are symmetric and therefore
- * stored at the same location. It may therefore be useful in
- * application programs to restrict operations on individual elements
- * to simple reads or writes.
+ * The elements of a tensor <tt>t</tt> can be accessed using the bracket
+ * operator, i.e. for a tensor of rank 4, <tt>t[0][1][0][1]</tt> accesses the
+ * element <tt>t<sub>0101</sub></tt>. This access can be used for both reading
+ * and writing (if the tensor is non-constant at least). You may also perform
+ * other operations on it, although that may lead to confusing situations
+ * because several elements of the tensor are stored at the same location. For
+ * example, for a rank-2 tensor that is assumed to be zero at the beginning,
+ * writing <tt>t[0][1]+=1; t[1][0]+=1;</tt> will lead to the same element
+ * being increased by one <em>twice</em>, because even though the accesses use
+ * different indices, the elements that are accessed are symmetric and
+ * therefore stored at the same location. It may therefore be useful in
+ * application programs to restrict operations on individual elements to
+ * simple reads or writes.
*
* @ingroup geomprimitives
* @author Wolfgang Bangerth, 2005
{
public:
/**
- * Provide a way to get the
- * dimension of an object without
- * explicit knowledge of it's
- * data type. Implementation is
- * this way instead of providing
- * a function <tt>dimension()</tt>
- * because now it is possible to
- * get the dimension at compile
- * time without the expansion and
- * preevaluation of an inlined
- * function; the compiler may
- * therefore produce more
- * efficient code and you may use
- * this value to declare other
- * data types.
+ * Provide a way to get the dimension of an object without explicit
+ * knowledge of it's data type. Implementation is this way instead of
+ * providing a function <tt>dimension()</tt> because now it is possible to
+ * get the dimension at compile time without the expansion and preevaluation
+ * of an inlined function; the compiler may therefore produce more efficient
+ * code and you may use this value to declare other data types.
*/
static const unsigned int dimension = dim;
/**
- * An integer denoting the number of
- * independent components that fully
- * describe a symmetric tensor. In $d$
- * space dimensions, this number equals
- * $\frac 12 (d^2+d)$ for symmetric
- * tensors of rank 2.
+ * An integer denoting the number of independent components that fully
+ * describe a symmetric tensor. In $d$ space dimensions, this number equals
+ * $\frac 12 (d^2+d)$ for symmetric tensors of rank 2.
*/
static const unsigned int n_independent_components
= internal::SymmetricTensorAccessors::StorageType<rank,dim,Number>::
n_independent_components;
/**
- * Default constructor. Creates a zero
- * tensor.
+ * Default constructor. Creates a zero tensor.
*/
SymmetricTensor ();
/**
- * Constructor. Generate a symmetric
- * tensor from a general one. Assumes
- * that @p t is already symmetric, and in
- * debug mode this is in fact
- * checked. Note that no provision is
- * made to assure that the tensor is
- * symmetric only up to round-off error:
- * if the incoming tensor is not exactly
- * symmetric, then an exception is
- * thrown. If you know that incoming
- * tensor is symmetric only up to
- * round-off, then you may want to call
- * the <tt>symmetrize</tt> function
- * first. If you aren't sure, it is good
- * practice to check before calling
- * <tt>symmetrize</tt>.
+ * Constructor. Generate a symmetric tensor from a general one. Assumes that
+ * @p t is already symmetric, and in debug mode this is in fact checked.
+ * Note that no provision is made to assure that the tensor is symmetric
+ * only up to round-off error: if the incoming tensor is not exactly
+ * symmetric, then an exception is thrown. If you know that incoming tensor
+ * is symmetric only up to round-off, then you may want to call the
+ * <tt>symmetrize</tt> function first. If you aren't sure, it is good
+ * practice to check before calling <tt>symmetrize</tt>.
*/
SymmetricTensor (const Tensor<2,dim,Number> &t);
/**
- * A constructor that creates a
- * symmetric tensor from an array
- * holding its independent
- * elements. Using this
- * constructor assumes that the
- * caller knows the order in
- * which elements are stored in
- * symmetric tensors; its use is
- * therefore discouraged, but if
- * you think you want to use it
- * anyway you can query the order
- * of elements using the
- * unrolled_index() function.
+ * A constructor that creates a symmetric tensor from an array holding its
+ * independent elements. Using this constructor assumes that the caller
+ * knows the order in which elements are stored in symmetric tensors; its
+ * use is therefore discouraged, but if you think you want to use it anyway
+ * you can query the order of elements using the unrolled_index() function.
*
- * This constructor is currently only
- * implemented for symmetric tensors of
+ * This constructor is currently only implemented for symmetric tensors of
* rank 2.
*
- * The size of the array passed
- * is equal to
- * SymmetricTensor<rank,dim>::n_independent_component;
- * the reason for using the
- * object from the internal
- * namespace is to work around
- * bugs in some older compilers.
+ * The size of the array passed is equal to
+ * SymmetricTensor<rank,dim>::n_independent_component; the reason for using
+ * the object from the internal namespace is to work around bugs in some
+ * older compilers.
*/
SymmetricTensor (const Number (&array) [n_independent_components]);
/**
- * Assignment operator.
+ * Assignment operator.
*/
SymmetricTensor &operator = (const SymmetricTensor &);
/**
- * This operator assigns a scalar
- * to a tensor. To avoid
- * confusion with what exactly it
- * means to assign a scalar value
- * to a tensor, zero is the only
- * value allowed for <tt>d</tt>,
- * allowing the intuitive
- * notation <tt>t=0</tt> to reset
- * all elements of the tensor to
- * zero.
+ * This operator assigns a scalar to a tensor. To avoid confusion with what
+ * exactly it means to assign a scalar value to a tensor, zero is the only
+ * value allowed for <tt>d</tt>, allowing the intuitive notation
+ * <tt>t=0</tt> to reset all elements of the tensor to zero.
*/
SymmetricTensor &operator = (const Number d);
/**
- * Convert the present symmetric tensor
- * into a full tensor with the same
- * elements, but using the different
- * storage scheme of full tensors.
+ * Convert the present symmetric tensor into a full tensor with the same
+ * elements, but using the different storage scheme of full tensors.
*/
operator Tensor<rank,dim,Number> () const;
/**
- * Test for equality of two tensors.
+ * Test for equality of two tensors.
*/
bool operator == (const SymmetricTensor &) const;
/**
- * Test for inequality of two tensors.
+ * Test for inequality of two tensors.
*/
bool operator != (const SymmetricTensor &) const;
/**
- * Add another tensor.
+ * Add another tensor.
*/
SymmetricTensor &operator += (const SymmetricTensor &);
/**
- * Subtract another tensor.
+ * Subtract another tensor.
*/
SymmetricTensor &operator -= (const SymmetricTensor &);
/**
- * Scale the tensor by <tt>factor</tt>,
- * i.e. multiply all components by
- * <tt>factor</tt>.
+ * Scale the tensor by <tt>factor</tt>, i.e. multiply all components by
+ * <tt>factor</tt>.
*/
SymmetricTensor &operator *= (const Number factor);
/**
- * Scale the vector by
- * <tt>1/factor</tt>.
+ * Scale the vector by <tt>1/factor</tt>.
*/
SymmetricTensor &operator /= (const Number factor);
/**
- * Add two tensors. If possible, you
- * should use <tt>operator +=</tt>
- * instead since this does not need the
- * creation of a temporary.
+ * Add two tensors. If possible, you should use <tt>operator +=</tt> instead
+ * since this does not need the creation of a temporary.
*/
SymmetricTensor operator + (const SymmetricTensor &s) const;
/**
- * Subtract two tensors. If possible,
- * you should use <tt>operator -=</tt>
- * instead since this does not need the
- * creation of a temporary.
+ * Subtract two tensors. If possible, you should use <tt>operator -=</tt>
+ * instead since this does not need the creation of a temporary.
*/
SymmetricTensor operator - (const SymmetricTensor &s) const;
/**
- * Unary minus operator. Negate all
- * entries of a tensor.
+ * Unary minus operator. Negate all entries of a tensor.
*/
SymmetricTensor operator - () const;
/**
- * Product between the present
- * symmetric tensor and a tensor
- * of rank 2. For example, if the
- * present object is also a
- * rank-2 tensor, then this is
- * the scalar-product double
- * contraction
- * <tt>a<sub>ij</sub>b<sub>ij</sub></tt>
- * over all indices
- * <tt>i,j</tt>. In this case,
- * the return value evaluates to
- * a single scalar. While it is
- * possible to define other
- * scalar product (and associated
- * induced norms), this one seems
- * to be the most appropriate
+ * Product between the present symmetric tensor and a tensor of rank 2. For
+ * example, if the present object is also a rank-2 tensor, then this is the
+ * scalar-product double contraction <tt>a<sub>ij</sub>b<sub>ij</sub></tt>
+ * over all indices <tt>i,j</tt>. In this case, the return value evaluates
+ * to a single scalar. While it is possible to define other scalar product
+ * (and associated induced norms), this one seems to be the most appropriate
* one.
*
- * If the present object is a
- * rank-4 tensor, then the result
- * is a rank-2 tensor, i.e., the
- * operation contracts over the
- * last two indices of the
- * present object and the indices
- * of the argument, and the
- * result is a tensor of rank 2.
+ * If the present object is a rank-4 tensor, then the result is a rank-2
+ * tensor, i.e., the operation contracts over the last two indices of the
+ * present object and the indices of the argument, and the result is a
+ * tensor of rank 2.
*
- * Note that the multiplication
- * operator for symmetrict
- * tensors is defined to be a
- * double contraction over two
- * indices, while it is defined
- * as a single contraction over
- * only one index for regular
- * <tt>Tensor</tt> objects. For
- * symmetric tensors it therefore
- * acts in a way that is commonly
- * denoted by a "colon
- * multiplication" in the
- * mathematica literature.
+ * Note that the multiplication operator for symmetrict tensors is defined
+ * to be a double contraction over two indices, while it is defined as a
+ * single contraction over only one index for regular <tt>Tensor</tt>
+ * objects. For symmetric tensors it therefore acts in a way that is
+ * commonly denoted by a "colon multiplication" in the mathematica
+ * literature.
*
- * There are global functions
- * <tt>double_contract</tt> that
- * do the same work as this
- * operator, but rather than
- * returning the result as a
- * return value, they write it
- * into the first argument to the
- * function.
+ * There are global functions <tt>double_contract</tt> that do the same work
+ * as this operator, but rather than returning the result as a return value,
+ * they write it into the first argument to the function.
*/
typename internal::SymmetricTensorAccessors::double_contraction_result<rank,2,dim,Number>::type
operator * (const SymmetricTensor<2,dim,Number> &s) const;
/**
- * Contraction over two indices
- * of the present object with the
- * rank-4 symmetric tensor given
- * as argument.
+ * Contraction over two indices of the present object with the rank-4
+ * symmetric tensor given as argument.
*/
typename internal::SymmetricTensorAccessors::double_contraction_result<rank,4,dim,Number>::type
operator * (const SymmetricTensor<4,dim,Number> &s) const;
/**
- * Return a read-write reference
- * to the indicated element.
+ * Return a read-write reference to the indicated element.
*/
Number &operator() (const TableIndices<rank> &indices);
/**
- * Return the value of the
- * indicated element as a
- * read-only reference.
+ * Return the value of the indicated element as a read-only reference.
*
- * We return the requested value
- * as a constant reference rather
- * than by value since this
- * object may hold data types
- * that may be large, and we
- * don't know here whether
- * copying is expensive or not.
+ * We return the requested value as a constant reference rather than by
+ * value since this object may hold data types that may be large, and we
+ * don't know here whether copying is expensive or not.
*/
Number operator() (const TableIndices<rank> &indices) const;
/**
- * Access the elements of a row of this
- * symmetric tensor. This function is
+ * Access the elements of a row of this symmetric tensor. This function is
* called for constant tensors.
*/
internal::SymmetricTensorAccessors::Accessor<rank,dim,true,rank-1,Number>
operator [] (const unsigned int row) const;
/**
- * Access the elements of a row of this
- * symmetric tensor. This function is
+ * Access the elements of a row of this symmetric tensor. This function is
* called for non-constant tensors.
*/
internal::SymmetricTensorAccessors::Accessor<rank,dim,false,rank-1,Number>
operator [] (const unsigned int row);
/**
- * Access to an element where you
- * specify the entire set of
- * indices.
+ * Access to an element where you specify the entire set of indices.
*/
Number
operator [] (const TableIndices<rank> &indices) const;
/**
- * Access to an element where you
- * specify the entire set of
- * indices.
+ * Access to an element where you specify the entire set of indices.
*/
Number &
operator [] (const TableIndices<rank> &indices);
/**
- * Access to an element according
- * to unrolled index. The
- * function
- * <tt>s.access_raw_entry(i)</tt>
- * does the same as
- * <tt>s[s.unrolled_to_component_indices(i)]</tt>,
- * but more efficiently.
+ * Access to an element according to unrolled index. The function
+ * <tt>s.access_raw_entry(i)</tt> does the same as
+ * <tt>s[s.unrolled_to_component_indices(i)]</tt>, but more efficiently.
*/
Number
access_raw_entry (const unsigned int unrolled_index) const;
/**
- * Access to an element according
- * to unrolled index. The
- * function
- * <tt>s.access_raw_entry(i)</tt>
- * does the same as
- * <tt>s[s.unrolled_to_component_indices(i)]</tt>,
- * but more efficiently.
+ * Access to an element according to unrolled index. The function
+ * <tt>s.access_raw_entry(i)</tt> does the same as
+ * <tt>s[s.unrolled_to_component_indices(i)]</tt>, but more efficiently.
*/
Number &
access_raw_entry (const unsigned int unrolled_index);
/**
- * Return the Frobenius-norm of a tensor,
- * i.e. the square root of the sum of
- * squares of all entries. This norm is
- * induced by the scalar product defined
- * above for two symmetric tensors. Note
- * that it includes <i>all</i> entries of
- * the tensor, counting symmetry, not
- * only the unique ones (for example, for
- * rank-2 tensors, this norm includes
- * adding up the squares of upper right
- * as well as lower left entries, not
- * just one of them, although they are
- * equal for symmetric tensors).
+ * Return the Frobenius-norm of a tensor, i.e. the square root of the sum of
+ * squares of all entries. This norm is induced by the scalar product
+ * defined above for two symmetric tensors. Note that it includes <i>all</i>
+ * entries of the tensor, counting symmetry, not only the unique ones (for
+ * example, for rank-2 tensors, this norm includes adding up the squares of
+ * upper right as well as lower left entries, not just one of them, although
+ * they are equal for symmetric tensors).
*/
Number norm () const;
/**
- * Tensors can be unrolled by
- * simply pasting all elements
- * into one long vector, but for
- * this an order of elements has
- * to be defined. For symmetric
- * tensors, this function returns
- * which index within the range
- * <code>[0,n_independent_components)</code>
- * the given entry in a symmetric
+ * Tensors can be unrolled by simply pasting all elements into one long
+ * vector, but for this an order of elements has to be defined. For
+ * symmetric tensors, this function returns which index within the range
+ * <code>[0,n_independent_components)</code> the given entry in a symmetric
* tensor has.
*/
static
component_to_unrolled_index (const TableIndices<rank> &indices);
/**
- * The opposite of the previous
- * function: given an index $i$
- * in the unrolled form of the
- * tensor, return what set of
- * indices $(k,l)$ (for rank-2
- * tensors) or $(k,l,m,n)$ (for
- * rank-4 tensors) corresponds to
- * it.
+ * The opposite of the previous function: given an index $i$ in the unrolled
+ * form of the tensor, return what set of indices $(k,l)$ (for rank-2
+ * tensors) or $(k,l,m,n)$ (for rank-4 tensors) corresponds to it.
*/
static
TableIndices<rank>
/**
* Reset all values to zero.
*
- * Note that this is partly inconsistent
- * with the semantics of the @p clear()
- * member functions of the STL and of
- * several other classes within deal.II
- * which not only reset the values of
- * stored elements to zero, but release
- * all memory and return the object into
- * a virginial state. However, since the
- * size of objects of the present type is
- * determined by its template parameters,
- * resizing is not an option, and indeed
- * the state where all elements have a
- * zero value is the state right after
+ * Note that this is partly inconsistent with the semantics of the @p
+ * clear() member functions of the STL and of several other classes within
+ * deal.II which not only reset the values of stored elements to zero, but
+ * release all memory and return the object into a virginial state. However,
+ * since the size of objects of the present type is determined by its
+ * template parameters, resizing is not an option, and indeed the state
+ * where all elements have a zero value is the state right after
* construction of such an object.
*/
void clear ();
/**
- * Determine an estimate for
- * the memory consumption (in
- * bytes) of this
+ * Determine an estimate for the memory consumption (in bytes) of this
* object.
*/
static std::size_t memory_consumption ();
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the purpose
+ * of serialization
*/
template <class Archive>
void serialize(Archive &ar, const unsigned int version);
private:
/**
- * A structure that describes
- * properties of the base tensor.
+ * A structure that describes properties of the base tensor.
*/
typedef
internal::SymmetricTensorAccessors::StorageType<rank,dim,Number>
base_tensor_descriptor;
/**
- * Data storage type for a
- * symmetric tensor.
+ * Data storage type for a symmetric tensor.
*/
typedef typename base_tensor_descriptor::base_tensor_type base_tensor_type;
/**
- * The place where we store the
- * data of the tensor.
+ * The place where we store the data of the tensor.
*/
base_tensor_type data;
/* ----------------- Non-member functions operating on tensors. ------------ */
/**
- * Compute the determinant of a tensor or rank 2. The determinant is
- * also commonly referred to as the third invariant of rank-2 tensors.
+ * Compute the determinant of a tensor or rank 2. The determinant is also
+ * commonly referred to as the third invariant of rank-2 tensors.
*
* For a one-dimensional tensor, the determinant equals the only element and
* is therefore equivalent to the trace.
/**
- * Compute and return the trace of a tensor of rank 2, i.e. the sum of
- * its diagonal entries. The trace is the first invariant of a rank-2
- * tensor.
+ * Compute and return the trace of a tensor of rank 2, i.e. the sum of its
+ * diagonal entries. The trace is the first invariant of a rank-2 tensor.
*
* @relates SymmetricTensor
* @author Wolfgang Bangerth, 2005
/**
- * Compute the trace of a tensor or rank 2. This function therefore
- * computes the same value as the <tt>trace()</tt> functions and is only
- * provided for greater notational simplicity (since there are also functions
+ * Compute the trace of a tensor or rank 2. This function therefore computes
+ * the same value as the <tt>trace()</tt> functions and is only provided for
+ * greater notational simplicity (since there are also functions
* <tt>second_invariant</tt> and <tt>third_invariant</tt>).
*
* @relates SymmetricTensor
/**
- * Return a unit symmetric tensor of rank 2, i.e., the dim-by-dim
- * identity matrix.
+ * Return a unit symmetric tensor of rank 2, i.e., the dim-by-dim identity
+ * matrix.
*
* @relates SymmetricTensor
* @author Wolfgang Bangerth, 2005
/**
- * Return a unit symmetric tensor of rank 2, i.e., the dim-by-dim
- * identity matrix. This specialization of the function uses
- * <code>double</code> as the data type for the elements.
+ * Return a unit symmetric tensor of rank 2, i.e., the dim-by-dim identity
+ * matrix. This specialization of the function uses <code>double</code> as the
+ * data type for the elements.
*
* @relates SymmetricTensor
* @author Wolfgang Bangerth, 2005
/**
* Return the tensor of rank 4 that, when multiplied by a symmetric rank 2
- * tensor <tt>t</tt> returns the deviator $\textrm{dev}\ t$. It is the operator
- * representation of the linear deviator operator.
+ * tensor <tt>t</tt> returns the deviator $\textrm{dev}\ t$. It is the
+ * operator representation of the linear deviator operator.
*
* For every tensor <tt>t</tt>, there holds the identity
* <tt>deviator(t)==deviator_tensor<dim>()*t</tt>, up to numerical
* form, and in particular does not only consist of zeros and ones. For
* example, for <tt>dim=2</tt>, the identity tensor has all zero entries
* except for <tt>id[0][0][0][0]=id[1][1][1][1]=1</tt> and
- * <tt>id[0][1][0][1]=id[0][1][1][0]=id[1][0][0][1]=id[1][0][1][0]=1/2</tt>. To
- * see why this factor of 1/2 is necessary, consider computing <tt>A=Id
- * : B</tt>. For the element <tt>a_01</tt> we have <tt>a_01=id_0100 b_00 +
+ * <tt>id[0][1][0][1]=id[0][1][1][0]=id[1][0][0][1]=id[1][0][1][0]=1/2</tt>.
+ * To see why this factor of 1/2 is necessary, consider computing <tt>A=Id :
+ * B</tt>. For the element <tt>a_01</tt> we have <tt>a_01=id_0100 b_00 +
* id_0111 b_11 + id_0101 b_01 + id_0110 b_10</tt>. On the other hand, we need
* to have <tt>a_01=b_01</tt>, and symmetry implies <tt>b_01=b_10</tt>,
* leading to <tt>a_01=(id_0101+id_0110) b_01</tt>, or, again by symmetry,
- * <tt>id_0101=id_0110=1/2</tt>. Similar considerations hold for the
- * three-dimensional case.
+ * <tt>id_0101=id_0110=1/2</tt>. Similar considerations hold for the three-
+ * dimensional case.
*
* This issue is also explained in the introduction to step-44.
*
* form, and in particular does not only consist of zeros and ones. For
* example, for <tt>dim=2</tt>, the identity tensor has all zero entries
* except for <tt>id[0][0][0][0]=id[1][1][1][1]=1</tt> and
- * <tt>id[0][1][0][1]=id[0][1][1][0]=id[1][0][0][1]=id[1][0][1][0]=1/2</tt>. To
- * see why this factor of 1/2 is necessary, consider computing <tt>A=Id
- * . B</tt>. For the element <tt>a_01</tt> we have <tt>a_01=id_0100 b_00 +
+ * <tt>id[0][1][0][1]=id[0][1][1][0]=id[1][0][0][1]=id[1][0][1][0]=1/2</tt>.
+ * To see why this factor of 1/2 is necessary, consider computing <tt>A=Id .
+ * B</tt>. For the element <tt>a_01</tt> we have <tt>a_01=id_0100 b_00 +
* id_0111 b_11 + id_0101 b_01 + id_0110 b_10</tt>. On the other hand, we need
* to have <tt>a_01=b_01</tt>, and symmetry implies <tt>b_01=b_10</tt>,
* leading to <tt>a_01=(id_0101+id_0110) b_01</tt>, or, again by symmetry,
- * <tt>id_0101=id_0110=1/2</tt>. Similar considerations hold for the
- * three-dimensional case.
+ * <tt>id_0101=id_0110=1/2</tt>. Similar considerations hold for the three-
+ * dimensional case.
*
* @relates SymmetricTensor
* @author Wolfgang Bangerth, 2005
/**
* Invert a symmetric rank-4 tensor. Since symmetric rank-4 tensors are
- * mappings from and to symmetric rank-2 tensors, they can have an
- * inverse. This function computes it, if it exists, for the case that the
- * dimension equals either 1 or 2.
+ * mappings from and to symmetric rank-2 tensors, they can have an inverse.
+ * This function computes it, if it exists, for the case that the dimension
+ * equals either 1 or 2.
*
* If a tensor is not invertible, then the result is unspecified, but will
* likely contain the results of a division by zero or a very small number at
/**
* Invert a symmetric rank-4 tensor. Since symmetric rank-4 tensors are
- * mappings from and to symmetric rank-2 tensors, they can have an
- * inverse. This function computes it, if it exists, for the case that the
- * dimension equals 3.
+ * mappings from and to symmetric rank-2 tensors, they can have an inverse.
+ * This function computes it, if it exists, for the case that the dimension
+ * equals 3.
*
* If a tensor is not invertible, then the result is unspecified, but will
* likely contain the results of a division by zero or a very small number at
/**
* Return the tensor of rank 4 that is the outer product of the two tensors
- * given as arguments, i.e. the result $T=t1 \otimes t2$ satisfies
- * <tt>T phi = t1 (t2 : phi)</tt> for all symmetric tensors <tt>phi</tt>.
+ * given as arguments, i.e. the result $T=t1 \otimes t2$ satisfies <tt>T phi =
+ * t1 (t2 : phi)</tt> for all symmetric tensors <tt>phi</tt>.
*
* For example, the deviator tensor can be computed as
* <tt>identity_tensor<dim,Number>() -
* 1/d*outer_product(unit_symmetric_tensor<dim,Number>(),
- * unit_symmetric_tensor<dim,Number>())</tt>, since the (double) contraction with the
- * unit tensor yields the trace of a symmetric tensor.
+ * unit_symmetric_tensor<dim,Number>())</tt>, since the (double) contraction
+ * with the unit tensor yields the trace of a symmetric tensor.
*
* @relates SymmetricTensor
* @author Wolfgang Bangerth, 2005
/**
- * Return the symmetrized version of a full rank-2 tensor,
- * i.e. (t+transpose(t))/2, as a symmetric rank-2 tensor. This is the version
- * for dim==1.
+ * Return the symmetrized version of a full rank-2 tensor, i.e.
+ * (t+transpose(t))/2, as a symmetric rank-2 tensor. This is the version for
+ * dim==1.
*
* @relates SymmetricTensor
* @author Wolfgang Bangerth, 2005
/**
- * Return the symmetrized version of a full rank-2 tensor,
- * i.e. (t+transpose(t))/2, as a symmetric rank-2 tensor. This is the version
- * for dim==2.
+ * Return the symmetrized version of a full rank-2 tensor, i.e.
+ * (t+transpose(t))/2, as a symmetric rank-2 tensor. This is the version for
+ * dim==2.
*
* @relates SymmetricTensor
* @author Wolfgang Bangerth, 2005
/**
- * Return the symmetrized version of a full rank-2 tensor,
- * i.e. (t+transpose(t))/2, as a symmetric rank-2 tensor. This is the version
- * for dim==3.
+ * Return the symmetrized version of a full rank-2 tensor, i.e.
+ * (t+transpose(t))/2, as a symmetric rank-2 tensor. This is the version for
+ * dim==3.
*
* @relates SymmetricTensor
* @author Wolfgang Bangerth, 2005
/**
- * Multiplication of a symmetric tensor of general rank with a scalar
- * from the right.
+ * Multiplication of a symmetric tensor of general rank with a scalar from the
+ * right.
*
* @relates SymmetricTensor
*/
/**
- * Multiplication of a symmetric tensor of general rank with a scalar
- * from the left.
+ * Multiplication of a symmetric tensor of general rank with a scalar from the
+ * left.
*
* @relates SymmetricTensor
*/
/**
- * Multiplication of a symmetric tensor of general rank with a scalar
- * from the right.
+ * Multiplication of a symmetric tensor of general rank with a scalar from the
+ * right.
*
* @relates SymmetricTensor
*/
/**
- * Multiplication of a symmetric tensor of general rank with a scalar
- * from the left.
+ * Multiplication of a symmetric tensor of general rank with a scalar from the
+ * left.
*
* @relates SymmetricTensor
*/
* Compute the scalar product $a:b=\sum_{i,j} a_{ij}b_{ij}$ between two
* tensors $a,b$ of rank 2. In the current case where both arguments are
* symmetric tensors, this is equivalent to calling the expression
- * <code>t1*t2</code> which uses the overloaded <code>operator*</code>
- * between two symmetric tensors of rank 2.
+ * <code>t1*t2</code> which uses the overloaded <code>operator*</code> between
+ * two symmetric tensors of rank 2.
*
* @relates SymmetricTensor
*/
* the contraction over the last index of the first tensor and the first index
* of the second tensor, for example $(a\cdot b)_{ij}=\sum_k a_{ik}b_{kj}$.
*
- * @relates Tensor
- * @relates SymmetricTensor
+ * @relates Tensor @relates SymmetricTensor
*/
template <int dim, typename Number>
inline
* the contraction over the last index of the first tensor and the first index
* of the second tensor, for example $(a\cdot b)_{ij}=\sum_k a_{ik}b_{kj}$.
*
- * @relates Tensor
- * @relates SymmetricTensor
+ * @relates Tensor @relates SymmetricTensor
*/
template <int dim, typename Number>
inline
/**
* Double contraction between a rank-4 and a rank-2 symmetric tensor,
- * resulting in the symmetric tensor of rank 2 that is given as first
- * argument to this function. This operation is the symmetric tensor
- * analogon of a matrix-vector multiplication.
+ * resulting in the symmetric tensor of rank 2 that is given as first argument
+ * to this function. This operation is the symmetric tensor analogon of a
+ * matrix-vector multiplication.
*
- * This function does the same as the member operator* of the
- * SymmetricTensor class. It should not be used, however, since the
- * member operator has knowledge of the actual data storage format and
- * is at least 2 orders of magnitude faster. This function mostly
- * exists for compatibility purposes with the general tensor class.
+ * This function does the same as the member operator* of the SymmetricTensor
+ * class. It should not be used, however, since the member operator has
+ * knowledge of the actual data storage format and is at least 2 orders of
+ * magnitude faster. This function mostly exists for compatibility purposes
+ * with the general tensor class.
*
* @related SymmetricTensor
* @author Wolfgang Bangerth, 2005
/**
* Double contraction between a rank-4 and a rank-2 symmetric tensor,
- * resulting in the symmetric tensor of rank 2 that is given as first
- * argument to this function. This operation is the symmetric tensor
- * analogon of a matrix-vector multiplication.
+ * resulting in the symmetric tensor of rank 2 that is given as first argument
+ * to this function. This operation is the symmetric tensor analogon of a
+ * matrix-vector multiplication.
*
- * This function does the same as the member operator* of the
- * SymmetricTensor class. It should not be used, however, since the
- * member operator has knowledge of the actual data storage format and
- * is at least 2 orders of magnitude faster. This function mostly
- * exists for compatibility purposes with the general tensor class.
+ * This function does the same as the member operator* of the SymmetricTensor
+ * class. It should not be used, however, since the member operator has
+ * knowledge of the actual data storage format and is at least 2 orders of
+ * magnitude faster. This function mostly exists for compatibility purposes
+ * with the general tensor class.
*
* @related SymmetricTensor
* @author Wolfgang Bangerth, 2005
/**
* Double contraction between a rank-4 and a rank-2 symmetric tensor,
- * resulting in the symmetric tensor of rank 2 that is given as first
- * argument to this function. This operation is the symmetric tensor
- * analogon of a matrix-vector multiplication.
+ * resulting in the symmetric tensor of rank 2 that is given as first argument
+ * to this function. This operation is the symmetric tensor analogon of a
+ * matrix-vector multiplication.
*
- * This function does the same as the member operator* of the
- * SymmetricTensor class. It should not be used, however, since the
- * member operator has knowledge of the actual data storage format and
- * is at least 2 orders of magnitude faster. This function mostly
- * exists for compatibility purposes with the general tensor class.
+ * This function does the same as the member operator* of the SymmetricTensor
+ * class. It should not be used, however, since the member operator has
+ * knowledge of the actual data storage format and is at least 2 orders of
+ * magnitude faster. This function mostly exists for compatibility purposes
+ * with the general tensor class.
*
* @related SymmetricTensor @author Wolfgang Bangerth, 2005
*/
/**
* Double contraction between a rank-4 and a rank-2 symmetric tensor,
- * resulting in the symmetric tensor of rank 2 that is given as first
- * argument to this function. This operation is the symmetric tensor
- * analogon of a matrix-vector multiplication.
+ * resulting in the symmetric tensor of rank 2 that is given as first argument
+ * to this function. This operation is the symmetric tensor analogon of a
+ * matrix-vector multiplication.
*
- * This function does the same as the member operator* of the
- * SymmetricTensor class. It should not be used, however, since the
- * member operator has knowledge of the actual data storage format and
- * is at least 2 orders of magnitude faster. This function mostly
- * exists for compatibility purposes with the general tensor class.
+ * This function does the same as the member operator* of the SymmetricTensor
+ * class. It should not be used, however, since the member operator has
+ * knowledge of the actual data storage format and is at least 2 orders of
+ * magnitude faster. This function mostly exists for compatibility purposes
+ * with the general tensor class.
*
* @related SymmetricTensor
* @author Wolfgang Bangerth, 2005
/**
* Double contraction between a rank-4 and a rank-2 symmetric tensor,
- * resulting in the symmetric tensor of rank 2 that is given as first
- * argument to this function. This operation is the symmetric tensor
- * analogon of a matrix-vector multiplication.
+ * resulting in the symmetric tensor of rank 2 that is given as first argument
+ * to this function. This operation is the symmetric tensor analogon of a
+ * matrix-vector multiplication.
*
- * This function does the same as the member operator* of the
- * SymmetricTensor class. It should not be used, however, since the
- * member operator has knowledge of the actual data storage format and
- * is at least 2 orders of magnitude faster. This function mostly
- * exists for compatibility purposes with the general tensor class.
+ * This function does the same as the member operator* of the SymmetricTensor
+ * class. It should not be used, however, since the member operator has
+ * knowledge of the actual data storage format and is at least 2 orders of
+ * magnitude faster. This function mostly exists for compatibility purposes
+ * with the general tensor class.
*
* @related SymmetricTensor
* @author Wolfgang Bangerth, 2005
/**
* Double contraction between a rank-4 and a rank-2 symmetric tensor,
- * resulting in the symmetric tensor of rank 2 that is given as first
- * argument to this function. This operation is the symmetric tensor
- * analogon of a matrix-vector multiplication.
+ * resulting in the symmetric tensor of rank 2 that is given as first argument
+ * to this function. This operation is the symmetric tensor analogon of a
+ * matrix-vector multiplication.
*
- * This function does the same as the member operator* of the
- * SymmetricTensor class. It should not be used, however, since the
- * member operator has knowledge of the actual data storage format and
- * is at least 2 orders of magnitude faster. This function mostly
- * exists for compatibility purposes with the general tensor class.
+ * This function does the same as the member operator* of the SymmetricTensor
+ * class. It should not be used, however, since the member operator has
+ * knowledge of the actual data storage format and is at least 2 orders of
+ * magnitude faster. This function mostly exists for compatibility purposes
+ * with the general tensor class.
*
* @related SymmetricTensor
* @author Wolfgang Bangerth, 2005
/**
- * Multiplication operator performing a contraction of the last index
- * of the first argument and the first index of the second
- * argument. This function therefore does the same as the
- * corresponding <tt>contract</tt> function, but returns the result as
- * a return value, rather than writing it into the reference given as
- * the first argument to the <tt>contract</tt> function.
- *
- * Note that for the <tt>Tensor</tt> class, the multiplication
- * operator only performs a contraction over a single pair of
- * indices. This is in contrast to the multiplication operator for
- * symmetric tensors, which does the double contraction.
+ * Multiplication operator performing a contraction of the last index of the
+ * first argument and the first index of the second argument. This function
+ * therefore does the same as the corresponding <tt>contract</tt> function,
+ * but returns the result as a return value, rather than writing it into the
+ * reference given as the first argument to the <tt>contract</tt> function.
+ *
+ * Note that for the <tt>Tensor</tt> class, the multiplication operator only
+ * performs a contraction over a single pair of indices. This is in contrast
+ * to the multiplication operator for symmetric tensors, which does the double
+ * contraction.
*
* @relates SymmetricTensor
* @author Wolfgang Bangerth, 2005
DEAL_II_NAMESPACE_OPEN
/**
- * A class that represents a set of
- * iterators each of which are
- * incremented by one at the same
- * time. This is typically used in calls
- * like <code>std::transform(a.begin(),
- * a.end(), b.begin(), functor);</code>
- * where we have synchronous iterators
- * marching through the containers
- * <code>a,b</code>. If an object of this
- * type represents the end of a range,
- * only the first element is considered
- * (we only have <code>a.end()</code>,
+ * A class that represents a set of iterators each of which are incremented by
+ * one at the same time. This is typically used in calls like
+ * <code>std::transform(a.begin(), a.end(), b.begin(), functor);</code> where
+ * we have synchronous iterators marching through the containers
+ * <code>a,b</code>. If an object of this type represents the end of a range,
+ * only the first element is considered (we only have <code>a.end()</code>,
* not <code>b.end()</code>)
*
- * The template argument of the current
- * class shall be of type
- * <code>std_cxx11::tuple</code> with
- * arguments equal to the iterator types.
+ * The template argument of the current class shall be of type
+ * <code>std_cxx11::tuple</code> with arguments equal to the iterator types.
*
- * This type, and the helper functions
- * associated with it, are used as the
- * Value concept for the blocked_range
- * type of the Threading Building Blocks.
+ * This type, and the helper functions associated with it, are used as the
+ * Value concept for the blocked_range type of the Threading Building Blocks.
*
* @author Wolfgang Bangerth, 2008
*/
SynchronousIterators (const SynchronousIterators &i);
/**
- * Storage for the iterators
- * represented by the current class.
+ * Storage for the iterators represented by the current class.
*/
Iterators iterators;
};
/**
- * Return whether the first element of
- * the first argument is less than the
- * first element of the second
- * argument. Since the objects compared
- * march forward all elements at the same
- * time, comparing the first element is
+ * Return whether the first element of the first argument is less than the
+ * first element of the second argument. Since the objects compared march
+ * forward all elements at the same time, comparing the first element is
* sufficient.
*/
template <typename Iterators>
/**
- * Return the distance between the first
- * and the second argument. Since the
- * objects compared march forward all
- * elements at the same time,
- * differencing the first element is
- * sufficient.
+ * Return the distance between the first and the second argument. Since the
+ * objects compared march forward all elements at the same time, differencing
+ * the first element is sufficient.
*/
template <typename Iterators>
inline
/**
- * Advance the elements of this iterator
- * by $n$.
+ * Advance the elements of this iterator by $n$.
*/
template <typename Iterators>
inline
}
/**
- * Advance the elements of this iterator
- * by 1.
+ * Advance the elements of this iterator by 1.
*/
template <typename Iterators>
inline
/**
- * Compare synch iterators for
- * inequality. Since they march in synch,
- * comparing only the first element is
- * sufficient.
+ * Compare synch iterators for inequality. Since they march in synch,
+ * comparing only the first element is sufficient.
*/
template <typename Iterators>
inline
{
/**
- * @internal
- * Have a namespace in which we declare some classes that are used to
- * access the elements of tables using the <tt>operator[]</tt>. These are
- * quite technical, since they have to do their work recursively (due
- * to the fact that the number of indices is not known, we have to
- * return an iterator into the next lower dimension object if we
- * access one object, until we are on the lowest level and can
- * actually return a reference to the stored data type itself). This
- * is so technical that you will not usually want to look at these
- * classes at all, except possibly for educational reasons. None of
- * the classes herein has a interface that you should use explicitly
- * in your programs (except, of course, through access to the elements
- * of tables with <tt>operator[]</tt>, which generates temporary objects of
- * the types of this namespace).
+ * @internal Have a namespace in which we declare some classes that are used
+ * to access the elements of tables using the <tt>operator[]</tt>. These are
+ * quite technical, since they have to do their work recursively (due to the
+ * fact that the number of indices is not known, we have to return an
+ * iterator into the next lower dimension object if we access one object,
+ * until we are on the lowest level and can actually return a reference to
+ * the stored data type itself). This is so technical that you will not
+ * usually want to look at these classes at all, except possibly for
+ * educational reasons. None of the classes herein has a interface that you
+ * should use explicitly in your programs (except, of course, through access
+ * to the elements of tables with <tt>operator[]</tt>, which generates
+ * temporary objects of the types of this namespace).
*
* @author Wolfgang Bangerth, 2002
*/
namespace TableBaseAccessors
{
/**
- * @internal
- * Have a class which declares some nested typedefs, depending on its
- * template parameters. The general template declares nothing, but
+ * @internal Have a class which declares some nested typedefs, depending
+ * on its template parameters. The general template declares nothing, but
* there are more useful specializations regaring the last parameter
- * indicating constness of the table for which accessor objects are to
- * be generated in this namespace.
+ * indicating constness of the table for which accessor objects are to be
+ * generated in this namespace.
*/
template <int N, typename T, bool Constness>
struct Types
{};
/**
- * @internal
- * Have a class which declares some nested typedefs, depending on its
- * template parameters. Specialization for accessors to constant
+ * @internal Have a class which declares some nested typedefs, depending
+ * on its template parameters. Specialization for accessors to constant
* objects.
*/
template <int N, typename T> struct Types<N,T,true>
};
/**
- * @internal
- * Have a class which declares some nested typedefs, depending on its
- * template parameters. Specialization for accessors to non-constant
- * objects.
+ * @internal Have a class which declares some nested typedefs, depending
+ * on its template parameters. Specialization for accessors to non-
+ * constant objects.
*/
template <int N, typename T> struct Types<N,T,false>
{
/**
- * @internal
- * Class that acts as accessor to subobjects of tables of type
- * <tt>Table<N,T></tt>. The template parameter <tt>C</tt> may be either true or
- * false, and indicates whether the objects worked on are constant or
- * not (i.e. write access is only allowed if the value is false).
+ * @internal Class that acts as accessor to subobjects of tables of type
+ * <tt>Table<N,T></tt>. The template parameter <tt>C</tt> may be either
+ * true or false, and indicates whether the objects worked on are constant
+ * or not (i.e. write access is only allowed if the value is false).
*
- * Since with <tt>N</tt> indices, the effect of applying <tt>operator[]</tt> is
- * getting access to something we <tt>N-1</tt> indices, we have to
- * implement these accessor classes recursively, with stopping when we
- * have only one index left. For the latter case, a specialization of
- * this class is declared below, where calling <tt>operator[]</tt> gives
- * you access to the objects actually stored by the table. In the
- * value given to the index operator needs to be checked whether it is
- * inside its bounds, for which we need to know which index of the
- * table we are actually accessing presently. This is done through the
- * template parameter <tt>P</tt>: it indicates, how many remaining indices
- * there are. For a vector, <tt>P</tt> may only be one (and then the
- * specialization below is used). For a table this value may be two,
- * and when using <tt>operator[]</tt>, an object with <tt>P=1</tt> emerges.
+ * Since with <tt>N</tt> indices, the effect of applying
+ * <tt>operator[]</tt> is getting access to something we <tt>N-1</tt>
+ * indices, we have to implement these accessor classes recursively, with
+ * stopping when we have only one index left. For the latter case, a
+ * specialization of this class is declared below, where calling
+ * <tt>operator[]</tt> gives you access to the objects actually stored by
+ * the table. In the value given to the index operator needs to be checked
+ * whether it is inside its bounds, for which we need to know which index
+ * of the table we are actually accessing presently. This is done through
+ * the template parameter <tt>P</tt>: it indicates, how many remaining
+ * indices there are. For a vector, <tt>P</tt> may only be one (and then
+ * the specialization below is used). For a table this value may be two,
+ * and when using <tt>operator[]</tt>, an object with <tt>P=1</tt>
+ * emerges.
*
* The value of <tt>P</tt> is also used to determine the stride: this
* object stores a pointer indicating the beginning of the range of
* objects that it may access. When we apply <tt>operator[]</tt> on this
- * object, the resulting new accessor may only access a subset of
- * these elements, and to know which subset we need to know the
- * dimensions of the table and the present index, which is indicated
- * by <tt>P</tt>.
+ * object, the resulting new accessor may only access a subset of these
+ * elements, and to know which subset we need to know the dimensions of
+ * the table and the present index, which is indicated by <tt>P</tt>.
*
* As stated for the entire namespace, you will not usually have to do
- * with these classes directly, and should not try to use their
- * interface directly as it may change without notice. In fact, since
- * the constructors are made private, you will not even be able to
- * generate objects of this class, as they are only thought as
- * temporaries for access to elements of the table class, not for
- * passing them around as arguments of functions, etc.
+ * with these classes directly, and should not try to use their interface
+ * directly as it may change without notice. In fact, since the
+ * constructors are made private, you will not even be able to generate
+ * objects of this class, as they are only thought as temporaries for
+ * access to elements of the table class, not for passing them around as
+ * arguments of functions, etc.
*
* @author Wolfgang Bangerth, 2002
*/
private:
/**
- * Constructor. Take a pointer
- * to the table object to know
- * about the sizes of the
- * various dimensions, and a
- * pointer to the subset of
- * data we may access.
+ * Constructor. Take a pointer to the table object to know about the
+ * sizes of the various dimensions, and a pointer to the subset of data
+ * we may access.
*/
Accessor (const TableType &table,
const iterator data);
/**
- * Default constructor. Not
- * needed, and invisible, so
- * private.
+ * Default constructor. Not needed, and invisible, so private.
*/
Accessor ();
public:
/**
- * Copy constructor. This constructor
- * is public so that one can pass
- * sub-tables to functions as
- * arguments, as in
- * <code>f(table[i])</code>.
+ * Copy constructor. This constructor is public so that one can pass
+ * sub-tables to functions as arguments, as in <code>f(table[i])</code>.
*
- * Using this constructor is risky if
- * accessors are stored longer than
- * the table it points to. Don't do
- * this.
+ * Using this constructor is risky if accessors are stored longer than
+ * the table it points to. Don't do this.
*/
Accessor (const Accessor &a);
/**
- * Index operator. Performs a
- * range check.
+ * Index operator. Performs a range check.
*/
Accessor<N,T,C,P-1> operator [] (const unsigned int i) const;
/**
- * Exception for range
- * check. Do not use global
- * exception since this way we
- * can output which index is
- * the wrong one.
+ * Exception for range check. Do not use global exception since this way
+ * we can output which index is the wrong one.
*/
DeclException3 (ExcIndexRange, int, int, int,
<< "Index " << N-P+1 << "has a value of "
<< arg2 << "," << arg3 << "[");
private:
/**
- * Store the data given to the
- * constructor. There are no
- * non-const member functions
- * of this class, so there is
- * no reason not to make these
- * elements constant.
+ * Store the data given to the constructor. There are no non-const
+ * member functions of this class, so there is no reason not to make
+ * these elements constant.
*/
const TableType &table;
const iterator data;
/**
- * @internal
- * Accessor class for tables. This is the specialization for the last
- * index, which actually allows access to the elements of the table,
- * rather than recursively returning access objects for further
- * subsets. The same holds for this specialization as for the general
- * template; see there for more information.
+ * @internal Accessor class for tables. This is the specialization for the
+ * last index, which actually allows access to the elements of the table,
+ * rather than recursively returning access objects for further subsets.
+ * The same holds for this specialization as for the general template; see
+ * there for more information.
*
* @author Wolfgang Bangerth, 2002
*/
{
public:
/**
- * Typedef constant and
- * non-constant iterator
- * types to the elements of
- * this row, as well as all
- * the other types usually
- * required for the standard
- * library algorithms.
+ * Typedef constant and non-constant iterator types to the elements of
+ * this row, as well as all the other types usually required for the
+ * standard library algorithms.
*/
typedef typename Types<N,T,C>::value_type value_type;
typedef ptrdiff_t difference_type;
/**
- * Import a typedef from the
- * switch class above.
+ * Import a typedef from the switch class above.
*/
typedef typename Types<N,T,C>::TableType TableType;
private:
/**
- * Constructor. Take an iterator
- * to the table object to know
- * about the sizes of the
- * various dimensions, and a
- * iterator to the subset of
- * data we may access (which in
- * this particular case is only
- * one row).
+ * Constructor. Take an iterator to the table object to know about the
+ * sizes of the various dimensions, and a iterator to the subset of data
+ * we may access (which in this particular case is only one row).
*
- * The constructor is made
- * private in order to prevent
- * you having such objects
- * around. The only way to
- * create such objects is via
- * the <tt>Table</tt> class, which
- * only generates them as
- * temporary objects. This
- * guarantees that the accessor
- * objects go out of scope
- * earlier than the mother
- * object, avoid problems with
- * data consistency.
+ * The constructor is made private in order to prevent you having such
+ * objects around. The only way to create such objects is via the
+ * <tt>Table</tt> class, which only generates them as temporary objects.
+ * This guarantees that the accessor objects go out of scope earlier
+ * than the mother object, avoid problems with data consistency.
*/
Accessor (const TableType &table,
const iterator data);
/**
- * Default constructor. Not needed,
- * so private.
+ * Default constructor. Not needed, so private.
*/
Accessor ();
public:
/**
- * Copy constructor. This constructor
- * is public so that one can pass
- * sub-tables to functions as
- * arguments, as in
- * <code>f(table[i])</code>.
+ * Copy constructor. This constructor is public so that one can pass
+ * sub-tables to functions as arguments, as in <code>f(table[i])</code>.
*
- * Using this constructor is risky if
- * accessors are stored longer than
- * the table it points to. Don't do
- * this.
+ * Using this constructor is risky if accessors are stored longer than
+ * the table it points to. Don't do this.
*/
Accessor (const Accessor &a);
/**
- * Index operator. Performs a
- * range check.
+ * Index operator. Performs a range check.
*/
reference operator [] (const unsigned int) const;
/**
- * Return the length of one row,
- * i.e. the number of elements
- * corresponding to the last
- * index of the table object.
+ * Return the length of one row, i.e. the number of elements
+ * corresponding to the last index of the table object.
*/
unsigned int size () const;
/**
- * Return an iterator to the
- * first element of this
- * row.
+ * Return an iterator to the first element of this row.
*/
iterator begin () const;
/**
- * Return an interator to the
- * element past the end of
- * this row.
+ * Return an interator to the element past the end of this row.
*/
iterator end () const;
private:
/**
- * Store the data given to the
- * constructor. There are no
- * non-const member functions
- * of this class, so there is
- * no reason not to make these
- * elements constant.
+ * Store the data given to the constructor. There are no non-const
+ * member functions of this class, so there is no reason not to make
+ * these elements constant.
*/
const TableType &table;
const iterator data;
/**
- * General class holding an array of objects of templated type in
- * multiple dimensions. If the template parameter indicating the
- * number of dimensions is one, then this is more or less a vector, if
- * it is two then it is a matrix, and so on.
+ * General class holding an array of objects of templated type in multiple
+ * dimensions. If the template parameter indicating the number of dimensions
+ * is one, then this is more or less a vector, if it is two then it is a
+ * matrix, and so on.
*
- * Previously, this data type was emulated in this library by
- * constructs like <tt>std::vector<std::vector<T>></tt>, or even higher
- * nested constructs. However, this has the disadvantage that it is
- * hard to initialize, and most importantly that it is very
- * inefficient if all rows have the same size (which is the usual
- * case), since then the memory for each row is allocated
+ * Previously, this data type was emulated in this library by constructs like
+ * <tt>std::vector<std::vector<T>></tt>, or even higher nested constructs.
+ * However, this has the disadvantage that it is hard to initialize, and most
+ * importantly that it is very inefficient if all rows have the same size
+ * (which is the usual case), since then the memory for each row is allocated
* independently, both wasting time and memory. This can be made more
- * efficient by allocating only one chunk of memory for the entire
- * object.
+ * efficient by allocating only one chunk of memory for the entire object.
*
- * Therefore, this data type was invented. Its implementation is
- * rather straightforward, with two exceptions. The first thing to
- * think about is how to pass the size in each of the coordinate
- * directions to the object; this is done using the TableIndices
- * class. Second, how to access the individual elements. The basic
- * problem here is that we would like to make the number of arguments
- * to be passed to the constructor as well as the access functions
- * dependent on the template parameter <tt>N</tt> indicating the number of
- * dimensions. Of course, this is not possible.
+ * Therefore, this data type was invented. Its implementation is rather
+ * straightforward, with two exceptions. The first thing to think about is how
+ * to pass the size in each of the coordinate directions to the object; this
+ * is done using the TableIndices class. Second, how to access the individual
+ * elements. The basic problem here is that we would like to make the number
+ * of arguments to be passed to the constructor as well as the access
+ * functions dependent on the template parameter <tt>N</tt> indicating the
+ * number of dimensions. Of course, this is not possible.
*
- * The way out of the first problem (and partly the second one as
- * well) is to have a common base class TableBase and a derived class
- * for each value of <tt>N</tt>. This derived class has a constructor
- * with the correct number of arguments, namely <tt>N</tt>. These then
- * transform their arguments into the data type the base class (this
- * class in fact) uses in the constructor as well as in
- * element access through operator() functions.
+ * The way out of the first problem (and partly the second one as well) is to
+ * have a common base class TableBase and a derived class for each value of
+ * <tt>N</tt>. This derived class has a constructor with the correct number
+ * of arguments, namely <tt>N</tt>. These then transform their arguments into
+ * the data type the base class (this class in fact) uses in the constructor
+ * as well as in element access through operator() functions.
*
- * The second problem is that we would like to allow access through a
- * sequence of <tt>operator[]</tt> calls. This mostly because, as said,
- * this class is a replacement for previous use of nested
- * <tt>std::vector</tt> objects, where we had to use the <tt>operator[]</tt>
- * access function recursively until we were at the innermost
- * object. Emulating this behavior without losing the ability to do
- * index checks, and in particular without losing performance is
- * possible but nontrivial, and done in the TableBaseAccessors
- * namespace.
+ * The second problem is that we would like to allow access through a sequence
+ * of <tt>operator[]</tt> calls. This mostly because, as said, this class is a
+ * replacement for previous use of nested <tt>std::vector</tt> objects, where
+ * we had to use the <tt>operator[]</tt> access function recursively until we
+ * were at the innermost object. Emulating this behavior without losing the
+ * ability to do index checks, and in particular without losing performance is
+ * possible but nontrivial, and done in the TableBaseAccessors namespace.
*
*
* <h3>Comparison with the Tensor class</h3>
*
- * In some way, this class is similar to the Tensor class, in
- * that it templatizes on the number of dimensions. However, there are
- * two major differences. The first is that the Tensor class
- * stores only numeric values (as <tt>double</tt>s), while the Table
- * class stores arbitrary objects. The second is that the Tensor
- * class has fixed dimensions, also given as a template argument, while
- * this class can handle arbitrary dimensions, which may also be
- * different between different indices.
+ * In some way, this class is similar to the Tensor class, in that it
+ * templatizes on the number of dimensions. However, there are two major
+ * differences. The first is that the Tensor class stores only numeric values
+ * (as <tt>double</tt>s), while the Table class stores arbitrary objects. The
+ * second is that the Tensor class has fixed dimensions, also given as a
+ * template argument, while this class can handle arbitrary dimensions, which
+ * may also be different between different indices.
*
- * This has two consequences. First, since the size is not known at
- * compile time, it has to do explicit memory allocating. Second, the
- * layout of individual elements is not known at compile time, so
- * access is slower than for the Tensor class where the number
- * of elements are their location is known at compile time and the
- * compiler can optimize with this knowledge (for example when
- * unrolling loops). On the other hand, this class is of course more
- * flexible, for example when you want a two-dimensional table with
- * the number of rows equal to the number of degrees of freedom on a
- * cell, and the number of columns equal to the number of quadrature
- * points. Both numbers may only be known at run-time, so a flexible
- * table is needed here. Furthermore, you may want to store, say, the
- * gradients of shape functions, so the data type is not a single
- * scalar value, but a tensor itself.
+ * This has two consequences. First, since the size is not known at compile
+ * time, it has to do explicit memory allocating. Second, the layout of
+ * individual elements is not known at compile time, so access is slower than
+ * for the Tensor class where the number of elements are their location is
+ * known at compile time and the compiler can optimize with this knowledge
+ * (for example when unrolling loops). On the other hand, this class is of
+ * course more flexible, for example when you want a two-dimensional table
+ * with the number of rows equal to the number of degrees of freedom on a
+ * cell, and the number of columns equal to the number of quadrature points.
+ * Both numbers may only be known at run-time, so a flexible table is needed
+ * here. Furthermore, you may want to store, say, the gradients of shape
+ * functions, so the data type is not a single scalar value, but a tensor
+ * itself.
*
* @ingroup data
* @author Wolfgang Bangerth, 2002.
{
public:
/**
- * Default constructor. Set all
- * dimensions to zero.
+ * Default constructor. Set all dimensions to zero.
*/
TableBase ();
/**
- * Constructor. Initialize the
- * array with the given
- * dimensions in each index
+ * Constructor. Initialize the array with the given dimensions in each index
* component.
*/
TableBase (const TableIndices<N> &sizes);
/**
- * Constructor. Initialize the
- * array with the given
- * dimensions in each index
- * component, and then initialize the elements of the table using the
- * second and third argument by calling fill(entries,C_style_indexing).
+ * Constructor. Initialize the array with the given dimensions in each index
+ * component, and then initialize the elements of the table using the second
+ * and third argument by calling fill(entries,C_style_indexing).
*/
template <typename InputIterator>
TableBase (const TableIndices<N> &sizes,
const bool C_style_indexing = true);
/**
- * Copy constructor. Performs a
- * deep copy.
+ * Copy constructor. Performs a deep copy.
*/
TableBase (const TableBase<N,T> &src);
/**
- * Copy constructor. Performs a
- * deep copy from a table object
- * storing some other data type.
+ * Copy constructor. Performs a deep copy from a table object storing some
+ * other data type.
*/
template <typename T2>
TableBase (const TableBase<N,T2> &src);
~TableBase ();
/**
- * Assignment operator.
- * Copy all elements of <tt>src</tt>
- * into the matrix. The size is
- * adjusted if needed.
+ * Assignment operator. Copy all elements of <tt>src</tt> into the matrix.
+ * The size is adjusted if needed.
*
- * We can't use the other, templatized
- * version since if we don't declare
- * this one, the compiler will happily
- * generate a predefined copy
- * operator which is not what we want.
+ * We can't use the other, templatized version since if we don't declare
+ * this one, the compiler will happily generate a predefined copy operator
+ * which is not what we want.
*/
TableBase<N,T> &operator = (const TableBase<N,T> &src);
/**
- * Copy operator.
- * Copy all elements of <tt>src</tt>
- * into the array. The size is
- * adjusted if needed.
+ * Copy operator. Copy all elements of <tt>src</tt> into the array. The size
+ * is adjusted if needed.
*
- * This function requires that the
- * type <tt>T2</tt> is convertible to
+ * This function requires that the type <tt>T2</tt> is convertible to
* <tt>T</tt>.
*/
template<typename T2>
TableBase<N,T> &operator = (const TableBase<N,T2> &src);
/**
- * Test for equality of two tables.
+ * Test for equality of two tables.
*/
bool operator == (const TableBase<N,T> &T2) const;
/**
- * Set all entries to their
- * default value (i.e. copy them
- * over with default constructed
- * objects). Do not change the
- * size of the table, though.
+ * Set all entries to their default value (i.e. copy them over with default
+ * constructed objects). Do not change the size of the table, though.
*/
void reset_values ();
/**
- * Set the dimensions of this object to
- * the sizes given in the argument, and
- * newly allocate the required
- * memory. If <tt>fast</tt> is set to
- * <tt>false</tt>, previous content is
- * deleted, otherwise the memory is not
+ * Set the dimensions of this object to the sizes given in the argument, and
+ * newly allocate the required memory. If <tt>fast</tt> is set to
+ * <tt>false</tt>, previous content is deleted, otherwise the memory is not
* touched.
*/
void reinit (const TableIndices<N> &new_size,
const bool fast = false);
/**
- * Size of the table in direction
- * <tt>i</tt>.
+ * Size of the table in direction <tt>i</tt>.
*/
unsigned int size (const unsigned int i) const;
/**
- * Return the sizes of this
- * object in each direction.
+ * Return the sizes of this object in each direction.
*/
const TableIndices<N> &size () const;
/**
- * Return the number of elements
- * stored in this object, which
- * is the product of the
- * extensions in each dimension.
+ * Return the number of elements stored in this object, which is the product
+ * of the extensions in each dimension.
*/
unsigned int n_elements () const;
/**
- * Return whether the object is
- * empty, i.e. one of the
- * directions is zero. This is
- * equivalent to
- * <tt>n_elements()==0</tt>.
+ * Return whether the object is empty, i.e. one of the directions is zero.
+ * This is equivalent to <tt>n_elements()==0</tt>.
*/
bool empty () const;
/**
- * Fill this table (which is assumed to already have the correct
- * size) from a source given by dereferencing the given forward
- * iterator (which could, for example, be a pointer to the first
- * element of an array, or an inserting std::istream_iterator). The
- * second argument denotes whether the elements pointed to are
- * arranged in a way that corresponds to the last index running
- * fastest or slowest. The default is to use C-style indexing
- * where the last index runs fastest (as opposed to Fortran-style
- * where the first index runs fastest when traversing multidimensional
- * arrays. For example, if you try to fill an object of type
- * Table<2,T>, then calling this function with the default
- * value for the second argument will result in the equivalent of
- * doing
+ * Fill this table (which is assumed to already have the correct size) from
+ * a source given by dereferencing the given forward iterator (which could,
+ * for example, be a pointer to the first element of an array, or an
+ * inserting std::istream_iterator). The second argument denotes whether the
+ * elements pointed to are arranged in a way that corresponds to the last
+ * index running fastest or slowest. The default is to use C-style indexing
+ * where the last index runs fastest (as opposed to Fortran-style where the
+ * first index runs fastest when traversing multidimensional arrays. For
+ * example, if you try to fill an object of type Table<2,T>, then calling
+ * this function with the default value for the second argument will result
+ * in the equivalent of doing
* @code
* Table<2,T> t;
* for (unsigned int i=0; i<t.sizes()[0]; ++i)
* for (unsigned int j=0; j<t.sizes()[1]; ++j)
* t[i][j] = *entries++;
* @endcode
- * On the other hand, if the second argument to this function is false,
- * then this would result in code of the following form:
+ * On the other hand, if the second argument to this function is false, then
+ * this would result in code of the following form:
* @code
* Table<2,T> t;
* for (unsigned int j=0; j<t.sizes()[1]; ++j)
* for (unsigned int i=0; i<t.sizes()[0]; ++i)
* t[i][j] = *entries++;
* @endcode
- * Note the switched order in which we fill the table elements by
- * traversing the given set of iterators.
+ * Note the switched order in which we fill the table elements by traversing
+ * the given set of iterators.
*
- * @param entries An iterator to a set of elements from which to
- * initialize this table. It is assumed that iterator can be
- * incremented and dereferenced a sufficient number of times
- * to fill this table.
- * @param C_style_indexing If true, run over elements of the
- * table with the last index changing fastest as we dereference
- * subsequent elements of the input range. If false, change
- * the first index fastest.
+ * @param entries An iterator to a set of elements from which to initialize
+ * this table. It is assumed that iterator can be incremented and
+ * dereferenced a sufficient number of times to fill this table.
+ * @param C_style_indexing If true, run over elements of the table with the
+ * last index changing fastest as we dereference subsequent elements of the
+ * input range. If false, change the first index fastest.
*/
template <typename InputIterator>
void fill (InputIterator entries,
const bool C_style_indexing = true);
/**
- * Fill all table entries with
- * the same value.
+ * Fill all table entries with the same value.
*/
void fill (const T &value);
/**
- * Return a read-write reference
- * to the indicated element.
+ * Return a read-write reference to the indicated element.
*/
typename AlignedVector<T>::reference
operator () (const TableIndices<N> &indices);
/**
- * Return the value of the
- * indicated element as a
- * read-only reference.
+ * Return the value of the indicated element as a read-only reference.
*
- * We return the requested value
- * as a constant reference rather
- * than by value since this
- * object may hold data types
- * that may be large, and we
- * don't know here whether
- * copying is expensive or not.
+ * We return the requested value as a constant reference rather than by
+ * value since this object may hold data types that may be large, and we
+ * don't know here whether copying is expensive or not.
*/
typename AlignedVector<T>::const_reference
operator () (const TableIndices<N> &indices) const;
protected:
/**
- * Return the position of the
- * indicated element within the
- * array of elements stored one
- * after the other. This function
- * does no index checking.
+ * Return the position of the indicated element within the array of elements
+ * stored one after the other. This function does no index checking.
*/
unsigned int position (const TableIndices<N> &indices) const;
/**
- * Return a read-write reference
- * to the indicated element.
+ * Return a read-write reference to the indicated element.
*
- * This function does no bounds
- * checking and is only to be
- * used internally and in
- * functions already checked.
+ * This function does no bounds checking and is only to be used internally
+ * and in functions already checked.
*/
typename AlignedVector<T>::reference el (const TableIndices<N> &indices);
/**
- * Return the value of the
- * indicated element as a
- * read-only reference.
+ * Return the value of the indicated element as a read-only reference.
*
- * This function does no bounds
- * checking and is only to be
- * used internally and in
- * functions already checked.
+ * This function does no bounds checking and is only to be used internally
+ * and in functions already checked.
*
- * We return the requested value
- * as a constant reference rather
- * than by value since this
- * object may hold data types
- * that may be large, and we
- * don't know here whether
- * copying is expensive or not.
+ * We return the requested value as a constant reference rather than by
+ * value since this object may hold data types that may be large, and we
+ * don't know here whether copying is expensive or not.
*/
typename AlignedVector<T>::const_reference el (const TableIndices<N> &indices) const;
/**
- * @deprecated This function
- * accesses data directly and
- * should not be used!
+ * @deprecated This function accesses data directly and should not be used!
*
- * Direct read-only access to
- * data field. Used by
- * <tt>FullMatrix</tt> of the LAC
- * sublibrary (there even with a
- * cast from const), otherwise,
- * keep away!
+ * Direct read-only access to data field. Used by <tt>FullMatrix</tt> of the
+ * LAC sublibrary (there even with a cast from const), otherwise, keep away!
*/
typename AlignedVector<T>::const_pointer data () const DEAL_II_DEPRECATED;
AlignedVector<T> values;
/**
- * Size in each direction of the
- * table.
+ * Size in each direction of the table.
*/
TableIndices<N> table_size;
/**
- * Make all other table classes
- * friends.
+ * Make all other table classes friends.
*/
template <int, typename> friend class TableBase;
};
/**
- * A class representing a table with arbitrary but fixed number of
- * indices. This general template implements some additional functions
- * over those provided by the TableBase class, such as indexing
- * functions taking the correct number of arguments, etc.
+ * A class representing a table with arbitrary but fixed number of indices.
+ * This general template implements some additional functions over those
+ * provided by the TableBase class, such as indexing functions taking the
+ * correct number of arguments, etc.
*
- * Rather than this general template, these functions are implemented
- * in partial specializations of this class, with fixed numbers of
- * dimensions. See there, and in the documentation of the base class
- * for more information.
+ * Rather than this general template, these functions are implemented in
+ * partial specializations of this class, with fixed numbers of dimensions.
+ * See there, and in the documentation of the base class for more information.
*
* @ingroup data
* @author Wolfgang Bangerth, 2002
/**
- * A class representing a one-dimensional table, i.e. a vector-like
- * class. Since the C++ library has a vector class, there is probably
- * not much need for this particular class, but since it is so simple
- * to implement on top of the template base class, we provide it
- * anyway.
+ * A class representing a one-dimensional table, i.e. a vector-like class.
+ * Since the C++ library has a vector class, there is probably not much need
+ * for this particular class, but since it is so simple to implement on top of
+ * the template base class, we provide it anyway.
*
- * For the rationale of this class, and a description of the
- * interface, see the base class.
+ * For the rationale of this class, and a description of the interface, see
+ * the base class.
*
* @ingroup data
* @author Wolfgang Bangerth, 2002
{
public:
/**
- * Default constructor. Set all
- * dimensions to zero.
+ * Default constructor. Set all dimensions to zero.
*/
Table ();
/**
- * Constructor. Pass down the
- * given dimension to the base
- * class.
+ * Constructor. Pass down the given dimension to the base class.
*/
Table (const unsigned int size);
/**
- * Constructor. Create a table with a given size and initialize it from
- * a set of iterators.
+ * Constructor. Create a table with a given size and initialize it from a
+ * set of iterators.
*
* This function is entirely equivalent to creating a table <code>t</code>
* of the given size and then calling
* on it, using the TableBase::fill() function where the arguments are
* explained in more detail. The point, however, is that that is only
* possible if the table can be changed after running the constructor,
- * whereas calling the current constructor allows sizing and initializing
- * an object right away so that it can be marked const.
+ * whereas calling the current constructor allows sizing and initializing an
+ * object right away so that it can be marked const.
*
* Using this constructor, you can do things like this:
* @code
*
*
* @param size The size of this one-dimensional table.
- * @param entries An iterator to a set of elements from which to
- * initialize this table. It is assumed that iterator can be
- * incremented and dereferenced a sufficient number of times
- * to fill this table.
- * @param C_style_indexing If true, run over elements of the
- * table with the last index changing fastest as we dereference
- * subsequent elements of the input range. If false, change
- * the first index fastest.
+ * @param entries An iterator to a set of elements from which to initialize
+ * this table. It is assumed that iterator can be incremented and
+ * dereferenced a sufficient number of times to fill this table.
+ * @param C_style_indexing If true, run over elements of the table with the
+ * last index changing fastest as we dereference subsequent elements of the
+ * input range. If false, change the first index fastest.
*/
template <typename InputIterator>
Table (const unsigned int size,
const bool C_style_indexing = true);
/**
- * Access operator. Since this is
- * a one-dimensional object, this
- * simply accesses the requested
- * data element. Returns a
- * read-only reference.
+ * Access operator. Since this is a one-dimensional object, this simply
+ * accesses the requested data element. Returns a read-only reference.
*/
typename AlignedVector<T>::const_reference
operator [] (const unsigned int i) const;
/**
- * Access operator. Since this is
- * a one-dimensional object, this
- * simply accesses the requested
- * data element. Returns a
- * read-write reference.
+ * Access operator. Since this is a one-dimensional object, this simply
+ * accesses the requested data element. Returns a read-write reference.
*/
typename AlignedVector<T>::reference
operator [] (const unsigned int i);
/**
- * Access operator. Since this is
- * a one-dimensional object, this
- * simply accesses the requested
- * data element. Returns a
- * read-only reference.
+ * Access operator. Since this is a one-dimensional object, this simply
+ * accesses the requested data element. Returns a read-only reference.
*/
typename AlignedVector<T>::const_reference
operator () (const unsigned int i) const;
/**
- * Access operator. Since this is
- * a one-dimensional object, this
- * simply accesses the requested
- * data element. Returns a
- * read-write reference.
+ * Access operator. Since this is a one-dimensional object, this simply
+ * accesses the requested data element. Returns a read-write reference.
*/
typename AlignedVector<T>::reference
operator () (const unsigned int i);
/**
- * Make the corresponding
- * operator () from the TableBase
- * base class available also in
- * this class.
+ * Make the corresponding operator () from the TableBase base class
+ * available also in this class.
*/
typename AlignedVector<T>::reference
operator () (const TableIndices<1> &indices);
/**
- * Make the corresponding
- * operator () from the TableBase
- * base class available also in
- * this class.
+ * Make the corresponding operator () from the TableBase base class
+ * available also in this class.
*/
typename AlignedVector<T>::const_reference
operator () (const TableIndices<1> &indices) const;
/**
- * A class representing a two-dimensional table, i.e. a matrix of
- * objects (not necessarily only numbers).
+ * A class representing a two-dimensional table, i.e. a matrix of objects (not
+ * necessarily only numbers).
*
- * For the rationale of this class, and a description of the
- * interface, see the base class. Since this serves as the base class
- * of the full matrix classes in this library, and to keep a minimal
- * compatibility with a predecessor class (<tt>vector2d</tt>), some
- * additional functions are provided.
+ * For the rationale of this class, and a description of the interface, see
+ * the base class. Since this serves as the base class of the full matrix
+ * classes in this library, and to keep a minimal compatibility with a
+ * predecessor class (<tt>vector2d</tt>), some additional functions are
+ * provided.
*
* @ingroup data
* @author Wolfgang Bangerth, 2002
{
public:
/**
- * Default constructor. Set all
- * dimensions to zero.
+ * Default constructor. Set all dimensions to zero.
*/
Table ();
/**
- * Constructor. Pass down the
- * given dimensions to the base
- * class.
+ * Constructor. Pass down the given dimensions to the base class.
*/
Table (const unsigned int size1,
const unsigned int size2);
/**
- * Constructor. Create a table with a given size and initialize it from
- * a set of iterators.
+ * Constructor. Create a table with a given size and initialize it from a
+ * set of iterators.
*
* This function is entirely equivalent to creating a table <code>t</code>
* of the given size and then calling
* on it, using the TableBase::fill() function where the arguments are
* explained in more detail. The point, however, is that that is only
* possible if the table can be changed after running the constructor,
- * whereas calling the current constructor allows sizing and initializing
- * an object right away so that it can be marked const.
+ * whereas calling the current constructor allows sizing and initializing an
+ * object right away so that it can be marked const.
*
* Using this constructor, you can do things like this:
* @code
*
* @param size1 The size of this table in the first dimension.
* @param size2 The size of this table in the second dimension.
- * @param entries An iterator to a set of elements from which to
- * initialize this table. It is assumed that iterator can be
- * incremented and dereferenced a sufficient number of times
- * to fill this table.
- * @param C_style_indexing If true, run over elements of the
- * table with the last index changing fastest as we dereference
- * subsequent elements of the input range. If false, change
- * the first index fastest.
+ * @param entries An iterator to a set of elements from which to initialize
+ * this table. It is assumed that iterator can be incremented and
+ * dereferenced a sufficient number of times to fill this table.
+ * @param C_style_indexing If true, run over elements of the table with the
+ * last index changing fastest as we dereference subsequent elements of the
+ * input range. If false, change the first index fastest.
*/
template <typename InputIterator>
Table (const unsigned int size1,
const bool C_style_indexing = true);
/**
- * Reinitialize the object. This
- * function is mostly here for
- * compatibility with the earlier
- * <tt>vector2d</tt> class. Passes
- * down to the base class by
- * converting the arguments to
- * the data type requested by the
- * base class.
+ * Reinitialize the object. This function is mostly here for compatibility
+ * with the earlier <tt>vector2d</tt> class. Passes down to the base class
+ * by converting the arguments to the data type requested by the base class.
*/
void reinit (const unsigned int size1,
const unsigned int size2,
const bool fast = false);
/**
- * Access operator. Generate an
- * object that accesses the
- * requested row of this
- * two-dimensional table. Range
- * checks are performed.
+ * Access operator. Generate an object that accesses the requested row of
+ * this two-dimensional table. Range checks are performed.
*
- * This version of the function
- * only allows read access.
+ * This version of the function only allows read access.
*/
dealii::internal::TableBaseAccessors::Accessor<2,T,true,1>
operator [] (const unsigned int i) const;
/**
- * Access operator. Generate an
- * object that accesses the
- * requested row of this
- * two-dimensional table. Range
- * checks are performed.
+ * Access operator. Generate an object that accesses the requested row of
+ * this two-dimensional table. Range checks are performed.
*
- * This version of the function
- * allows read-write access.
+ * This version of the function allows read-write access.
*/
dealii::internal::TableBaseAccessors::Accessor<2,T,false,1>
operator [] (const unsigned int i);
/**
- * Direct access to one element
- * of the table by specifying all
- * indices at the same time. Range
- * checks are performed.
+ * Direct access to one element of the table by specifying all indices at
+ * the same time. Range checks are performed.
*
- * This version of the function
- * only allows read access.
+ * This version of the function only allows read access.
*/
typename AlignedVector<T>::const_reference
operator () (const unsigned int i,
/**
- * Direct access to one element
- * of the table by specifying all
- * indices at the same time. Range
- * checks are performed.
+ * Direct access to one element of the table by specifying all indices at
+ * the same time. Range checks are performed.
*
- * This version of the function
- * allows read-write access.
+ * This version of the function allows read-write access.
*/
typename AlignedVector<T>::reference
operator () (const unsigned int i,
const unsigned int j);
/**
- * Make the corresponding
- * operator () from the TableBase
- * base class available also in
- * this class.
+ * Make the corresponding operator () from the TableBase base class
+ * available also in this class.
*/
typename AlignedVector<T>::reference
operator () (const TableIndices<2> &indices);
/**
- * Make the corresponding
- * operator () from the TableBase
- * base class available also in
- * this class.
+ * Make the corresponding operator () from the TableBase base class
+ * available also in this class.
*/
typename AlignedVector<T>::const_reference
operator () (const TableIndices<2> &indices) const;
/**
- * Number of rows. This function
- * really makes only sense since
- * we have a two-dimensional
- * object here.
+ * Number of rows. This function really makes only sense since we have a
+ * two-dimensional object here.
*/
unsigned int n_rows () const;
/**
- * Number of columns. This function
- * really makes only sense since
- * we have a two-dimensional
- * object here.
+ * Number of columns. This function really makes only sense since we have a
+ * two-dimensional object here.
*/
unsigned int n_cols () const;
protected:
/**
- * Return a read-write reference
- * to the element <tt>(i,j)</tt>.
+ * Return a read-write reference to the element <tt>(i,j)</tt>.
*
- * This function does no bounds
- * checking and is only to be
- * used internally and in
- * functions already checked.
+ * This function does no bounds checking and is only to be used internally
+ * and in functions already checked.
*
- * These functions are mainly
- * here for compatibility with a
- * former implementation of these
- * table classes for 2d arrays,
- * then called <tt>vector2d</tt>.
+ * These functions are mainly here for compatibility with a former
+ * implementation of these table classes for 2d arrays, then called
+ * <tt>vector2d</tt>.
*/
typename AlignedVector<T>::reference el (const unsigned int i,
const unsigned int j);
/**
- * Return the value of the
- * element <tt>(i,j)</tt> as a
- * read-only reference.
+ * Return the value of the element <tt>(i,j)</tt> as a read-only reference.
*
- * This function does no bounds
- * checking and is only to be
- * used internally and in
- * functions already checked.
+ * This function does no bounds checking and is only to be used internally
+ * and in functions already checked.
*
- * We return the requested value
- * as a constant reference rather
- * than by value since this
- * object may hold data types
- * that may be large, and we
- * don't know here whether
- * copying is expensive or not.
+ * We return the requested value as a constant reference rather than by
+ * value since this object may hold data types that may be large, and we
+ * don't know here whether copying is expensive or not.
*
- * These functions are mainly
- * here for compatibility with a
- * former implementation of these
- * table classes for 2d arrays,
- * then called <tt>vector2d</tt>.
+ * These functions are mainly here for compatibility with a former
+ * implementation of these table classes for 2d arrays, then called
+ * <tt>vector2d</tt>.
*/
typename AlignedVector<T>::const_reference el (const unsigned int i,
const unsigned int j) const;
/**
- * A class representing a three-dimensional table of objects (not
- * necessarily only numbers).
+ * A class representing a three-dimensional table of objects (not necessarily
+ * only numbers).
*
- * For the rationale of this class, and a description of the
- * interface, see the base class.
+ * For the rationale of this class, and a description of the interface, see
+ * the base class.
*
* @ingroup data
* @author Wolfgang Bangerth, 2002
{
public:
/**
- * Default constructor. Set all
- * dimensions to zero.
+ * Default constructor. Set all dimensions to zero.
*/
Table ();
/**
- * Constructor. Pass down the
- * given dimensions to the base
- * class.
+ * Constructor. Pass down the given dimensions to the base class.
*/
Table (const unsigned int size1,
const unsigned int size2,
const unsigned int size3);
/**
- * Constructor. Create a table with a given size and initialize it from
- * a set of iterators.
+ * Constructor. Create a table with a given size and initialize it from a
+ * set of iterators.
*
* This function is entirely equivalent to creating a table <code>t</code>
* of the given size and then calling
* on it, using the TableBase::fill() function where the arguments are
* explained in more detail. The point, however, is that that is only
* possible if the table can be changed after running the constructor,
- * whereas calling the current constructor allows sizing and initializing
- * an object right away so that it can be marked const.
+ * whereas calling the current constructor allows sizing and initializing an
+ * object right away so that it can be marked const.
*
- * Using this constructor, you can do things like this (shown here for
- * a two-dimensional table, but the same works for the current class):
+ * Using this constructor, you can do things like this (shown here for a
+ * two-dimensional table, but the same works for the current class):
* @code
* const double values[] = { 1, 2, 3, 4, 5, 6 };
* const Table<2,double> t(2, 3, entries, true);
* @param size1 The size of this table in the first dimension.
* @param size2 The size of this table in the second dimension.
* @param size3 The size of this table in the third dimension.
- * @param entries An iterator to a set of elements from which to
- * initialize this table. It is assumed that iterator can be
- * incremented and dereferenced a sufficient number of times
- * to fill this table.
- * @param C_style_indexing If true, run over elements of the
- * table with the last index changing fastest as we dereference
- * subsequent elements of the input range. If false, change
- * the first index fastest.
+ * @param entries An iterator to a set of elements from which to initialize
+ * this table. It is assumed that iterator can be incremented and
+ * dereferenced a sufficient number of times to fill this table.
+ * @param C_style_indexing If true, run over elements of the table with the
+ * last index changing fastest as we dereference subsequent elements of the
+ * input range. If false, change the first index fastest.
*/
template <typename InputIterator>
Table (const unsigned int size1,
const bool C_style_indexing = true);
/**
- * Access operator. Generate an
- * object that accesses the
- * requested two-dimensional
- * subobject of this
- * three-dimensional table. Range
- * checks are performed.
+ * Access operator. Generate an object that accesses the requested two-
+ * dimensional subobject of this three-dimensional table. Range checks are
+ * performed.
*
- * This version of the function
- * only allows read access.
+ * This version of the function only allows read access.
*/
dealii::internal::TableBaseAccessors::Accessor<3,T,true,2>
operator [] (const unsigned int i) const;
/**
- * Access operator. Generate an
- * object that accesses the
- * requested two-dimensional
- * subobject of this
- * three-dimensional table. Range
- * checks are performed.
+ * Access operator. Generate an object that accesses the requested two-
+ * dimensional subobject of this three-dimensional table. Range checks are
+ * performed.
*
- * This version of the function
- * allows read-write access.
+ * This version of the function allows read-write access.
*/
dealii::internal::TableBaseAccessors::Accessor<3,T,false,2>
operator [] (const unsigned int i);
/**
- * Direct access to one element
- * of the table by specifying all
- * indices at the same time. Range
- * checks are performed.
+ * Direct access to one element of the table by specifying all indices at
+ * the same time. Range checks are performed.
*
- * This version of the function
- * only allows read access.
+ * This version of the function only allows read access.
*/
typename AlignedVector<T>::const_reference operator () (const unsigned int i,
const unsigned int j,
/**
- * Direct access to one element
- * of the table by specifying all
- * indices at the same time. Range
- * checks are performed.
+ * Direct access to one element of the table by specifying all indices at
+ * the same time. Range checks are performed.
*
- * This version of the function
- * allows read-write access.
+ * This version of the function allows read-write access.
*/
typename AlignedVector<T>::reference operator () (const unsigned int i,
const unsigned int j,
const unsigned int k);
/**
- * Make the corresponding
- * operator () from the TableBase
- * base class available also in
- * this class.
+ * Make the corresponding operator () from the TableBase base class
+ * available also in this class.
*/
typename AlignedVector<T>::reference operator () (const TableIndices<3> &indices);
/**
- * Make the corresponding
- * operator () from the TableBase
- * base class available also in
- * this class.
+ * Make the corresponding operator () from the TableBase base class
+ * available also in this class.
*/
typename AlignedVector<T>::const_reference operator () (const TableIndices<3> &indices) const;
};
/**
- * A class representing a four-dimensional table of objects (not
- * necessarily only numbers).
+ * A class representing a four-dimensional table of objects (not necessarily
+ * only numbers).
*
- * For the rationale of this class, and a description of the
- * interface, see the base class.
+ * For the rationale of this class, and a description of the interface, see
+ * the base class.
*
* @ingroup data
* @author Wolfgang Bangerth, Ralf Hartmann 2002
{
public:
/**
- * Default constructor. Set all
- * dimensions to zero.
+ * Default constructor. Set all dimensions to zero.
*/
Table ();
/**
- * Constructor. Pass down the
- * given dimensions to the base
- * class.
+ * Constructor. Pass down the given dimensions to the base class.
*/
Table (const unsigned int size1,
const unsigned int size2,
const unsigned int size4);
/**
- * Access operator. Generate an
- * object that accesses the
- * requested three-dimensional
- * subobject of this
- * four-dimensional table. Range
- * checks are performed.
+ * Access operator. Generate an object that accesses the requested three-
+ * dimensional subobject of this four-dimensional table. Range checks are
+ * performed.
*
- * This version of the function
- * only allows read access.
+ * This version of the function only allows read access.
*/
dealii::internal::TableBaseAccessors::Accessor<4,T,true,3>
operator [] (const unsigned int i) const;
/**
- * Access operator. Generate an
- * object that accesses the
- * requested three-dimensional
- * subobject of this
- * four-dimensional table. Range
- * checks are performed.
+ * Access operator. Generate an object that accesses the requested three-
+ * dimensional subobject of this four-dimensional table. Range checks are
+ * performed.
*
- * This version of the function
- * allows read-write access.
+ * This version of the function allows read-write access.
*/
dealii::internal::TableBaseAccessors::Accessor<4,T,false,3>
operator [] (const unsigned int i);
/**
- * Direct access to one element
- * of the table by specifying all
- * indices at the same time. Range
- * checks are performed.
+ * Direct access to one element of the table by specifying all indices at
+ * the same time. Range checks are performed.
*
- * This version of the function
- * only allows read access.
+ * This version of the function only allows read access.
*/
typename AlignedVector<T>::const_reference operator () (const unsigned int i,
const unsigned int j,
/**
- * Direct access to one element
- * of the table by specifying all
- * indices at the same time. Range
- * checks are performed.
+ * Direct access to one element of the table by specifying all indices at
+ * the same time. Range checks are performed.
*
- * This version of the function
- * allows read-write access.
+ * This version of the function allows read-write access.
*/
typename AlignedVector<T>::reference operator () (const unsigned int i,
const unsigned int j,
const unsigned int l);
/**
- * Make the corresponding
- * operator () from the TableBase
- * base class available also in
- * this class.
+ * Make the corresponding operator () from the TableBase base class
+ * available also in this class.
*/
typename AlignedVector<T>::reference
operator () (const TableIndices<4> &indices);
/**
- * Make the corresponding
- * operator () from the TableBase
- * base class available also in
- * this class.
+ * Make the corresponding operator () from the TableBase base class
+ * available also in this class.
*/
typename AlignedVector<T>::const_reference
operator () (const TableIndices<4> &indices) const;
/**
- * A class representing a five-dimensional table of objects (not
- * necessarily only numbers).
+ * A class representing a five-dimensional table of objects (not necessarily
+ * only numbers).
*
- * For the rationale of this class, and a description of the
- * interface, see the base class.
+ * For the rationale of this class, and a description of the interface, see
+ * the base class.
*
* @ingroup data
* @author Wolfgang Bangerth, Ralf Hartmann 2002
{
public:
/**
- * Default constructor. Set all
- * dimensions to zero.
+ * Default constructor. Set all dimensions to zero.
*/
Table ();
/**
- * Constructor. Pass down the
- * given dimensions to the base
- * class.
+ * Constructor. Pass down the given dimensions to the base class.
*/
Table (const unsigned int size1,
const unsigned int size2,
const unsigned int size5);
/**
- * Access operator. Generate an
- * object that accesses the
- * requested four-dimensional
- * subobject of this
- * five-dimensional table. Range
- * checks are performed.
+ * Access operator. Generate an object that accesses the requested four-
+ * dimensional subobject of this five-dimensional table. Range checks are
+ * performed.
*
- * This version of the function
- * only allows read access.
+ * This version of the function only allows read access.
*/
dealii::internal::TableBaseAccessors::Accessor<5,T,true,4>
operator [] (const unsigned int i) const;
/**
- * Access operator. Generate an
- * object that accesses the
- * requested four-dimensional
- * subobject of this
- * five-dimensional table. Range
- * checks are performed.
+ * Access operator. Generate an object that accesses the requested four-
+ * dimensional subobject of this five-dimensional table. Range checks are
+ * performed.
*
- * This version of the function
- * allows read-write access.
+ * This version of the function allows read-write access.
*/
dealii::internal::TableBaseAccessors::Accessor<5,T,false,4>
operator [] (const unsigned int i);
/**
- * Direct access to one element
- * of the table by specifying all
- * indices at the same time. Range
- * checks are performed.
+ * Direct access to one element of the table by specifying all indices at
+ * the same time. Range checks are performed.
*
- * This version of the function
- * only allows read access.
+ * This version of the function only allows read access.
*/
typename AlignedVector<T>::const_reference operator () (const unsigned int i,
const unsigned int j,
const unsigned int m) const;
/**
- * Direct access to one element
- * of the table by specifying all
- * indices at the same time. Range
- * checks are performed.
+ * Direct access to one element of the table by specifying all indices at
+ * the same time. Range checks are performed.
*
- * This version of the function
- * allows read-write access.
+ * This version of the function allows read-write access.
*/
typename AlignedVector<T>::reference operator () (const unsigned int i,
const unsigned int j,
const unsigned int m);
/**
- * Make the corresponding
- * operator () from the TableBase
- * base class available also in
- * this class.
+ * Make the corresponding operator () from the TableBase base class
+ * available also in this class.
*/
typename AlignedVector<T>::reference
operator () (const TableIndices<5> &indices);
/**
- * Make the corresponding
- * operator () from the TableBase
- * base class available also in
- * this class.
+ * Make the corresponding operator () from the TableBase base class
+ * available also in this class.
*/
typename AlignedVector<T>::const_reference
operator () (const TableIndices<5> &indices) const;
/**
- * A class representing a six-dimensional table of objects (not
- * necessarily only numbers).
+ * A class representing a six-dimensional table of objects (not necessarily
+ * only numbers).
*
- * For the rationale of this class, and a description of the
- * interface, see the base class.
+ * For the rationale of this class, and a description of the interface, see
+ * the base class.
*
* @ingroup data
* @author Wolfgang Bangerth, Ralf Hartmann 2002
{
public:
/**
- * Default constructor. Set all
- * dimensions to zero.
+ * Default constructor. Set all dimensions to zero.
*/
Table ();
/**
- * Constructor. Pass down the
- * given dimensions to the base
- * class.
+ * Constructor. Pass down the given dimensions to the base class.
*/
Table (const unsigned int size1,
const unsigned int size2,
const unsigned int size6);
/**
- * Access operator. Generate an
- * object that accesses the
- * requested five-dimensional
- * subobject of this
- * six-dimensional table. Range
- * checks are performed.
+ * Access operator. Generate an object that accesses the requested five-
+ * dimensional subobject of this six-dimensional table. Range checks are
+ * performed.
*
- * This version of the function
- * only allows read access.
+ * This version of the function only allows read access.
*/
dealii::internal::TableBaseAccessors::Accessor<6,T,true,5>
operator [] (const unsigned int i) const;
/**
- * Access operator. Generate an
- * object that accesses the
- * requested five-dimensional
- * subobject of this
- * six-dimensional table. Range
- * checks are performed.
+ * Access operator. Generate an object that accesses the requested five-
+ * dimensional subobject of this six-dimensional table. Range checks are
+ * performed.
*
- * This version of the function
- * allows read-write access.
+ * This version of the function allows read-write access.
*/
dealii::internal::TableBaseAccessors::Accessor<6,T,false,5>
operator [] (const unsigned int i);
/**
- * Direct access to one element
- * of the table by specifying all
- * indices at the same time. Range
- * checks are performed.
+ * Direct access to one element of the table by specifying all indices at
+ * the same time. Range checks are performed.
*
- * This version of the function
- * only allows read access.
+ * This version of the function only allows read access.
*/
typename AlignedVector<T>::const_reference operator () (const unsigned int i,
const unsigned int j,
const unsigned int n) const;
/**
- * Direct access to one element
- * of the table by specifying all
- * indices at the same time. Range
- * checks are performed.
+ * Direct access to one element of the table by specifying all indices at
+ * the same time. Range checks are performed.
*
- * This version of the function
- * allows read-write access.
+ * This version of the function allows read-write access.
*/
typename AlignedVector<T>::reference operator () (const unsigned int i,
const unsigned int j,
const unsigned int n);
/**
- * Make the corresponding
- * operator () from the TableBase
- * base class available also in
- * this class.
+ * Make the corresponding operator () from the TableBase base class
+ * available also in this class.
*/
typename AlignedVector<T>::reference
operator () (const TableIndices<6> &indices);
/**
- * Make the corresponding
- * operator () from the TableBase
- * base class available also in
- * this class.
+ * Make the corresponding operator () from the TableBase base class
+ * available also in this class.
*/
typename AlignedVector<T>::const_reference
operator () (const TableIndices<6> &indices) const;
/**
- * A class representing a seven-dimensional table of objects (not
- * necessarily only numbers).
+ * A class representing a seven-dimensional table of objects (not necessarily
+ * only numbers).
*
- * For the rationale of this class, and a description of the
- * interface, see the base class.
+ * For the rationale of this class, and a description of the interface, see
+ * the base class.
*
* @ingroup data
* @author Wolfgang Bangerth, 2002, Ralf Hartmann 2004
{
public:
/**
- * Default constructor. Set all
- * dimensions to zero.
+ * Default constructor. Set all dimensions to zero.
*/
Table ();
/**
- * Constructor. Pass down the
- * given dimensions to the base
- * class.
+ * Constructor. Pass down the given dimensions to the base class.
*/
Table (const unsigned int size1,
const unsigned int size2,
const unsigned int size7);
/**
- * Access operator. Generate an
- * object that accesses the
- * requested six-dimensional
- * subobject of this
- * seven-dimensional table. Range
- * checks are performed.
+ * Access operator. Generate an object that accesses the requested six-
+ * dimensional subobject of this seven-dimensional table. Range checks are
+ * performed.
*
- * This version of the function
- * only allows read access.
+ * This version of the function only allows read access.
*/
dealii::internal::TableBaseAccessors::Accessor<7,T,true,6>
operator [] (const unsigned int i) const;
/**
- * Access operator. Generate an
- * object that accesses the
- * requested six-dimensional
- * subobject of this
- * seven-dimensional table. Range
- * checks are performed.
+ * Access operator. Generate an object that accesses the requested six-
+ * dimensional subobject of this seven-dimensional table. Range checks are
+ * performed.
*
- * This version of the function
- * allows read-write access.
+ * This version of the function allows read-write access.
*/
dealii::internal::TableBaseAccessors::Accessor<7,T,false,6>
operator [] (const unsigned int i);
/**
- * Direct access to one element
- * of the table by specifying all
- * indices at the same time. Range
- * checks are performed.
+ * Direct access to one element of the table by specifying all indices at
+ * the same time. Range checks are performed.
*
- * This version of the function
- * only allows read access.
+ * This version of the function only allows read access.
*/
typename AlignedVector<T>::const_reference operator () (const unsigned int i,
const unsigned int j,
const unsigned int o) const;
/**
- * Direct access to one element
- * of the table by specifying all
- * indices at the same time. Range
- * checks are performed.
+ * Direct access to one element of the table by specifying all indices at
+ * the same time. Range checks are performed.
*
- * This version of the function
- * allows read-write access.
+ * This version of the function allows read-write access.
*/
typename AlignedVector<T>::reference operator () (const unsigned int i,
const unsigned int j,
const unsigned int o);
/**
- * Make the corresponding
- * operator () from the TableBase
- * base class available also in
- * this class.
+ * Make the corresponding operator () from the TableBase base class
+ * available also in this class.
*/
typename AlignedVector<T>::reference
operator () (const TableIndices<7> &indices);
/**
- * Make the corresponding
- * operator () from the TableBase
- * base class available also in
- * this class.
+ * Make the corresponding operator () from the TableBase base class
+ * available also in this class.
*/
typename AlignedVector<T>::const_reference
operator () (const TableIndices<7> &indices) const;
* convention). The only real difference is therefore really in the storage
* format.
*
- * This class copies the functions of Table<2,T>, but the element
- * access and the dimensions will be for the transpose ordering of the
- * data field in TableBase.
+ * This class copies the functions of Table<2,T>, but the element access and
+ * the dimensions will be for the transpose ordering of the data field in
+ * TableBase.
*
* @ingroup data
* @author Guido Kanschat, 2005
{
public:
/**
- * Default constructor. Set all
- * dimensions to zero.
+ * Default constructor. Set all dimensions to zero.
*/
TransposeTable ();
/**
- * Constructor. Pass down the
- * given dimensions to the base
- * class.
+ * Constructor. Pass down the given dimensions to the base class.
*/
TransposeTable (const unsigned int size1,
const unsigned int size2);
/**
- * Reinitialize the object. This
- * function is mostly here for
- * compatibility with the earlier
- * <tt>vector2d</tt> class. Passes
- * down to the base class by
- * converting the arguments to
- * the data type requested by the
- * base class.
+ * Reinitialize the object. This function is mostly here for compatibility
+ * with the earlier <tt>vector2d</tt> class. Passes down to the base class
+ * by converting the arguments to the data type requested by the base class.
*/
void reinit (const unsigned int size1,
const unsigned int size2,
const bool fast = false);
/**
- * Direct access to one element
- * of the table by specifying all
- * indices at the same time. Range
- * checks are performed.
+ * Direct access to one element of the table by specifying all indices at
+ * the same time. Range checks are performed.
*
- * This version of the function
- * only allows read access.
+ * This version of the function only allows read access.
*/
typename AlignedVector<T>::const_reference operator () (const unsigned int i,
const unsigned int j) const;
/**
- * Direct access to one element
- * of the table by specifying all
- * indices at the same time. Range
- * checks are performed.
+ * Direct access to one element of the table by specifying all indices at
+ * the same time. Range checks are performed.
*
- * This version of the function
- * allows read-write access.
+ * This version of the function allows read-write access.
*/
typename AlignedVector<T>::reference operator () (const unsigned int i,
const unsigned int j);
/**
- * Number of rows. This function
- * really makes only sense since
- * we have a two-dimensional
- * object here.
+ * Number of rows. This function really makes only sense since we have a
+ * two-dimensional object here.
*/
unsigned int n_rows () const;
/**
- * Number of columns. This function
- * really makes only sense since
- * we have a two-dimensional
- * object here.
+ * Number of columns. This function really makes only sense since we have a
+ * two-dimensional object here.
*/
unsigned int n_cols () const;
protected:
/**
- * Return a read-write reference
- * to the element <tt>(i,j)</tt>.
+ * Return a read-write reference to the element <tt>(i,j)</tt>.
*
- * This function does no bounds
- * checking and is only to be
- * used internally and in
- * functions already checked.
+ * This function does no bounds checking and is only to be used internally
+ * and in functions already checked.
*
- * These functions are mainly
- * here for compatibility with a
- * former implementation of these
- * table classes for 2d arrays,
- * then called <tt>vector2d</tt>.
+ * These functions are mainly here for compatibility with a former
+ * implementation of these table classes for 2d arrays, then called
+ * <tt>vector2d</tt>.
*/
typename AlignedVector<T>::reference el (const unsigned int i,
const unsigned int j);
/**
- * Return the value of the
- * element <tt>(i,j)</tt> as a
- * read-only reference.
+ * Return the value of the element <tt>(i,j)</tt> as a read-only reference.
*
- * This function does no bounds
- * checking and is only to be
- * used internally and in
- * functions already checked.
+ * This function does no bounds checking and is only to be used internally
+ * and in functions already checked.
*
- * We return the requested value
- * as a constant reference rather
- * than by value since this
- * object may hold data types
- * that may be large, and we
- * don't know here whether
- * copying is expensive or not.
+ * We return the requested value as a constant reference rather than by
+ * value since this object may hold data types that may be large, and we
+ * don't know here whether copying is expensive or not.
*
- * These functions are mainly
- * here for compatibility with a
- * former implementation of these
- * table classes for 2d arrays,
- * then called <tt>vector2d</tt>.
+ * These functions are mainly here for compatibility with a former
+ * implementation of these table classes for 2d arrays, then called
+ * <tt>vector2d</tt>.
*/
typename AlignedVector<T>::const_reference el (const unsigned int i,
const unsigned int j) const;
/**
- * Global function @p swap which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two tables.
+ * Global function @p swap which overloads the default implementation of the
+ * C++ standard library which uses a temporary object. The function simply
+ * exchanges the data of the two tables.
*
* @author Martin Kronbichler, 2013
*/
namespace internal
{
/**
- * A <tt>TableEntry</tt> stores the value of a table entry.
- * It can either be of type int, unsigned int, double or std::string.
- * In essence, this structure is the same as
- * <code>boost::variant@<int,unsigned int,double,std::string@></code>
- * but we wrap this object in a structure for which we can write
- * a function that can serialize it. This is also why the function
- * is not in fact of type boost::any.
+ * A <tt>TableEntry</tt> stores the value of a table entry. It can either be
+ * of type int, unsigned int, double or std::string. In essence, this
+ * structure is the same as <code>boost::variant@<int,unsigned
+ * int,double,std::string@></code> but we wrap this object in a structure
+ * for which we can write a function that can serialize it. This is also why
+ * the function is not in fact of type boost::any.
*/
struct TableEntry
{
TableEntry ();
/**
- * Constructor. Initialize this table element with the value <code>t</code>.
+ * Constructor. Initialize this table element with the value
+ * <code>t</code>.
*/
template <typename T>
TableEntry (const T &t);
/**
- * Return the value stored by this object. The template type
- * T must be one of <code>int,unsigned int,double,std::string</code>
- * and it must match the data type of the object originally stored
- * in this TableEntry object.
+ * Return the value stored by this object. The template type T must be one
+ * of <code>int,unsigned int,double,std::string</code> and it must match
+ * the data type of the object originally stored in this TableEntry
+ * object.
*/
template <typename T>
T get () const;
/**
- * Return the numeric value of this object if data has been stored in
- * it either as an integer, an unsigned integer, or a double.
+ * Return the numeric value of this object if data has been stored in it
+ * either as an integer, an unsigned integer, or a double.
*
* @return double
- **/
+ */
double get_numeric_value () const;
/**
- * Cache the contained value with the given formatting and return it. The given parameters
- * from the column definition are used for the formatting. The value
- * is cached as a string internally in cached_value. The cache needs to be invalidated with this routine
- * if the formatting of the column changes.
+ * Cache the contained value with the given formatting and return it. The
+ * given parameters from the column definition are used for the
+ * formatting. The value is cached as a string internally in cached_value.
+ * The cache needs to be invalidated with this routine if the formatting
+ * of the column changes.
*/
void cache_string(bool scientific, unsigned int precision) const;
/**
- * Return the value cached using cache_string(). This is just a wrapper around cached_value.
+ * Return the value cached using cache_string(). This is just a wrapper
+ * around cached_value.
*/
const std::string &get_cached_string() const;
/**
- * Return a TableEntry object that has the same data type
- * of the stored value but with a value that is default
- * constructed for this data type. This is used to pad
- * columns below previously set ones.
+ * Return a TableEntry object that has the same data type of the stored
+ * value but with a value that is default constructed for this data type.
+ * This is used to pad columns below previously set ones.
*/
TableEntry get_default_constructed_copy() const;
/**
- * Write the data of this object to a
- * stream for the purpose of
+ * Write the data of this object to a stream for the purpose of
* serialization.
*/
template <class Archive>
void save (Archive &ar, const unsigned int version) const;
/**
- * Read the data of this object from a
- * stream for the purpose of
+ * Read the data of this object from a stream for the purpose of
* serialization.
*/
template <class Archive>
/**
- * The TableHandler stores TableEntries of arbitrary value
- * type and writes the table as text or in tex format to an output
- * stream. The value type actually may vary from column to column and
- * from row to row.
+ * The TableHandler stores TableEntries of arbitrary value type and writes the
+ * table as text or in tex format to an output stream. The value type actually
+ * may vary from column to column and from row to row.
*
* <h3>Usage</h3>
*
* exist and adds the given value of type <tt>T</tt> (which must be one of
* <tt>int</tt>, <tt>unsigned int</tt>, <tt>double</tt>, <tt>std::string</tt>)
* to this column. After the table is complete there are different
- * possibilities of output, e.g., into a latex file with write_tex() or as text
- * with write_text().
+ * possibilities of output, e.g., into a latex file with write_tex() or as
+ * text with write_text().
*
- * Two (or more) columns may be merged into a "supercolumn" by twice
- * (or multiple) calling add_column_to_supercolumn(), see
- * there. Additionally there is a function to set for each column the
- * precision of the output of numbers, and there are several functions
- * to prescribe the format and the captions the columns are written
- * with in tex mode.
+ * Two (or more) columns may be merged into a "supercolumn" by twice (or
+ * multiple) calling add_column_to_supercolumn(), see there. Additionally
+ * there is a function to set for each column the precision of the output of
+ * numbers, and there are several functions to prescribe the format and the
+ * captions the columns are written with in tex mode.
*
* A detailed explanation of this class is also given in the step-13 tutorial
* program.
*
* <h3>Example</h3>
*
- * This is a simple example demonstrating the usage of this class. The
- * first column includes the numbers <tt>i=1..n</tt>, the second
- * $1^2$...$n^2$, the third $sqrt(1)...sqrt(n)$, where the second and
- * third columns are merged into one supercolumn with the superkey
- * <tt>squares and roots</tt>. Additionally the first column is aligned to
- * the right (the default was <tt>centered</tt>) and the precision of the
- * square roots are set to be 6 (instead of 4 as default).
+ * This is a simple example demonstrating the usage of this class. The first
+ * column includes the numbers <tt>i=1..n</tt>, the second $1^2$...$n^2$, the
+ * third $sqrt(1)...sqrt(n)$, where the second and third columns are merged
+ * into one supercolumn with the superkey <tt>squares and roots</tt>.
+ * Additionally the first column is aligned to the right (the default was
+ * <tt>centered</tt>) and the precision of the square roots are set to be 6
+ * (instead of 4 as default).
*
* @code
* TableHandler table;
*
* <h3>Dealing with sparse data: auto-fill mode</h3>
*
- * When generating output, TableHandler expects that all columns have the exact
- * same number of elements in it so that the result is in fact a table. This
- * assumes that in each of the iterations (time steps, nonlinear iterations, etc)
- * you fill every single column. On the other hand, this may not always be what
- * you want to do. For example, it could be that the function that computes the
- * nonlinear residual is only called every few time steps; or, a function computing
- * statistics of the mesh is only called whenever the mesh is in fact refined.
- * In these cases, the add_value() function will be called less often for some
- * columns and the column would therefore have fewer elements; furthermore, these
- * elements would not be aligned with the rows that contain the other data elements
- * that were produced during this iteration.
- * An entirely different scenario is that the table is filled and at a later time
- * we use the data in there to compute the elements of other rows; the ConvergenceTable
- * class does something like this.
+ * When generating output, TableHandler expects that all columns have the
+ * exact same number of elements in it so that the result is in fact a table.
+ * This assumes that in each of the iterations (time steps, nonlinear
+ * iterations, etc) you fill every single column. On the other hand, this may
+ * not always be what you want to do. For example, it could be that the
+ * function that computes the nonlinear residual is only called every few time
+ * steps; or, a function computing statistics of the mesh is only called
+ * whenever the mesh is in fact refined. In these cases, the add_value()
+ * function will be called less often for some columns and the column would
+ * therefore have fewer elements; furthermore, these elements would not be
+ * aligned with the rows that contain the other data elements that were
+ * produced during this iteration. An entirely different scenario is that the
+ * table is filled and at a later time we use the data in there to compute the
+ * elements of other rows; the ConvergenceTable class does something like
+ * this.
*
- * To support both scenarios, the TableHandler class has a property called
- * <i>auto-fill mode</i>. By default, auto-fill mode is off, but it can be
- * enabled by calling set_auto_fill_mode(). If auto-fill mode is enabled
- * we use the following algorithm:
- * - When calling <code>add_value(key, value)</code>, we count the number of elements
- * in the column corresponding to <code>key</code>. Let's call this number $m$.
- * - We also determine the maximal number of elements in the other columns; call
- * it $n$.
- * - If $m < n-1$ then we add $n-m-1$ copies of the object <code>T()</code>
- * to this column. Here, <code>T</code> is the data type of the given <code>value</code>.
- * For example, if <code>T</code> is a numeric type, then <code>T()</code> is
- * the number zero; if <code>T</code> is <code>std::string</code>, then
- * <code>T()</code> is the empty string <code>""</code>.
- * - Add the given value to this column.
+ * To support both scenarios, the TableHandler class has a property called <i
+ * >auto-fill mode</i>. By default, auto-fill mode is off, but it can be
+ * enabled by calling set_auto_fill_mode(). If auto-fill mode is enabled we
+ * use the following algorithm: - When calling <code>add_value(key,
+ * value)</code>, we count the number of elements in the column corresponding
+ * to <code>key</code>. Let's call this number $m$. - We also determine the
+ * maximal number of elements in the other columns; call it $n$. - If $m <
+ * n-1$ then we add $n-m-1$ copies of the object <code>T()</code> to this
+ * column. Here, <code>T</code> is the data type of the given
+ * <code>value</code>. For example, if <code>T</code> is a numeric type, then
+ * <code>T()</code> is the number zero; if <code>T</code> is
+ * <code>std::string</code>, then <code>T()</code> is the empty string
+ * <code>""</code>. - Add the given value to this column.
*
- * Padding the column with default elements makes sure that after the addition the
- * column has as many entries as the longest other column. In other words, if
- * we have skipped previous invokations of add_value() for a given key, then the
- * padding will enter default values into this column.
+ * Padding the column with default elements makes sure that after the addition
+ * the column has as many entries as the longest other column. In other words,
+ * if we have skipped previous invokations of add_value() for a given key,
+ * then the padding will enter default values into this column.
*
- * The algorithm as described will fail if you try to skip adding values for a key
- * if adding an element for this key is the first thing you want to do for a given
- * iteration or time step, since we would then pad to the length of the longest
- * column of the <i>previous</i> iteration or time step. You may have to re-order
- * adding to this column to a different spot in your program, after adding to
- * a column that will always be added to; or, you may want to start every iteration
- * by adding the number of the iteration to the table, for example in column 1.
+ * The algorithm as described will fail if you try to skip adding values for a
+ * key if adding an element for this key is the first thing you want to do for
+ * a given iteration or time step, since we would then pad to the length of
+ * the longest column of the <i>previous</i> iteration or time step. You may
+ * have to re-order adding to this column to a different spot in your program,
+ * after adding to a column that will always be added to; or, you may want to
+ * start every iteration by adding the number of the iteration to the table,
+ * for example in column 1.
*
- * In the case above, we have always padded columns <b>above</b> the element that
- * is being added to a column. However, there is also a case where we have to pad
- * <b>below</b>. Namely, if a previous row has been completely filled using
- * TableHandler::add_value(), subsequent rows have been filled partially, and we
- * then ask for output via write_text() or write_tex(). In that case, the last
- * few rows that have been filled only partially need to be padded below the last
- * element that has been added to them. As before, we do that by using default
- * constructed objects of the same type as the last element of that column.
+ * In the case above, we have always padded columns <b>above</b> the element
+ * that is being added to a column. However, there is also a case where we
+ * have to pad <b>below</b>. Namely, if a previous row has been completely
+ * filled using TableHandler::add_value(), subsequent rows have been filled
+ * partially, and we then ask for output via write_text() or write_tex(). In
+ * that case, the last few rows that have been filled only partially need to
+ * be padded below the last element that has been added to them. As before, we
+ * do that by using default constructed objects of the same type as the last
+ * element of that column.
*
* @ingroup textoutput
* @author Ralf Hartmann, 1999; Wolfgang Bangerth, 2011
{
public:
/**
- * Set of options how a table should be formatted when output with
- * the write_text() function. The following possibilities exist:
+ * Set of options how a table should be formatted when output with the
+ * write_text() function. The following possibilities exist:
*
* - <code>table_with_headers</code>: The table is formatted in such a way
- * that the contents are aligned under the key of each column, i.e. the
- * key sits atop each column. This is suitable for tables with few columns
- * where the entire table can be displayed on the screen. Output looks
- * like this:
+ * that the contents are aligned under the key of each column, i.e. the key
+ * sits atop each column. This is suitable for tables with few columns where
+ * the entire table can be displayed on the screen. Output looks like this:
* @code
* key1 key2 key3
* 0 0 ""
* 1 0 ""
* @endcode
* - <code>table_with_separate_column_description</code>: This is a better
- * format when there are many columns and the table as a whole can not
- * be displayed on the screen. Here, the column keys are first listed
- * one-by-one on lines of their own, and are numbered for better readability.
- * In addition, each of these description lines are prefixed by '#' to mark
- * these lines as comments for programs that want to read the following
- * table as data and should ignore these descriptive lines. GNUPLOT is
- * one such program that will automatically ignore lines so prefixed.
- * Output with this option looks like this:
+ * format when there are many columns and the table as a whole can not be
+ * displayed on the screen. Here, the column keys are first listed one-by-
+ * one on lines of their own, and are numbered for better readability. In
+ * addition, each of these description lines are prefixed by '#' to mark
+ * these lines as comments for programs that want to read the following
+ * table as data and should ignore these descriptive lines. GNUPLOT is one
+ * such program that will automatically ignore lines so prefixed. Output
+ * with this option looks like this:
* @code
* # 1: key1
* # 2: key2
* 1 0 ""
* @endcode
* - <code>simple_table_with_separate_column_description</code>: This format
- * is very similar to <code>table_with_separate_column_description</code>,
- * but it skips aligning the columns with additional white space. This
- * increases the performance o fwrite_text() for large tables. Example output:
+ * is very similar to <code>table_with_separate_column_description</code>,
+ * but it skips aligning the columns with additional white space. This
+ * increases the performance o fwrite_text() for large tables. Example
+ * output:
* @code
* # 1: key1
* # 2: key2
* 2 13 a
* 1 0 ""
* @endcode
- * - <code>org_mode_table</code>: Outputs to org-mode (http://orgmode.org/) table
- * format. It is easy to convert org-mode tables to HTML/LaTeX/csv.
- * Example output:
+ * - <code>org_mode_table</code>: Outputs to org-mode (http://orgmode.org/)
+ * table format. It is easy to convert org-mode tables to HTML/LaTeX/csv.
+ * Example output:
* @code
* | key1 | key2 | key3 |
* | 0 | 0 | "" |
TableHandler ();
/**
- * Adds a column (if not yet existent)
- * with the key <tt>key</tt> and adds the
- * value of type <tt>T</tt> to the
- * column. Values of type <tt>T</tt> must
- * be convertible to one of <code>int,
- * unsigned int, double,
- * std::string</code> or a compiler error
- * will result.
+ * Adds a column (if not yet existent) with the key <tt>key</tt> and adds
+ * the value of type <tt>T</tt> to the column. Values of type <tt>T</tt>
+ * must be convertible to one of <code>int, unsigned int, double,
+ * std::string</code> or a compiler error will result.
*/
template <typename T>
void add_value (const std::string &key,
const T value);
/**
- * Switch auto-fill mode on or off. See the general documentation
- * of this class for a description of what auto-fill mode does.
+ * Switch auto-fill mode on or off. See the general documentation of this
+ * class for a description of what auto-fill mode does.
*/
void set_auto_fill_mode (const bool state);
/**
- * Creates a supercolumn (if not
- * yet existent) and includes
- * column to it. The keys of the
- * column and the supercolumn are
- * <tt>key</tt> and <tt>superkey</tt>,
- * respectively. To merge two
- * columns <tt>c1</tt> and <tt>c2</tt> to a
- * supercolumn <tt>sc</tt> hence call
- * <tt>add_column_to_supercolumn(c1,sc)</tt>
- * and
+ * Creates a supercolumn (if not yet existent) and includes column to it.
+ * The keys of the column and the supercolumn are <tt>key</tt> and
+ * <tt>superkey</tt>, respectively. To merge two columns <tt>c1</tt> and
+ * <tt>c2</tt> to a supercolumn <tt>sc</tt> hence call
+ * <tt>add_column_to_supercolumn(c1,sc)</tt> and
* <tt>add_column_to_supercolumn(c2,sc)</tt>.
*
- * Concerning the order of the
- * columns, the supercolumn
- * replaces the first column that
- * is added to the supercolumn.
- * Within the supercolumn the
- * order of output follows the
- * order the columns are added to
- * the supercolumn.
+ * Concerning the order of the columns, the supercolumn replaces the first
+ * column that is added to the supercolumn. Within the supercolumn the order
+ * of output follows the order the columns are added to the supercolumn.
*/
void add_column_to_supercolumn (const std::string &key,
const std::string &superkey);
/**
- * Change the order of columns and
- * supercolumns in the table.
+ * Change the order of columns and supercolumns in the table.
*
- * <tt>new_order</tt> includes the
- * keys and superkeys of the
- * columns and supercolumns in
- * the order the user would like them to be output.
- * If a superkey is included the
- * keys of the subcolumns need
- * not be explicitly
- * mentioned in this vector. The
- * order of subcolumns within a
- * supercolumn is not changeable
- * and remains in the order in which
- * the columns are added to the
- * supercolumn.
+ * <tt>new_order</tt> includes the keys and superkeys of the columns and
+ * supercolumns in the order the user would like them to be output. If a
+ * superkey is included the keys of the subcolumns need not be explicitly
+ * mentioned in this vector. The order of subcolumns within a supercolumn
+ * is not changeable and remains in the order in which the columns are added
+ * to the supercolumn.
*
- * This function may also be used
- * to break big tables with too
- * many columns into smaller
- * ones. For example, you can call this function with
- * the first five columns
- * and then call one of the <tt>write_*</tt> functions,
- * then call this function
- * with the next five
- * columns and again <tt>write_*</tt>,
+ * This function may also be used to break big tables with too many columns
+ * into smaller ones. For example, you can call this function with the first
+ * five columns and then call one of the <tt>write_*</tt> functions, then
+ * call this function with the next five columns and again <tt>write_*</tt>,
* and so on.
*/
void set_column_order (const std::vector<std::string> &new_order);
/**
- * Sets the <tt>precision</tt>
- * e.g. double or float variables
- * are written
- * with. <tt>precision</tt> is the
- * same as in calling
+ * Sets the <tt>precision</tt> e.g. double or float variables are written
+ * with. <tt>precision</tt> is the same as in calling
* <tt>out<<setprecision(precision)</tt>.
*/
void set_precision (const std::string &key,
const unsigned int precision);
/**
- * Sets the
- * <tt>scientific_flag</tt>. True
- * means scientific, false means
+ * Sets the <tt>scientific_flag</tt>. True means scientific, false means
* fixed point notation.
*/
void set_scientific (const std::string &key,
const bool scientific);
/**
- * Sets the caption of the column
- * <tt>key</tt> for tex output. You
- * may want to chose this
- * different from <tt>key</tt>, if it
- * contains formulas or similar
- * constructs.
+ * Sets the caption of the column <tt>key</tt> for tex output. You may want
+ * to chose this different from <tt>key</tt>, if it contains formulas or
+ * similar constructs.
*/
void set_tex_caption (const std::string &key,
const std::string &tex_caption);
/**
- * Sets the tex caption of the entire
- * <tt>table</tt> for tex output.
- */
+ * Sets the tex caption of the entire <tt>table</tt> for tex output.
+ */
void set_tex_table_caption (const std::string &table_caption);
/**
- * Sets the label of this
- * <tt>table</tt> for tex output.
+ * Sets the label of this <tt>table</tt> for tex output.
*/
void set_tex_table_label (const std::string &table_label);
/**
- * Sets the caption the the
- * supercolumn <tt>superkey</tt> for
- * tex output. You may want to
- * chose this different from
- * <tt>superkey</tt>, if it contains
- * formulas or similar
- * constructs.
+ * Sets the caption the the supercolumn <tt>superkey</tt> for tex output.
+ * You may want to chose this different from <tt>superkey</tt>, if it
+ * contains formulas or similar constructs.
*/
void set_tex_supercaption (const std::string &superkey,
const std::string &tex_supercaption);
/**
- * Sets the tex output format of
- * a column, e.g. <tt>c</tt>, <tt>r</tt>,
- * <tt>l</tt>, or <tt>p{3cm}</tt>. The
- * default is <tt>c</tt>. Also if this
- * function is not called for a
- * column, the default is preset
- * to be <tt>c</tt>.
+ * Sets the tex output format of a column, e.g. <tt>c</tt>, <tt>r</tt>,
+ * <tt>l</tt>, or <tt>p{3cm}</tt>. The default is <tt>c</tt>. Also if this
+ * function is not called for a column, the default is preset to be
+ * <tt>c</tt>.
*/
void set_tex_format (const std::string &key,
const std::string &format="c");
/**
- * Write table as formatted text to the
- * given stream. The text is formatted in
- * such as way that it represents data as
- * formatted columns of text. To avoid
- * problems when reading these tables
- * automatically, for example for
- * postprocessing, if an entry in a cell
- * of this table is empty (i.e. it has
- * been created by calling the
- * add_value() function with an empty
- * string), then the entry of the table
- * is printed as <code>""</code>.
+ * Write table as formatted text to the given stream. The text is formatted
+ * in such as way that it represents data as formatted columns of text. To
+ * avoid problems when reading these tables automatically, for example for
+ * postprocessing, if an entry in a cell of this table is empty (i.e. it has
+ * been created by calling the add_value() function with an empty string),
+ * then the entry of the table is printed as <code>""</code>.
*
- * The second argument indicates how
- * column keys are to be displayed. See
- * the description of TextOutputFormat
- * for more information
+ * The second argument indicates how column keys are to be displayed. See
+ * the description of TextOutputFormat for more information
*/
void write_text (std::ostream &out,
const TextOutputFormat format = table_with_headers) const;
/**
- * Write table as a tex file. If
- * with_header is set to false
- * (it is true by default), then
- * no "\documentclass{...}",
- * "\begin{document}" and
- * "\end{document}" are used. In
- * this way the file can be
- * included into an existing tex
- * file using a command like
- * "\input{table_file}".
+ * Write table as a tex file. If with_header is set to false (it is true by
+ * default), then no "\documentclass{...}", "\begin{document}" and
+ * "\end{document}" are used. In this way the file can be included into an
+ * existing tex file using a command like "\input{table_file}".
*/
void write_tex (std::ostream &file, const bool with_header=true) const;
/**
- * Clears the rows of the table,
- * i.e. calls clear() on all the
- * underlying storage data structures.
+ * Clears the rows of the table, i.e. calls clear() on all the underlying
+ * storage data structures.
*/
void clear ();
/**
- * Read or write the data of this
- * object to or from a stream for
- * the purpose of serialization.
+ * Read or write the data of this object to or from a stream for the purpose
+ * of serialization.
*/
template <class Archive>
void serialize(Archive &ar, const unsigned int version);
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
protected:
/**
- * Structure encapsulating all the data
- * that is needed to describe one column
- * of a table.
+ * Structure encapsulating all the data that is needed to describe one
+ * column of a table.
*/
struct Column
{
Column (const std::string &tex_caption);
/**
- * Pad this column with default constructed elements to the
- * number of rows given by the argument.
+ * Pad this column with default constructed elements to the number of rows
+ * given by the argument.
*/
void pad_column_below (const unsigned int length);
/**
- * Read or write the data of this
- * object to or from a stream for
- * the purpose of serialization.
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization.
*/
template <class Archive>
void save(Archive &ar, const unsigned int version) const;
/**
- * Invalidates the string cache of all the entries and recomputes
- * the maximum length max_length.
+ * Invalidates the string cache of all the entries and recomputes the
+ * maximum length max_length.
*/
void invalidate_cache();
/**
- * List of entries within
- * this column. Values are
- * always immediately
- * converted to strings to
- * provide a uniform method
- * of lookup.
+ * List of entries within this column. Values are always immediately
+ * converted to strings to provide a uniform method of lookup.
*/
std::vector<internal::TableEntry> entries;
/**
- * The caption of the column
- * in tex output. By
- * default, this is the key
- * string that is given to
- * the <tt>TableHandler</tt> by
- * <tt>TableHandler::add_value(...)</tt>. This
- * may be changed by calling
+ * The caption of the column in tex output. By default, this is the key
+ * string that is given to the <tt>TableHandler</tt> by
+ * <tt>TableHandler::add_value(...)</tt>. This may be changed by calling
* <tt>TableHandler::set_tex_caption(...)</tt>.
*/
std::string tex_caption;
/**
- * The column format in tex
- * output. By default, this
- * is <tt>"c"</tt>, meaning
- * `centered'. This may be
- * changed by calling
- * <tt>TableHandler::set_tex_format(...)</tt>
- * with <tt>"c", "r", "l"</tt> for
- * centered, right or left.
+ * The column format in tex output. By default, this is <tt>"c"</tt>,
+ * meaning `centered'. This may be changed by calling
+ * <tt>TableHandler::set_tex_format(...)</tt> with <tt>"c", "r", "l"</tt>
+ * for centered, right or left.
*/
std::string tex_format;
/**
- * Double or float entries
- * are written with this
- * precision (set by the
+ * Double or float entries are written with this precision (set by the
* user). The default is 4.
*/
unsigned int precision;
/**
- * <tt>scientific</tt>=false means
- * fixed point notation.
+ * <tt>scientific</tt>=false means fixed point notation.
*/
bool scientific;
/**
- * Flag that may be used by
- * derived classes for
- * arbitrary purposes.
+ * Flag that may be used by derived classes for arbitrary purposes.
*
- * In particular, the
- * ConvergenceTable class uses the
- * flag to denote columns for which
- * convergence information has
- * already been computed, or should
- * not be computed at all.
+ * In particular, the ConvergenceTable class uses the flag to denote
+ * columns for which convergence information has already been computed, or
+ * should not be computed at all.
*/
unsigned int flag;
/**
- * This entry caches the maximum length in characters for all entries in this table.
+ * This entry caches the maximum length in characters for all entries in
+ * this table.
*/
unsigned int max_length;
};
/**
- * Help function that gives a
- * vector of the keys of all
- * columns that are mentioned in
- * <tt>column_order</tt>, where each
- * supercolumn key is replaced by
- * its subcolumn keys.
+ * Help function that gives a vector of the keys of all columns that are
+ * mentioned in <tt>column_order</tt>, where each supercolumn key is
+ * replaced by its subcolumn keys.
*
- * This function implicitly
- * checks the consistency of the
- * data. The result is returned
- * in <tt>sel_columns</tt>.
+ * This function implicitly checks the consistency of the data. The result
+ * is returned in <tt>sel_columns</tt>.
*/
void get_selected_columns (std::vector<std::string> &sel_columns) const;
/**
- * Builtin function, that gives
- * the number of rows in the
- * table and that checks if the
- * number of rows is equal in
- * every column. This function is
- * e.g. called before writing
- * output.
+ * Builtin function, that gives the number of rows in the table and that
+ * checks if the number of rows is equal in every column. This function is
+ * e.g. called before writing output.
*/
unsigned int n_rows() const;
/**
- * Stores the column and
- * supercolumn keys in the order
- * desired by the user. By
- * default this is the order of
- * adding the columns. This order
- * may be changed by
- * <tt>set_column_order(...)</tt>.
+ * Stores the column and supercolumn keys in the order desired by the user.
+ * By default this is the order of adding the columns. This order may be
+ * changed by <tt>set_column_order(...)</tt>.
*/
std::vector<std::string> column_order;
/**
- * Maps the column keys to the
- * columns (not supercolumns).
+ * Maps the column keys to the columns (not supercolumns).
*
- * The field is declared mutable so
- * that the write_text() and write_tex()
- * functions can be const, even though they
- * may pad columns below if auto_fill_mode
- * is on.
+ * The field is declared mutable so that the write_text() and write_tex()
+ * functions can be const, even though they may pad columns below if
+ * auto_fill_mode is on.
*/
mutable std::map<std::string,Column> columns;
/**
- * Maps each supercolumn key to
- * the the keys of its subcolumns
- * in the right order. It is
- * allowed that a supercolumn has
- * got the same key as a column.
+ * Maps each supercolumn key to the the keys of its subcolumns in the right
+ * order. It is allowed that a supercolumn has got the same key as a
+ * column.
*
- * Note that we do not use a <tt>multimap</tt>
- * here since the order of column
- * keys for each supercolumn key is
- * relevant.
+ * Note that we do not use a <tt>multimap</tt> here since the order of
+ * column keys for each supercolumn key is relevant.
*/
std::map<std::string, std::vector<std::string> > supercolumns;
/**
- * Maps the supercolumn keys to
- * the captions of the
- * supercolumns that are used in
- * tex output.
+ * Maps the supercolumn keys to the captions of the supercolumns that are
+ * used in tex output.
*
- * By default these are just the
- * supercolumn keys but they may
- * be changed by
+ * By default these are just the supercolumn keys but they may be changed by
* <tt>set_tex_supercaptions(...)</tt>.
*/
std::map<std::string, std::string> tex_supercaptions;
{
public:
/**
- * Access the value of the
- * <tt>i</tt>th index.
+ * Access the value of the <tt>i</tt>th index.
*/
unsigned int operator[] (const unsigned int i) const;
/**
- * Write access the value of the
- * <tt>i</tt>th index.
+ * Write access the value of the <tt>i</tt>th index.
*/
unsigned int &operator[] (const unsigned int i);
/**
- * Compare two index fields for
- * equality.
+ * Compare two index fields for equality.
*/
bool operator == (const TableIndicesBase<N> &other) const;
/**
- * Compare two index fields for
- * inequality.
+ * Compare two index fields for inequality.
*/
bool operator != (const TableIndicesBase<N> &other) const;
/**
- * Sort the indices in ascending
- * order. While this operation is not
- * very useful for Table objects, it is
- * used for the SymmetricTensor class.
+ * Sort the indices in ascending order. While this operation is not very
+ * useful for Table objects, it is used for the SymmetricTensor class.
*/
void sort ();
/**
- * Write or read the data of this object to or
- * from a stream for the purpose of serialization.
+ * Write or read the data of this object to or from a stream for the purpose
+ * of serialization.
*/
template <class Archive>
void serialize (Archive &ar, const unsigned int version);
/**
- * Array of indices of fixed size used for the TableBase
- * class.
+ * Array of indices of fixed size used for the TableBase class.
*
- * This is the general template, and has no implementation. There are
- * a number of specializations that are actually implemented (one for
- * each used value of <tt>N</tt>), which only differ in the way they
- * implement their constructors (they take <tt>N</tt> arguments, something
- * that cannot be represented by a general template). Actual storage
- * of and access to data is done by the TableIndicesBase base
- * class of a specializations.
+ * This is the general template, and has no implementation. There are a number
+ * of specializations that are actually implemented (one for each used value
+ * of <tt>N</tt>), which only differ in the way they implement their
+ * constructors (they take <tt>N</tt> arguments, something that cannot be
+ * represented by a general template). Actual storage of and access to data is
+ * done by the TableIndicesBase base class of a specializations.
*
* @ingroup data
* @author Wolfgang Bangerth, 2002
class TableIndices : public TableIndicesBase<N>
{
/**
- * Standard constructor, setting
- * all indices to zero.
+ * Standard constructor, setting all indices to zero.
*/
TableIndices();
/**
- * The actual constructor, taking
- * @p N arguments of type
- * <tt>unsigned int</tt> to
- * initialize the index object.
+ * The actual constructor, taking @p N arguments of type <tt>unsigned
+ * int</tt> to initialize the index object.
*/
TableIndices(...);
};
/**
- * Array of indices of fixed size used for the TableBase
- * class.
+ * Array of indices of fixed size used for the TableBase class.
*
- * This is the specialization for a one-dimensional table, i.e. a
- * vector. This class only differs in the non-default constructors
- * from the other specializations. Actual storage of and access to
- * data is done by the TableIndicesBase base class of a
- * specializations.
+ * This is the specialization for a one-dimensional table, i.e. a vector. This
+ * class only differs in the non-default constructors from the other
+ * specializations. Actual storage of and access to data is done by the
+ * TableIndicesBase base class of a specializations.
*
* @ingroup data
* @author Wolfgang Bangerth, 2002
{
public:
/**
- * Default constructor. Set all
- * indices to zero.
+ * Default constructor. Set all indices to zero.
*/
TableIndices ();
/**
- * Constructor. Set indices to
- * the given values.
+ * Constructor. Set indices to the given values.
*/
TableIndices (const unsigned int index1);
};
//the constructors into the class template
/**
- * Array of indices of fixed size used for the TableBase
- * class.
+ * Array of indices of fixed size used for the TableBase class.
*
- * This is the specialization for a two-dimensional table. This class
- * only differs in the non-default constructors from the other
- * specializations. Actual storage of and access to data is done by
- * the TableIndicesBase base class of a specializations.
+ * This is the specialization for a two-dimensional table. This class only
+ * differs in the non-default constructors from the other specializations.
+ * Actual storage of and access to data is done by the TableIndicesBase base
+ * class of a specializations.
*
* @ingroup data
* @author Wolfgang Bangerth, 2002
{
public:
/**
- * Default constructor. Set all
- * indices to zero.
+ * Default constructor. Set all indices to zero.
*/
TableIndices ();
/**
- * Constructor. Set indices to
- * the given values.
+ * Constructor. Set indices to the given values.
*
- * The default values for the
- * second and subsequent
- * arguments are necessary for
- * some neat template tricks in
- * SymmetricTensor where we only
- * want to set the first index
- * and construct the subsequent
- * ones later on, i.e. for the
- * moment we don't care about the
- * later indices.
+ * The default values for the second and subsequent arguments are necessary
+ * for some neat template tricks in SymmetricTensor where we only want to
+ * set the first index and construct the subsequent ones later on, i.e. for
+ * the moment we don't care about the later indices.
*/
TableIndices (const unsigned int index1,
const unsigned int index2 = numbers::invalid_unsigned_int);
/**
- * Array of indices of fixed size used for the TableBase
- * class.
+ * Array of indices of fixed size used for the TableBase class.
*
- * This is the specialization for a three-dimensional table. This class
- * only differs in the non-default constructors from the other
- * specializations. Actual storage of and access to data is done by
- * the TableIndicesBase base class of a specializations.
+ * This is the specialization for a three-dimensional table. This class only
+ * differs in the non-default constructors from the other specializations.
+ * Actual storage of and access to data is done by the TableIndicesBase base
+ * class of a specializations.
*
* @ingroup data
* @author Wolfgang Bangerth, 2002
{
public:
/**
- * Default constructor. Set all
- * indices to zero.
+ * Default constructor. Set all indices to zero.
*/
TableIndices ();
/**
- * Constructor. Set indices to
- * the given values.
+ * Constructor. Set indices to the given values.
*
- * The default values for the
- * second and subsequent
- * arguments are necessary for
- * some neat template tricks in
- * SymmetricTensor where we only
- * want to set the first index
- * and construct the subsequent
- * ones later on, i.e. for the
- * moment we don't care about the
- * later indices.
+ * The default values for the second and subsequent arguments are necessary
+ * for some neat template tricks in SymmetricTensor where we only want to
+ * set the first index and construct the subsequent ones later on, i.e. for
+ * the moment we don't care about the later indices.
*/
TableIndices (const unsigned int index1,
const unsigned int index2 = numbers::invalid_unsigned_int,
/**
- * Array of indices of fixed size used for the TableBase
- * class.
+ * Array of indices of fixed size used for the TableBase class.
*
- * This is the specialization for a four-dimensional table. This class
- * only differs in the non-default constructors from the other
- * specializations. Actual storage of and access to data is done by
- * the TableIndicesBase base class of a specializations.
+ * This is the specialization for a four-dimensional table. This class only
+ * differs in the non-default constructors from the other specializations.
+ * Actual storage of and access to data is done by the TableIndicesBase base
+ * class of a specializations.
*
* @ingroup data
* @author Wolfgang Bangerth, Ralf Hartmann 2002
{
public:
/**
- * Default constructor. Set all
- * indices to zero.
+ * Default constructor. Set all indices to zero.
*/
TableIndices ();
/**
- * Constructor. Set indices to
- * the given values.
+ * Constructor. Set indices to the given values.
*
- * The default values for the
- * second and subsequent
- * arguments are necessary for
- * some neat template tricks in
- * SymmetricTensor where we only
- * want to set the first index
- * and construct the subsequent
- * ones later on, i.e. for the
- * moment we don't care about the
- * later indices.
+ * The default values for the second and subsequent arguments are necessary
+ * for some neat template tricks in SymmetricTensor where we only want to
+ * set the first index and construct the subsequent ones later on, i.e. for
+ * the moment we don't care about the later indices.
*/
TableIndices (const unsigned int index1,
const unsigned int index2 = numbers::invalid_unsigned_int,
/**
- * Array of indices of fixed size used for the TableBase
- * class.
+ * Array of indices of fixed size used for the TableBase class.
*
- * This is the specialization for a five-dimensional table. This class
- * only differs in the non-default constructors from the other
- * specializations. Actual storage of and access to data is done by
- * the TableIndicesBase base class of a specializations.
+ * This is the specialization for a five-dimensional table. This class only
+ * differs in the non-default constructors from the other specializations.
+ * Actual storage of and access to data is done by the TableIndicesBase base
+ * class of a specializations.
*
* @ingroup data
* @author Wolfgang Bangerth, Ralf Hartmann 2002
{
public:
/**
- * Default constructor. Set all
- * indices to zero.
+ * Default constructor. Set all indices to zero.
*/
TableIndices ();
/**
- * Constructor. Set indices to
- * the given values.
+ * Constructor. Set indices to the given values.
*
- * The default values for the
- * second and subsequent
- * arguments are necessary for
- * some neat template tricks in
- * SymmetricTensor where we only
- * want to set the first index
- * and construct the subsequent
- * ones later on, i.e. for the
- * moment we don't care about the
- * later indices.
+ * The default values for the second and subsequent arguments are necessary
+ * for some neat template tricks in SymmetricTensor where we only want to
+ * set the first index and construct the subsequent ones later on, i.e. for
+ * the moment we don't care about the later indices.
*/
TableIndices (const unsigned int index1,
const unsigned int index2 = numbers::invalid_unsigned_int,
/**
- * Array of indices of fixed size used for the TableBase
- * class.
+ * Array of indices of fixed size used for the TableBase class.
*
- * This is the specialization for a six-dimensional table. This class
- * only differs in the non-default constructors from the other
- * specializations. Actual storage of and access to data is done by
- * the TableIndicesBase base class of a specializations.
+ * This is the specialization for a six-dimensional table. This class only
+ * differs in the non-default constructors from the other specializations.
+ * Actual storage of and access to data is done by the TableIndicesBase base
+ * class of a specializations.
*
* @ingroup data
* @author Wolfgang Bangerth, Ralf Hartmann 2002
{
public:
/**
- * Default constructor. Set all
- * indices to zero.
+ * Default constructor. Set all indices to zero.
*/
TableIndices ();
/**
- * Constructor. Set indices to
- * the given values.
+ * Constructor. Set indices to the given values.
*
- * The default values for the
- * second and subsequent
- * arguments are necessary for
- * some neat template tricks in
- * SymmetricTensor where we only
- * want to set the first index
- * and construct the subsequent
- * ones later on, i.e. for the
- * moment we don't care about the
- * later indices.
+ * The default values for the second and subsequent arguments are necessary
+ * for some neat template tricks in SymmetricTensor where we only want to
+ * set the first index and construct the subsequent ones later on, i.e. for
+ * the moment we don't care about the later indices.
*/
TableIndices (const unsigned int index1,
const unsigned int index2 = numbers::invalid_unsigned_int,
/**
- * Array of indices of fixed size used for the TableBase
- * class.
+ * Array of indices of fixed size used for the TableBase class.
*
- * This is the specialization for a seven-dimensional table. This
- * class only differs in the non-default constructors from the other
- * specializations. Actual storage of and access to data is done by
- * the TableIndicesBase base class of a specializations.
+ * This is the specialization for a seven-dimensional table. This class only
+ * differs in the non-default constructors from the other specializations.
+ * Actual storage of and access to data is done by the TableIndicesBase base
+ * class of a specializations.
*
* @ingroup data
* @author Wolfgang Bangerth, 2002, Ralf Hartmann 2004
{
public:
/**
- * Default constructor. Set all
- * indices to zero.
+ * Default constructor. Set all indices to zero.
*/
TableIndices ();
/**
- * Constructor. Set indices to
- * the given values.
+ * Constructor. Set indices to the given values.
*
- * The default values for the
- * second and subsequent
- * arguments are necessary for
- * some neat template tricks in
- * SymmetricTensor where we only
- * want to set the first index
- * and construct the subsequent
- * ones later on, i.e. for the
- * moment we don't care about the
- * later indices.
+ * The default values for the second and subsequent arguments are necessary
+ * for some neat template tricks in SymmetricTensor where we only want to
+ * set the first index and construct the subsequent ones later on, i.e. for
+ * the moment we don't care about the later indices.
*/
TableIndices (const unsigned int index1,
const unsigned int index2 = numbers::invalid_unsigned_int,
/**
- * This specialization of the general template for the case of a
- * <tt>true</tt> first template argument declares a local typedef <tt>type</tt>
- * to the second template argument. It is used in order to construct
- * constraints on template arguments in template (and member template)
- * functions. The negative specialization is missing.
+ * This specialization of the general template for the case of a <tt>true</tt>
+ * first template argument declares a local typedef <tt>type</tt> to the
+ * second template argument. It is used in order to construct constraints on
+ * template arguments in template (and member template) functions. The
+ * negative specialization is missing.
*
- * Here's how the trick works, called SFINAE (substitution failure is
- * not an error): The C++ standard prescribes that a template function
- * is only considered in a call, if all parts of its signature can be
- * instantiated with the template parameter replaced by the respective
- * types/values in this particular call. Example:
+ * Here's how the trick works, called SFINAE (substitution failure is not an
+ * error): The C++ standard prescribes that a template function is only
+ * considered in a call, if all parts of its signature can be instantiated
+ * with the template parameter replaced by the respective types/values in this
+ * particular call. Example:
* @code
* template <typename T>
* typename T::type foo(T) {...};
* ...
* foo(1);
* @endcode
- * The compiler should detect that in this call, the template
- * parameter T must be identified with the type "int". However,
- * the return type T::type does not exist. The trick now is
- * that this is not considered an error: this template is simply
- * not considered, the compiler keeps on looking for another
- * possible function foo.
+ * The compiler should detect that in this call, the template parameter T must
+ * be identified with the type "int". However, the return type T::type does
+ * not exist. The trick now is that this is not considered an error: this
+ * template is simply not considered, the compiler keeps on looking for
+ * another possible function foo.
*
- * The idea is then to make the return type un-instantiatable if
- * certain constraints on the template types are not satisfied:
+ * The idea is then to make the return type un-instantiatable if certain
+ * constraints on the template types are not satisfied:
* @code
* template <bool, typename> struct constraint_and_return_value;
* template <typename T> struct constraint_and_return_value<true,T> {
* typename constraint_and_return_value<int_or_double<T>::value,void>::type
* f (T);
* @endcode
- * which can only be instantiated if T=int or T=double. A call to
- * f('c') will just fail with a compiler error: "no instance of
- * f(char) found". On the other hand, if the predicate in the first
- * argument to the constraint_and_return_value template is true, then
- * the return type is just the second type in the template.
+ * which can only be instantiated if T=int or T=double. A call to f('c') will
+ * just fail with a compiler error: "no instance of f(char) found". On the
+ * other hand, if the predicate in the first argument to the
+ * constraint_and_return_value template is true, then the return type is just
+ * the second type in the template.
*
* @author Wolfgang Bangerth, 2003
*/
* template <typename T> void f(T, T);
* @endcode
* then it can't be called in an expression like <code>f(1, 3.141)</code>
- * because the type <code>T</code> of the template can not be deduced
- * in a unique way from the types of the arguments. However, if the
- * template is written as
+ * because the type <code>T</code> of the template can not be deduced in a
+ * unique way from the types of the arguments. However, if the template is
+ * written as
* @code
* template <typename T> void f(T, typename identity<T>::type);
* @endcode
- * then the call becomes valid: the type <code>T</code> is not deducible
- * from the second argument to the function, so only the first argument
+ * then the call becomes valid: the type <code>T</code> is not deducible from
+ * the second argument to the function, so only the first argument
* participates in template type resolution.
*
* The context for this feature is as follows: consider
* template type <code>A</code> should be <code>double</code> (from the
* signature of the function given as first argument to
* <code>forward_call</code>, or <code>int</code> because the expression
- * <code>1</code> has that type. Of course, what we would like the compiler
- * to do is simply cast the <code>1</code> to <code>double</code>. We can
- * achieve this by writing the code as follows:
+ * <code>1</code> has that type. Of course, what we would like the compiler to
+ * do is simply cast the <code>1</code> to <code>double</code>. We can achieve
+ * this by writing the code as follows:
* @code
* template <typename RT, typename A>
* void forward_call(RT (*p) (A), typename identity<A>::type a) { p(a); }
struct PointerComparison
{
/**
- * Comparison function for pointers of
- * the same type. Returns @p true if the
+ * Comparison function for pointers of the same type. Returns @p true if the
* two pointers are equal.
*/
template <typename T>
static bool equal (const T *p1, const T *p2);
/**
- * Comparison function for pointers of
- * different types. The C++ language does
- * not allow comparing these pointers
- * using <tt>operator==</tt>. However,
- * since the two pointers have different
- * types, we know that they can't be the
- * same, so we always return @p false.
+ * Comparison function for pointers of different types. The C++ language
+ * does not allow comparing these pointers using <tt>operator==</tt>.
+ * However, since the two pointers have different types, we know that they
+ * can't be the same, so we always return @p false.
*/
template <typename T, typename U>
static bool equal (const T *, const U *);
namespace internal
{
/**
- * A type that is sometimes used for template tricks. For example, in
- * some situations one would like to do this:
+ * A type that is sometimes used for template tricks. For example, in some
+ * situations one would like to do this:
*
* @code
* template <int dim>
* @endcode
*
* The problem is: the language doesn't allow us to specialize
- * <code>X::f()</code> without specializing the outer class first. One
- * of the common tricks is therefore to use something like this:
+ * <code>X::f()</code> without specializing the outer class first. One of
+ * the common tricks is therefore to use something like this:
*
* @code
* template <int N> struct int2type {};
* @endcode
*
* Note that we have replaced specialization of <code>X::f()</code> by
- * overloading, but that from inside the function <code>g()</code>, we
- * can still select which of the different <code>X::f()</code> we want
- * based on the <code>subdim</code> template argument.
+ * overloading, but that from inside the function <code>g()</code>, we can
+ * still select which of the different <code>X::f()</code> we want based on
+ * the <code>subdim</code> template argument.
*
* @author Wolfgang Bangerth, 2006
*/
/**
- * A type that can be used to determine whether two types are equal.
- * It allows to write code like
+ * A type that can be used to determine whether two types are equal. It allows
+ * to write code like
* @code
* template <typename T>
* void Vector<T>::some_operation () {
/**
- * Partial specialization of the general template for the case that
- * both template arguments are equal. See the documentation of the
- * general template for more information.
+ * Partial specialization of the general template for the case that both
+ * template arguments are equal. See the documentation of the general template
+ * for more information.
*/
template <typename T>
struct types_are_equal<T,T>
template <int dim, typename Number> class Tensor<1,dim,Number>;
/**
- * Provide a general tensor class with an arbitrary rank, i.e. with
- * an arbitrary number of indices. The Tensor class provides an
- * indexing operator and a bit of infrastructure, but most
- * functionality is recursively handed down to tensors of rank 1 or
- * put into external templated functions, e.g. the <tt>contract</tt> family.
- *
- * Using this tensor class for objects of rank 2 has advantages over
- * matrices in many cases since the dimension is known to the compiler
- * as well as the location of the data. It is therefore possible to
- * produce far more efficient code than for matrices with
- * runtime-dependent dimension.
+ * Provide a general tensor class with an arbitrary rank, i.e. with an
+ * arbitrary number of indices. The Tensor class provides an indexing operator
+ * and a bit of infrastructure, but most functionality is recursively handed
+ * down to tensors of rank 1 or put into external templated functions, e.g.
+ * the <tt>contract</tt> family.
+ *
+ * Using this tensor class for objects of rank 2 has advantages over matrices
+ * in many cases since the dimension is known to the compiler as well as the
+ * location of the data. It is therefore possible to produce far more
+ * efficient code than for matrices with runtime-dependent dimension.
*
* This class provides an optional template argument for the type of the
* underlying data. It defaults to @p double values. It can be used to base
{
public:
/**
- * Provide a way to get the
- * dimension of an object without
- * explicit knowledge of it's
- * data type. Implementation is
- * this way instead of providing
- * a function <tt>dimension()</tt>
- * because now it is possible to
- * get the dimension at compile
- * time without the expansion and
- * preevaluation of an inlined
- * function; the compiler may
- * therefore produce more
- * efficient code and you may use
- * this value to declare other
- * data types.
+ * Provide a way to get the dimension of an object without explicit
+ * knowledge of it's data type. Implementation is this way instead of
+ * providing a function <tt>dimension()</tt> because now it is possible to
+ * get the dimension at compile time without the expansion and preevaluation
+ * of an inlined function; the compiler may therefore produce more efficient
+ * code and you may use this value to declare other data types.
*/
static const unsigned int dimension = dim;
/**
- * Publish the rank of this tensor to
- * the outside world.
+ * Publish the rank of this tensor to the outside world.
*/
static const unsigned int rank = rank_;
/**
- * Number of independent components of a
- * tensor of current rank. This is dim times the
- * number of independent components of each sub-tensor.
+ * Number of independent components of a tensor of current rank. This is dim
+ * times the number of independent components of each sub-tensor.
*/
static const unsigned int
n_independent_components = Tensor<rank_-1,dim>::n_independent_components *dim;
/**
- * Type of stored objects. This
- * is a tensor of lower rank.
+ * Type of stored objects. This is a tensor of lower rank.
*/
typedef Tensor<rank_-1,dim,Number> value_type;
/**
- * Declare a type that has holds
- * real-valued numbers with the same
- * precision as the template argument to
- * this class. For std::complex<number>,
- * this corresponds to type number, and
- * it is equal to Number for all other
- * cases. See also the respective field
- * in Vector<Number>.
+ * Declare a type that has holds real-valued numbers with the same precision
+ * as the template argument to this class. For std::complex<number>, this
+ * corresponds to type number, and it is equal to Number for all other
+ * cases. See also the respective field in Vector<Number>.
*
- * This typedef is used to
- * represent the return type of
- * norms.
+ * This typedef is used to represent the return type of norms.
*/
typedef typename numbers::NumberTraits<Number>::real_type real_type;
/**
- * Declare an array type which
- * can be used to initialize an
- * object of this type
- * statically.
+ * Declare an array type which can be used to initialize an object of this
+ * type statically.
*/
typedef typename Tensor<rank_-1,dim,Number>::array_type array_type[dim];
/**
- * Constructor. Initialize all entries
- * to zero.
+ * Constructor. Initialize all entries to zero.
*/
Tensor ();
/**
- * Copy constructor, where the data is
- * copied from a C-style array.
+ * Copy constructor, where the data is copied from a C-style array.
*/
Tensor (const array_type &initializer);
/**
- * Conversion operator from tensor of
- * tensors.
+ * Conversion operator from tensor of tensors.
*/
Tensor (const Tensor<1,dim,Tensor<rank_-1,dim,Number> > &tensor_in);
/**
- * Conversion operator to tensor of
- * tensors.
+ * Conversion operator to tensor of tensors.
*/
operator Tensor<1,dim,Tensor<rank_-1,dim,Number> > () const;
Number &operator [](const TableIndices<rank_> &indices);
/**
- * Assignment operator.
+ * Assignment operator.
*/
Tensor &operator = (const Tensor<rank_,dim,Number> &);
/**
- * This operator assigns a scalar
- * to a tensor. To avoid
- * confusion with what exactly it
- * means to assign a scalar value
- * to a tensor, zero is the only
- * value allowed for <tt>d</tt>,
- * allowing the intuitive
- * notation <tt>t=0</tt> to reset
- * all elements of the tensor to
- * zero.
+ * This operator assigns a scalar to a tensor. To avoid confusion with what
+ * exactly it means to assign a scalar value to a tensor, zero is the only
+ * value allowed for <tt>d</tt>, allowing the intuitive notation
+ * <tt>t=0</tt> to reset all elements of the tensor to zero.
*/
Tensor<rank_,dim,Number> &operator = (const Number d);
/**
- * Test for equality of two tensors.
+ * Test for equality of two tensors.
*/
bool operator == (const Tensor<rank_,dim,Number> &) const;
/**
- * Test for inequality of two tensors.
+ * Test for inequality of two tensors.
*/
bool operator != (const Tensor<rank_,dim,Number> &) const;
/**
- * Add another tensor.
+ * Add another tensor.
*/
Tensor<rank_,dim,Number> &operator += (const Tensor<rank_,dim,Number> &);
/**
- * Subtract another tensor.
+ * Subtract another tensor.
*/
Tensor<rank_,dim,Number> &operator -= (const Tensor<rank_,dim,Number> &);
/**
- * Scale the tensor by <tt>factor</tt>,
- * i.e. multiply all components by
- * <tt>factor</tt>.
+ * Scale the tensor by <tt>factor</tt>, i.e. multiply all components by
+ * <tt>factor</tt>.
*/
Tensor<rank_,dim,Number> &operator *= (const Number factor);
/**
- * Scale the vector by
- * <tt>1/factor</tt>.
+ * Scale the vector by <tt>1/factor</tt>.
*/
Tensor<rank_,dim,Number> &operator /= (const Number factor);
/**
- * Add two tensors. If possible, you
- * should use <tt>operator +=</tt>
- * instead since this does not need the
- * creation of a temporary.
+ * Add two tensors. If possible, you should use <tt>operator +=</tt> instead
+ * since this does not need the creation of a temporary.
*/
Tensor<rank_,dim,Number> operator + (const Tensor<rank_,dim,Number> &) const;
/**
- * Subtract two tensors. If possible,
- * you should use <tt>operator -=</tt>
- * instead since this does not need the
- * creation of a temporary.
+ * Subtract two tensors. If possible, you should use <tt>operator -=</tt>
+ * instead since this does not need the creation of a temporary.
*/
Tensor<rank_,dim,Number> operator - (const Tensor<rank_,dim,Number> &) const;
/**
- * Unary minus operator. Negate all
- * entries of a tensor.
+ * Unary minus operator. Negate all entries of a tensor.
*/
Tensor<rank_,dim,Number> operator - () const;
/**
- * Return the Frobenius-norm of a tensor,
- * i.e. the square root of the sum of
+ * Return the Frobenius-norm of a tensor, i.e. the square root of the sum of
* squares of all entries.
*/
real_type norm () const;
/**
- * Return the square of the
- * Frobenius-norm of a tensor,
- * i.e. the
- * sum of squares of all entries.
+ * Return the square of the Frobenius-norm of a tensor, i.e. the sum of
+ * squares of all entries.
*
- * This function mainly exists
- * because it makes computing the
- * norm simpler recursively, but
- * may also be useful in other
- * contexts.
+ * This function mainly exists because it makes computing the norm simpler
+ * recursively, but may also be useful in other contexts.
*/
real_type norm_square () const;
/**
* Fill a vector with all tensor elements.
*
- * This function unrolls all
- * tensor entries into a single,
- * linearly numbered vector. As
- * usual in C++, the rightmost
- * index of the tensor marches fastest.
+ * This function unrolls all tensor entries into a single, linearly numbered
+ * vector. As usual in C++, the rightmost index of the tensor marches
+ * fastest.
*/
template <typename Number2>
void unroll (Vector<Number2> &result) const;
/**
- * Returns an unrolled index in
- * the range [0,dim^rank-1] for the element of the tensor indexed by
- * the argument to the function.
+ * Returns an unrolled index in the range [0,dim^rank-1] for the element of
+ * the tensor indexed by the argument to the function.
*/
static
unsigned int
component_to_unrolled_index(const TableIndices<rank_> &indices);
/**
- * Opposite of component_to_unrolled_index: For an index in the
- * range [0,dim^rank-1], return which set of indices it would
- * correspond to.
+ * Opposite of component_to_unrolled_index: For an index in the range
+ * [0,dim^rank-1], return which set of indices it would correspond to.
*/
static
TableIndices<rank_> unrolled_to_component_indices(const unsigned int i);
/**
* Reset all values to zero.
*
- * Note that this is partly inconsistent
- * with the semantics of the @p clear()
- * member functions of the STL and of
- * several other classes within deal.II
- * which not only reset the values of
- * stored elements to zero, but release
- * all memory and return the object into
- * a virginial state. However, since the
- * size of objects of the present type is
- * determined by its template parameters,
- * resizing is not an option, and indeed
- * the state where all elements have a
- * zero value is the state right after
+ * Note that this is partly inconsistent with the semantics of the @p
+ * clear() member functions of the STL and of several other classes within
+ * deal.II which not only reset the values of stored elements to zero, but
+ * release all memory and return the object into a virginial state. However,
+ * since the size of objects of the present type is determined by its
+ * template parameters, resizing is not an option, and indeed the state
+ * where all elements have a zero value is the state right after
* construction of such an object.
*/
void clear ();
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
static std::size_t memory_consumption ();
<< "Invalid tensor index " << arg1);
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the purpose
+ * of serialization
*/
template <class Archive>
void serialize(Archive &ar, const unsigned int version);
private:
/**
- * Array of tensors holding the
- * subelements.
+ * Array of tensors holding the subelements.
*/
Tensor<rank_-1,dim,Number> subtensor[dim];
/**
- * Output operator for tensors. Print the elements consecutively, with
- * a space in between, two spaces between rank 1 subtensors, three
- * between rank 2 and so on.
+ * Output operator for tensors. Print the elements consecutively, with a space
+ * in between, two spaces between rank 1 subtensors, three between rank 2 and
+ * so on.
*
* @relates Tensor
*/
/**
- * Multiplication operator performing a contraction of the last index
- * of the first argument and the first index of the second
- * argument. This function therefore does the same as the
- * corresponding <tt>contract</tt> function, but returns the result as
- * a return value, rather than writing it into the reference given as
- * the first argument to the <tt>contract</tt> function.
- *
- * Note that for the <tt>Tensor</tt> class, the multiplication
- * operator only performs a contraction over a single pair of
- * indices. This is in contrast to the multiplication operator for
- * symmetric tensors, which does the double contraction.
+ * Multiplication operator performing a contraction of the last index of the
+ * first argument and the first index of the second argument. This function
+ * therefore does the same as the corresponding <tt>contract</tt> function,
+ * but returns the result as a return value, rather than writing it into the
+ * reference given as the first argument to the <tt>contract</tt> function.
+ *
+ * Note that for the <tt>Tensor</tt> class, the multiplication operator only
+ * performs a contraction over a single pair of indices. This is in contrast
+ * to the multiplication operator for symmetric tensors, which does the double
+ * contraction.
*
* @relates Tensor
* @author Wolfgang Bangerth, 2005
/**
- * Double contract two tensors of rank 2, thus computing the Frobenius
- * inner product <tt> sum<sub>i,j</sub> src1[i][j]*src2[i][j]</tt>.
+ * Double contract two tensors of rank 2, thus computing the Frobenius inner
+ * product <tt> sum<sub>i,j</sub> src1[i][j]*src2[i][j]</tt>.
*
* @relates Tensor
* @author Guido Kanschat, 2000
/**
- * Multiplication operator performing a contraction of the last index
- * of the first argument and the first index of the second
- * argument. This function therefore does the same as the
- * corresponding <tt>contract</tt> function, but returns the result as
- * a return value, rather than writing it into the reference given as
- * the first argument to the <tt>contract</tt> function.
- *
- * Note that for the <tt>Tensor</tt> class, the multiplication
- * operator only performs a contraction over a single pair of
- * indices. This is in contrast to the multiplication operator for
- * symmetric tensors, which does the double contraction.
+ * Multiplication operator performing a contraction of the last index of the
+ * first argument and the first index of the second argument. This function
+ * therefore does the same as the corresponding <tt>contract</tt> function,
+ * but returns the result as a return value, rather than writing it into the
+ * reference given as the first argument to the <tt>contract</tt> function.
+ *
+ * Note that for the <tt>Tensor</tt> class, the multiplication operator only
+ * performs a contraction over a single pair of indices. This is in contrast
+ * to the multiplication operator for symmetric tensors, which does the double
+ * contraction.
*
* @relates Tensor
* @author Wolfgang Bangerth, 2005
/**
- * Multiplication operator performing a contraction of the last index
- * of the first argument and the first index of the second
- * argument. This function therefore does the same as the
- * corresponding <tt>contract</tt> function, but returns the result as
- * a return value, rather than writing it into the reference given as
- * the first argument to the <tt>contract</tt> function.
- *
- * Note that for the <tt>Tensor</tt> class, the multiplication
- * operator only performs a contraction over a single pair of
- * indices. This is in contrast to the multiplication operator for
- * symmetric tensors, which does the double contraction.
+ * Multiplication operator performing a contraction of the last index of the
+ * first argument and the first index of the second argument. This function
+ * therefore does the same as the corresponding <tt>contract</tt> function,
+ * but returns the result as a return value, rather than writing it into the
+ * reference given as the first argument to the <tt>contract</tt> function.
+ *
+ * Note that for the <tt>Tensor</tt> class, the multiplication operator only
+ * performs a contraction over a single pair of indices. This is in contrast
+ * to the multiplication operator for symmetric tensors, which does the double
+ * contraction.
*
* @relates Tensor
* @author Wolfgang Bangerth, 2005
/**
- * Multiplication operator performing a contraction of the last index
- * of the first argument and the first index of the second
- * argument. This function therefore does the same as the
- * corresponding <tt>contract</tt> function, but returns the result as
- * a return value, rather than writing it into the reference given as
- * the first argument to the <tt>contract</tt> function.
- *
- * Note that for the <tt>Tensor</tt> class, the multiplication
- * operator only performs a contraction over a single pair of
- * indices. This is in contrast to the multiplication operator for
- * symmetric tensors, which does the double contraction.
+ * Multiplication operator performing a contraction of the last index of the
+ * first argument and the first index of the second argument. This function
+ * therefore does the same as the corresponding <tt>contract</tt> function,
+ * but returns the result as a return value, rather than writing it into the
+ * reference given as the first argument to the <tt>contract</tt> function.
+ *
+ * Note that for the <tt>Tensor</tt> class, the multiplication operator only
+ * performs a contraction over a single pair of indices. This is in contrast
+ * to the multiplication operator for symmetric tensors, which does the double
+ * contraction.
*
* @relates Tensor
* @author Wolfgang Bangerth, 2005
/**
- * Contract a tensor of rank 2 with a tensor of rank 2. The
- * contraction is performed over index <tt>index1</tt> of the first tensor,
- * and <tt>index2</tt> of the second tensor. Thus, if <tt>index1==2</tt>,
- * <tt>index2==1</tt>, the result is the usual contraction, but if for
- * example <tt>index1==1</tt>, <tt>index2==2</tt>, then the result is
- * <tt>dest[i][k] = sum_j src1[j][i] src2[k][j]</tt>.
+ * Contract a tensor of rank 2 with a tensor of rank 2. The contraction is
+ * performed over index <tt>index1</tt> of the first tensor, and
+ * <tt>index2</tt> of the second tensor. Thus, if <tt>index1==2</tt>,
+ * <tt>index2==1</tt>, the result is the usual contraction, but if for example
+ * <tt>index1==1</tt>, <tt>index2==2</tt>, then the result is <tt>dest[i][k] =
+ * sum_j src1[j][i] src2[k][j]</tt>.
*
- * Note that the number of the index is counted from 1 on, not from
- * zero as usual.
+ * Note that the number of the index is counted from 1 on, not from zero as
+ * usual.
*
* @relates Tensor
* @author Wolfgang Bangerth, 1998
/**
- * Contract a tensor of rank 3 with a tensor of rank 1. The
- * contraction is performed over index <tt>index1</tt> of the first
- * tensor.
+ * Contract a tensor of rank 3 with a tensor of rank 1. The contraction is
+ * performed over index <tt>index1</tt> of the first tensor.
*
- * Note that the number of the index is counted from 1 on, not from
- * zero as usual.
+ * Note that the number of the index is counted from 1 on, not from zero as
+ * usual.
*
* @relates Tensor
* @author Wolfgang Bangerth, 1998
/**
- * Contract a tensor of rank 3 with a tensor of rank 2. The
- * contraction is performed over index <tt>index1</tt> of the first tensor,
- * and <tt>index2</tt> of the second tensor. Thus, if <tt>index1==3</tt>,
- * <tt>index2==1</tt>, the result is the usual contraction, but if for
- * example <tt>index1==1</tt>, <tt>index2==2</tt>, then the result is
+ * Contract a tensor of rank 3 with a tensor of rank 2. The contraction is
+ * performed over index <tt>index1</tt> of the first tensor, and
+ * <tt>index2</tt> of the second tensor. Thus, if <tt>index1==3</tt>,
+ * <tt>index2==1</tt>, the result is the usual contraction, but if for example
+ * <tt>index1==1</tt>, <tt>index2==2</tt>, then the result is
* <tt>dest[i][j][k] = sum_l src1[l][i][j] src2[k][l]</tt>.
*
- * Note that the number of the index is counted from 1 on, not from
- * zero as usual.
+ * Note that the number of the index is counted from 1 on, not from zero as
+ * usual.
*
* @relates Tensor
*/
/**
- * Multiplication operator performing a contraction of the last index
- * of the first argument and the first index of the second
- * argument. This function therefore does the same as the
- * corresponding <tt>contract</tt> function, but returns the result as
- * a return value, rather than writing it into the reference given as
- * the first argument to the <tt>contract</tt> function.
- *
- * Note that for the <tt>Tensor</tt> class, the multiplication
- * operator only performs a contraction over a single pair of
- * indices. This is in contrast to the multiplication operator for
- * symmetric tensors, which does the double contraction.
+ * Multiplication operator performing a contraction of the last index of the
+ * first argument and the first index of the second argument. This function
+ * therefore does the same as the corresponding <tt>contract</tt> function,
+ * but returns the result as a return value, rather than writing it into the
+ * reference given as the first argument to the <tt>contract</tt> function.
+ *
+ * Note that for the <tt>Tensor</tt> class, the multiplication operator only
+ * performs a contraction over a single pair of indices. This is in contrast
+ * to the multiplication operator for symmetric tensors, which does the double
+ * contraction.
*
* @relates Tensor
* @author Wolfgang Bangerth, 2005
/**
- * Multiplication operator performing a contraction of the last index
- * of the first argument and the first index of the second
- * argument. This function therefore does the same as the
- * corresponding <tt>contract</tt> function, but returns the result as
- * a return value, rather than writing it into the reference given as
- * the first argument to the <tt>contract</tt> function.
- *
- * Note that for the <tt>Tensor</tt> class, the multiplication
- * operator only performs a contraction over a single pair of
- * indices. This is in contrast to the multiplication operator for
- * symmetric tensors, which does the double contraction.
+ * Multiplication operator performing a contraction of the last index of the
+ * first argument and the first index of the second argument. This function
+ * therefore does the same as the corresponding <tt>contract</tt> function,
+ * but returns the result as a return value, rather than writing it into the
+ * reference given as the first argument to the <tt>contract</tt> function.
+ *
+ * Note that for the <tt>Tensor</tt> class, the multiplication operator only
+ * performs a contraction over a single pair of indices. This is in contrast
+ * to the multiplication operator for symmetric tensors, which does the double
+ * contraction.
*
* @relates Tensor
* @author Wolfgang Bangerth, 2005
/**
* Contract the last two indices of <tt>src1</tt> with the two indices
- * <tt>src2</tt>, creating a rank-2 tensor. This is the matrix-vector
- * product analog operation between tensors of rank 4 and rank 2.
+ * <tt>src2</tt>, creating a rank-2 tensor. This is the matrix-vector product
+ * analog operation between tensors of rank 4 and rank 2.
*
* @relates Tensor
* @author Wolfgang Bangerth, 2005
/**
- * Form the outer product of two tensors of rank 1 and 1, i.e.
- * <tt>dst[i][j] = src1[i] * src2[j]</tt>.
+ * Form the outer product of two tensors of rank 1 and 1, i.e. <tt>dst[i][j] =
+ * src1[i] * src2[j]</tt>.
*
* @relates Tensor
* @author Wolfgang Bangerth, 2000
/**
- * Form the outer product of two tensors of rank 0 and 1, i.e.
- * <tt>dst[i] = src1 * src2[i]</tt>. Of course, this is only a scaling of
- * <tt>src2</tt>, but we consider this an outer product for completeness of
- * these functions and since this is sometimes needed when writing
- * templates that depend on the rank of a tensor, which may sometimes
- * be zero (i.e. a scalar).
+ * Form the outer product of two tensors of rank 0 and 1, i.e. <tt>dst[i] =
+ * src1 * src2[i]</tt>. Of course, this is only a scaling of <tt>src2</tt>,
+ * but we consider this an outer product for completeness of these functions
+ * and since this is sometimes needed when writing templates that depend on
+ * the rank of a tensor, which may sometimes be zero (i.e. a scalar).
*
* @relates Tensor
* @author Wolfgang Bangerth, 2000
/**
- * Form the outer product of two tensors of rank 1 and 0, i.e.
- * <tt>dst[i] = src1[i] * src2</tt>. Of course, this is only a scaling of
- * <tt>src1</tt>, but we consider this an outer product for completeness of
- * these functions and since this is sometimes needed when writing
- * templates that depend on the rank of a tensor, which may sometimes
- * be zero (i.e. a scalar).
+ * Form the outer product of two tensors of rank 1 and 0, i.e. <tt>dst[i] =
+ * src1[i] * src2</tt>. Of course, this is only a scaling of <tt>src1</tt>,
+ * but we consider this an outer product for completeness of these functions
+ * and since this is sometimes needed when writing templates that depend on
+ * the rank of a tensor, which may sometimes be zero (i.e. a scalar).
*
* @relates Tensor
* @author Wolfgang Bangerth, 2000
/**
- * Cross-product in 2d. This is just a rotation by 90 degrees
- * clockwise to compute the outer normal from a tangential
- * vector. This function is defined for all space dimensions to allow
- * for dimension independent programming (e.g. within switches over
- * the space dimenion), but may only be called if the actual dimension
- * of the arguments is two (e.g. from the <tt>dim==2</tt> case in the
- * switch).
+ * Cross-product in 2d. This is just a rotation by 90 degrees clockwise to
+ * compute the outer normal from a tangential vector. This function is defined
+ * for all space dimensions to allow for dimension independent programming
+ * (e.g. within switches over the space dimenion), but may only be called if
+ * the actual dimension of the arguments is two (e.g. from the <tt>dim==2</tt>
+ * case in the switch).
*
* @relates Tensor
* @author Guido Kanschat, 2001
/**
- * Cross-product of 2 vectors in 3d. This function is defined for all
- * space dimensions to allow for dimension independent programming
- * (e.g. within switches over the space dimenion), but may only be
- * called if the actual dimension of the arguments is three (e.g. from
- * the <tt>dim==3</tt> case in the switch).
+ * Cross-product of 2 vectors in 3d. This function is defined for all space
+ * dimensions to allow for dimension independent programming (e.g. within
+ * switches over the space dimenion), but may only be called if the actual
+ * dimension of the arguments is three (e.g. from the <tt>dim==3</tt> case in
+ * the switch).
*
* @relates Tensor
* @author Guido Kanschat, 2001
/**
- * Compute the determinant of a tensor of arbitrary rank and dimension
- * one. Since this is a number, the return value is, of course, the
- * number itself.
+ * Compute the determinant of a tensor of arbitrary rank and dimension one.
+ * Since this is a number, the return value is, of course, the number itself.
*
* @relates Tensor
* @author Wolfgang Bangerth, 1998
/**
- * Compute the determinant of a tensor of rank one and dimension
- * one. Since this is a number, the return value is, of course, the
- * number itself.
+ * Compute the determinant of a tensor of rank one and dimension one. Since
+ * this is a number, the return value is, of course, the number itself.
*
* @relates Tensor
* @author Wolfgang Bangerth, 1998
/**
- * Compute the determinant of a tensor of rank two and dimension
- * one. Since this is a number, the return value is, of course, the
- * number itself.
+ * Compute the determinant of a tensor of rank two and dimension one. Since
+ * this is a number, the return value is, of course, the number itself.
*
* @relates Tensor
* @author Wolfgang Bangerth, 1998
/**
- * Compute and return the trace of a tensor of rank 2, i.e. the sum of
- * its diagonal entries.
+ * Compute and return the trace of a tensor of rank 2, i.e. the sum of its
+ * diagonal entries.
*
* @relates Tensor
* @author Wolfgang Bangerth, 2001
/**
- * Compute and return the inverse of the given tensor. Since the
- * compiler can perform the return value optimization, and since the
- * size of the return object is known, it is acceptable to return the
- * result by value, rather than by reference as a parameter.
+ * Compute and return the inverse of the given tensor. Since the compiler can
+ * perform the return value optimization, and since the size of the return
+ * object is known, it is acceptable to return the result by value, rather
+ * than by reference as a parameter.
*
* @relates Tensor
* @author Wolfgang Bangerth, 2000
/**
- * Return the transpose of the given tensor. Since the compiler can
- * perform the return value optimization, and since the size of the
- * return object is known, it is acceptable to return the result by
- * value, rather than by reference as a parameter. Note that there are
- * specializations of this function for <tt>dim==1,2,3</tt>.
+ * Return the transpose of the given tensor. Since the compiler can perform
+ * the return value optimization, and since the size of the return object is
+ * known, it is acceptable to return the result by value, rather than by
+ * reference as a parameter. Note that there are specializations of this
+ * function for <tt>dim==1,2,3</tt>.
*
* @relates Tensor
* @author Wolfgang Bangerth, 2002
#ifndef DOXYGEN
/**
- * Return the transpose of the given tensor. This is the
- * specialization of the general template for <tt>dim==1</tt>.
+ * Return the transpose of the given tensor. This is the specialization of the
+ * general template for <tt>dim==1</tt>.
*
* @relates Tensor
* @author Wolfgang Bangerth, 2002
/**
- * Return the transpose of the given tensor. This is the
- * specialization of the general template for <tt>dim==2</tt>.
+ * Return the transpose of the given tensor. This is the specialization of the
+ * general template for <tt>dim==2</tt>.
*
* @relates Tensor
* @author Wolfgang Bangerth, 2002
/**
- * Return the transpose of the given tensor. This is the
- * specialization of the general template for <tt>dim==3</tt>.
+ * Return the transpose of the given tensor. This is the specialization of the
+ * general template for <tt>dim==3</tt>.
*
* @relates Tensor
* @author Wolfgang Bangerth, 2002
/**
- * Return the $l_1$ norm of the given rank-2 tensor, where
- * $||t||_1 = \max_j \sum_i |t_{ij}|$ (maximum of
- * the sums over columns).
+ * Return the $l_1$ norm of the given rank-2 tensor, where $||t||_1 = \max_j
+ * \sum_i |t_{ij}|$ (maximum of the sums over columns).
*
* @relates Tensor
* @author Wolfgang Bangerth, 2012
/**
- * Return the $l_\infty$ norm of the given rank-2 tensor, where
- * $||t||_\infty = \max_i \sum_j |t_{ij}|$ (maximum of
- * the sums over rows).
+ * Return the $l_\infty$ norm of the given rank-2 tensor, where $||t||_\infty
+ * = \max_i \sum_j |t_{ij}|$ (maximum of the sums over rows).
*
* @relates Tensor
* @author Wolfgang Bangerth, 2012
/**
- * Multiplication of a tensor of general rank with a scalar Number
- * from the right.
+ * Multiplication of a tensor of general rank with a scalar Number from the
+ * right.
*
* @relates Tensor
*/
/**
- * Multiplication of a tensor of general rank with a scalar Number
- * from the left.
+ * Multiplication of a tensor of general rank with a scalar Number from the
+ * left.
*
* @relates Tensor
*/
/**
- * Multiplication of a tensor of general rank with a scalar double
- * from the right.
+ * Multiplication of a tensor of general rank with a scalar double from the
+ * right.
*
* @relates Tensor
*/
/**
- * Multiplication of a tensor of general rank with a scalar double
- * from the left.
+ * Multiplication of a tensor of general rank with a scalar double from the
+ * left.
*
* @relates Tensor
*/
/**
- * Multiplication of a tensor of general rank by a scalar
- * complex<double> from the left.
+ * Multiplication of a tensor of general rank by a scalar complex<double> from
+ * the left.
*
* @relates Tensor
*/
/**
- * Multiplication of a tensor of general rank by a scalar
- * complex<double> from the right.
+ * Multiplication of a tensor of general rank by a scalar complex<double> from
+ * the right.
*
* @relates Tensor
*/
* class. It handles tensors of rank zero, i.e. scalars. The second template
* argument is ignored.
*
- * This class exists because in some cases we want to construct
- * objects of type Tensor@<spacedim-dim,dim,Number@>, which should expand to
- * scalars, vectors, matrices, etc, depending on the values of the
- * template arguments @p dim and @p spacedim. We therefore need a
- * class that acts as a scalar (i.e. @p Number) for all purposes but
- * is part of the Tensor template family.
+ * This class exists because in some cases we want to construct objects of
+ * type Tensor@<spacedim-dim,dim,Number@>, which should expand to scalars,
+ * vectors, matrices, etc, depending on the values of the template arguments
+ * @p dim and @p spacedim. We therefore need a class that acts as a scalar
+ * (i.e. @p Number) for all purposes but is part of the Tensor template
+ * family.
*
* @ingroup geomprimitives
* @author Wolfgang Bangerth, 2009
{
public:
/**
- * Provide a way to get the
- * dimension of an object without
- * explicit knowledge of it's
- * data type. Implementation is
- * this way instead of providing
- * a function <tt>dimension()</tt>
- * because now it is possible to
- * get the dimension at compile
- * time without the expansion and
- * preevaluation of an inlined
- * function; the compiler may
- * therefore produce more
- * efficient code and you may use
- * this value to declare other
- * data types.
+ * Provide a way to get the dimension of an object without explicit
+ * knowledge of it's data type. Implementation is this way instead of
+ * providing a function <tt>dimension()</tt> because now it is possible to
+ * get the dimension at compile time without the expansion and preevaluation
+ * of an inlined function; the compiler may therefore produce more efficient
+ * code and you may use this value to declare other data types.
*/
static const unsigned int dimension = dim;
/**
- * Publish the rank of this tensor to
- * the outside world.
+ * Publish the rank of this tensor to the outside world.
*/
static const unsigned int rank = 0;
/**
- * Type of stored objects. This
- * is a Number for a rank 1 tensor.
+ * Type of stored objects. This is a Number for a rank 1 tensor.
*/
typedef Number value_type;
/**
- * Declare a type that has holds
- * real-valued numbers with the same
- * precision as the template argument to
- * this class. For std::complex<number>,
- * this corresponds to type number, and
- * it is equal to Number for all other
- * cases. See also the respective field
- * in Vector<Number>.
+ * Declare a type that has holds real-valued numbers with the same precision
+ * as the template argument to this class. For std::complex<number>, this
+ * corresponds to type number, and it is equal to Number for all other
+ * cases. See also the respective field in Vector<Number>.
*
- * This typedef is used to
- * represent the return type of
- * norms.
+ * This typedef is used to represent the return type of norms.
*/
typedef typename numbers::NumberTraits<Number>::real_type real_type;
Tensor ();
/**
- * Copy constructor, where the
- * data is copied from a C-style
- * array.
+ * Copy constructor, where the data is copied from a C-style array.
*/
Tensor (const value_type &initializer);
Tensor (const Tensor<0,dim,Number> &);
/**
- * Conversion to Number. Since
- * rank-0 tensors are scalars,
- * this is a natural operation.
+ * Conversion to Number. Since rank-0 tensors are scalars, this is a natural
+ * operation.
*/
operator Number () const;
/**
- * Conversion to Number. Since
- * rank-0 tensors are scalars,
- * this is a natural operation.
+ * Conversion to Number. Since rank-0 tensors are scalars, this is a natural
+ * operation.
*
- * This is the non-const
- * conversion operator that
- * returns a writable reference.
+ * This is the non-const conversion operator that returns a writable
+ * reference.
*/
operator Number &();
Tensor<0,dim,Number> &operator = (const Number d);
/**
- * Test for equality of two
- * tensors.
+ * Test for equality of two tensors.
*/
bool operator == (const Tensor<0,dim,Number> &) const;
/**
- * Test for inequality of two
- * tensors.
+ * Test for inequality of two tensors.
*/
bool operator != (const Tensor<0,dim,Number> &) const;
/**
- * Add another vector, i.e. move
- * this point by the given
- * offset.
+ * Add another vector, i.e. move this point by the given offset.
*/
Tensor<0,dim,Number> &operator += (const Tensor<0,dim,Number> &);
Tensor<0,dim,Number> &operator -= (const Tensor<0,dim,Number> &);
/**
- * Scale the vector by
- * <tt>factor</tt>, i.e. multiply all
- * coordinates by <tt>factor</tt>.
+ * Scale the vector by <tt>factor</tt>, i.e. multiply all coordinates by
+ * <tt>factor</tt>.
*/
Tensor<0,dim,Number> &operator *= (const Number factor);
Tensor<0,dim,Number> &operator /= (const Number factor);
/**
- * Returns the scalar product of
- * two vectors.
+ * Returns the scalar product of two vectors.
*/
Number operator * (const Tensor<0,dim,Number> &) const;
/**
- * Add two tensors. If possible,
- * use <tt>operator +=</tt> instead
- * since this does not need to
- * copy a point at least once.
+ * Add two tensors. If possible, use <tt>operator +=</tt> instead since this
+ * does not need to copy a point at least once.
*/
Tensor<0,dim,Number> operator + (const Tensor<0,dim,Number> &) const;
/**
- * Subtract two tensors. If
- * possible, use <tt>operator +=</tt>
- * instead since this does not
- * need to copy a point at least
- * once.
+ * Subtract two tensors. If possible, use <tt>operator +=</tt> instead since
+ * this does not need to copy a point at least once.
*/
Tensor<0,dim,Number> operator - (const Tensor<0,dim,Number> &) const;
Tensor<0,dim,Number> operator - () const;
/**
- * Return the Frobenius-norm of a
- * tensor, i.e. the square root
- * of the sum of squares of all
- * entries. For the present case
- * of rank-1 tensors, this equals
- * the usual
- * <tt>l<sub>2</sub></tt> norm of
- * the vector.
+ * Return the Frobenius-norm of a tensor, i.e. the square root of the sum of
+ * squares of all entries. For the present case of rank-1 tensors, this
+ * equals the usual <tt>l<sub>2</sub></tt> norm of the vector.
*/
real_type norm () const;
/**
- * Return the square of the
- * Frobenius-norm of a tensor,
- * i.e. the square root of the
- * sum of squares of all entries.
+ * Return the square of the Frobenius-norm of a tensor, i.e. the square root
+ * of the sum of squares of all entries.
*
- * This function mainly exists
- * because it makes computing the
- * norm simpler recursively, but
- * may also be useful in other
- * contexts.
+ * This function mainly exists because it makes computing the norm simpler
+ * recursively, but may also be useful in other contexts.
*/
real_type norm_square () const;
/**
* Reset all values to zero.
*
- * Note that this is partly inconsistent
- * with the semantics of the @p clear()
- * member functions of the STL and of
- * several other classes within deal.II
- * which not only reset the values of
- * stored elements to zero, but release
- * all memory and return the object into
- * a virginial state. However, since the
- * size of objects of the present type is
- * determined by its template parameters,
- * resizing is not an option, and indeed
- * the state where all elements have a
- * zero value is the state right after
+ * Note that this is partly inconsistent with the semantics of the @p
+ * clear() member functions of the STL and of several other classes within
+ * deal.II which not only reset the values of stored elements to zero, but
+ * release all memory and return the object into a virginial state. However,
+ * since the size of objects of the present type is determined by its
+ * template parameters, resizing is not an option, and indeed the state
+ * where all elements have a zero value is the state right after
* construction of such an object.
*/
void clear ();
/**
- * Only tensors with a positive
- * dimension are implemented. This
- * exception is thrown by the
- * constructor if the template
- * argument <tt>dim</tt> is zero or
- * less.
+ * Only tensors with a positive dimension are implemented. This exception is
+ * thrown by the constructor if the template argument <tt>dim</tt> is zero
+ * or less.
*
* @ingroup Exceptions
*/
<< "dim must be positive, but was " << arg1);
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the purpose
+ * of serialization
*/
template <class Archive>
void serialize(Archive &ar, const unsigned int version);
{
public:
/**
- * Provide a way to get the
- * dimension of an object without
- * explicit knowledge of it's
- * data type. Implementation is
- * this way instead of providing
- * a function <tt>dimension()</tt>
- * because now it is possible to
- * get the dimension at compile
- * time without the expansion and
- * preevaluation of an inlined
- * function; the compiler may
- * therefore produce more
- * efficient code and you may use
- * this value to declare other
- * data types.
+ * Provide a way to get the dimension of an object without explicit
+ * knowledge of it's data type. Implementation is this way instead of
+ * providing a function <tt>dimension()</tt> because now it is possible to
+ * get the dimension at compile time without the expansion and preevaluation
+ * of an inlined function; the compiler may therefore produce more efficient
+ * code and you may use this value to declare other data types.
*/
static const unsigned int dimension = dim;
/**
- * Publish the rank of this tensor to
- * the outside world.
+ * Publish the rank of this tensor to the outside world.
*/
static const unsigned int rank = 1;
/**
- * Number of independent components of a
- * tensor of rank 1.
+ * Number of independent components of a tensor of rank 1.
*/
static const unsigned int
n_independent_components = dim;
/**
- * Type of stored objects. This
- * is a Number for a rank 1 tensor.
+ * Type of stored objects. This is a Number for a rank 1 tensor.
*/
typedef Number value_type;
/**
- * Declare a type that has holds
- * real-valued numbers with the same
- * precision as the template argument to
- * this class. For std::complex<number>,
- * this corresponds to type number, and
- * it is equal to Number for all other
- * cases. See also the respective field
- * in Vector<Number>.
+ * Declare a type that has holds real-valued numbers with the same precision
+ * as the template argument to this class. For std::complex<number>, this
+ * corresponds to type number, and it is equal to Number for all other
+ * cases. See also the respective field in Vector<Number>.
*
- * This typedef is used to
- * represent the return type of
- * norms.
+ * This typedef is used to represent the return type of norms.
*/
typedef typename numbers::NumberTraits<Number>::real_type real_type;
/**
- * Declare an array type which can
- * be used to initialize statically
- * an object of this type.
+ * Declare an array type which can be used to initialize statically an
+ * object of this type.
*
- * Avoid warning about zero-sized
- * array for <tt>dim==0</tt> by
- * choosing lunatic value that is
- * likely to overflow memory
- * limits.
+ * Avoid warning about zero-sized array for <tt>dim==0</tt> by choosing
+ * lunatic value that is likely to overflow memory limits.
*/
typedef Number array_type[(dim!=0) ? dim : 100000000];
/**
- * Constructor. Initialize all entries
- * to zero if <tt>initialize==true</tt>; this
- * is the default behaviour.
+ * Constructor. Initialize all entries to zero if <tt>initialize==true</tt>;
+ * this is the default behaviour.
*/
explicit Tensor (const bool initialize = true);
/**
- * Copy constructor, where the
- * data is copied from a C-style
- * array.
+ * Copy constructor, where the data is copied from a C-style array.
*/
Tensor (const array_type &initializer);
Tensor (const Tensor<1,dim,Number> &);
/**
- * Read access to the <tt>index</tt>th
- * coordinate.
+ * Read access to the <tt>index</tt>th coordinate.
*
- * Note that the derived
- * <tt>Point</tt> class also provides
- * access through the <tt>()</tt>
- * operator for
- * backcompatibility.
+ * Note that the derived <tt>Point</tt> class also provides access through
+ * the <tt>()</tt> operator for backcompatibility.
*/
Number operator [] (const unsigned int index) const;
/**
- * Read and write access to the
- * <tt>index</tt>th coordinate.
+ * Read and write access to the <tt>index</tt>th coordinate.
*
- * Note that the derived
- * <tt>Point</tt> class also provides
- * access through the <tt>()</tt>
- * operator for
- * backcompatibility.
+ * Note that the derived <tt>Point</tt> class also provides access through
+ * the <tt>()</tt> operator for backcompatibility.
*/
Number &operator [] (const unsigned int index);
Tensor<1,dim,Number> &operator = (const Tensor<1,dim,Number> &);
/**
- * This operator assigns a scalar
- * to a tensor. To avoid
- * confusion with what exactly it
- * means to assign a scalar value
- * to a tensor, zero is the only
- * value allowed for <tt>d</tt>,
- * allowing the intuitive
- * notation <tt>t=0</tt> to reset
- * all elements of the tensor to
- * zero.
+ * This operator assigns a scalar to a tensor. To avoid confusion with what
+ * exactly it means to assign a scalar value to a tensor, zero is the only
+ * value allowed for <tt>d</tt>, allowing the intuitive notation
+ * <tt>t=0</tt> to reset all elements of the tensor to zero.
*/
Tensor<1,dim,Number> &operator = (const Number d);
/**
- * Test for equality of two
- * tensors.
+ * Test for equality of two tensors.
*/
bool operator == (const Tensor<1,dim,Number> &) const;
/**
- * Test for inequality of two
- * tensors.
+ * Test for inequality of two tensors.
*/
bool operator != (const Tensor<1,dim,Number> &) const;
/**
- * Add another vector, i.e. move
- * this point by the given
- * offset.
+ * Add another vector, i.e. move this point by the given offset.
*/
Tensor<1,dim,Number> &operator += (const Tensor<1,dim,Number> &);
Tensor<1,dim,Number> &operator -= (const Tensor<1,dim,Number> &);
/**
- * Scale the vector by
- * <tt>factor</tt>, i.e. multiply all
- * coordinates by <tt>factor</tt>.
+ * Scale the vector by <tt>factor</tt>, i.e. multiply all coordinates by
+ * <tt>factor</tt>.
*/
Tensor<1,dim,Number> &operator *= (const Number factor);
Tensor<1,dim,Number> &operator /= (const Number factor);
/**
- * Returns the scalar product of
- * two vectors.
+ * Returns the scalar product of two vectors.
*/
Number operator * (const Tensor<1,dim,Number> &) const;
/**
- * Add two tensors. If possible,
- * use <tt>operator +=</tt> instead
- * since this does not need to
- * copy a point at least once.
+ * Add two tensors. If possible, use <tt>operator +=</tt> instead since this
+ * does not need to copy a point at least once.
*/
Tensor<1,dim,Number> operator + (const Tensor<1,dim,Number> &) const;
/**
- * Subtract two tensors. If
- * possible, use <tt>operator +=</tt>
- * instead since this does not
- * need to copy a point at least
- * once.
+ * Subtract two tensors. If possible, use <tt>operator +=</tt> instead since
+ * this does not need to copy a point at least once.
*/
Tensor<1,dim,Number> operator - (const Tensor<1,dim,Number> &) const;
Tensor<1,dim,Number> operator - () const;
/**
- * Return the Frobenius-norm of a
- * tensor, i.e. the square root
- * of the sum of squares of all
- * entries. For the present case
- * of rank-1 tensors, this equals
- * the usual
- * <tt>l<sub>2</sub></tt> norm of
- * the vector.
+ * Return the Frobenius-norm of a tensor, i.e. the square root of the sum of
+ * squares of all entries. For the present case of rank-1 tensors, this
+ * equals the usual <tt>l<sub>2</sub></tt> norm of the vector.
*/
real_type norm () const;
/**
- * Return the square of the
- * Frobenius-norm of a tensor,
- * i.e. the square root of the
- * sum of squares of all entries.
+ * Return the square of the Frobenius-norm of a tensor, i.e. the square root
+ * of the sum of squares of all entries.
*
- * This function mainly exists
- * because it makes computing the
- * norm simpler recursively, but
- * may also be useful in other
- * contexts.
+ * This function mainly exists because it makes computing the norm simpler
+ * recursively, but may also be useful in other contexts.
*/
real_type norm_square () const;
/**
* Reset all values to zero.
*
- * Note that this is partly inconsistent
- * with the semantics of the @p clear()
- * member functions of the STL and of
- * several other classes within deal.II
- * which not only reset the values of
- * stored elements to zero, but release
- * all memory and return the object into
- * a virginial state. However, since the
- * size of objects of the present type is
- * determined by its template parameters,
- * resizing is not an option, and indeed
- * the state where all elements have a
- * zero value is the state right after
+ * Note that this is partly inconsistent with the semantics of the @p
+ * clear() member functions of the STL and of several other classes within
+ * deal.II which not only reset the values of stored elements to zero, but
+ * release all memory and return the object into a virginial state. However,
+ * since the size of objects of the present type is determined by its
+ * template parameters, resizing is not an option, and indeed the state
+ * where all elements have a zero value is the state right after
* construction of such an object.
*/
void clear ();
/**
* Fill a vector with all tensor elements.
*
- * This function unrolls all
- * tensor entries into a single,
- * linearly numbered vector. As
- * usual in C++, the rightmost
- * index marches fastest.
+ * This function unrolls all tensor entries into a single, linearly numbered
+ * vector. As usual in C++, the rightmost index marches fastest.
*/
template <typename Number2>
void unroll (Vector<Number2> &result) const;
/**
- * Returns an unrolled index in
- * the range [0,dim-1] for the element of the tensor indexed by
- * the argument to the function.
+ * Returns an unrolled index in the range [0,dim-1] for the element of the
+ * tensor indexed by the argument to the function.
*
- * Given that this is a rank-1 object, the returned value
- * is simply the value of the only index stored by the argument.
+ * Given that this is a rank-1 object, the returned value is simply the
+ * value of the only index stored by the argument.
*/
static
unsigned int
component_to_unrolled_index(const TableIndices<1> &indices);
/**
- * Opposite of component_to_unrolled_index: For an index in the
- * range [0,dim-1], return which set of indices it would
- * correspond to.
+ * Opposite of component_to_unrolled_index: For an index in the range
+ * [0,dim-1], return which set of indices it would correspond to.
*
- * Given that this is a rank-1 object, the returned set of indices
- * consists of only a single element with value equal to the argument
- * to this function.
+ * Given that this is a rank-1 object, the returned set of indices consists
+ * of only a single element with value equal to the argument to this
+ * function.
*/
static
TableIndices<1> unrolled_to_component_indices(const unsigned int i);
/**
- * Determine an estimate for
- * the memory consumption (in
- * bytes) of this
+ * Determine an estimate for the memory consumption (in bytes) of this
* object.
*/
static std::size_t memory_consumption ();
/**
- * Only tensors with a positive
- * dimension are implemented. This
- * exception is thrown by the
- * constructor if the template
- * argument <tt>dim</tt> is zero or
- * less.
+ * Only tensors with a positive dimension are implemented. This exception is
+ * thrown by the constructor if the template argument <tt>dim</tt> is zero
+ * or less.
*
* @ingroup Exceptions
*/
<< "dim must be positive, but was " << arg1);
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the purpose
+ * of serialization
*/
template <class Archive>
void serialize(Archive &ar, const unsigned int version);
private:
/**
- * Store the values in a simple
- * array. For <tt>dim==0</tt> store
- * one element, because otherways
- * the compiler would choke. We
- * catch this case in the
- * constructor to disallow the
- * creation of such an object.
+ * Store the values in a simple array. For <tt>dim==0</tt> store one
+ * element, because otherways the compiler would choke. We catch this case
+ * in the constructor to disallow the creation of such an object.
*/
Number values[(dim!=0) ? (dim) : (dim+1)];
/**
- * Help function for unroll. If
- * we have detected an access
- * control bug in the compiler,
- * this function is declared
- * public, otherwise private. Do
- * not attempt to use this
- * function from outside in any
- * case, even if it should be
- * public for your compiler.
+ * Help function for unroll. If we have detected an access control bug in
+ * the compiler, this function is declared public, otherwise private. Do not
+ * attempt to use this function from outside in any case, even if it should
+ * be public for your compiler.
*/
template <typename Number2>
void unroll_recursion (Vector<Number2> &result,
private:
/**
- * Make the following classes
- * friends to this class. In
- * principle, it would suffice if
- * otherrank==2, but that is not
- * possible in C++ at present.
+ * Make the following classes friends to this class. In principle, it would
+ * suffice if otherrank==2, but that is not possible in C++ at present.
*
- * Also, it would be sufficient
- * to make the function
- * unroll_loops a friend, but
- * that seems to be impossible as
- * well.
+ * Also, it would be sufficient to make the function unroll_loops a friend,
+ * but that seems to be impossible as well.
*/
template <int otherrank, int otherdim, typename OtherNumber> friend class dealii::Tensor;
/**
- * Point is allowed access to
- * the coordinates. This is
- * supposed to improve speed.
+ * Point is allowed access to the coordinates. This is supposed to improve
+ * speed.
*/
friend class Point<dim,Number>;
};
/**
- * Prints the value of this scalar.
+ * Prints the value of this scalar.
*/
template <int dim,typename Number>
std::ostream &operator << (std::ostream &out, const Tensor<0,dim,Number> &p);
/**
- * Prints the values of this tensor in the
- * form <tt>x1 x2 x3 etc</tt>.
+ * Prints the values of this tensor in the form <tt>x1 x2 x3 etc</tt>.
*/
template <int dim,typename Number>
std::ostream &operator << (std::ostream &out, const Tensor<1,dim,Number> &p);
/**
- * Output operator for tensors of rank 0. Since such tensors are
- * scalars, we simply print this one value.
+ * Output operator for tensors of rank 0. Since such tensors are scalars, we
+ * simply print this one value.
*
* @relates Tensor<0,dim,Number>
*/
/**
- * Output operator for tensors of rank 1. Print the elements
- * consecutively, with a space in between.
+ * Output operator for tensors of rank 1. Print the elements consecutively,
+ * with a space in between.
*
* @relates Tensor<1,dim,Number>
*/
/**
- * Output operator for tensors of rank 1 and dimension 1. This is
- * implemented specialized from the general template in order to avoid
- * a compiler warning that the loop is empty.
+ * Output operator for tensors of rank 1 and dimension 1. This is implemented
+ * specialized from the general template in order to avoid a compiler warning
+ * that the loop is empty.
*
* @relates Tensor<1,dim,Number>
*/
/**
- * Multiplication of a tensor of rank 1 by a scalar complex<double>
- * from the right.
+ * Multiplication of a tensor of rank 1 by a scalar complex<double> from the
+ * right.
*
* @relates Tensor<1,dim,Number>
*/
/**
- * Multiplication of a tensor of rank 1 by a scalar complex<double>
- * from the left.
+ * Multiplication of a tensor of rank 1 by a scalar complex<double> from the
+ * left.
*
* @relates Tensor<1,dim,Number>
*/
DEAL_II_NAMESPACE_OPEN
/**
- * This class is a model for a tensor valued function. The interface
- * of the class is mostly the same as that for the Function
- * class, with the exception that it does not support vector-valued
- * functions with several components, but that the return type is
- * always tensor-valued. The returned values of the evaluation of
- * objects of this type are always whole tensors, while for the
- * <tt>Function</tt> class, one can ask for a specific component only, or
- * use the <tt>vector_value</tt> function, which however does not return
- * the value, but rather writes it into the address provided by its
- * second argument. The reason for the different behaviour of the
- * classes is that in the case of tensor valued functions, the size
- * of the argument is known to the compiler a priori, such that the
- * correct amount of memory can be allocated on the stack for the
- * return value; on the other hand, for the vector valued functions,
- * the size is not known to the compiler, so memory has to be
- * allocated on the heap, resulting in relatively expensive copy
- * operations. One can therefore consider this class a specialization
- * of the <tt>Function</tt> class for which the size is known. An
- * additional benefit is that tensors of arbitrary rank can be
- * returned, not only vectors, as for them the size can be determined
- * similarly simply.
+ * This class is a model for a tensor valued function. The interface of the
+ * class is mostly the same as that for the Function class, with the exception
+ * that it does not support vector-valued functions with several components,
+ * but that the return type is always tensor-valued. The returned values of
+ * the evaluation of objects of this type are always whole tensors, while for
+ * the <tt>Function</tt> class, one can ask for a specific component only, or
+ * use the <tt>vector_value</tt> function, which however does not return the
+ * value, but rather writes it into the address provided by its second
+ * argument. The reason for the different behaviour of the classes is that in
+ * the case of tensor valued functions, the size of the argument is known to
+ * the compiler a priori, such that the correct amount of memory can be
+ * allocated on the stack for the return value; on the other hand, for the
+ * vector valued functions, the size is not known to the compiler, so memory
+ * has to be allocated on the heap, resulting in relatively expensive copy
+ * operations. One can therefore consider this class a specialization of the
+ * <tt>Function</tt> class for which the size is known. An additional benefit
+ * is that tensors of arbitrary rank can be returned, not only vectors, as for
+ * them the size can be determined similarly simply.
*
- * @ingroup functions
- * @author Guido Kanschat, 1999
+ * @ingroup functions
+ * @author Guido Kanschat, 1999
*/
template <int rank, int dim, typename Number=double>
class TensorFunction : public FunctionTime<Number>,
/**
* Virtual destructor; absolutely necessary in this case, as classes are
- * usually not used by their true type, but rather through pointers to
- * this base class.
+ * usually not used by their true type, but rather through pointers to this
+ * base class.
*/
virtual ~TensorFunction ();
{
public:
/**
- * Constructor; takes the constant tensor value as an argument.
- * The reference value is copied internally.
+ * Constructor; takes the constant tensor value as an argument. The
+ * reference value is copied internally.
*
* An initial value for the time variable may be specified, otherwise it
* defaults to zero.
/**
- * Provide a tensor valued function which always returns zero.
- * Obviously, all derivates of this function are zero.
+ * Provide a tensor valued function which always returns zero. Obviously, all
+ * derivates of this function are zero.
*
* @ingroup functions
* @author Matthias Maier, 2013
/**
* Tensor product of given polynomials.
*
- * Given a vector of <i>n</i> one-dimensional polynomials
- * <i>P<sub>1</sub></i> to <i>P<sub>n</sub></i>, this class generates
- * <i>n<sup>dim</sup></i> polynomials of the form
- * <i>Q<sub>ijk</sub>(x,y,z) =
+ * Given a vector of <i>n</i> one-dimensional polynomials <i>P<sub>1</sub></i>
+ * to <i>P<sub>n</sub></i>, this class generates <i>n<sup>dim</sup></i>
+ * polynomials of the form <i>Q<sub>ijk</sub>(x,y,z) =
* P<sub>i</sub>(x)P<sub>j</sub>(y)P<sub>k</sub>(z)</i>. If the base
- * polynomials are mutually orthogonal on the interval [-1,1] or
- * [0,1], then the tensor product polynomials are orthogonal on
- * [-1,1]<sup>dim</sup> or [0,1]<sup>dim</sup>, respectively.
+ * polynomials are mutually orthogonal on the interval [-1,1] or [0,1], then
+ * the tensor product polynomials are orthogonal on [-1,1]<sup>dim</sup> or
+ * [0,1]<sup>dim</sup>, respectively.
*
* Indexing is as follows: the order of dim-dimensional polynomials is
- * x-coordinates running fastest, then y-coordinate, etc. The first
- * few polynomials are thus <i>P<sub>1</sub>(x)P<sub>1</sub>(y),
- * P<sub>2</sub>(x)P<sub>1</sub>(y), P<sub>3</sub>(x)P<sub>1</sub>(y),
- * ..., P<sub>1</sub>(x)P<sub>2</sub>(y),
- * P<sub>2</sub>(x)P<sub>2</sub>(y), P<sub>3</sub>(x)P<sub>2</sub>(y),
- * ...</i> and likewise in 3d.
+ * x-coordinates running fastest, then y-coordinate, etc. The first few
+ * polynomials are thus <i>P<sub>1</sub>(x)P<sub>1</sub>(y),
+ * P<sub>2</sub>(x)P<sub>1</sub>(y), P<sub>3</sub>(x)P<sub>1</sub>(y), ...,
+ * P<sub>1</sub>(x)P<sub>2</sub>(y), P<sub>2</sub>(x)P<sub>2</sub>(y),
+ * P<sub>3</sub>(x)P<sub>2</sub>(y), ...</i> and likewise in 3d.
*
- * The output_indices() function prints the ordering of the
- * dim-dimensional polynomials, i.e. for each polynomial in the
- * polynomial space it gives the indices i,j,k of the one-dimensional
- * polynomials in x,y and z direction. The ordering of the
- * dim-dimensional polynomials can be changed by using the
+ * The output_indices() function prints the ordering of the dim-dimensional
+ * polynomials, i.e. for each polynomial in the polynomial space it gives the
+ * indices i,j,k of the one-dimensional polynomials in x,y and z direction.
+ * The ordering of the dim-dimensional polynomials can be changed by using the
* set_numbering() function.
*
- * @author Ralf Hartmann, 2000, 2004, Guido Kanschat, 2000, Wolfgang Bangerth 2003
+ * @author Ralf Hartmann, 2000, 2004, Guido Kanschat, 2000, Wolfgang Bangerth
+ * 2003
*/
template <int dim, typename POLY=Polynomials::Polynomial<double> >
class TensorProductPolynomials
/**
* Each tensor product polynomial <i>i</i> is a product of one-dimensional
- * polynomials in each space direction. Compute the indices of these
- * one-dimensional polynomials for each space direction, given the index
+ * polynomials in each space direction. Compute the indices of these one-
+ * dimensional polynomials for each space direction, given the index
* <i>i</i>.
*/
// fix to avoid compiler warnings about zero length arrays
* Anisotropic tensor product of given polynomials.
*
* Given one-dimensional polynomials <tt>Px1</tt>, <tt>Px2</tt>, ... in
- * x-direction, <tt>Py1</tt>, <tt>Py2</tt>, ... in y-direction, and so on, this
- * class generates polynomials of the form <i>Q<sub>ijk</sub>(x,y,z) =
- * Pxi(x)Pyj(y)Pzk(z)</i>. If the base polynomials are mutually
- * orthogonal on the interval $[-1,1]$ or $[0,d]$, then the tensor
- * product polynomials are orthogonal on $[-1,1]^d$ or $[0,1]^d$,
- * respectively.
+ * x-direction, <tt>Py1</tt>, <tt>Py2</tt>, ... in y-direction, and so on,
+ * this class generates polynomials of the form <i>Q<sub>ijk</sub>(x,y,z) =
+ * Pxi(x)Pyj(y)Pzk(z)</i>. If the base polynomials are mutually orthogonal on
+ * the interval $[-1,1]$ or $[0,d]$, then the tensor product polynomials are
+ * orthogonal on $[-1,1]^d$ or $[0,1]^d$, respectively.
*
- * Indexing is as follows: the order of dim-dimensional polynomials
- * is x-coordinates running fastest, then y-coordinate, etc. The first
- * few polynomials are thus <tt>Px1(x)Py1(y)</tt>, <tt>Px2(x)Py1(y)</tt>,
+ * Indexing is as follows: the order of dim-dimensional polynomials is
+ * x-coordinates running fastest, then y-coordinate, etc. The first few
+ * polynomials are thus <tt>Px1(x)Py1(y)</tt>, <tt>Px2(x)Py1(y)</tt>,
* <tt>Px3(x)Py1(y)</tt>, ..., <tt>Px1(x)Py2(y)</tt>, <tt>Px2(x)Py2(y)</tt>,
* <tt>Px3(x)Py2(y)</tt>, ..., and likewise in 3d.
*
/**
* Each tensor product polynomial @þ{i} is a product of one-dimensional
- * polynomials in each space direction. Compute the indices of these
- * one-dimensional polynomials for each space direction, given the index
+ * polynomials in each space direction. Compute the indices of these one-
+ * dimensional polynomials for each space direction, given the index
* <tt>i</tt>.
*/
void compute_index (const unsigned int i,
{
public:
/**
- * Access to the dimension of
- * this object, for checking and
- * automatic setting of dimension
- * in other classes.
+ * Access to the dimension of this object, for checking and automatic
+ * setting of dimension in other classes.
*/
static const unsigned int dimension = dim;
namespace Threads
{
/**
- * @brief A class that provides a separate storage location on each thread that accesses the object.
+ * @brief A class that provides a separate storage location on each thread
+ * that accesses the object.
*
- * This class offers ways so that every thread that accesses it has its
- * own copy of an object of type T. In essence, accessing this object
- * can never result in race conditions in multithreaded programs since
- * no other thread than the current one can ever access it.
+ * This class offers ways so that every thread that accesses it has its own
+ * copy of an object of type T. In essence, accessing this object can never
+ * result in race conditions in multithreaded programs since no other thread
+ * than the current one can ever access it.
*
- * The class builds on the Threading Building Blocks's tbb::enumerable_thread_specific
- * class but wraps it in such a way that this class can also be used when deal.II
- * is configured not to use threads at all -- in that case, this class simply
- * stores a single copy of an object of type T.
+ * The class builds on the Threading Building Blocks's
+ * tbb::enumerable_thread_specific class but wraps it in such a way that
+ * this class can also be used when deal.II is configured not to use threads
+ * at all -- in that case, this class simply stores a single copy of an
+ * object of type T.
*
* <h3>Construction and destruction</h3>
*
- * Objects of this class can either be default constructed or by providing an
- * "exemplar", i.e. an object of type T so that every time we need to create
- * a T on a thread that doesn't already have such an object, it is copied from
- * the exemplar.
+ * Objects of this class can either be default constructed or by providing
+ * an "exemplar", i.e. an object of type T so that every time we need to
+ * create a T on a thread that doesn't already have such an object, it is
+ * copied from the exemplar.
*
* Upon destruction of objects of this class, all T objects that correspond
- * to threads that have accessed this object are destroyed. Note that this may be
- * before the time when a thread is terminated.
+ * to threads that have accessed this object are destroyed. Note that this
+ * may be before the time when a thread is terminated.
*
* <h3>Access</h3>
*
- * The T object stored by this object can be accessed using the get() function. It
- * provides a reference to a unique object when accessed from different threads.
- * Objects of type T are created lazily, i.e. they are only created whenever a
- * thread actually calls get().
+ * The T object stored by this object can be accessed using the get()
+ * function. It provides a reference to a unique object when accessed from
+ * different threads. Objects of type T are created lazily, i.e. they are
+ * only created whenever a thread actually calls get().
*/
template <typename T>
class ThreadLocalStorage
{
public:
/**
- * Default constructor. Initialize each thread local object
- * using its default constructor.
- **/
+ * Default constructor. Initialize each thread local object using its
+ * default constructor.
+ */
ThreadLocalStorage ();
/**
- * A kind of copy constructor. Initialize each thread local object
- * by copying the given object.
- **/
+ * A kind of copy constructor. Initialize each thread local object by
+ * copying the given object.
+ */
explicit ThreadLocalStorage (const T &t);
/**
- * Copy constructor. Initialize each thread local object
- * with the corresponding object of the given object.
+ * Copy constructor. Initialize each thread local object with the
+ * corresponding object of the given object.
*/
ThreadLocalStorage (const ThreadLocalStorage<T> &t);
* Return a reference to the data stored by this object for the current
* thread this function is called on.
*
- * Note that there is no member function get() that is const and
- * returns a const reference as one would expect. The reason is that
- * if such a member function were called on a thread for which no
- * thread-local object has been created yet, then one has to create
- * such an object first which would certainly be a non-constant
- * operation. If you need to call the get() function for a member
- * variable of a class from a const member function, then you
- * need to declare the member variable <code>mutable</code> to
- * allow such access.
+ * Note that there is no member function get() that is const and returns a
+ * const reference as one would expect. The reason is that if such a
+ * member function were called on a thread for which no thread-local
+ * object has been created yet, then one has to create such an object
+ * first which would certainly be a non-constant operation. If you need to
+ * call the get() function for a member variable of a class from a const
+ * member function, then you need to declare the member variable
+ * <code>mutable</code> to allow such access.
*/
T &get ();
/**
- * Same as above, except that @p exists is set to true if an element
- * was already present for the current thread; false otherwise.
+ * Same as above, except that @p exists is set to true if an element was
+ * already present for the current thread; false otherwise.
*/
T &get (bool &exists);
/**
- * Conversion operator that simply converts the thread-local object
- * to the data type that it stores. This function is equivalent to
- * calling the get() member function; it's purpose is to make the
- * TLS object look more like the object it is storing.
+ * Conversion operator that simply converts the thread-local object to the
+ * data type that it stores. This function is equivalent to calling the
+ * get() member function; it's purpose is to make the TLS object look more
+ * like the object it is storing.
*/
operator T &();
/**
- * Copy the given argument into the storage space used to represent
- * the current thread. Calling this function as <code>tls_data = object</code>
+ * Copy the given argument into the storage space used to represent the
+ * current thread. Calling this function as <code>tls_data = object</code>
* is equivalent to calling <code>tls_data.get() = object</code>. The
- * intent of this operator is to make the ThreadLocalStorage object
- * look more like the object it represents on the current thread.
+ * intent of this operator is to make the ThreadLocalStorage object look
+ * more like the object it represents on the current thread.
*
- * @param t The object to be copied into the storage space used
- * for the current thread.
+ * @param t The object to be copied into the storage space used for the
+ * current thread.
*
* @return The current object, after the changes have been made
- **/
+ */
ThreadLocalStorage<T> &operator = (const T &t);
/**
* Remove the thread-local objects stored for all threads that have
- * created one with this object (i.e., that have called get()
- * at least once on this thread. This includes the current thread. If you
- * call get() subsequently on this or any other thread, new objects will
- * again be created.
+ * created one with this object (i.e., that have called get() at least
+ * once on this thread. This includes the current thread. If you call
+ * get() subsequently on this or any other thread, new objects will again
+ * be created.
*
- * If deal.II has been configured to not use multithreading, then this function
- * does not do anything at all. Note that this of course has different semantics
- * as in the multithreading context the objects are deleted and created again
- * (possible by copying from a sample object, if the appropriate constructor
- * of this class was called), whereas in the multithreaded context the object
- * is simply not touched at all. At the same time, the purpose of this function
- * is to release memory other threads may have allocated for their own thread
- * local objects after which every use of this object will require some kind
- * of initialization. This is necessary both in the multithreaded or
- * non-multithreaded case.
+ * If deal.II has been configured to not use multithreading, then this
+ * function does not do anything at all. Note that this of course has
+ * different semantics as in the multithreading context the objects are
+ * deleted and created again (possible by copying from a sample object, if
+ * the appropriate constructor of this class was called), whereas in the
+ * multithreaded context the object is simply not touched at all. At the
+ * same time, the purpose of this function is to release memory other
+ * threads may have allocated for their own thread local objects after
+ * which every use of this object will require some kind of
+ * initialization. This is necessary both in the multithreaded or non-
+ * multithreaded case.
*/
void clear ();
/**
* Returns a reference to the internal Threading Building Blocks
- * implementation. This function is really only useful if deal.II
- * has been configured with multithreading and has no useful
- * purpose otherwise.
+ * implementation. This function is really only useful if deal.II has been
+ * configured with multithreading and has no useful purpose otherwise.
*/
#ifdef DEAL_II_WITH_THREADS
tbb::enumerable_thread_specific<T> &
private:
#ifdef DEAL_II_WITH_THREADS
/**
- * The data element we store. If we support threads, then this
- * object will be of a type that provides a separate object
- * for each thread. Otherwise, it is simply a single object
- * of type T.
- **/
+ * The data element we store. If we support threads, then this object will
+ * be of a type that provides a separate object for each thread.
+ * Otherwise, it is simply a single object of type T.
+ */
tbb::enumerable_thread_specific<T> data;
#else
T data;
/**
- * A namespace for the implementation of thread management in
- * 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.
+ * A namespace for the implementation of thread management in 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
*/
{
/**
* This class is used instead of a true lock class when not using
- * multithreading. It allows to write programs such that they start
- * new threads and/or lock objects in multithreading mode, and use
- * dummy thread management and synchronization classes instead when
- * running in single-thread mode. Specifically, the new_thread()
- * functions only call the function but wait for it to return
- * instead of running in on another thread, and the mutices do
- * nothing really. The only reason to provide such a function is
- * that the program can be compiled both in MT and non-MT mode
- * without difference.
+ * multithreading. It allows to write programs such that they start new
+ * threads and/or lock objects in multithreading mode, and use dummy thread
+ * management and synchronization classes instead when running in single-
+ * thread mode. Specifically, the new_thread() functions only call the
+ * function but wait for it to return instead of running in on another
+ * thread, and the mutices do nothing really. The only reason to provide
+ * such a function is that the program can be compiled both in MT and non-MT
+ * mode without difference.
*
* @author Wolfgang Bangerth, 2000, 2003
*/
{
public:
/**
- * Scoped lock class. When you declare an object of this type, you
- * have to pass it a mutex, which is locked in the constructor of
- * this class and unlocked in the destructor. The lock is thus
- * held during the entire lifetime of this object, i.e. until the
- * end of the present scope, which explains where the name comes
- * from. This pattern of using locks with mutexes follows the
- * resource-acquisition-is-initialization pattern, and was used
- * first for mutexes by Doug Schmidt. It has the advantage that
- * locking a mutex this way is thread-safe, i.e. when an exception
- * is thrown between the locking and unlocking point, the
- * destructor makes sure that the mutex is unlocked; this would
- * not automatically be the case when you lock and unlock the
- * mutex "by hand", i.e. using Mutex::acquire() and
- * Mutex::release().
+ * Scoped lock class. When you declare an object of this type, you have to
+ * pass it a mutex, which is locked in the constructor of this class and
+ * unlocked in the destructor. The lock is thus held during the entire
+ * lifetime of this object, i.e. until the end of the present scope, which
+ * explains where the name comes from. This pattern of using locks with
+ * mutexes follows the resource-acquisition-is-initialization pattern, and
+ * was used first for mutexes by Doug Schmidt. It has the advantage that
+ * locking a mutex this way is thread-safe, i.e. when an exception is
+ * thrown between the locking and unlocking point, the destructor makes
+ * sure that the mutex is unlocked; this would not automatically be the
+ * case when you lock and unlock the mutex "by hand", i.e. using
+ * Mutex::acquire() and Mutex::release().
*/
class ScopedLock
{
public:
/**
- * Constructor. Lock the mutex. Since this is a dummy mutex
- * class, this of course does nothing.
+ * Constructor. Lock the mutex. Since this is a dummy mutex class, this
+ * of course does nothing.
*/
ScopedLock (DummyThreadMutex &) {}
/**
- * Destructor. Unlock the mutex. Since this is a dummy mutex
- * class, this of course does nothing.
+ * Destructor. Unlock the mutex. Since this is a dummy mutex class, this
+ * of course does nothing.
*/
~ScopedLock () {}
};
/**
- * Simulate acquisition of the mutex. As this class does nothing
- * really, this function does nothing as well.
+ * Simulate acquisition of the mutex. As this class does nothing really,
+ * this function does nothing as well.
*/
inline void acquire () const {}
/**
- * Simulate release of the mutex. As this class does nothing
- * really, this function does nothing as well.
+ * Simulate release of the mutex. As this class does nothing really, this
+ * function does nothing as well.
*/
inline void release () const {}
};
/**
* This class is used in single threaded mode instead of a class
- * implementing real condition variable semantics. It allows to
- * write programs such that they start new threads and/or lock
- * objects in multithreading mode, and use dummy thread management
- * and synchronization classes instead when running in single-thread
- * mode. Specifically, the new_thread() functions only call the
- * function but wait for it to return instead of running in on
- * another thread, and the mutexes do nothing really. The only
- * reason to provide such a function is that the program can be
- * compiled both in MT and non-MT mode without difference.
+ * implementing real condition variable semantics. It allows to write
+ * programs such that they start new threads and/or lock objects in
+ * multithreading mode, and use dummy thread management and synchronization
+ * classes instead when running in single-thread mode. Specifically, the
+ * new_thread() functions only call the function but wait for it to return
+ * instead of running in on another thread, and the mutexes do nothing
+ * really. The only reason to provide such a function is that the program
+ * can be compiled both in MT and non-MT mode without difference.
*
- * In this particular case, just as with mutexes, the functions do
- * nothing, and by this provide the same semantics of condition
- * variables as in multi-threaded mode.
+ * In this particular case, just as with mutexes, the functions do nothing,
+ * and by this provide the same semantics of condition variables as in
+ * multi-threaded mode.
*
* @author Wolfgang Bangerth, 2003
*/
{
public:
/**
- * Signal to a single listener that a condition has been met,
- * i.e. that some data will now be available. Since in single
- * threaded mode, this function of course does nothing.
+ * Signal to a single listener that a condition has been met, i.e. that
+ * some data will now be available. Since in single threaded mode, this
+ * function of course does nothing.
*/
inline void signal () const {}
/**
- * Signal to multiple listener that a condition has been met,
- * i.e. that some data will now be available. Since in single
- * threaded mode, this function of course does nothing.
+ * Signal to multiple listener that a condition has been met, i.e. that
+ * some data will now be available. Since in single threaded mode, this
+ * function of course does nothing.
*/
inline void broadcast () const {}
/**
- * Wait for the condition to be signalled. Signal variables need
- * to be guarded by a mutex which needs to be given to this
- * function as an argument, see the man page of
- * <code>posix_cond_wait</code> for a description of the
- * mechanisms. Since in single threaded mode, this function of
- * course does nothing, but returns immediately.
+ * Wait for the condition to be signalled. Signal variables need to be
+ * guarded by a mutex which needs to be given to this function as an
+ * argument, see the man page of <code>posix_cond_wait</code> for a
+ * description of the mechanisms. Since in single threaded mode, this
+ * function of course does nothing, but returns immediately.
*/
inline void wait (DummyThreadMutex &) const {}
};
/**
* This class is used instead of a true barrier class when not using
- * multithreading. It allows to write programs such that they use
- * the same class names in multithreading and non-MT mode and thus
- * may be compiled with or without thread-support without the need
- * to use conditional compilation. Since a barrier class only makes
- * sense in non-multithread mode if only one thread is to be
- * synchronised (otherwise, the barrier could not be left, since the
- * one thread is waiting for some other part of the program to reach
- * a certain point of execution), the constructor of this class
- * throws an exception if the <code>count</code> argument denoting
- * the number of threads that need to be synchronized is not equal
+ * multithreading. It allows to write programs such that they use the same
+ * class names in multithreading and non-MT mode and thus may be compiled
+ * with or without thread-support without the need to use conditional
+ * compilation. Since a barrier class only makes sense in non-multithread
+ * mode if only one thread is to be synchronised (otherwise, the barrier
+ * could not be left, since the one thread is waiting for some other part of
+ * the program to reach a certain point of execution), the constructor of
+ * this class throws an exception if the <code>count</code> argument
+ * denoting the number of threads that need to be synchronized is not equal
* to one.
*
* @author Wolfgang Bangerth, 2001
{
public:
/**
- * Constructor. Since barriers are only useful in single-threaded
- * mode if the number of threads to be synchronised is one, this
- * constructor raises an exception if the <code>count</code>
- * argument is one.
+ * Constructor. Since barriers are only useful in single-threaded mode if
+ * the number of threads to be synchronised is one, this constructor
+ * raises an exception if the <code>count</code> argument is one.
*/
DummyBarrier (const unsigned int count,
const char *name = 0,
void *arg = 0);
/**
- * Wait for all threads to reach this point. Since there may only
- * be one thread, return immediately, i.e. this function is a
- * no-op.
+ * Wait for all threads to reach this point. Since there may only be one
+ * thread, return immediately, i.e. this function is a no-op.
*/
int wait () const
{
*/
void dump () const {}
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception.
#ifdef DEAL_II_WITH_THREADS
/**
- * Class implementing a Mutex. Mutexes are used to lock data
- * structures to ensure that only a single thread of execution can
- * access them at the same time.
+ * Class implementing a Mutex. Mutexes are used to lock data structures to
+ * ensure that only a single thread of execution can access them at the same
+ * time.
*
* <h3>Copy semantics</h3>
*
- * When copied, the receiving object does not receive any state from
- * the object being copied, i.e. an entirely new mutex is
- * created. This is consistent with expectations if a mutex is used
- * as a member variable to lock the other member variables of a
- * class: in that case, the mutex of the copied-to object should
- * only guard the members of the copied-to object, not the members
- * of both the copied-to and copied-from object.
+ * When copied, the receiving object does not receive any state from the
+ * object being copied, i.e. an entirely new mutex is created. This is
+ * consistent with expectations if a mutex is used as a member variable to
+ * lock the other member variables of a class: in that case, the mutex of
+ * the copied-to object should only guard the members of the copied-to
+ * object, not the members of both the copied-to and copied-from object.
*
* @author Wolfgang Bangerth, 2002, 2003, 2009
*/
{
public:
/**
- * Scoped lock class. When you declare an object of this type, you
- * have to pass it a mutex, which is locked in the constructor of
- * this class and unlocked in the destructor. The lock is thus
- * held during the entire lifetime of this object, i.e. until the
- * end of the present scope, which explains where the name comes
- * from. This pattern of using locks with mutexes follows the
- * resource-acquisition-is-initialization pattern, and was used
- * first for mutexes by Doug Schmidt. It has the advantage that
- * locking a mutex this way is thread-safe, i.e. when an exception
- * is thrown between the locking and unlocking point, the
- * destructor makes sure that the mutex is unlocked; this would
- * not automatically be the case when you lock and unlock the
- * mutex "by hand", i.e. using Mutex::acquire() and
- * Mutex::release().
+ * Scoped lock class. When you declare an object of this type, you have to
+ * pass it a mutex, which is locked in the constructor of this class and
+ * unlocked in the destructor. The lock is thus held during the entire
+ * lifetime of this object, i.e. until the end of the present scope, which
+ * explains where the name comes from. This pattern of using locks with
+ * mutexes follows the resource-acquisition-is-initialization pattern, and
+ * was used first for mutexes by Doug Schmidt. It has the advantage that
+ * locking a mutex this way is thread-safe, i.e. when an exception is
+ * thrown between the locking and unlocking point, the destructor makes
+ * sure that the mutex is unlocked; this would not automatically be the
+ * case when you lock and unlock the mutex "by hand", i.e. using
+ * Mutex::acquire() and Mutex::release().
*/
class ScopedLock
{
}
/**
- * Destructor. Unlock the mutex. Since this is a dummy mutex
- * class, this of course does nothing.
+ * Destructor. Unlock the mutex. Since this is a dummy mutex class, this
+ * of course does nothing.
*/
~ScopedLock ()
{
{}
/**
- * Copy constructor. As discussed in this class's documentation,
- * no state is copied from the object given as argument.
+ * Copy constructor. As discussed in this class's documentation, no state
+ * is copied from the object given as argument.
*/
Mutex (const Mutex &)
:
std_cxx11::mutex mutex;
/**
- * Make the class implementing condition variables a friend, since
- * it needs to access the mutex.
+ * Make the class implementing condition variables a friend, since it
+ * needs to access the mutex.
*/
friend class ConditionVariable;
};
/**
- * Class implementing a condition variable. The semantics of this
- * class and its member functions are the same as those of the POSIX
- * functions.
+ * Class implementing a condition variable. The semantics of this class and
+ * its member functions are the same as those of the POSIX functions.
*
* @author Wolfgang Bangerth, 2003
*/
{
public:
/**
- * Signal to a single listener that a condition has been met,
- * i.e. that some data will now be available.
+ * Signal to a single listener that a condition has been met, i.e. that
+ * some data will now be available.
*/
inline void signal ()
{
}
/**
- * Signal to multiple listener that a condition has been met,
- * i.e. that some data will now be available.
+ * Signal to multiple listener that a condition has been met, i.e. that
+ * some data will now be available.
*/
inline void broadcast ()
{
}
/**
- * Wait for the condition to be signalled. Signal variables need
- * to be guarded by a mutex which needs to be given to this
- * function as an argument, see the man page of
- * <code>pthread_cond_wait</code> for a description of the
- * mechanisms.
+ * Wait for the condition to be signalled. Signal variables need to be
+ * guarded by a mutex which needs to be given to this function as an
+ * argument, see the man page of <code>pthread_cond_wait</code> for a
+ * description of the mechanisms.
*
- * The mutex is assumed held at the entry to this function but is
- * released upon exit.
+ * The mutex is assumed held at the entry to this function but is released
+ * upon exit.
*/
inline void wait (Mutex &mutex)
{
/**
- * Implementation of a thread barrier class, based on the POSIX
- * thread functions. POSIX barriers are a relatively new feature and
- * are not supported on all systems.
+ * Implementation of a thread barrier class, based on the POSIX thread
+ * functions. POSIX barriers are a relatively new feature and are not
+ * supported on all systems.
*
- * If the configuration detected the absence of these functions,
- * then barriers will not be available, and creating objects of this
- * class will result in an exception been thrown unless the count
- * given for the parties waiting for the barrier is equal to one (as
- * in this case waiting for the barrier is a no-operation, and we
- * can dispense with the POSIX functions at all). The rest of the
- * threading functionality will be available in its full extent,
- * though, even if POSIX barriers are not available.
+ * If the configuration detected the absence of these functions, then
+ * barriers will not be available, and creating objects of this class will
+ * result in an exception been thrown unless the count given for the parties
+ * waiting for the barrier is equal to one (as in this case waiting for the
+ * barrier is a no-operation, and we can dispense with the POSIX functions
+ * at all). The rest of the threading functionality will be available in its
+ * full extent, though, even if POSIX barriers are not available.
*
* @author Wolfgang Bangerth, 2002
*/
{
public:
/**
- * Constructor. Initialize the underlying POSIX barrier data
- * structure.
+ * Constructor. Initialize the underlying POSIX barrier data structure.
*/
PosixThreadBarrier (const unsigned int count,
const char *name = 0,
~PosixThreadBarrier ();
/**
- * Wait for all threads to reach this point. The return value is
- * zero for all participating threads except for one, for which
- * the return value is some non-zero value. The operating system
- * picks the special thread by some not further known method.
+ * Wait for all threads to reach this point. The return value is zero for
+ * all participating threads except for one, for which the return value is
+ * some non-zero value. The operating system picks the special thread by
+ * some not further known method.
*/
int wait ();
private:
/**
- * Data object storing the POSIX data which we need to call the
- * POSIX functions.
+ * Data object storing the POSIX data which we need to call the POSIX
+ * functions.
*/
#ifndef DEAL_II_USE_MT_POSIX_NO_BARRIERS
pthread_barrier_t barrier;
/**
- * Provide a backward compatible name (we used ThreadMutex up to
- * release 6.1, but since it is already in a namespace Threads this
- * seems redundant).
+ * Provide a backward compatible name (we used ThreadMutex up to release
+ * 6.1, but since it is already in a namespace Threads this seems
+ * redundant).
*
* @deprecated
*/
typedef Mutex ThreadMutex DEAL_II_DEPRECATED;
/**
- * Provide a backward compatible name (we used ThreadCondition up to
- * release 6.1, but since it is already in a namespace Threads this
- * seems redundant).
+ * Provide a backward compatible name (we used ThreadCondition up to release
+ * 6.1, but since it is already in a namespace Threads this seems
+ * redundant).
*
* @deprecated
*/
typedef ConditionVariable ThreadCondition DEAL_II_DEPRECATED;
/**
- * If using POSIX functions, then alias the POSIX wrapper classes to
- * the names we use throughout the library.
+ * If using POSIX functions, then alias the POSIX wrapper classes to the
+ * names we use throughout the library.
*/
typedef PosixThreadBarrier Barrier;
#else
/**
- * In non-multithread mode, the mutex and thread management classes
- * are aliased to dummy classes that actually do nothing, in
- * particular not lock objects. Likewise for the barrier class.
+ * In non-multithread mode, the mutex and thread management classes are
+ * aliased to dummy classes that actually do nothing, in particular not lock
+ * objects. Likewise for the barrier class.
*/
typedef DummyThreadMutex Mutex;
typedef DummyThreadMutex ThreadMutex;
/**
- * In non-multithread mode, the mutex and thread management classes
- * are aliased to dummy classes that actually do nothing, in
- * particular not lock objects. Likewise for the barrier class.
+ * In non-multithread mode, the mutex and thread management classes are
+ * aliased to dummy classes that actually do nothing, in particular not lock
+ * objects. Likewise for the barrier class.
*/
typedef DummyThreadCondition ConditionVariable;
typedef DummyThreadCondition ThreadCondition;
/**
- * In non-multithread mode, the mutex and thread management classes
- * are aliased to dummy classes that actually do nothing, in
- * particular not lock objects. Likewise for the barrier class.
+ * In non-multithread mode, the mutex and thread management classes are
+ * aliased to dummy classes that actually do nothing, in particular not lock
+ * objects. Likewise for the barrier class.
*/
typedef DummyBarrier Barrier;
#endif
{
/**
- * Return the number of presently existing threads. This function
- * may be useful in a situation where a large number of threads are
- * concurrently, and you want to decide whether creation of another
- * thread is reasonable or whether running the respective operation
- * sequentially is more useful since already many more threads than
- * processors are running.
+ * Return the number of presently existing threads. This function may be
+ * useful in a situation where a large number of threads are concurrently,
+ * and you want to decide whether creation of another thread is reasonable
+ * or whether running the respective operation sequentially is more useful
+ * since already many more threads than processors are running.
*
- * Note that the function returns the total number of threads, not
- * those actually running. Some of the threads may be waiting for
- * locks and mutexes, or may be sleeping until they are delivered
- * with data to work on.
+ * Note that the function returns the total number of threads, not those
+ * actually running. Some of the threads may be waiting for locks and
+ * mutexes, or may be sleeping until they are delivered with data to work
+ * on.
*
- * Upon program start, this number is one. It is increased each time
- * a thread is created using the Threads::new_thread function. It is
- * decreased once a thread terminates by returning from the function
- * that was spawned.
+ * Upon program start, this number is one. It is increased each time a
+ * thread is created using the Threads::new_thread function. It is decreased
+ * once a thread terminates by returning from the function that was spawned.
*
- * Note that this means that only threads created and terminated
- * through the interfaces of this namespace are taken care of. If
- * threads are created by directly calling the respective functions
- * of the operating system (e.g. <code>pthread_create</code> for the
- * POSIX thread interface), or if they are killed (e.g. either
- * through <code>pthread_exit</code> from the spawned thread, or
- * <code>pthread_kill</code> from another thread), then these events
- * are not registered and counted for the result of this
- * function. Likewise, threads that the Threading Building Blocks
- * library may have created to work on tasks created using the
- * Threads::new_task functions are not counted.
+ * Note that this means that only threads created and terminated through the
+ * interfaces of this namespace are taken care of. If threads are created by
+ * directly calling the respective functions of the operating system (e.g.
+ * <code>pthread_create</code> for the POSIX thread interface), or if they
+ * are killed (e.g. either through <code>pthread_exit</code> from the
+ * spawned thread, or <code>pthread_kill</code> from another thread), then
+ * these events are not registered and counted for the result of this
+ * function. Likewise, threads that the Threading Building Blocks library
+ * may have created to work on tasks created using the Threads::new_task
+ * functions are not counted.
*
* @ingroup threads
*/
unsigned int n_existing_threads ();
/**
- * Return a number used as id of this thread. This number is
- * generated using the system call <code>getpid</code>, or, if it
- * exists <code>gettid</code>. The result of either is converted to
- * an integer and returned by this function.
+ * Return a number used as id of this thread. This number is generated using
+ * the system call <code>getpid</code>, or, if it exists
+ * <code>gettid</code>. The result of either is converted to an integer and
+ * returned by this function.
*
* @todo As of now, none of our systems seems to support
* <code>gettid</code>, so that part of the code is untested yet.
unsigned int this_thread_id ();
/**
- * Split the range <code>[begin,end)</code> into
- * <code>n_intervals</code> subintervals of equal size. The last
- * interval will be a little bit larger, if the number of elements
- * in the whole range is not exactly divisible by
- * <code>n_intervals</code>. The type of the iterators has to
- * fulfill the requirements of a forward iterator,
- * i.e. <code>operator++</code> must be available, and of course it
- * must be assignable.
+ * Split the range <code>[begin,end)</code> into <code>n_intervals</code>
+ * subintervals of equal size. The last interval will be a little bit
+ * larger, if the number of elements in the whole range is not exactly
+ * divisible by <code>n_intervals</code>. The type of the iterators has to
+ * fulfill the requirements of a forward iterator, i.e.
+ * <code>operator++</code> must be available, and of course it must be
+ * assignable.
*
- * A list of subintervals is returned as a vector of pairs of
- * iterators, where each pair denotes the range
- * <code>[begin[i],end[i])</code>.
+ * A list of subintervals is returned as a vector of pairs of iterators,
+ * where each pair denotes the range <code>[begin[i],end[i])</code>.
*
* @ingroup threads
*/
const unsigned int n_intervals);
/**
- * Split the interval <code>[begin,end)</code> into subintervals of
- * (almost) equal size. This function works mostly as the one
- * before, with the difference that instead of iterators, now values
- * are taken that define the whole interval.
+ * Split the interval <code>[begin,end)</code> into subintervals of (almost)
+ * equal size. This function works mostly as the one before, with the
+ * difference that instead of iterators, now values are taken that define
+ * the whole interval.
*
* @ingroup threads
*/
*/
/**
- * A namespace in which helper functions and the like for the
- * threading subsystem are implemented. The members of this
- * namespace are not meant for public use.
+ * A namespace in which helper functions and the like for the threading
+ * subsystem are implemented. The members of this namespace are not meant
+ * for public use.
*
* @author Wolfgang Bangerth, 2003
*/
/**
* @internal
*
- * If in a sub-thread an exception is thrown, it is not
- * propagated to the main thread. Therefore, the exception handler
- * that is provided by the applications main function or some of
- * its other parts will not be able to catch these
- * exceptions. Therefore, we have to provide an exception handler
- * in the top function of each sub-thread that at least catches
- * the exception and prints some information, rather than letting
- * the operating system to just kill the program without a
- * message. In each of the functions we use as entry points to new
- * threads, we therefore install a try-catch block, and if an
- * exception of type <code>std::exception</code> is caught, it
- * passes over control to this function, which will then provide
- * some output.
+ * If in a sub-thread an exception is thrown, it is not propagated to the
+ * main thread. Therefore, the exception handler that is provided by the
+ * applications main function or some of its other parts will not be able
+ * to catch these exceptions. Therefore, we have to provide an exception
+ * handler in the top function of each sub-thread that at least catches
+ * the exception and prints some information, rather than letting the
+ * operating system to just kill the program without a message. In each of
+ * the functions we use as entry points to new threads, we therefore
+ * install a try-catch block, and if an exception of type
+ * <code>std::exception</code> is caught, it passes over control to this
+ * function, which will then provide some output.
*/
void handle_std_exception (const std::exception &exc);
/**
* @internal
*
- * Same as above, but the type of the exception is not
- * derived from <code>std::exception</code>, so there is little
- * way to provide something more useful.
+ * Same as above, but the type of the exception is not derived from
+ * <code>std::exception</code>, so there is little way to provide
+ * something more useful.
*/
void handle_unknown_exception ();
/**
* @internal
*
- * The following function is used for internal bookkeeping of the
- * number of existing threads. It is not thought for use in
- * application programs, but only for use in the template
- * functions below.
+ * The following function is used for internal bookkeeping of the number
+ * of existing threads. It is not thought for use in application programs,
+ * but only for use in the template functions below.
*/
void register_thread ();
/**
* @internal
*
- * The following function is used for internal bookkeeping of the
- * number of existing threads. It is not thought for use in
- * application programs, but only for use in the template
- * functions below.
+ * The following function is used for internal bookkeeping of the number
+ * of existing threads. It is not thought for use in application programs,
+ * but only for use in the template functions below.
*/
void deregister_thread ();
}
/**
* @internal
*
- * Given an arbitrary type RT, store an element of it and grant
- * access to it through functions get() and set(). There are
- * specializations for reference types (which cannot be set), and
- * for type void.
+ * Given an arbitrary type RT, store an element of it and grant access to
+ * it through functions get() and set(). There are specializations for
+ * reference types (which cannot be set), and for type void.
*/
template <typename RT> struct return_value
{
/**
* @internal
*
- * Given an arbitrary type RT, store an element of it and grant
- * access to it through functions get() and set(). This is the
- * specialization for reference types: since they cannot be set
- * after construction time, we store a pointer instead, that holds
- * the address of the object being referenced.
+ * Given an arbitrary type RT, store an element of it and grant access to
+ * it through functions get() and set(). This is the specialization for
+ * reference types: since they cannot be set after construction time, we
+ * store a pointer instead, that holds the address of the object being
+ * referenced.
*/
template <typename RT> struct return_value<RT &>
{
/**
* @internal
*
- * Given an arbitrary type RT, store an element of it and grant
- * access to it through functions get() and set(). This is the
- * specialization for type void: there is obviously nothing to
- * store, so no function set(), and a function get() that returns
- * void.
+ * Given an arbitrary type RT, store an element of it and grant access to
+ * it through functions get() and set(). This is the specialization for
+ * type void: there is obviously nothing to store, so no function set(),
+ * and a function get() that returns void.
*/
template <> struct return_value<void>
{
/**
* @internal
*
- * Construct a pointer to non-member function based on the
- * template arguments, and whether the second argument is a const
- * or non-const class, depending on which the member function will
- * also me const or non-const. There are specializations of this
- * class for each number of arguments.
+ * Construct a pointer to non-member function based on the template
+ * arguments, and whether the second argument is a const or non-const
+ * class, depending on which the member function will also me const or
+ * non-const. There are specializations of this class for each number of
+ * arguments.
*/
template <typename RT, typename ArgList,
int length = std_cxx11::tuple_size<ArgList>::value>
/**
* @internal
*
- * Construct a pointer to non-member function based on the
- * template arguments. This is the specialization for 0 arguments.
+ * Construct a pointer to non-member function based on the template
+ * arguments. This is the specialization for 0 arguments.
*/
template <typename RT, typename ArgList>
struct fun_ptr_helper<RT, ArgList, 0>
/**
* @internal
*
- * Construct a pointer to non-member function based on the
- * template arguments. This is the specialization for 1 argument.
+ * Construct a pointer to non-member function based on the template
+ * arguments. This is the specialization for 1 argument.
*/
template <typename RT, typename ArgList>
struct fun_ptr_helper<RT, ArgList, 1>
/**
* @internal
*
- * Construct a pointer to non-member function based on the
- * template arguments. This is the specialization for 2 arguments.
+ * Construct a pointer to non-member function based on the template
+ * arguments. This is the specialization for 2 arguments.
*/
template <typename RT, typename ArgList>
struct fun_ptr_helper<RT, ArgList, 2>
/**
* @internal
*
- * Construct a pointer to non-member function based on the
- * template arguments. This is the specialization for 3 arguments.
+ * Construct a pointer to non-member function based on the template
+ * arguments. This is the specialization for 3 arguments.
*/
template <typename RT, typename ArgList>
struct fun_ptr_helper<RT, ArgList, 3>
/**
* @internal
*
- * Construct a pointer to non-member function based on the
- * template arguments. This is the specialization for 4 arguments.
+ * Construct a pointer to non-member function based on the template
+ * arguments. This is the specialization for 4 arguments.
*/
template <typename RT, typename ArgList>
struct fun_ptr_helper<RT, ArgList, 4>
/**
* @internal
*
- * Construct a pointer to non-member function based on the
- * template arguments. This is the specialization for 5 arguments.
+ * Construct a pointer to non-member function based on the template
+ * arguments. This is the specialization for 5 arguments.
*/
template <typename RT, typename ArgList>
struct fun_ptr_helper<RT, ArgList, 5>
/**
* @internal
*
- * Construct a pointer to non-member function based on the
- * template arguments. This is the specialization for 6 arguments.
+ * Construct a pointer to non-member function based on the template
+ * arguments. This is the specialization for 6 arguments.
*/
template <typename RT, typename ArgList>
struct fun_ptr_helper<RT, ArgList, 6>
/**
* @internal
*
- * Construct a pointer to non-member function based on the
- * template arguments. This is the specialization for 7 arguments.
+ * Construct a pointer to non-member function based on the template
+ * arguments. This is the specialization for 7 arguments.
*/
template <typename RT, typename ArgList>
struct fun_ptr_helper<RT, ArgList, 7>
/**
* @internal
*
- * Construct a pointer to non-member function based on the
- * template arguments. This is the specialization for 8 arguments.
+ * Construct a pointer to non-member function based on the template
+ * arguments. This is the specialization for 8 arguments.
*/
template <typename RT, typename ArgList>
struct fun_ptr_helper<RT, ArgList, 8>
/**
* @internal
*
- * Construct a pointer to non-member function based on the
- * template arguments. This is the specialization for 9 arguments.
+ * Construct a pointer to non-member function based on the template
+ * arguments. This is the specialization for 9 arguments.
*/
template <typename RT, typename ArgList>
struct fun_ptr_helper<RT, ArgList, 9>
/**
* @internal
*
- * Construct a pointer to non-member function based on the
- * template arguments. This is the specialization for 10
- * arguments.
+ * Construct a pointer to non-member function based on the template
+ * arguments. This is the specialization for 10 arguments.
*/
template <typename RT, typename ArgList>
struct fun_ptr_helper<RT, ArgList, 10>
/**
* @internal
*
- * Construct a pointer to non-member function based on the
- * template arguments. We do this by dispatching to the
- * fun_ptr_helper classes that are overloaded on the number of
- * elements.
+ * Construct a pointer to non-member function based on the template
+ * arguments. We do this by dispatching to the fun_ptr_helper classes that
+ * are overloaded on the number of elements.
*
- * Note that the last template argument for the fun_ptr_helper
- * class is automatically computed in the default argument to the
- * general template.
+ * Note that the last template argument for the fun_ptr_helper class is
+ * automatically computed in the default argument to the general template.
*/
template <typename RT, typename ArgList>
struct fun_ptr
#ifdef DEAL_II_WITH_THREADS
/**
- * A class that represents threads. For each thread, we create
- * exactly one of these objects -- exactly one because it carries
- * the returned value of the function called on the thread.
+ * A class that represents threads. For each thread, we create exactly one
+ * of these objects -- exactly one because it carries the returned value
+ * of the function called on the thread.
*
* While we have only one of these objects per thread, several
- * Threads::Thread objects may refer to this descriptor. If all
- * Thread objects go out of scope the ThreadDescriptor will detach
- * from the thread before being destructed.
+ * Threads::Thread objects may refer to this descriptor. If all Thread
+ * objects go out of scope the ThreadDescriptor will detach from the
+ * thread before being destructed.
*/
template <typename RT>
struct ThreadDescriptor
std_cxx11::thread thread;
/**
- * An object that will hold the value returned by the function
- * called on the thread.
+ * An object that will hold the value returned by the function called on
+ * the thread.
*
- * The return value is stored in a shared_ptr because we might
- * abandon the the ThreadDescriptor. This makes sure the object
- * stays alive until the thread exits.
+ * The return value is stored in a shared_ptr because we might abandon
+ * the the ThreadDescriptor. This makes sure the object stays alive
+ * until the thread exits.
*/
std_cxx11::shared_ptr<return_value<RT> > ret_val;
/**
- * A bool variable that is initially false, is set to true when
- * a new thread is started, and is set back to false once join()
- * has been called.
+ * A bool variable that is initially false, is set to true when a new
+ * thread is started, and is set back to false once join() has been
+ * called.
*
- * We use this variable to make sure we can call join() twice on
- * the same thread. For some reason, the C++ standard library
- * throws a std::system_error exception if one tries to call
- * std::thread::join twice (and in fact, before the second call,
- * std::thread::joinable returns false) but this is a somewhat
- * desirable thing to do because one doesn't have to keep track
- * whether join() has been called before. Using this variable,
- * whenever we have called join() before, the variable is set to
- * true and we can skip over calling std::thread::join() a
- * second time. Access to this variable is guarded by the
- * following mutex.
+ * We use this variable to make sure we can call join() twice on the
+ * same thread. For some reason, the C++ standard library throws a
+ * std::system_error exception if one tries to call std::thread::join
+ * twice (and in fact, before the second call, std::thread::joinable
+ * returns false) but this is a somewhat desirable thing to do because
+ * one doesn't have to keep track whether join() has been called before.
+ * Using this variable, whenever we have called join() before, the
+ * variable is set to true and we can skip over calling
+ * std::thread::join() a second time. Access to this variable is guarded
+ * by the following mutex.
*
- * @note Historically, we did not need the mutex for this
- * variable: threads can only be joined from the thread that
- * created it originally. Consequently, everything that happens
- * in a function that does not create threads (such as the
- * join() function below) looks atomic to the outside
- * world. Since we clear and test thread_is_active in the same
- * function as we call std::thread::join, these actions are
- * atomic and need no mutex. Of course, two threads may call
- * join() on the same thread object at the same time, but this
- * action is undefined anyway since they can not both join the
- * same thread. That said, more recent C++ standards do not
- * appear to have the requirement any more that the only thread
- * that can call join() is the one that created the
- * thread. Neither does pthread_join appear to have this
- * requirement any more. Consequently, we can in fact join from
- * different threads and we test this in
- * base/thread_validity_07.
+ * @note Historically, we did not need the mutex for this variable:
+ * threads can only be joined from the thread that created it
+ * originally. Consequently, everything that happens in a function that
+ * does not create threads (such as the join() function below) looks
+ * atomic to the outside world. Since we clear and test thread_is_active
+ * in the same function as we call std::thread::join, these actions are
+ * atomic and need no mutex. Of course, two threads may call join() on
+ * the same thread object at the same time, but this action is undefined
+ * anyway since they can not both join the same thread. That said, more
+ * recent C++ standards do not appear to have the requirement any more
+ * that the only thread that can call join() is the one that created the
+ * thread. Neither does pthread_join appear to have this requirement any
+ * more. Consequently, we can in fact join from different threads and
+ * we test this in base/thread_validity_07.
*/
bool thread_is_active;
}
/**
- * Start the thread and let it put its return value into the
- * ret_val object.
+ * Start the thread and let it put its return value into the ret_val
+ * object.
*/
void start (const std_cxx11::function<RT ()> &function)
{
#else
/**
- * A class that represents threads. For each thread, we create
- * exactly one of these objects -- exactly one because it carries
- * the returned value of the function called on the thread.
+ * A class that represents threads. For each thread, we create exactly one
+ * of these objects -- exactly one because it carries the returned value
+ * of the function called on the thread.
*
* While we have only one of these objects per thread, several
* Threads::Thread objects may refer to this descriptor.
struct ThreadDescriptor
{
/**
- * An object that will hold the value returned by the function
- * called on the thread.
+ * An object that will hold the value returned by the function called on
+ * the thread.
*/
std_cxx11::shared_ptr<return_value<RT> > ret_val;
/**
- * Start the thread and let it put its return value into the
- * ret_val object.
+ * Start the thread and let it put its return value into the ret_val
+ * object.
*/
void start (const std_cxx11::function<RT ()> &function)
{
/**
- * An object that represents a spawned thread. This object can be
- * freely copied around in user space, and all instances will
- * represent the same thread and can require to wait for its
- * termination and access its return value.
+ * An object that represents a spawned thread. This object can be freely
+ * copied around in user space, and all instances will represent the same
+ * thread and can require to wait for its termination and access its return
+ * value.
*
- * Threads can be abandoned, i.e. if you just call
- * Threads::new_thread but don't care about the returned object, or
- * if you assign the return Threads::Thread object to an object that
- * subsequently goes out of scope, then the thread previously
- * created will still continue to do work. You will simply not be
- * able to access its return value any more, and it may also happen
- * that your program terminates before the thread has finished its
- * work.
+ * Threads can be abandoned, i.e. if you just call Threads::new_thread but
+ * don't care about the returned object, or if you assign the return
+ * Threads::Thread object to an object that subsequently goes out of scope,
+ * then the thread previously created will still continue to do work. You
+ * will simply not be able to access its return value any more, and it may
+ * also happen that your program terminates before the thread has finished
+ * its work.
*
- * The default value of the template argument is <code>void</code>,
- * so if the function you are calling on a new thread has no return
- * value, you can omit the template argument.
+ * The default value of the template argument is <code>void</code>, so if
+ * the function you are calling on a new thread has no return value, you can
+ * omit the template argument.
*
* @author Wolfgang Bangerth, 2003, 2009
* @ingroup threads
}
/**
- * Default constructor. You can't do much with a thread object
- * constructed this way, except for assigning it a thread object
- * that holds data created by the new_thread() functions.
+ * Default constructor. You can't do much with a thread object constructed
+ * this way, except for assigning it a thread object that holds data
+ * created by the new_thread() functions.
*/
Thread () {}
{}
/**
- * Join the thread represented by this object, i.e. wait for it to
- * finish. If you have used the default constructor of this class
- * and have not assigned a thread object to it, then this function
- * is a no-op.
+ * Join the thread represented by this object, i.e. wait for it to finish.
+ * If you have used the default constructor of this class and have not
+ * assigned a thread object to it, then this function is a no-op.
*/
void join () const
{
}
/**
- * Get the return value of the function of the thread. Since this
- * is only available once the thread finishes, this implicitly
- * also calls join().
+ * Get the return value of the function of the thread. Since this is only
+ * available once the thread finishes, this implicitly also calls join().
*/
RT return_value ()
{
}
/**
- * Return true if this object has had a thread associated with it,
- * either by using the non-default constructor or by assignment.
+ * Return true if this object has had a thread associated with it, either
+ * by using the non-default constructor or by assignment.
*/
bool valid () const
{
/**
- * Check for equality of thread objects. Since objects of this
- * class store an implicit pointer to an object that exists
- * exactly once for each thread, the check is simply to compare
- * these pointers.
+ * Check for equality of thread objects. Since objects of this class store
+ * an implicit pointer to an object that exists exactly once for each
+ * thread, the check is simply to compare these pointers.
*/
bool operator == (const Thread &t)
{
private:
/**
- * Shared pointer to the object representing the thread, and
- * abstracting operating system functions to work on it. Boost's
- * shared pointer implementation will make sure that that object
- * lives as long as there is at least one subscriber to it.
+ * Shared pointer to the object representing the thread, and abstracting
+ * operating system functions to work on it. Boost's shared pointer
+ * implementation will make sure that that object lives as long as there
+ * is at least one subscriber to it.
*/
std_cxx11::shared_ptr<internal::ThreadDescriptor<RT> > thread_descriptor;
};
namespace internal
{
/**
- * A general template that returns std_cxx11::ref(t) if t is of
- * reference type, and t otherwise.
+ * A general template that returns std_cxx11::ref(t) if t is of reference
+ * type, and t otherwise.
*
* The case that t is of reference type is handled in a partial
* specialization declared below.
/**
- * A general template that returns std_cxx11::ref(t) if t is of
- * reference type, and t otherwise.
+ * A general template that returns std_cxx11::ref(t) if t is of reference
+ * type, and t otherwise.
*
* The case that t is of reference type is handled in this partial
* specialization.
/**
* @internal
*
- * General template declaration of a class that is used to
- * encapsulate arguments to global and static member functions,
- * make sure a new thread is created and that function being run
- * on that thread.
+ * General template declaration of a class that is used to encapsulate
+ * arguments to global and static member functions, make sure a new thread
+ * is created and that function being run on that thread.
*
- * Although this general template is not implemented at all, the
- * default template argument makes sure that whenever using the
- * name of this class, the last template argument will be computed
- * correctly from the previous arguments, and the correct
- * specialization for this last template argument be used, even
- * though we need to specify it.
+ * Although this general template is not implemented at all, the default
+ * template argument makes sure that whenever using the name of this
+ * class, the last template argument will be computed correctly from the
+ * previous arguments, and the correct specialization for this last
+ * template argument be used, even though we need to specify it.
*/
template <typename RT, typename ArgList, int length>
class fun_encapsulator;
// ----------- encapsulators for functions not taking any parameters
/**
- * Overload of the spawn function for non-member or static member
- * functions with no arguments.
+ * Overload of the spawn function for non-member or static member functions
+ * with no arguments.
*
* @deprecated Use new_thread() instead.
*/
/**
- * Overload of the non-const spawn function for member functions
- * with no arguments.
+ * Overload of the non-const spawn function for member functions with no
+ * arguments.
*
* @deprecated Use new_thread() instead.
*/
// ----------- encapsulators for unary functions
/**
- * Overload of the spawn function for non-member or static member
- * functions with 1 argument.
+ * Overload of the spawn function for non-member or static member functions
+ * with 1 argument.
*
* @deprecated Use new_thread() instead.
*/
/**
- * Overload of the non-const spawn function for member functions
- * with 1 argument.
+ * Overload of the non-const spawn function for member functions with 1
+ * argument.
*
* @deprecated Use new_thread() instead.
*/
// ----------- encapsulators for binary functions
/**
- * Overload of the spawn function for non-member or static member
- * functions with 2 arguments.
+ * Overload of the spawn function for non-member or static member functions
+ * with 2 arguments.
*
* @deprecated Use new_thread() instead.
*/
/**
- * Overload of the non-const spawn function for member functions
- * with 2 arguments.
+ * Overload of the non-const spawn function for member functions with 2
+ * arguments.
*
* @deprecated Use new_thread() instead.
*/
// ----------- encapsulators for ternary functions
/**
- * Overload of the spawn function for non-member or static member
- * functions with 3 arguments.
+ * Overload of the spawn function for non-member or static member functions
+ * with 3 arguments.
*
* @deprecated Use new_thread() instead.
*/
/**
- * Overload of the non-const spawn function for member functions
- * with 3 arguments.
+ * Overload of the non-const spawn function for member functions with 3
+ * arguments.
*
* @deprecated Use new_thread() instead.
*/
// ----------- encapsulators for functions with 4 arguments
/**
- * Overload of the spawn function for non-member or static member
- * functions with 4 arguments.
+ * Overload of the spawn function for non-member or static member functions
+ * with 4 arguments.
*
* @deprecated Use new_thread() instead.
*/
/**
- * Overload of the non-const spawn function for member functions
- * with 4 arguments.
+ * Overload of the non-const spawn function for member functions with 4
+ * arguments.
*
* @deprecated Use new_thread() instead.
*/
// ----------- encapsulators for functions with 5 arguments
/**
- * Overload of the spawn function for non-member or static member
- * functions with 5 arguments.
+ * Overload of the spawn function for non-member or static member functions
+ * with 5 arguments.
*
* @deprecated Use new_thread() instead.
*/
/**
- * Overload of the non-const spawn function for member functions
- * with 5 arguments.
+ * Overload of the non-const spawn function for member functions with 5
+ * arguments.
*
* @deprecated Use new_thread() instead.
*/
// ----------- encapsulators for functions with 6 arguments
/**
- * Overload of the spawn function for non-member or static member
- * functions with 6 arguments.
+ * Overload of the spawn function for non-member or static member functions
+ * with 6 arguments.
*
* @deprecated Use new_thread() instead.
*/
/**
- * Overload of the non-const spawn function for member functions
- * with 6 arguments.
+ * Overload of the non-const spawn function for member functions with 6
+ * arguments.
*
* @deprecated Use new_thread() instead.
*/
// ----------- encapsulators for functions with 7 arguments
/**
- * Overload of the spawn function for non-member or static member
- * functions with 7 arguments.
+ * Overload of the spawn function for non-member or static member functions
+ * with 7 arguments.
*
* @deprecated Use new_thread() instead.
*/
/**
- * Overload of the non-const spawn function for member functions
- * with 7 arguments.
+ * Overload of the non-const spawn function for member functions with 7
+ * arguments.
*
* @deprecated Use new_thread() instead.
*/
// ----------- encapsulators for functions with 8 arguments
/**
- * Overload of the spawn function for non-member or static member
- * functions with 8 arguments.
+ * Overload of the spawn function for non-member or static member functions
+ * with 8 arguments.
*
* @deprecated Use new_thread() instead.
*/
/**
- * Overload of the non-const spawn function for member functions
- * with 8 arguments.
+ * Overload of the non-const spawn function for member functions with 8
+ * arguments.
*
* @deprecated Use new_thread() instead.
*/
// ----------- encapsulators for functions with 9 arguments
/**
- * Overload of the spawn function for non-member or static member
- * functions with 9 arguments.
+ * Overload of the spawn function for non-member or static member functions
+ * with 9 arguments.
*
* @deprecated Use new_thread() instead.
*/
/**
- * Overload of the non-const spawn function for member functions
- * with 9 arguments.
+ * Overload of the non-const spawn function for member functions with 9
+ * arguments.
*
* @deprecated Use new_thread() instead.
*/
// ----------- thread starters for functions not taking any parameters
/**
- * Overload of the new_thread function for objects that can be
- * converted to std_cxx11::function<RT ()>, i.e. anything that can
- * be called like a function object without arguments and returning
- * an object of type RT (or void).
+ * Overload of the new_thread function for objects that can be converted to
+ * std_cxx11::function<RT ()>, i.e. anything that can be called like a
+ * function object without arguments and returning an object of type RT (or
+ * void).
*
* @ingroup threads
*/
}
/**
- * Overload of the new_thread function for non-member or static
- * member functions with no arguments.
+ * Overload of the new_thread function for non-member or static member
+ * functions with no arguments.
*
* @ingroup threads
*/
/**
- * Overload of the non-const new_thread function for member
- * functions with no arguments.
+ * Overload of the non-const new_thread function for member functions with
+ * no arguments.
*
* @ingroup threads
*/
#ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
/**
- * Overload of the new_thread function for const member functions
- * with no arguments.
+ * Overload of the new_thread function for const member functions with no
+ * arguments.
*
* @ingroup threads
*/
// ----------- thread starters for unary functions
/**
- * Overload of the new_thread function for non-member or static
- * member functions with 1 argument.
+ * Overload of the new_thread function for non-member or static member
+ * functions with 1 argument.
*
* @ingroup threads
*/
/**
- * Overload of the non-const new_thread function for member
- * functions with 1 argument.
+ * Overload of the non-const new_thread function for member functions with 1
+ * argument.
*
* @ingroup threads
*/
#ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
/**
- * Overload of the new_thread function for const member functions
- * with 1 argument.
+ * Overload of the new_thread function for const member functions with 1
+ * argument.
*
* @ingroup threads
*/
// ----------- thread starters for binary functions
/**
- * Overload of the new_thread function for non-member or static
- * member functions with 2 arguments.
+ * Overload of the new_thread function for non-member or static member
+ * functions with 2 arguments.
*
* @ingroup threads
*/
/**
- * Overload of the non-const new_thread function for member
- * functions with 2 arguments.
+ * Overload of the non-const new_thread function for member functions with 2
+ * arguments.
*
* @ingroup threads
*/
#ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
/**
- * Overload of the new_thread function for const member functions
- * with 2 arguments.
+ * Overload of the new_thread function for const member functions with 2
+ * arguments.
*
* @ingroup threads
*/
// ----------- thread starters for ternary functions
/**
- * Overload of the new_thread function for non-member or static
- * member functions with 3 arguments.
+ * Overload of the new_thread function for non-member or static member
+ * functions with 3 arguments.
*
* @ingroup threads
*/
/**
- * Overload of the non-const new_thread function for member
- * functions with 3 arguments.
+ * Overload of the non-const new_thread function for member functions with 3
+ * arguments.
*
* @ingroup threads
*/
#ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
/**
- * Overload of the new_thread function for const member functions
- * with 3 arguments.
+ * Overload of the new_thread function for const member functions with 3
+ * arguments.
*
* @ingroup threads
*/
// ----------- thread starters for functions with 4 arguments
/**
- * Overload of the new_thread function for non-member or static
- * member functions with 4 arguments.
+ * Overload of the new_thread function for non-member or static member
+ * functions with 4 arguments.
*
* @ingroup threads
*/
/**
- * Overload of the non-const new_thread function for member
- * functions with 4 arguments.
+ * Overload of the non-const new_thread function for member functions with 4
+ * arguments.
*
* @ingroup threads
*/
#ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
/**
- * Overload of the new_thread function for const member functions
- * with 4 arguments.
+ * Overload of the new_thread function for const member functions with 4
+ * arguments.
*
* @ingroup threads
*/
// ----------- thread starters for functions with 5 arguments
/**
- * Overload of the new_thread function for non-member or static
- * member functions with 5 arguments.
+ * Overload of the new_thread function for non-member or static member
+ * functions with 5 arguments.
*
* @ingroup threads
*/
/**
- * Overload of the non-const new_thread function for member
- * functions with 5 arguments.
+ * Overload of the non-const new_thread function for member functions with 5
+ * arguments.
*
* @ingroup threads
*/
#ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
/**
- * Overload of the new_thread function for const member functions
- * with 5 arguments.
+ * Overload of the new_thread function for const member functions with 5
+ * arguments.
*
* @ingroup threads
*/
// ----------- thread starters for functions with 6 arguments
/**
- * Overload of the new_thread function for non-member or static
- * member functions with 6 arguments.
+ * Overload of the new_thread function for non-member or static member
+ * functions with 6 arguments.
*
* @ingroup threads
*/
/**
- * Overload of the non-const new_thread function for member
- * functions with 6 arguments.
+ * Overload of the non-const new_thread function for member functions with 6
+ * arguments.
*
* @ingroup threads
*/
#ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
/**
- * Overload of the new_thread function for const member functions
- * with 6 arguments.
+ * Overload of the new_thread function for const member functions with 6
+ * arguments.
*
* @ingroup threads
*/
// ----------- thread starters for functions with 7 arguments
/**
- * Overload of the new_thread function for non-member or static
- * member functions with 7 arguments.
+ * Overload of the new_thread function for non-member or static member
+ * functions with 7 arguments.
*
* @ingroup threads
*/
/**
- * Overload of the non-const new_thread function for member
- * functions with 7 arguments.
+ * Overload of the non-const new_thread function for member functions with 7
+ * arguments.
*
* @ingroup threads
*/
#ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
/**
- * Overload of the new_thread function for const member functions
- * with 7 arguments.
+ * Overload of the new_thread function for const member functions with 7
+ * arguments.
*
* @ingroup threads
*/
// ----------- thread starters for functions with 8 arguments
/**
- * Overload of the new_thread function for non-member or static
- * member functions with 8 arguments.
+ * Overload of the new_thread function for non-member or static member
+ * functions with 8 arguments.
*
* @ingroup threads
*/
/**
- * Overload of the non-const new_thread function for member
- * functions with 8 arguments.
+ * Overload of the non-const new_thread function for member functions with 8
+ * arguments.
*
* @ingroup threads
*/
#ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
/**
- * Overload of the new_thread function for const member functions
- * with 8 arguments.
+ * Overload of the new_thread function for const member functions with 8
+ * arguments.
*
* @ingroup threads
*/
// ----------- thread starters for functions with 9 arguments
/**
- * Overload of the new_thread function for non-member or static
- * member functions with 9 arguments.
+ * Overload of the new_thread function for non-member or static member
+ * functions with 9 arguments.
*
* @ingroup threads
*/
/**
- * Overload of the non-const new_thread function for member
- * functions with 9 arguments.
+ * Overload of the non-const new_thread function for member functions with 9
+ * arguments.
*
* @ingroup threads
*/
#ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
/**
- * Overload of the new_thread function for const member functions
- * with 9 arguments.
+ * Overload of the new_thread function for const member functions with 9
+ * arguments.
*
* @ingroup threads
*/
// ------------------------ ThreadGroup -------------------------------------
/**
- * A container for thread objects. Allows to add new thread objects
- * and wait for them all together. The thread objects need to have
- * the same return value for the called function.
+ * A container for thread objects. Allows to add new thread objects and wait
+ * for them all together. The thread objects need to have the same return
+ * value for the called function.
*
* @author Wolfgang Bangerth, 2003
* @ingroup threads
{
public:
/**
- * Add another thread object to
- * the collection.
+ * Add another thread object to the collection.
*/
ThreadGroup &operator += (const Thread<RT> &t)
{
}
/**
- * Wait for all threads in the collection to finish. It is not a
- * problem if some of them have already been waited for, i.e. you
- * may call this function more than once, and you can also add new
- * thread objects between subsequent calls to this function if you
- * want.
+ * Wait for all threads in the collection to finish. It is not a problem
+ * if some of them have already been waited for, i.e. you may call this
+ * function more than once, and you can also add new thread objects
+ * between subsequent calls to this function if you want.
*/
void join_all () const
{
template <typename> struct TaskDescriptor;
/**
- * The task class for TBB that is used by the TaskDescriptor
- * class.
+ * The task class for TBB that is used by the TaskDescriptor class.
*/
template <typename RT>
struct TaskEntryPoint : public tbb::task
/**
* @internal
*
- * Base class describing a task. This is the basic class
- * abstracting the Threading Building Blocks implementation of
- * tasks. It provides a mechanism to start a new task, as well as
- * for joining it.
+ * Base class describing a task. This is the basic class abstracting the
+ * Threading Building Blocks implementation of tasks. It provides a
+ * mechanism to start a new task, as well as for joining it.
*
- * Internally, the way things are implemented is that all Task<>
- * objects keep a shared pointer to the task descriptor. When the
- * last Task<> object goes out of scope, the destructor of the
- * descriptor is called. Since tasks can not be abandoned, the
- * destructor makes sure that the task is finished before it can
- * continue to destroy the object.
+ * Internally, the way things are implemented is that all Task<> objects
+ * keep a shared pointer to the task descriptor. When the last Task<>
+ * object goes out of scope, the destructor of the descriptor is called.
+ * Since tasks can not be abandoned, the destructor makes sure that the
+ * task is finished before it can continue to destroy the object.
*
- * Note that unlike threads, tasks are not always started right
- * away, and so the starting thread can't rely on the fact that
- * the started task can copy things off the spawning thread's
- * stack frame. As a consequence, the task description needs to
- * include a way to store the function and its arguments that
- * shall be run on the task.
+ * Note that unlike threads, tasks are not always started right away, and
+ * so the starting thread can't rely on the fact that the started task can
+ * copy things off the spawning thread's stack frame. As a consequence,
+ * the task description needs to include a way to store the function and
+ * its arguments that shall be run on the task.
*
* @author Wolfgang Bangerth, 2009
*/
{
private:
/**
- * The function and its arguments that are to be run on the
- * task.
+ * The function and its arguments that are to be run on the task.
*/
std_cxx11::function<RT ()> function;
/**
- * Variable holding the data the TBB needs to work with a
- * task. Set by the queue_up_task() function. Note that the
- * object behind this pointer will be deleted upon termination
- * of the task, so we do not have to do so ourselves. In
- * particular, if all objects with pointers to this
- * task_description object go out of scope then no action is
+ * Variable holding the data the TBB needs to work with a task. Set by
+ * the queue_up_task() function. Note that the object behind this
+ * pointer will be deleted upon termination of the task, so we do not
+ * have to do so ourselves. In particular, if all objects with pointers
+ * to this task_description object go out of scope then no action is
* needed on our behalf.
*/
tbb::task *task;
public:
/**
- * Constructor. Take the function to be run on this task as
- * argument.
+ * Constructor. Take the function to be run on this task as argument.
*/
TaskDescriptor (const std_cxx11::function<RT ()> &function);
/**
- * Default constructor. Throws an exception since we want to
- * queue a task immediately upon construction of these objects
- * to make sure that each TaskDescriptor object corresponds to
- * exactly one task.
+ * Default constructor. Throws an exception since we want to queue a
+ * task immediately upon construction of these objects to make sure that
+ * each TaskDescriptor object corresponds to exactly one task.
*/
TaskDescriptor ();
/**
- * Copy constructor. Throws an exception since we want to make
- * sure that each TaskDescriptor object corresponds to exactly
- * one task.
+ * Copy constructor. Throws an exception since we want to make sure that
+ * each TaskDescriptor object corresponds to exactly one task.
*/
TaskDescriptor (const TaskDescriptor &);
~TaskDescriptor ();
/**
- * Queue up the task to the scheduler. We need to do this in a
- * separate function since the new tasks needs to access objects
- * from the current object and that can only reliably happen if
- * the current object is completely constructed already.
+ * Queue up the task to the scheduler. We need to do this in a separate
+ * function since the new tasks needs to access objects from the current
+ * object and that can only reliably happen if the current object is
+ * completely constructed already.
*/
void queue_task ();
/**
- * Join a task, i.e. wait for it to finish. This function can
- * safely be called from different threads at the same time, and
- * can also be called more than once.
+ * Join a task, i.e. wait for it to finish. This function can safely be
+ * called from different threads at the same time, and can also be
+ * called more than once.
*/
void join ();
#else // no threading enabled
/**
- * A way to describe tasks. Since we are in non-MT mode at this
- * place, things are a lot simpler than in MT mode.
+ * A way to describe tasks. Since we are in non-MT mode at this place,
+ * things are a lot simpler than in MT mode.
*/
template <typename RT>
struct TaskDescriptor
return_value<RT> ret_val;
/**
- * Constructor. Call the given function and emplace the return
- * value into the slot reserved for this purpose.
+ * Constructor. Call the given function and emplace the return value
+ * into the slot reserved for this purpose.
*/
TaskDescriptor (const std_cxx11::function<RT ()> &function)
{
}
/**
- * Wait for the task to return. Since we are in non-MT mode
- * here, there is nothing to do.
+ * Wait for the task to return. Since we are in non-MT mode here, there
+ * is nothing to do.
*/
static void join () {}
/**
- * Run the task. Since we are here in non-MT mode, there is
- * nothing to do that the constructor hasn't already done.
+ * Run the task. Since we are here in non-MT mode, there is nothing to
+ * do that the constructor hasn't already done.
*/
static void queue_task () {}
};
/**
- * Describes one task object based on the Threading Building Blocks'
- * Task. Note that the call to join() must be executed on the same
- * thread as the call to the constructor. Otherwise, there might be
- * a deadlock. In other words, a Task object should never passed on
- * to another task for calling the join() method.
+ * Describes one task object based on the Threading Building Blocks' Task.
+ * Note that the call to join() must be executed on the same thread as the
+ * call to the constructor. Otherwise, there might be a deadlock. In other
+ * words, a Task object should never passed on to another task for calling
+ * the join() method.
*
* @author Wolfgang Bangerth, 2009
* @ingroup threads
{
public:
/**
- * Construct a task object given a function object to execute on
- * the task, and then schedule this function for execution.
+ * Construct a task object given a function object to execute on the task,
+ * and then schedule this function for execution.
*
- * @post Using this constructor automatically makes the task
- * object joinable().
+ * @post Using this constructor automatically makes the task object
+ * joinable().
*/
Task (const std_cxx11::function<RT ()> &function_object)
{
/**
* Copy constructor.
*
- * @post Using this constructor automatically makes the task
- * object joinable().
+ * @post Using this constructor automatically makes the task object
+ * joinable().
*/
Task (const Task<RT> &t)
:
/**
- * Default constructor. You can't do much with a task object
- * constructed this way, except for assigning it a task object
- * that holds data created by the Threads::new_task() functions.
+ * Default constructor. You can't do much with a task object constructed
+ * this way, except for assigning it a task object that holds data created
+ * by the Threads::new_task() functions.
*
- * @post Using this constructor leaves the object in an unjoinable
- * state, i.e., joinable() will return false.
+ * @post Using this constructor leaves the object in an unjoinable state,
+ * i.e., joinable() will return false.
*/
Task () {}
/**
- * Join the task represented by this object, i.e. wait for it to
- * finish.
+ * Join the task represented by this object, i.e. wait for it to finish.
*
* A task can be joined multiple times (while the first join() operation
* may block until the task has completed running, all successive attempts
* to join will return immediately).
*
* @pre You can't call this function if you have used the default
- * constructor of this class and have not assigned a task object
- * to it. In other words, the function joinable() must return
- * true.
+ * constructor of this class and have not assigned a task object to it. In
+ * other words, the function joinable() must return true.
*/
void join () const
{
}
/**
- * Return whether the current object can be joined. You can join a
- * task object once a task (typically created with
- * Threads::new_task()) has actually been assigned to it. On the
- * other hand, the function returns false if the object has been
- * default constructed.
+ * Return whether the current object can be joined. You can join a task
+ * object once a task (typically created with Threads::new_task()) has
+ * actually been assigned to it. On the other hand, the function returns
+ * false if the object has been default constructed.
*
* A task can be joined multiple times (while the first join() operation
* may block until the task has completed running, all successive attempts
/**
- * Get the return value of the function of the task. Since this is
- * only available once the task finishes, this implicitly also
- * calls join(). You can call this function multiple times
- * as long as the object refers to the same task, and expect to get
- * the same return value every time.
+ * Get the return value of the function of the task. Since this is only
+ * available once the task finishes, this implicitly also calls join().
+ * You can call this function multiple times as long as the object refers
+ * to the same task, and expect to get the same return value every time.
*
* @pre You can't call this function if you have used the default
- * constructor of this class and have not assigned a task object
- * to it. In other words, the function joinable() must return
- * true.
+ * constructor of this class and have not assigned a task object to it. In
+ * other words, the function joinable() must return true.
*/
RT return_value ()
{
/**
- * Check for equality of task objects. Since objects of this class
- * store an implicit pointer to an object that exists exactly once
- * for each task, the check is simply to compare these pointers.
+ * Check for equality of task objects. Since objects of this class store
+ * an implicit pointer to an object that exists exactly once for each
+ * task, the check is simply to compare these pointers.
*/
bool operator == (const Task &t)
{
return task_descriptor == t.task_descriptor;
}
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
//@}
private:
/**
- * Shared pointer to the object representing the task. Boost's
- * shared pointer implementation will make sure that that object
- * lives as long as there is at least one subscriber to it.
+ * Shared pointer to the object representing the task. Boost's shared
+ * pointer implementation will make sure that that object lives as long as
+ * there is at least one subscriber to it.
*/
std_cxx11::shared_ptr<internal::TaskDescriptor<RT> > task_descriptor;
};
/**
- * Overload of the new_task function for objects that can be
- * converted to std_cxx11::function<RT ()>, i.e. anything that can
- * be called like a function object without arguments and returning
- * an object of type RT (or void).
+ * Overload of the new_task function for objects that can be converted to
+ * std_cxx11::function<RT ()>, i.e. anything that can be called like a
+ * function object without arguments and returning an object of type RT (or
+ * void).
*
* @ingroup threads
*/
/**
- * Overload of the non-const new_task function for member functions
- * with no arguments.
+ * Overload of the non-const new_task function for member functions with no
+ * arguments.
*
* @ingroup threads
*/
#ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
/**
- * Overload of the new_task function for const member functions with
- * no arguments.
+ * Overload of the new_task function for const member functions with no
+ * arguments.
*
* @ingroup threads
*/
/**
- * Overload of the non-const new_task function for member functions
- * with 1 argument.
+ * Overload of the non-const new_task function for member functions with 1
+ * argument.
*
* @ingroup threads
*/
#ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
/**
- * Overload of the new_task function for const member functions with
- * 1 argument.
+ * Overload of the new_task function for const member functions with 1
+ * argument.
*
* @ingroup threads
*/
/**
- * Overload of the non-const new_task function for member functions
- * with 2 arguments.
+ * Overload of the non-const new_task function for member functions with 2
+ * arguments.
*
* @ingroup threads
*/
#ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
/**
- * Overload of the new_task function for const member functions with
- * 2 arguments.
+ * Overload of the new_task function for const member functions with 2
+ * arguments.
*
* @ingroup threads
*/
/**
- * Overload of the non-const new_task function for member functions
- * with 3 arguments.
+ * Overload of the non-const new_task function for member functions with 3
+ * arguments.
*
* @ingroup threads
*/
#ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
/**
- * Overload of the new_task function for const member functions with
- * 3 arguments.
+ * Overload of the new_task function for const member functions with 3
+ * arguments.
*
* @ingroup threads
*/
/**
- * Overload of the non-const new_task function for member functions
- * with 4 arguments.
+ * Overload of the non-const new_task function for member functions with 4
+ * arguments.
*
* @ingroup threads
*/
#ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
/**
- * Overload of the new_task function for const member functions with
- * 4 arguments.
+ * Overload of the new_task function for const member functions with 4
+ * arguments.
*
* @ingroup threads
*/
/**
- * Overload of the non-const new_task function for member functions
- * with 5 arguments.
+ * Overload of the non-const new_task function for member functions with 5
+ * arguments.
*
* @ingroup threads
*/
#ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
/**
- * Overload of the new_task function for const member functions with
- * 5 arguments.
+ * Overload of the new_task function for const member functions with 5
+ * arguments.
*
* @ingroup threads
*/
/**
- * Overload of the non-const new_task function for member functions
- * with 6 arguments.
+ * Overload of the non-const new_task function for member functions with 6
+ * arguments.
*
* @ingroup threads
*/
#ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
/**
- * Overload of the new_task function for const member functions with
- * 6 arguments.
+ * Overload of the new_task function for const member functions with 6
+ * arguments.
*
* @ingroup threads
*/
/**
- * Overload of the non-const new_task function for member functions
- * with 7 arguments.
+ * Overload of the non-const new_task function for member functions with 7
+ * arguments.
*
* @ingroup threads
*/
#ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
/**
- * Overload of the new_task function for const member functions with
- * 7 arguments.
+ * Overload of the new_task function for const member functions with 7
+ * arguments.
*
* @ingroup threads
*/
/**
- * Overload of the non-const new_task function for member functions
- * with 8 arguments.
+ * Overload of the non-const new_task function for member functions with 8
+ * arguments.
*
* @ingroup threads
*/
#ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
/**
- * Overload of the new_task function for const member functions with
- * 8 arguments.
+ * Overload of the new_task function for const member functions with 8
+ * arguments.
*
* @ingroup threads
*/
/**
- * Overload of the non-const new_task function for member functions
- * with 9 arguments.
+ * Overload of the non-const new_task function for member functions with 9
+ * arguments.
*
* @ingroup threads
*/
#ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
/**
- * Overload of the new_task function for const member functions with
- * 9 arguments.
+ * Overload of the new_task function for const member functions with 9
+ * arguments.
*
* @ingroup threads
*/
// ------------------------ TaskGroup -------------------------------------
/**
- * A container for task objects. Allows to add new task objects and
- * wait for them all together. The task objects need to have the
- * same return value for the called function.
+ * A container for task objects. Allows to add new task objects and wait for
+ * them all together. The task objects need to have the same return value
+ * for the called function.
*
- * Note that the call to join_all() must be executed on the same
- * thread as the calls that add subtasks. Otherwise, there might be
- * a deadlock. In other words, a Task object should never passed on
- * to another task for calling the join() method.
+ * Note that the call to join_all() must be executed on the same thread as
+ * the calls that add subtasks. Otherwise, there might be a deadlock. In
+ * other words, a Task object should never passed on to another task for
+ * calling the join() method.
*
* @author Wolfgang Bangerth, 2003
* @ingroup tasks
{
public:
/**
- * Add another task object to
- * the collection.
+ * Add another task object to the collection.
*/
TaskGroup &operator += (const Task<RT> &t)
{
}
/**
- * Wait for all tasks in the collection to finish. It is not a
- * problem if some of them have already been waited for, i.e. you
- * may call this function more than once, and you can also add new
- * task objects between subsequent calls to this function if you
- * want.
+ * Wait for all tasks in the collection to finish. It is not a problem if
+ * some of them have already been waited for, i.e. you may call this
+ * function more than once, and you can also add new task objects between
+ * subsequent calls to this function if you want.
*/
void join_all () const
{
namespace TimeStepping
{
/**
- * Runge-Kutta methods available:
- * - Explicit methods:
- * - FORWARD_EULER: first order
- * - RK_THIRD_ORDER: third order Runge-Kutta
- * - RK_CLASSIC_FOURTH_ORDER: classical fourth order Runge-Kutta
- * - Implicit methods:
- * - BACKWARD_EULER: first order
- * - IMPLICIT_MIDPOINT: second order
- * - CRANK_NICOLSON: second order
- * - SDIRK_TWO_STAGES: second order
- * - Embedded explicit methods:
- * - HEUN_EULER: second order
- * - BOGACKI_SHAMPINE: third order
- * - DOPRI: Dormand-Prince fifth order (method used by ode45 in MATLAB)
- * - FEHLBERG: fifth order
- * - CASH_KARP: firth order
+ * Runge-Kutta methods available: - Explicit methods: - FORWARD_EULER: first
+ * order - RK_THIRD_ORDER: third order Runge-Kutta -
+ * RK_CLASSIC_FOURTH_ORDER: classical fourth order Runge-Kutta - Implicit
+ * methods: - BACKWARD_EULER: first order - IMPLICIT_MIDPOINT: second order
+ * - CRANK_NICOLSON: second order - SDIRK_TWO_STAGES: second order -
+ * Embedded explicit methods: - HEUN_EULER: second order - BOGACKI_SHAMPINE:
+ * third order - DOPRI: Dormand-Prince fifth order (method used by ode45 in
+ * MATLAB) - FEHLBERG: fifth order - CASH_KARP: firth order
*/
enum runge_kutta_method { FORWARD_EULER, RK_THIRD_ORDER, RK_CLASSIC_FOURTH_ORDER,
BACKWARD_EULER, IMPLICIT_MIDPOINT, CRANK_NICOLSON,
/**
- * Reason for exiting evolve_one_time_step when using an embedded
- * method: DELTA_T (the time step is in the valid range), MIN_DELTA_T (the
- * time step was increased to the minimum acceptable time step), MAX_DELTA_T
- * (the time step was reduced to the maximum acceptable time step).
+ * Reason for exiting evolve_one_time_step when using an embedded method:
+ * DELTA_T (the time step is in the valid range), MIN_DELTA_T (the time step
+ * was increased to the minimum acceptable time step), MAX_DELTA_T (the time
+ * step was reduced to the maximum acceptable time step).
*/
enum embedded_runge_kutta_time_step { DELTA_T, MIN_DELTA_T, MAX_DELTA_T };
/**
* Purely virtual function. This function is used to advance from time @p
- * t to t+ @p delta_t. @p F is a vector of functions $ f(t,y) $ that should be
- * integrated, the input parameters are the time t and the vector y and the
- * output is value of f at this point. @p J_inverse is a vector
- * functions that compute the inverse of the Jacobians associated to the
- * implicit problems. The input parameters are the
- * time, $ \tau $, and a vector. The output is the value of function
- * at this point. This function returns the time at the end of the
- * time step.
+ * t to t+ @p delta_t. @p F is a vector of functions $ f(t,y) $ that
+ * should be integrated, the input parameters are the time t and the
+ * vector y and the output is value of f at this point. @p J_inverse is a
+ * vector functions that compute the inverse of the Jacobians associated
+ * to the implicit problems. The input parameters are the time, $ \tau $,
+ * and a vector. The output is the value of function at this point. This
+ * function returns the time at the end of the time step.
*/
virtual double evolve_one_time_step(
std::vector<std_cxx11::function<VECTOR (const double, const VECTOR &)> > &F,
*/
virtual void initialize(runge_kutta_method method) = 0;
/**
- * This function is used to advance from time @p
- * t to t+ @p delta_t. @p F is a vector of functions $ f(t,y) $ that should be
- * integrated, the input parameters are the time t and the vector y and the
- * output is value of f at this point. @p J_inverse is a vector
- * functions that compute the inverse of the Jacobians associated to the
- * implicit problems. The input parameters are the
- * time, $ \tau $, and a vector. The output is the value of function
- * at this point. This function returns the time at the end of the
- * time step. When using Runge-Kutta methods, @p F and @ J_inverse can
- * only contain one element.
+ * This function is used to advance from time @p t to t+ @p delta_t. @p F
+ * is a vector of functions $ f(t,y) $ that should be integrated, the
+ * input parameters are the time t and the vector y and the output is
+ * value of f at this point. @p J_inverse is a vector functions that
+ * compute the inverse of the Jacobians associated to the implicit
+ * problems. The input parameters are the time, $ \tau $, and a vector.
+ * The output is the value of function at this point. This function
+ * returns the time at the end of the time step. When using Runge-Kutta
+ * methods, @p F and @ J_inverse can only contain one element.
*/
double evolve_one_time_step(
std::vector<std_cxx11::function<VECTOR (const double, const VECTOR &)> > &F,
VECTOR &y);
/**
- * Purely virtual function. This function is used to advance from time @p t
- * to t+ @p delta_t. @p f is the function $ f(t,y) $ that should be
- * integrated, the input parameters are the time t and the vector y and the
- * output is value of f at this point. @p id_minus_tau_J_inverse is a function
- * that computes $ inv(I-\tau J)$ where $ I $ is the identity matrix,
- * $ \tau $ is given, and $ J $ is the Jacobian $ \frac{\partial
- * J}{\partial y} $. The input parameters are the time, $ \tau $, and
- * a vector. The output is the value of function at this point.
+ * Purely virtual function. This function is used to advance from time @p
+ * t to t+ @p delta_t. @p f is the function $ f(t,y) $ that should be
+ * integrated, the input parameters are the time t and the vector y and
+ * the output is value of f at this point. @p id_minus_tau_J_inverse is a
+ * function that computes $ inv(I-\tau J)$ where $ I $ is the identity
+ * matrix, $ \tau $ is given, and $ J $ is the Jacobian $ \frac{\partial
+ * J}{\partial y} $. The input parameters are the time, $ \tau $, and a
+ * vector. The output is the value of function at this point.
* evolve_one_time_step returns the time at the end of the time step.
*/
virtual double evolve_one_time_step(
/**
- * ExplicitRungeKutta is derived from RungeKutta and implement the explicit methods.
+ * ExplicitRungeKutta is derived from RungeKutta and implement the explicit
+ * methods.
*/
template <typename VECTOR>
class ExplicitRungeKutta : public RungeKutta<VECTOR>
/**
* This function is used to advance from time @p t to t+ @p delta_t. @p f
* is the function $ f(t,y) $ that should be integrated, the input
- * parameters are the time t and the vector y and the output is value of
- * f at this point. @p id_minus_tau_J_inverse is a function that computes
- * $ inv(I-\tau J)$ where $ I $ is the identity matrix, $ \tau
- * $ is given, and $ J $ is the Jacobian $ \frac{\partial
- * J}{\partial y} $. The input parameter are the time, $ \tau $, and
- * a vector. The output is the value of function at this point.
- * evolve_one_time_step returns the time at the end of the time step.
+ * parameters are the time t and the vector y and the output is value of f
+ * at this point. @p id_minus_tau_J_inverse is a function that computes $
+ * inv(I-\tau J)$ where $ I $ is the identity matrix, $ \tau $ is given,
+ * and $ J $ is the Jacobian $ \frac{\partial J}{\partial y} $. The input
+ * parameter are the time, $ \tau $, and a vector. The output is the value
+ * of function at this point. evolve_one_time_step returns the time at the
+ * end of the time step.
*/
double evolve_one_time_step(
std_cxx11::function<VECTOR (const double, const VECTOR &)> f,
VECTOR &y);
/**
- * This function is used to advance from time @p t to t+ @p delta_t.
- * This function is similar to the one derived from RungeKutta, but
- * does not required id_minus_tau_J_inverse because it is not used for
- * explicit methods. evolve_one_time_step returns the time at the end of the
- * time step.
+ * This function is used to advance from time @p t to t+ @p delta_t. This
+ * function is similar to the one derived from RungeKutta, but does not
+ * required id_minus_tau_J_inverse because it is not used for explicit
+ * methods. evolve_one_time_step returns the time at the end of the time
+ * step.
*/
double evolve_one_time_step(std_cxx11::function<VECTOR (const double, const VECTOR &)> f,
double t,
/**
- * This class is derived from RungeKutta and implement the implicit
- * methods. This class works only for Diagonal Implicit Runge-Kutta
- * (DIRK) methods.
+ * This class is derived from RungeKutta and implement the implicit methods.
+ * This class works only for Diagonal Implicit Runge-Kutta (DIRK) methods.
*/
template <typename VECTOR>
class ImplicitRungeKutta : public RungeKutta<VECTOR>
/**
* Default constructor. initialize(runge_kutta_method) and
- * set_newton_solver_parameters(unsigned int,double)
- * need to be called before the object can be used.
+ * set_newton_solver_parameters(unsigned int,double) need to be called
+ * before the object can be used.
*/
ImplicitRungeKutta() {};
/**
* This function is used to advance from time @p t to t+ @p delta_t. @p f
* is the function $ f(t,y) $ that should be integrated, the input
- * parameters are the time t and the vector y and the output is value of
- * f at this point. @p id_minus_tau_J_inverse is a function that computes
- * $ (I-\tau J)^{-1}$ where $ I $ is the identity matrix, $ \tau $
- * is given, and $ J $ is the Jacobian $ \frac{\partial
- * J}{\partial y} $. The input parameters this function receives
- * are the time, $ \tau $, and
- * a vector. The output is the value of function at this point.
- * evolve_one_time_step returns the time at the end of the time step.
+ * parameters are the time t and the vector y and the output is value of f
+ * at this point. @p id_minus_tau_J_inverse is a function that computes $
+ * (I-\tau J)^{-1}$ where $ I $ is the identity matrix, $ \tau $ is given,
+ * and $ J $ is the Jacobian $ \frac{\partial J}{\partial y} $. The input
+ * parameters this function receives are the time, $ \tau $, and a vector.
+ * The output is the value of function at this point. evolve_one_time_step
+ * returns the time at the end of the time step.
*/
double evolve_one_time_step(
std_cxx11::function<VECTOR (const double, const VECTOR &)> f,
void set_newton_solver_parameters(unsigned int max_it, double tolerance);
/**
- * Structure that stores the name of the method, the number of
- * Newton iterations and the norm of the residual when exiting the
- * Newton solver.
+ * Structure that stores the name of the method, the number of Newton
+ * iterations and the norm of the residual when exiting the Newton solver.
*/
struct Status : public TimeStepping<VECTOR>::Status
{
VECTOR &residual) const;
/**
- * When using SDIRK, there is no need to compute the linear combination
- * of the stages. Thus, when this flag is true, the linear combination
- * is skipped.
+ * When using SDIRK, there is no need to compute the linear combination of
+ * the stages. Thus, when this flag is true, the linear combination is
+ * skipped.
*/
bool skip_linear_combi;
/**
* Default constructor. initialize(runge_kutta_method) and
- * set_time_adaptation_parameters(double, double, double, double, double, double)
- * need to be called before the object can be used.
+ * set_time_adaptation_parameters(double, double, double, double, double,
+ * double) need to be called before the object can be used.
*/
EmbeddedExplicitRungeKutta() {};
/**
* This function is used to advance from time @p t to t+ @p delta_t. @p f
* is the function $ f(t,y) $ that should be integrated, the input
- * parameters are the time t and the vector y and the output is value of
- * f at this point. @p id_minus_tau_J_inverse is a function that computes
- * $ inv(I-\tau J)$ where $ I $ is the identity matrix, $ \tau
- * $ is given, and $ J $ is the Jacobian $ \frac{\partial
- * J}{\partial y} $. The input parameters are the time, $ \tau $, and
- * a vector. The output is the value of function at this point.
- * evolve_one_time_step returns the time at the end of the time step.
+ * parameters are the time t and the vector y and the output is value of f
+ * at this point. @p id_minus_tau_J_inverse is a function that computes $
+ * inv(I-\tau J)$ where $ I $ is the identity matrix, $ \tau $ is given,
+ * and $ J $ is the Jacobian $ \frac{\partial J}{\partial y} $. The input
+ * parameters are the time, $ \tau $, and a vector. The output is the
+ * value of function at this point. evolve_one_time_step returns the time
+ * at the end of the time step.
*/
double evolve_one_time_step(
std_cxx11::function<VECTOR (const double, const VECTOR &)> f,
VECTOR &y);
/**
- * This function is used to advance from time @p t to t+ @p delta_t.
- * This function is similar to the one derived from TimeStepping, but
- * does not required id_minus_tau_J_inverse because it is not used for
- * explicit methods. evolve_one_time_step returns the time at the end of the
- * time step.
+ * This function is used to advance from time @p t to t+ @p delta_t. This
+ * function is similar to the one derived from TimeStepping, but does not
+ * required id_minus_tau_J_inverse because it is not used for explicit
+ * methods. evolve_one_time_step returns the time at the end of the time
+ * step.
*/
double evolve_one_time_step(std_cxx11::function<VECTOR (const double, const VECTOR &)> f,
double t,
/**
* Structure that stores the name of the method, the reason to exit
- * evolve_one_time_step, the number of iteration inside n_iterations, a guess
- * of what the next time step should be, and an estimate of the norm of
- * the error.
+ * evolve_one_time_step, the number of iteration inside n_iterations, a
+ * guess of what the next time step should be, and an estimate of the norm
+ * of the error.
*/
struct Status : public TimeStepping<VECTOR>::Status
{
std::vector<VECTOR> &f_stages);
/**
- * This parameter is the factor (>1) by which the time step is
- * multiplied when the time stepping can be coarsen.
+ * This parameter is the factor (>1) by which the time step is multiplied
+ * when the time stepping can be coarsen.
*/
double coarsen_param;
/**
- * This parameter is the factor (<1) by which the time step is
- * multiplied when the time stepping must be refined.
+ * This parameter is the factor (<1) by which the time step is multiplied
+ * when the time stepping must be refined.
*/
double refine_param;
double max_delta_t;
/**
- * Refinement tolerance: if the error estimate is larger than
- * refine_tol, the time step is refined.
+ * Refinement tolerance: if the error estimate is larger than refine_tol,
+ * the time step is refined.
*/
double refine_tol;
/**
- * Coarsening tolerance: if the error estimate is smaller than
- * coarse_tol, the time step is coarsen.
+ * Coarsening tolerance: if the error estimate is smaller than coarse_tol,
+ * the time step is coarsen.
*/
double coarsen_tol;
/**
- * If the flag is true, the last stage is the same as the first stage
- * and one evaluation of f can be saved.
+ * If the flag is true, the last stage is the same as the first stage and
+ * one evaluation of f can be saved.
*/
bool last_same_as_first;
std::vector<double> b2;
/**
- * If the last_same_as_first flag is set to true, the last stage is
- * saved and reused as the first stage of the next time step.
+ * If the last_same_as_first flag is set to true, the last stage is saved
+ * and reused as the first stage of the next time step.
*/
VECTOR *last_stage;
/**
* This is a very simple class which provides information about both the CPU
- * time and the wallclock time elapsed since the timer was started last
- * time. Information is retrieved from the system on the basis of clock cycles
- * since last time the computer was booted for the CPU time. The wall time is
- * based on the system clock accessed by @p gettimeofday, with a typical
- * accuracy of 0.01 ms on linux systems.
+ * time and the wallclock time elapsed since the timer was started last time.
+ * Information is retrieved from the system on the basis of clock cycles since
+ * last time the computer was booted for the CPU time. The wall time is based
+ * on the system clock accessed by @p gettimeofday, with a typical accuracy of
+ * 0.01 ms on linux systems.
*
*
* <h3>Usage</h3>
* timer.reset();
* @endcode
*
- * Alternatively, you can also restart the timer instead of resetting
- * it. The times between successive calls to start() / stop() will then be
- * accumulated. The usage of this class is also explained in the
- * step-28, step-29 and step-30 tutorial programs.
+ * Alternatively, you can also restart the timer instead of resetting it. The
+ * times between successive calls to start() / stop() will then be
+ * accumulated. The usage of this class is also explained in the step-28,
+ * step-29 and step-30 tutorial programs.
*
* @note Implementation of this class is system dependent. In case
* multithreaded routines (matrix-vector products, error estimators, etc.) are
#ifdef DEAL_II_WITH_MPI
/**
- * Constructor that takes an MPI
- * communicator as input. A timer
- * constructed this way will sum up the
- * CPU times over all processors in the
- * MPI network when requested by the
- * operator ().
+ * Constructor that takes an MPI communicator as input. A timer constructed
+ * this way will sum up the CPU times over all processors in the MPI network
+ * when requested by the operator ().
*
* Starts the timer at 0 sec.
*
- * If @p sync_wall_time is true, the wall
- * time is synchronized between all CPUs
- * using a MPI_Barrier() and a collective
- * operation. Note that this only works
- * if you stop() the timer before
- * querying for the wall time. The time
- * for the MPI operations are not
- * included in the timing but may slow
+ * If @p sync_wall_time is true, the wall time is synchronized between all
+ * CPUs using a MPI_Barrier() and a collective operation. Note that this
+ * only works if you stop() the timer before querying for the wall time. The
+ * time for the MPI operations are not included in the timing but may slow
* down your program.
*
- * This constructor is only available
- * if the deal.II compiler is an MPI
+ * This constructor is only available if the deal.II compiler is an MPI
* compiler.
*/
Timer (MPI_Comm mpi_communicator,
const bool sync_wall_time = false);
/**
- * Returns a reference to the data
- * structure with global timing
- * information. Filled after calling
- * stop().
+ * Returns a reference to the data structure with global timing information.
+ * Filled after calling stop().
*/
const Utilities::MPI::MinMaxAvg &get_data() const;
#endif
/**
- * Re-start the timer at the point where
- * it was stopped. This way a cumulative
- * measurement of time is possible.
+ * Re-start the timer at the point where it was stopped. This way a
+ * cumulative measurement of time is possible.
*/
void start ();
/**
- * Sets the current time as next
- * starting time and return the
- * elapsed time in seconds.
+ * Sets the current time as next starting time and return the elapsed time
+ * in seconds.
*/
double stop ();
/**
- * Stop the timer if necessary and reset
- * the elapsed time to zero.
+ * Stop the timer if necessary and reset the elapsed time to zero.
*/
void reset ();
/**
- * Resets the elapsed time to zero and
- * starts the timer. This corresponds to
- * calling @p reset() and @p start() on
- * the Timer object.
+ * Resets the elapsed time to zero and starts the timer. This corresponds to
+ * calling @p reset() and @p start() on the Timer object.
*/
void restart();
/**
- * Access to the current CPU time
- * without disturbing time
- * measurement. The elapsed time is
- * returned in units of seconds.
+ * Access to the current CPU time without disturbing time measurement. The
+ * elapsed time is returned in units of seconds.
*/
double operator() () const;
/**
- * Access to the current wall time
- * without disturbing time
- * measurement. The elapsed time is
- * returned in units of seconds.
+ * Access to the current wall time without disturbing time measurement. The
+ * elapsed time is returned in units of seconds.
*/
double wall_time () const;
/**
- * Returns the last lap time; the
- * time taken between the last start()/stop()
+ * Returns the last lap time; the time taken between the last start()/stop()
* call.
*/
double get_lap_time () const;
private:
/**
- * Value of the user time when start()
- * was called the last time or when the
- * object was created and no stop() was
- * issued in between.
+ * Value of the user time when start() was called the last time or when the
+ * object was created and no stop() was issued in between.
*/
double start_time;
/**
- * Similar to #start_time, but
- * needed for children threads
- * in multithread mode. Value of
- * the user time when start()
- * was called the last time or
- * when the object was created
- * and no stop() was issued in
- * between.
+ * Similar to #start_time, but needed for children threads in multithread
+ * mode. Value of the user time when start() was called the last time or
+ * when the object was created and no stop() was issued in between.
*
- * For some reason (error in
- * operating system?) the
- * function call
- * <tt>getrusage(RUSAGE_CHILDREN,.)</tt>
- * gives always 0 (at least
- * on Solaris7). Hence the
- * Timer class still does not
- * yet work for multithreading
- * mode.
+ * For some reason (error in operating system?) the function call
+ * <tt>getrusage(RUSAGE_CHILDREN,.)</tt> gives always 0 (at least on
+ * Solaris7). Hence the Timer class still does not yet work for
+ * multithreading mode.
*/
double start_time_children;
/**
- * Value of the wall time when start()
- * was called the last time or when the
- * object was created and no stop() was
- * issued in between.
+ * Value of the wall time when start() was called the last time or when the
+ * object was created and no stop() was issued in between.
*/
double start_wall_time;
/**
- * Accumulated time for all previous
- * start()/stop() cycles. The time for
- * the present cycle is not included.
+ * Accumulated time for all previous start()/stop() cycles. The time for the
+ * present cycle is not included.
*/
double cumulative_time;
/**
- * Accumulated wall time for all
- * previous start()/stop() cycles. The
- * wall time for the present cycle is
- * not included.
+ * Accumulated wall time for all previous start()/stop() cycles. The wall
+ * time for the present cycle is not included.
*/
double cumulative_wall_time;
/**
- * Stores the last lap time; the time
- * between the last start()/stop() cycle.
+ * Stores the last lap time; the time between the last start()/stop() cycle.
*/
double last_lap_time;
/**
- * Store whether the timer is presently
- * running.
+ * Store whether the timer is presently running.
*/
bool running;
/**
- * Store whether the timer is presently
- * running.
+ * Store whether the timer is presently running.
*/
MPI_Comm mpi_communicator;
#ifdef DEAL_II_WITH_MPI
/**
- * Store whether the wall time is
- * synchronized between machines.
+ * Store whether the wall time is synchronized between machines.
*/
bool sync_wall_time;
/**
- * A structure for parallel wall time
- * measurement that includes the minimum
- * time recorded among all processes, the
- * maximum time as well as the average
- * time defined as the sum of all
- * individual times divided by the number
- * of MPI processes in the MPI_Comm.
+ * A structure for parallel wall time measurement that includes the minimum
+ * time recorded among all processes, the maximum time as well as the
+ * average time defined as the sum of all individual times divided by the
+ * number of MPI processes in the MPI_Comm.
*/
Utilities::System::MinMaxAvg mpi_data;
#endif
//TODO: The following class is not thread-safe
/**
- * This class can be used to generate formatted output from time
- * measurements of different subsections in a program. It is possible to
- * create several sections that perform certain aspects of the program. A
- * section can be entered several times. By changing the options in
- * OutputFrequency and OutputType, the user can choose whether output should
- * be generated every time a section is joined or just in the end of the
- * program. Moreover, it is possible to show CPU times, wall times or both.
+ * This class can be used to generate formatted output from time measurements
+ * of different subsections in a program. It is possible to create several
+ * sections that perform certain aspects of the program. A section can be
+ * entered several times. By changing the options in OutputFrequency and
+ * OutputType, the user can choose whether output should be generated every
+ * time a section is joined or just in the end of the program. Moreover, it is
+ * possible to show CPU times, wall times or both.
*
* <h3>Usage</h3>
*
* | Setup dof system | 1 | 3.97s | 4.5% |
* +---------------------------------+-----------+------------+------------+
* @endcode
- * The output will see that we entered the assembly and solve section
- * twice, and reports how much time we spent there. Moreover, the class
- * measures the total time spent from start to termination of the TimerOutput
- * object. In this case, we did a lot of other stuff, so that the time
- * proportions of the functions we measured are far away from 100 precent.
+ * The output will see that we entered the assembly and solve section twice,
+ * and reports how much time we spent there. Moreover, the class measures the
+ * total time spent from start to termination of the TimerOutput object. In
+ * this case, we did a lot of other stuff, so that the time proportions of the
+ * functions we measured are far away from 100 precent.
*
*
* <h3>Using scoped timers</h3>
* awkward if the sections in between these calls contain <code>return</code>
* statements or may throw exceptions. In that case, it is easy to forget that
* one nevertheless needs to leave the section somehow, somewhere. An easier
- * approach is to use "scoped" sections. This is a variable that when you create
- * it enters a section, and leaves the section when you destroy it. If this is
- * a variable local to a particular scope (a code block between curly braces)
- * and you leave this scope due to a <code>return</code> statements or an
- * exception, then the variable is destroyed and the timed section is left
- * automatically. Consequently, we could have written the code piece above
- * as follows, with exactly the same result but now exception-safe:
+ * approach is to use "scoped" sections. This is a variable that when you
+ * create it enters a section, and leaves the section when you destroy it. If
+ * this is a variable local to a particular scope (a code block between curly
+ * braces) and you leave this scope due to a <code>return</code> statements or
+ * an exception, then the variable is destroyed and the timed section is left
+ * automatically. Consequently, we could have written the code piece above as
+ * follows, with exactly the same result but now exception-safe:
* @code
* TimerOutput timer (std::cout, TimerOutput::summary,
* TimerOutput::wall_times);
*
* <h3>Usage in parallel programs using MPI</h3>
*
- * In a parallel program built on MPI, using the class in a way such
- * as the one shown above would result in a situation where each
- * process times the corresponding sections and then outputs the resulting
- * timing information at the end. This is annoying since you'd get a lot
- * of output -- one set of timing information from each processor.
+ * In a parallel program built on MPI, using the class in a way such as the
+ * one shown above would result in a situation where each process times the
+ * corresponding sections and then outputs the resulting timing information at
+ * the end. This is annoying since you'd get a lot of output -- one set of
+ * timing information from each processor.
*
* This can be avoided by only letting one processor generate screen output,
* typically by using an object of type ConditionalOStream instead of
* <code>std::cout</code> to write to screen (see, for example, step-17,
* step-18, step-32 and step-40, all of which use this method).
*
- * This way, only a single processor outputs timing information, typically
- * the first process in the MPI universe. However,
- * if you take the above code snippet as an example, imagine what would happen
- * if <code>setup_dofs()</code> is fast on processor zero and slow on at
- * least one of the other processors; and if the first thing
+ * This way, only a single processor outputs timing information, typically the
+ * first process in the MPI universe. However, if you take the above code
+ * snippet as an example, imagine what would happen if
+ * <code>setup_dofs()</code> is fast on processor zero and slow on at least
+ * one of the other processors; and if the first thing
* <code>assemble_system_1()</code> does is something that requires all
* processors to communicate. In this case, on processor zero, the timing
- * section with name <code>"Setup dof system"</code> will yield a short
- * run time on processor zero, whereas the section <code> "Assemble"</code>
- * will take a long time: not because <code>assemble_system_1()</code>
- * takes a particularly long time, but because on the processor on which
- * we time (or, rather, the one on which we generate output) happens to
- * have to wait for a long time till the other processor is finally done
- * with <code>setup_dofs()</code> and starts to participate in
+ * section with name <code>"Setup dof system"</code> will yield a short run
+ * time on processor zero, whereas the section <code> "Assemble"</code> will
+ * take a long time: not because <code>assemble_system_1()</code> takes a
+ * particularly long time, but because on the processor on which we time (or,
+ * rather, the one on which we generate output) happens to have to wait for a
+ * long time till the other processor is finally done with
+ * <code>setup_dofs()</code> and starts to participate in
* <code>assemble_system_1()</code>. In other words, the timing that is
- * reported is unreliable because it reflects run times from other
- * processors. Furthermore, the run time of this section on processor zero
- * has nothing to do with the run time of the section on other processors
- * but instead with the run time of <i>the previous section</i> on another
- * processor.
+ * reported is unreliable because it reflects run times from other processors.
+ * Furthermore, the run time of this section on processor zero has nothing to
+ * do with the run time of the section on other processors but instead with
+ * the run time of <i>the previous section</i> on another processor.
*
* The usual way to avoid this is to introduce a barrier into the parallel
- * code just before we start and stop timing sections. This ensures that
- * all processes are at the same place and the timing information then
- * reflects the maximal run time across all processors. To achieve this,
- * you need to initialize the TimerOutput object with an MPI communicator
- * object, for example as in the following code:
+ * code just before we start and stop timing sections. This ensures that all
+ * processes are at the same place and the timing information then reflects
+ * the maximal run time across all processors. To achieve this, you need to
+ * initialize the TimerOutput object with an MPI communicator object, for
+ * example as in the following code:
* @code
* TimerOutput timer (MPI_COMM_WORLD,
* pcout,
* TimerOutput::summary,
* TimerOutput::wall_times);
* @endcode
- * Here, <code>pcout</code> is an object of type ConditionalOStream that
- * makes sure that we only generate output on a single processor.
- * See the step-32 and step-40 tutorial programs for this kind of usage
- * of this class.
+ * Here, <code>pcout</code> is an object of type ConditionalOStream that makes
+ * sure that we only generate output on a single processor. See the step-32
+ * and step-40 tutorial programs for this kind of usage of this class.
*
* @ingroup utilities
* @author M. Kronbichler, 2009.
{
public:
/**
- * Helper class to enter/exit sections in TimerOutput be constructing
- * a simple scope-based object. The purpose of this class is explained
- * in the documentation of TimerOutput.
+ * Helper class to enter/exit sections in TimerOutput be constructing a
+ * simple scope-based object. The purpose of this class is explained in the
+ * documentation of TimerOutput.
*/
class Scope
{
/**
* Constructor.
*
- * @param stream The stream (of type std::ostream) to which output is written.
- * @param output_frequency A variable indicating when output is to be written
- * to the given stream.
+ * @param stream The stream (of type std::ostream) to which output is
+ * written.
+ * @param output_frequency A variable indicating when output is to be
+ * written to the given stream.
* @param output_type A variable indicating what kind of timing the output
- * should represent (CPU or wall time).
+ * should represent (CPU or wall time).
*/
TimerOutput (std::ostream &stream,
const enum OutputFrequency output_frequency,
/**
* Constructor.
*
- * @param stream The stream (of type ConditionalOstream) to which output is written.
- * @param output_frequency A variable indicating when output is to be written
- * to the given stream.
+ * @param stream The stream (of type ConditionalOstream) to which output is
+ * written.
+ * @param output_frequency A variable indicating when output is to be
+ * written to the given stream.
* @param output_type A variable indicating what kind of timing the output
- * should represent (CPU or wall time).
+ * should represent (CPU or wall time).
*/
TimerOutput (ConditionalOStream &stream,
const enum OutputFrequency output_frequency,
#ifdef DEAL_II_WITH_MPI
/**
- * Constructor that takes an MPI communicator as input. A timer
- * constructed this way will sum up the CPU times over all
- * processors in the MPI network for calculating the CPU time, or
- * take the maximum over all processors, depending on the value of
- * @p output_type . See the documentation of this class for the
- * rationale for this constructor and an example.
+ * Constructor that takes an MPI communicator as input. A timer constructed
+ * this way will sum up the CPU times over all processors in the MPI network
+ * for calculating the CPU time, or take the maximum over all processors,
+ * depending on the value of @p output_type . See the documentation of this
+ * class for the rationale for this constructor and an example.
*
* @param mpi_comm An MPI communicator across which we should accumulate or
- * otherwise synchronize the timing information we produce on every MPI process.
- * @param stream The stream (of type std::ostream) to which output is written.
- * @param output_frequency A variable indicating when output is to be written
- * to the given stream.
+ * otherwise synchronize the timing information we produce on every MPI
+ * process.
+ * @param stream The stream (of type std::ostream) to which output is
+ * written.
+ * @param output_frequency A variable indicating when output is to be
+ * written to the given stream.
* @param output_type A variable indicating what kind of timing the output
- * should represent (CPU or wall time). In this parallel context, when this
- * argument selects CPU time, then times are accumulated over all processes
- * participating in the MPI communicator. If this argument selects wall
- * time, then reported times are the maximum over all processors' run times
- * for this section. (The latter is computed by placing an
- * <code>MPI_Barrier</code> call before starting and stopping the timer
- * for each section.
+ * should represent (CPU or wall time). In this parallel context, when this
+ * argument selects CPU time, then times are accumulated over all processes
+ * participating in the MPI communicator. If this argument selects wall
+ * time, then reported times are the maximum over all processors' run times
+ * for this section. (The latter is computed by placing an
+ * <code>MPI_Barrier</code> call before starting and stopping the timer for
+ * each section.
*/
TimerOutput (MPI_Comm mpi_comm,
std::ostream &stream,
const enum OutputType output_type);
/**
- * Constructor that takes an MPI communicator as input. A timer
- * constructed this way will sum up the CPU times over all
- * processors in the MPI network for calculating the CPU time, or
- * take the maximum over all processors, depending on the value of
- * @p output_type . See the documentation of this class for the
- * rationale for this constructor and an example.
+ * Constructor that takes an MPI communicator as input. A timer constructed
+ * this way will sum up the CPU times over all processors in the MPI network
+ * for calculating the CPU time, or take the maximum over all processors,
+ * depending on the value of @p output_type . See the documentation of this
+ * class for the rationale for this constructor and an example.
*
* @param mpi_comm An MPI communicator across which we should accumulate or
- * otherwise synchronize the timing information we produce on every MPI process.
- * @param stream The stream (of type ConditionalOstream) to which output is written.
- * @param output_frequency A variable indicating when output is to be written
- * to the given stream.
+ * otherwise synchronize the timing information we produce on every MPI
+ * process.
+ * @param stream The stream (of type ConditionalOstream) to which output is
+ * written.
+ * @param output_frequency A variable indicating when output is to be
+ * written to the given stream.
* @param output_type A variable indicating what kind of timing the output
- * should represent (CPU or wall time). In this parallel context, when this
- * argument selects CPU time, then times are accumulated over all processes
- * participating in the MPI communicator. If this argument selects wall
- * time, then reported times are the maximum over all processors' run times
- * for this section. (The latter is computed by placing an
- * <code>MPI_Barrier</code> call before starting and stopping the timer
- * for each section.)
+ * should represent (CPU or wall time). In this parallel context, when this
+ * argument selects CPU time, then times are accumulated over all processes
+ * participating in the MPI communicator. If this argument selects wall
+ * time, then reported times are the maximum over all processors' run times
+ * for this section. (The latter is computed by placing an
+ * <code>MPI_Barrier</code> call before starting and stopping the timer for
+ * each section.)
*/
TimerOutput (MPI_Comm mpi_comm,
ConditionalOStream &stream,
#endif
/**
- * Destructor. Calls print_summary() in
- * case the option for writing the
+ * Destructor. Calls print_summary() in case the option for writing the
* summary output is set.
*/
~TimerOutput();
/**
- * Open a section by given a string name
- * of it. In case the name already
- * exists, that section is entered once
- * again and times are accumulated.
+ * Open a section by given a string name of it. In case the name already
+ * exists, that section is entered once again and times are accumulated.
*/
void enter_subsection (const std::string §ion_name);
//TODO: make some of these functions DEPRECATED (I would keep enter/exit_section)
/**
- * Leave a section. If no name is given,
- * the last section that was entered is
- * left.
+ * Leave a section. If no name is given, the last section that was entered
+ * is left.
*/
void leave_subsection (const std::string §ion_name = std::string());
void exit_section (const std::string §ion_name = std::string());
/**
- * Print a formatted table that
- * summarizes the time consumed in the
- * various sections.
+ * Print a formatted table that summarizes the time consumed in the various
+ * sections.
*/
void print_summary () const;
/**
- * By calling this function, all output
- * can be disabled. This function
- * together with enable_output() can be
- * useful if one wants to control the
- * output in a flexible way without
- * putting a lot of <tt>if</tt> clauses
- * in the program.
+ * By calling this function, all output can be disabled. This function
+ * together with enable_output() can be useful if one wants to control the
+ * output in a flexible way without putting a lot of <tt>if</tt> clauses in
+ * the program.
*/
void disable_output ();
/**
- * This function re-enables output of
- * this class if it was previously
- * disabled with disable_output(). This
- * function together with
- * disable_output() can be useful if
- * one wants to control the output in a
- * flexible way without putting a lot
- * of <tt>if</tt> clauses in the
- * program.
+ * This function re-enables output of this class if it was previously
+ * disabled with disable_output(). This function together with
+ * disable_output() can be useful if one wants to control the output in a
+ * flexible way without putting a lot of <tt>if</tt> clauses in the program.
*/
void enable_output ();
OutputFrequency output_frequency;
/**
- * Whether to show CPU times, wall
- * times, or both CPU and wall times.
+ * Whether to show CPU times, wall times, or both CPU and wall times.
*/
OutputType output_type;
/**
- * A timer object for the overall
- * run time. If we are using MPI,
- * this timer also accumulates
- * over all MPI processes.
+ * A timer object for the overall run time. If we are using MPI, this timer
+ * also accumulates over all MPI processes.
*/
Timer timer_all;
/**
- * A structure that groups all
- * information that we collect
- * about each of the sections.
+ * A structure that groups all information that we collect about each of the
+ * sections.
*/
struct Section
{
};
/**
- * A list of all the sections and
- * their information.
+ * A list of all the sections and their information.
*/
std::map<std::string, Section> sections;
/**
- * The stream object to which we
- * are to output.
+ * The stream object to which we are to output.
*/
ConditionalOStream out_stream;
/**
- * A boolean variable that sets whether
- * output of this class is currently on
+ * A boolean variable that sets whether output of this class is currently on
* or off.
*/
bool output_is_enabled;
/**
- * A list of the sections that
- * have been entered and not
- * exited. The list is kept in
- * the order in which sections
- * have been entered, but
- * elements may be removed in the
- * middle if an argument is given
- * to the exit_section()
+ * A list of the sections that have been entered and not exited. The list is
+ * kept in the order in which sections have been entered, but elements may
+ * be removed in the middle if an argument is given to the exit_section()
* function.
*/
std::list<std::string> active_sections;
MPI_Comm mpi_communicator;
/**
- * A lock that makes sure that this
- * class gives reasonable results even
- * when used with several threads.
+ * A lock that makes sure that this class gives reasonable results even when
+ * used with several threads.
*/
Threads::Mutex mutex;
};
DEAL_II_NAMESPACE_OPEN
/**
- * A namespace in which we declare typedefs for types used in deal.II,
- * as well as special values for these types.
+ * A namespace in which we declare typedefs for types used in deal.II, as well
+ * as special values for these types.
*/
namespace types
{
/**
- * The type used to denote
- * subdomain_ids of cells.
+ * The type used to denote subdomain_ids of cells.
*
- * See the @ref GlossSubdomainId
- * "glossary" for more information.
- *
- * There is a special value,
- * numbers::invalid_subdomain_id
- * that is used to indicate an
- * invalid value of this type.
+ * See the @ref GlossSubdomainId "glossary" for more information.
+ *
+ * There is a special value, numbers::invalid_subdomain_id that is used to
+ * indicate an invalid value of this type.
*/
typedef unsigned int subdomain_id;
typedef subdomain_id subdomain_id_t DEAL_II_DEPRECATED;
/**
- * @deprecated Use numbers::invalid_subdomain_id
+ * @deprecated Use numbers::invalid_subdomain_id
*/
const unsigned int invalid_subdomain_id DEAL_II_DEPRECATED = static_cast<subdomain_id>(-1);
#ifdef DEAL_II_WITH_64BIT_INDICES
/**
- * The type used for global indices of
- * degrees of freedom. While in sequential
- * computations the 4 billion indices of
- * 32-bit unsigned integers is plenty,
- * parallel computations using the
- * parallel::distributed::Triangulation
- * class can overflow this number and we
- * need a bigger index space.
+ * The type used for global indices of degrees of freedom. While in
+ * sequential computations the 4 billion indices of 32-bit unsigned integers
+ * is plenty, parallel computations using the
+ * parallel::distributed::Triangulation class can overflow this number and
+ * we need a bigger index space.
*
- * The data type always indicates an
- * unsigned integer type.
+ * The data type always indicates an unsigned integer type.
*
- * See the @ref GlobalDoFIndex page for guidance on when this
- * type should or should not be used.
+ * See the @ref GlobalDoFIndex page for guidance on when this type should or
+ * should not be used.
*/
// TODO: we should check that unsigned long long int
// has the same size as uint64_t
typedef unsigned long long int global_dof_index;
/**
- * An identifier that denotes the MPI type
- * associated with types::global_dof_index.
+ * An identifier that denotes the MPI type associated with
+ * types::global_dof_index.
*/
# define DEAL_II_DOF_INDEX_MPI_TYPE MPI_UNSIGNED_LONG_LONG
#else
/**
- * The type used for global indices of
- * degrees of freedom. While in sequential
- * computations the 4 billion indices of
- * 32-bit unsigned integers is plenty,
- * parallel computations using the
- * parallel::distributed::Triangulation
- * class can overflow this number and we
- * need a bigger index space.
+ * The type used for global indices of degrees of freedom. While in
+ * sequential computations the 4 billion indices of 32-bit unsigned integers
+ * is plenty, parallel computations using the
+ * parallel::distributed::Triangulation class can overflow this number and
+ * we need a bigger index space.
*
- * The data type always indicates an
- * unsigned integer type.
+ * The data type always indicates an unsigned integer type.
*/
typedef unsigned int global_dof_index;
/**
- * An identifier that denotes the MPI type
- * associated with types::global_dof_index.
+ * An identifier that denotes the MPI type associated with
+ * types::global_dof_index.
*/
# define DEAL_II_DOF_INDEX_MPI_TYPE MPI_UNSIGNED
#endif
/**
- * @deprecated Use numbers::invalid_dof_index
+ * @deprecated Use numbers::invalid_dof_index
*/
const global_dof_index invalid_dof_index DEAL_II_DEPRECATED = static_cast<global_dof_index>(-1);
/**
- * The type used to denote boundary indicators associated with every
- * piece of the boundary and, in the case of meshes that describe
- * manifolds in higher dimensions, associated with every cell.
+ * The type used to denote boundary indicators associated with every piece
+ * of the boundary and, in the case of meshes that describe manifolds in
+ * higher dimensions, associated with every cell.
*
- * There is a special value, numbers::internal_face_boundary_id
- * that is used to indicate an invalid value of this type and that
- * is used as the boundary indicator for faces that are in the interior
- * of the domain and therefore not part of any addressable boundary
- * component.
+ * There is a special value, numbers::internal_face_boundary_id that is used
+ * to indicate an invalid value of this type and that is used as the
+ * boundary indicator for faces that are in the interior of the domain and
+ * therefore not part of any addressable boundary component.
*
* @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
*/
typedef unsigned char boundary_id;
/**
- * The type used to denote manifold indicators associated with every
- * object of the mesh.
+ * The type used to denote manifold indicators associated with every object
+ * of the mesh.
*
- * There is a special value, numbers::flat_manifold_id
- * that is used to indicate the standard cartesian manifold.
+ * There is a special value, numbers::flat_manifold_id that is used to
+ * indicate the standard cartesian manifold.
*
* @see @ref GlossManifoldIndicator "Glossary entry on manifold indicators"
*/
typedef boundary_id boundary_id_t DEAL_II_DEPRECATED;
/**
- * The type used to denote material indicators associated with every
- * cell.
- *
- * There is a special value, numbers::invalid_material_id
- * that is used to indicate an invalid value of this type.
+ * The type used to denote material indicators associated with every cell.
+ *
+ * There is a special value, numbers::invalid_material_id that is used to
+ * indicate an invalid value of this type.
*/
typedef unsigned char material_id;
namespace numbers
{
/**
- * Representation of the
- * largest number that
- * can be put into an
- * unsigned integer. This
- * value is widely used
- * throughout the library
- * as a marker for an
- * invalid unsigned
- * integer value, such as
- * an invalid array
- * index, an invalid
- * array size, and the
- * like.
+ * Representation of the largest number that can be put into an unsigned
+ * integer. This value is widely used throughout the library as a marker for
+ * an invalid unsigned integer value, such as an invalid array index, an
+ * invalid array size, and the like.
*/
static const unsigned int
invalid_unsigned_int = static_cast<unsigned int> (-1);
/**
- * Representation of the
- * largest number that
- * can be put into a
- * size_type. This value
- * is used throughout
- * the library as a
- * marker for an
- * invalid size_type
- * value, such as
- * an invalid array
- * index, an invalid
- * array size, and the
- * like. Invalid_size_type
- * is equivalent to
- * invalid_dof_index.
+ * Representation of the largest number that can be put into a size_type.
+ * This value is used throughout the library as a marker for an invalid
+ * size_type value, such as an invalid array index, an invalid array size,
+ * and the like. Invalid_size_type is equivalent to invalid_dof_index.
*/
const types::global_dof_index
invalid_size_type = static_cast<types::global_dof_index> (-1);
/**
- * An invalid value for indices of degrees
- * of freedom.
+ * An invalid value for indices of degrees of freedom.
*/
const types::global_dof_index invalid_dof_index = static_cast<types::global_dof_index>(-1);
/**
- * Invalid material_id which we
- * need in several places as a
- * default value. We assume that
- * all material_ids lie in the
- * range [0, invalid_material_id).
+ * Invalid material_id which we need in several places as a default value.
+ * We assume that all material_ids lie in the range [0,
+ * invalid_material_id).
*/
const types::material_id invalid_material_id = static_cast<types::material_id>(-1);
/**
- * Invalid boundary_id which we
- * need in several places as a
- * default value. We assume that
- * all valid boundary_ids lie in the
- * range [0, invalid_boundary_id).
+ * Invalid boundary_id which we need in several places as a default value.
+ * We assume that all valid boundary_ids lie in the range [0,
+ * invalid_boundary_id).
*
* @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
*/
const types::boundary_id invalid_boundary_id = static_cast<types::boundary_id>(-1);
/**
- * A boundary indicator number that we reserve for
- * internal faces. We assume that
- * all valid boundary_ids lie in the
- * range [0,
+ * A boundary indicator number that we reserve for internal faces. We
+ * assume that all valid boundary_ids lie in the range [0,
* internal_face_boundary_id).
*
* This is an indicator that is used internally (by the library) to
- * differentiate between faces that lie at the boundary of the domain
- * and faces that lie in the interior of the domain. You should never try
- * to assign this boundary indicator to anything in user code.
+ * differentiate between faces that lie at the boundary of the domain and
+ * faces that lie in the interior of the domain. You should never try to
+ * assign this boundary indicator to anything in user code.
*
* @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
*/
const types::boundary_id internal_face_boundary_id = static_cast<types::boundary_id>(-1);
/**
- * Invalid manifold_id which we
- * need in several places as a
- * default value. We assume that
- * all valid manifold_ids lie in the
- * range [0, invalid_maifold_id).
+ * Invalid manifold_id which we need in several places as a default value.
+ * We assume that all valid manifold_ids lie in the range [0,
+ * invalid_maifold_id).
*
* @see @ref GlossManifoldIndicator "Glossary entry on manifold indicators"
*/
const types::manifold_id flat_manifold_id = static_cast<types::manifold_id>(-1);
/**
- * A special id for an invalid
- * subdomain id. This value may not
- * be used as a valid id but is
- * used, for example, for default
- * arguments to indicate a
- * subdomain id that is not to be
- * used.
+ * A special id for an invalid subdomain id. This value may not be used as a
+ * valid id but is used, for example, for default arguments to indicate a
+ * subdomain id that is not to be used.
*
- * See the @ref GlossSubdomainId
- * "glossary" for more information.
+ * See the @ref GlossSubdomainId "glossary" for more information.
*/
const types::subdomain_id invalid_subdomain_id = static_cast<types::subdomain_id>(-1);
/**
- * The subdomain id assigned to a
- * cell whose true subdomain id we
- * don't know, for example because
- * it resides on a different
- * processor on a mesh that is kept
- * distributed on many
- * processors. Such cells are
- * called "artificial".
+ * The subdomain id assigned to a cell whose true subdomain id we don't
+ * know, for example because it resides on a different processor on a mesh
+ * that is kept distributed on many processors. Such cells are called
+ * "artificial".
*
- * See the glossary entries on @ref
- * GlossSubdomainId "subdomain ids"
- * and @ref GlossArtificialCell
- * "artificial cells" as well as
- * the @ref distributed module for
- * more information.
+ * See the glossary entries on @ref GlossSubdomainId "subdomain ids" and
+ * @ref GlossArtificialCell "artificial cells" as well as the @ref
+ * distributed module for more information.
*/
const types::subdomain_id artificial_subdomain_id = static_cast<types::subdomain_id>(-2);
}
{
/**
- * Convert a number @p i to a string, with
- * as many digits as given to fill with
- * leading zeros.
+ * Convert a number @p i to a string, with as many digits as given to fill
+ * with leading zeros.
*
- * If the second parameter is left at its
- * default value, the number is not padded
- * with leading zeros. The result is then
- * the same as of the standard C function
- * <code>itoa()</code> had been called.
+ * If the second parameter is left at its default value, the number is not
+ * padded with leading zeros. The result is then the same as of the standard
+ * C function <code>itoa()</code> had been called.
*/
std::string
int_to_string (const unsigned int i,
const unsigned int digits = numbers::invalid_unsigned_int);
/**
- * Determine how many digits are needed to
- * represent numbers at most as large as
- * the given number.
+ * Determine how many digits are needed to represent numbers at most as
+ * large as the given number.
*/
unsigned int
needed_digits (const unsigned int max_number);
/**
- * Given a string, convert it to an
- * integer. Throw an assertion if that is
+ * Given a string, convert it to an integer. Throw an assertion if that is
* not possible.
*/
int
string_to_int (const std::string &s);
/**
- * Return a string describing the dimensions of the object. Often,
- * functions in the deal.II library as well as in user codes need to
- * define a string containing the template dimensions of some
- * objects defined using two template parameters: dim (the
- * topological dimension of the object) and spacedim (the dimension
- * of the embedding Euclidean space). Since in all deal.II classes,
- * by default spacedim is equal to dimension, the above string is
- * usually contracted to <dim>, instead of <dim,spacedim>. This
- * function returns a string containing "dim" if dim is equal to
- * spacedim, otherwhise it returns "dim,spacedim".
+ * Return a string describing the dimensions of the object. Often, functions
+ * in the deal.II library as well as in user codes need to define a string
+ * containing the template dimensions of some objects defined using two
+ * template parameters: dim (the topological dimension of the object) and
+ * spacedim (the dimension of the embedding Euclidean space). Since in all
+ * deal.II classes, by default spacedim is equal to dimension, the above
+ * string is usually contracted to <dim>, instead of <dim,spacedim>. This
+ * function returns a string containing "dim" if dim is equal to spacedim,
+ * otherwhise it returns "dim,spacedim".
*/
std::string dim_string(const int dim, const int spacedim);
/**
- * Given a list of strings, convert it to a
- * list of integers. Throw an assertion if
- * that is not possible.
+ * Given a list of strings, convert it to a list of integers. Throw an
+ * assertion if that is not possible.
*/
std::vector<int>
string_to_int (const std::vector<std::string> &s);
/**
- * Given a string, convert it to an
- * double. Throw an assertion if that is
+ * Given a string, convert it to an double. Throw an assertion if that is
* not possible.
*/
double
/**
- * Given a list of strings, convert it to a
- * list of doubles. Throw an assertion if
- * that is not possible.
+ * Given a list of strings, convert it to a list of doubles. Throw an
+ * assertion if that is not possible.
*/
std::vector<double>
string_to_double (const std::vector<std::string> &s);
/**
- * Given a string that contains text
- * separated by a @p delimiter, split it into
- * its components; for each component,
- * remove leading and trailing spaces.
+ * Given a string that contains text separated by a @p delimiter, split it
+ * into its components; for each component, remove leading and trailing
+ * spaces.
*
- * The default value of the delimiter is a
- * comma, so that the function splits comma
- * separated lists of strings.
+ * The default value of the delimiter is a comma, so that the function
+ * splits comma separated lists of strings.
*/
std::vector<std::string>
split_string_list (const std::string &s,
const char delimiter = ',');
/**
- * Take a text, usually a documentation or
- * something, and try to break it into
- * individual lines of text at most @p
- * width characters wide, by breaking at
- * positions marked by @p delimiter in the
- * text. If this is not possible, return
- * the shortest lines that are longer than
- * @p width. The default value of the
- * delimiter is a space character. If
- * original_text contains newline
- * characters (\n), the string is split at
- * these locations, too.
+ * Take a text, usually a documentation or something, and try to break it
+ * into individual lines of text at most @p width characters wide, by
+ * breaking at positions marked by @p delimiter in the text. If this is not
+ * possible, return the shortest lines that are longer than @p width. The
+ * default value of the delimiter is a space character. If original_text
+ * contains newline characters (\n), the string is split at these locations,
+ * too.
*/
std::vector<std::string>
break_text_into_lines (const std::string &original_text,
const char delimiter = ' ');
/**
- * Return true if the given pattern
- * string appears in the first
- * position of the string.
+ * Return true if the given pattern string appears in the first position of
+ * the string.
*/
bool
match_at_string_start (const std::string &name,
const std::string &pattern);
/**
- * Read a (signed) integer starting
- * at the position in @p name
- * indicated by the second
- * argument, and retun this integer
- * as a pair together with how many
- * characters it takes up in the
- * string.
+ * Read a (signed) integer starting at the position in @p name indicated by
+ * the second argument, and retun this integer as a pair together with how
+ * many characters it takes up in the string.
*
- * If no integer can be read at the
- * indicated position, return
+ * If no integer can be read at the indicated position, return
* (-1,numbers::invalid_unsigned_int)
*/
std::pair<int, unsigned int>
const unsigned int position);
/**
- * Generate a random number from a
- * normalized Gaussian probability
- * distribution centered around @p a and
- * with standard deviation @p sigma.
+ * Generate a random number from a normalized Gaussian probability
+ * distribution centered around @p a and with standard deviation @p sigma.
*
- * This function is reentrant, i.e., it can safely be
- * called from multiple threads at the same time. However, if
- * so done, then there is no guarantee that each thread will
- * get the same sequence of numbers every time. Rather, the
- * produced sequence of random numbers will be apportioned to
- * the different threads in non-deterministic ways. If this
- * is a problem, for example for exactly reproducibility, then
- * you need to use separate random number facilities for separate
- * threads, rather than this global function. For example, the C++11
- * standard offers such objects, as does BOOST.
+ * This function is reentrant, i.e., it can safely be called from multiple
+ * threads at the same time. However, if so done, then there is no guarantee
+ * that each thread will get the same sequence of numbers every time.
+ * Rather, the produced sequence of random numbers will be apportioned to
+ * the different threads in non-deterministic ways. If this is a problem,
+ * for example for exactly reproducibility, then you need to use separate
+ * random number facilities for separate threads, rather than this global
+ * function. For example, the C++11 standard offers such objects, as does
+ * BOOST.
*
- * @note Like the system function rand(), this function produces
- * the same sequence of random numbers every time a program is
- * started. This is an important property for debugging codes,
- * but it makes it impossible to really verify statistics
- * properties of a code. For rand(), you can call srand() to
- * "seed" the random number generator to get different sequences
- * of random numbers every time a program is called. However, this
- * function does not allow seeding the random number generator.
- * If you need this, as above, use one of the C++ or BOOST
- * facilities.
+ * @note Like the system function rand(), this function produces the same
+ * sequence of random numbers every time a program is started. This is an
+ * important property for debugging codes, but it makes it impossible to
+ * really verify statistics properties of a code. For rand(), you can call
+ * srand() to "seed" the random number generator to get different sequences
+ * of random numbers every time a program is called. However, this function
+ * does not allow seeding the random number generator. If you need this, as
+ * above, use one of the C++ or BOOST facilities.
*/
double
generate_normal_random_number (const double a,
/**
- * Calculate a fixed power, provided as a
- * template argument, of a number.
+ * Calculate a fixed power, provided as a template argument, of a number.
*
- * This function provides an efficient way
- * to calculate things like
- * <code>t^N</code> where <code>N</code> is
- * a known number at compile time.
+ * This function provides an efficient way to calculate things like
+ * <code>t^N</code> where <code>N</code> is a known number at compile time.
*
- * Use this function as in
- * <code>fixed_power@<dim@> (n)</code>.
+ * Use this function as in <code>fixed_power@<dim@> (n)</code>.
*/
template <int N, typename T>
T
fixed_power (const T t);
/**
- * Calculate a fixed power of an integer
- * number by a template expression where
- * both the number <code>a</code> and the
- * power <code>N</code> are compile-time
- * constants. This computes the result of
- * the power operation at compile time,
- * enabling its use e.g. in other
- * templates.
+ * Calculate a fixed power of an integer number by a template expression
+ * where both the number <code>a</code> and the power <code>N</code> are
+ * compile-time constants. This computes the result of the power operation
+ * at compile time, enabling its use e.g. in other templates.
*
- * Use this class as in
- * <code>fixed_int_power@<5,2@>::%value</code>
- * to compute 5<sup>2</sup>.
+ * Use this class as in <code>fixed_int_power@<5,2@>::%value</code> to
+ * compute 5<sup>2</sup>.
*/
template <int a, int N>
struct fixed_int_power
};
/**
- * Base case for the power operation with
- * <code>N=0</code>, which gives the result
- * 1.
+ * Base case for the power operation with <code>N=0</code>, which gives the
+ * result 1.
*/
template <int a>
struct fixed_int_power<a,0>
};
/**
- * Optimized replacement for
- * <tt>std::lower_bound</tt> for
- * searching within the range of
- * column indices. Slashes
- * execution time by
- * approximately one half for the
- * present application, partly
- * because because the
- * binary search is replaced by a
- * linear search for small loop
- * lengths.
+ * Optimized replacement for <tt>std::lower_bound</tt> for searching within
+ * the range of column indices. Slashes execution time by approximately one
+ * half for the present application, partly because because the binary
+ * search is replaced by a linear search for small loop lengths.
*
- * Another reason for this function is
- * rather obscure:
- * when using the GCC libstdc++
- * function std::lower_bound,
- * complexity is O(log(N)) as
- * required. However, when using the
- * debug version of the GCC libstdc++
- * as we do when running the testsuite,
- * then std::lower_bound tests whether
- * the sequence is in fact partitioned
- * with respect to the pivot 'value'
- * (i.e. in essence that the sequence
- * is sorted as required for binary
- * search to work). However, verifying
- * this means that the complexity of
- * std::lower_bound jumps to O(N); we
- * call this function O(N) times below,
- * making the overall complexity
- * O(N**2). The consequence is that a
- * few tests with big meshes completely
- * run off the wall time limit for
- * tests and fail with the libstdc++
- * debug mode
+ * Another reason for this function is rather obscure: when using the GCC
+ * libstdc++ function std::lower_bound, complexity is O(log(N)) as required.
+ * However, when using the debug version of the GCC libstdc++ as we do when
+ * running the testsuite, then std::lower_bound tests whether the sequence
+ * is in fact partitioned with respect to the pivot 'value' (i.e. in essence
+ * that the sequence is sorted as required for binary search to work).
+ * However, verifying this means that the complexity of std::lower_bound
+ * jumps to O(N); we call this function O(N) times below, making the overall
+ * complexity O(N**2). The consequence is that a few tests with big meshes
+ * completely run off the wall time limit for tests and fail with the
+ * libstdc++ debug mode
*
- * This function simply makes the
- * assumption that the sequence is
- * sorted, and we simply don't do the
- * additional check.
+ * This function simply makes the assumption that the sequence is sorted,
+ * and we simply don't do the additional check.
*/
template<typename Iterator, typename T>
Iterator
/**
- * The same function as above, but taking
- * an argument that is used to compare
- * individual elements of the sequence of
- * objects pointed to by the iterators.
+ * The same function as above, but taking an argument that is used to
+ * compare individual elements of the sequence of objects pointed to by the
+ * iterators.
*/
template<typename Iterator, typename T, typename Comp>
Iterator
const Comp comp);
/**
- * Given a permutation vector (i.e. a
- * vector $p_0\ldots p_{N-1}$ where each
- * $p_i\in [0,N)$ and $p_i\neq p_j$ for
- * $i\neq j$), produce the reverse
+ * Given a permutation vector (i.e. a vector $p_0\ldots p_{N-1}$ where each
+ * $p_i\in [0,N)$ and $p_i\neq p_j$ for $i\neq j$), produce the reverse
* permutation $q_i=N-1-p_i$.
*/
std::vector<unsigned int>
reverse_permutation (const std::vector<unsigned int> &permutation);
/**
- * Given a permutation vector (i.e. a
- * vector $p_0\ldots p_{N-1}$ where each
- * $p_i\in [0,N)$ and $p_i\neq p_j$ for
- * $i\neq j$), produce the inverse
- * permutation $q_0\ldots q_{N-1}$ so that
- * $q_{p_i}=p_{q_i}=i$.
+ * Given a permutation vector (i.e. a vector $p_0\ldots p_{N-1}$ where each
+ * $p_i\in [0,N)$ and $p_i\neq p_j$ for $i\neq j$), produce the inverse
+ * permutation $q_0\ldots q_{N-1}$ so that $q_{p_i}=p_{q_i}=i$.
*/
std::vector<unsigned int>
invert_permutation (const std::vector<unsigned int> &permutation);
/**
- * Given a permutation vector (i.e. a
- * vector $p_0\ldots p_{N-1}$ where each
- * $p_i\in [0,N)$ and $p_i\neq p_j$ for
- * $i\neq j$), produce the reverse
+ * Given a permutation vector (i.e. a vector $p_0\ldots p_{N-1}$ where each
+ * $p_i\in [0,N)$ and $p_i\neq p_j$ for $i\neq j$), produce the reverse
* permutation $q_i=N-1-p_i$.
*/
std::vector<unsigned long long int>
reverse_permutation (const std::vector<unsigned long long int> &permutation);
/**
- * Given a permutation vector (i.e. a
- * vector $p_0\ldots p_{N-1}$ where each
- * $p_i\in [0,N)$ and $p_i\neq p_j$ for
- * $i\neq j$), produce the inverse
- * permutation $q_0\ldots q_{N-1}$ so that
- * $q_{p_i}=p_{q_i}=i$.
+ * Given a permutation vector (i.e. a vector $p_0\ldots p_{N-1}$ where each
+ * $p_i\in [0,N)$ and $p_i\neq p_j$ for $i\neq j$), produce the inverse
+ * permutation $q_0\ldots q_{N-1}$ so that $q_{p_i}=p_{q_i}=i$.
*/
std::vector<unsigned long long int>
invert_permutation (const std::vector<unsigned long long int> &permutation);
/**
- * A namespace for utility functions that
- * probe system properties.
+ * A namespace for utility functions that probe system properties.
*
* @ingroup utilities
*/
{
/**
- * Return the CPU load as returned by
- * "uptime". Note that the interpretation
- * of this number depends on the actual
- * number of processors in the
- * machine. This is presently only
- * implemented on Linux, using the
- * /proc/loadavg pseudo-file, on other
- * systems we simply return zero.
+ * Return the CPU load as returned by "uptime". Note that the
+ * interpretation of this number depends on the actual number of
+ * processors in the machine. This is presently only implemented on Linux,
+ * using the /proc/loadavg pseudo-file, on other systems we simply return
+ * zero.
*/
double get_cpu_load ();
/**
- * Structure that hold information about
- * memory usage in kB. Used by
- * get_memory_stats(). See man 5 proc
- * entry /status for details.
+ * Structure that hold information about memory usage in kB. Used by
+ * get_memory_stats(). See man 5 proc entry /status for details.
*/
struct MemoryStats
{
/**
- * Fills the @p stats structure with
- * information about the memory
- * consumption of this process. This is
- * only implemented on Linux.
+ * Fills the @p stats structure with information about the memory
+ * consumption of this process. This is only implemented on Linux.
*/
void get_memory_stats (MemoryStats &stats);
/**
- * Return the name of the host this
- * process runs on.
+ * Return the name of the host this process runs on.
*/
std::string get_hostname ();
std::string get_time ();
/**
- * Return whether (i) deal.II has
- * been compiled to support MPI
- * (for example by compiling with
- * <code>CXX=mpiCC</code>) and if
- * so whether (ii)
- * <code>MPI_Init()</code> has
- * been called (for example using
- * the
- * Utilities::System::MPI_InitFinalize
- * class). In other words, the
- * result indicates whether the
- * current job is running under
- * MPI.
+ * Return whether (i) deal.II has been compiled to support MPI (for
+ * example by compiling with <code>CXX=mpiCC</code>) and if so whether
+ * (ii) <code>MPI_Init()</code> has been called (for example using the
+ * Utilities::System::MPI_InitFinalize class). In other words, the result
+ * indicates whether the current job is running under MPI.
*
- * @note The function does not
- * take into account whether an
- * MPI job actually runs on more
- * than one processor or is, in
- * fact, a single-node job that
- * happens to run under MPI.
+ * @note The function does not take into account whether an MPI job
+ * actually runs on more than one processor or is, in fact, a single-node
+ * job that happens to run under MPI.
*/
bool job_supports_mpi ();
bool program_uses_mpi () DEAL_II_DEPRECATED;
/**
- * @name Functions that work
- * in parallel via MPI. The
- * functions following here
- * are all deprecated and have
- * been moved to namespace
+ * @name Functions that work in parallel via MPI. The functions following
+ * here are all deprecated and have been moved to namespace
* Utilities::MPI.
*/
/** @{ */
/**
- * This function is an alias for
- * Utilities::MPI::n_mpi_processes.
+ * This function is an alias for Utilities::MPI::n_mpi_processes.
*
* @deprecated
*/
unsigned int get_n_mpi_processes (const MPI_Comm &mpi_communicator) DEAL_II_DEPRECATED;
/**
- * This function is an alias for
- * Utilities::MPI::this_mpi_process.
+ * This function is an alias for Utilities::MPI::this_mpi_process.
*
* @deprecated
*/
/**
- * This function is an alias for
- * Utilities::MPI::duplicate_communicator.
+ * This function is an alias for Utilities::MPI::duplicate_communicator.
*
* @deprecated
*/
namespace Trilinos
{
/**
- * Returns a Trilinos Epetra_Comm
- * object needed for creation of
+ * Returns a Trilinos Epetra_Comm object needed for creation of
* Epetra_Maps.
*
- * If deal.II has been configured to use
- * a compiler that does not support MPI
- * then the resulting communicator will
- * be a serial one. Otherwise, the
- * communicator will correspond to
- * MPI_COMM_WORLD, i.e. a communicator
- * that encompasses all processes within
- * this MPI universe.
+ * If deal.II has been configured to use a compiler that does not support
+ * MPI then the resulting communicator will be a serial one. Otherwise,
+ * the communicator will correspond to MPI_COMM_WORLD, i.e. a communicator
+ * that encompasses all processes within this MPI universe.
*/
const Epetra_Comm &comm_world();
/**
- * Returns a Trilinos Epetra_Comm
- * object needed for creation of
+ * Returns a Trilinos Epetra_Comm object needed for creation of
* Epetra_Maps.
*
- * If deal.II has been configured to use
- * a compiler that does not support MPI
- * then the resulting communicator will
- * be a serial one. Otherwise, the
- * communicator will correspond to
- * MPI_COMM_SELF, i.e. a communicator
- * that comprises only this one
- * processor.
+ * If deal.II has been configured to use a compiler that does not support
+ * MPI then the resulting communicator will be a serial one. Otherwise,
+ * the communicator will correspond to MPI_COMM_SELF, i.e. a communicator
+ * that comprises only this one processor.
*/
const Epetra_Comm &comm_self();
/**
- * Given a communicator, duplicate it. If
- * the given communicator is serial, that
- * means to just return a copy of
- * itself. On the other hand, if it is
- * %parallel, we duplicate the underlying
- * MPI_Comm object: we create a separate
- * MPI communicator that contains the
- * same processors and in the same order
- * but has a separate identifier distinct
- * from the given communicator. The
- * function returns a pointer to a new
- * object of a class derived from
- * Epetra_Comm. The caller of this
- * function needs to assume ownership of
- * this function. The returned object
- * should be destroyed using the
- * destroy_communicator() function.
+ * Given a communicator, duplicate it. If the given communicator is
+ * serial, that means to just return a copy of itself. On the other hand,
+ * if it is %parallel, we duplicate the underlying MPI_Comm object: we
+ * create a separate MPI communicator that contains the same processors
+ * and in the same order but has a separate identifier distinct from the
+ * given communicator. The function returns a pointer to a new object of a
+ * class derived from Epetra_Comm. The caller of this function needs to
+ * assume ownership of this function. The returned object should be
+ * destroyed using the destroy_communicator() function.
*
- * This facility is used to separate
- * streams of communication. For example,
- * a program could simply use
- * MPI_Comm_World for everything. But it
- * is easy to come up with scenarios
- * where sometimes not all processors
- * participate in a communication that is
- * intended to be global -- for example
- * if we assemble a matrix on a coarse
- * mesh with fewer cells than there are
- * processors, some processors may not
- * sync their matrices with the rest
- * because they haven't written into it
- * because they own no cells. That's
- * clearly a bug. However, if these
- * processors just continue their work,
- * and the next %parallel operation
- * happens to be a sync on a different
- * matrix, then the sync could succeed --
- * by accident, since different
- * processors are talking about different
- * matrices.
+ * This facility is used to separate streams of communication. For
+ * example, a program could simply use MPI_Comm_World for everything. But
+ * it is easy to come up with scenarios where sometimes not all processors
+ * participate in a communication that is intended to be global -- for
+ * example if we assemble a matrix on a coarse mesh with fewer cells than
+ * there are processors, some processors may not sync their matrices with
+ * the rest because they haven't written into it because they own no
+ * cells. That's clearly a bug. However, if these processors just continue
+ * their work, and the next %parallel operation happens to be a sync on a
+ * different matrix, then the sync could succeed -- by accident, since
+ * different processors are talking about different matrices.
*
- * This kind of situation can be avoided
- * if we use different communicators for
- * different matrices which reduces the
- * likelihood that communications meant
- * to be separate aren't recognized as
- * such just because they happen on the
- * same communicator. In addition, it is
- * conceivable that some MPI operations
- * can be parallelized using multiple
- * threads because their communicators
- * identifies the communication in
- * question, not their relative timing as
- * is the case in a sequential program
- * that just uses a single communicator.
+ * This kind of situation can be avoided if we use different communicators
+ * for different matrices which reduces the likelihood that communications
+ * meant to be separate aren't recognized as such just because they happen
+ * on the same communicator. In addition, it is conceivable that some MPI
+ * operations can be parallelized using multiple threads because their
+ * communicators identifies the communication in question, not their
+ * relative timing as is the case in a sequential program that just uses a
+ * single communicator.
*/
Epetra_Comm *
duplicate_communicator (const Epetra_Comm &communicator);
/**
- * Given an Epetra communicator that was
- * created by the
- * duplicate_communicator() function,
- * destroy the underlying MPI
- * communicator object and reset the
- * Epetra_Comm object to a the result of
+ * Given an Epetra communicator that was created by the
+ * duplicate_communicator() function, destroy the underlying MPI
+ * communicator object and reset the Epetra_Comm object to a the result of
* comm_self().
*
- * It is necessary to call this function
- * at the time when the result of
- * duplicate_communicator() is no longer
- * needed. The reason is that in that
- * function, we first create a new
- * MPI_Comm object and then create an
- * Epetra_Comm around it. While we can
- * take care of destroying the latter, it
- * doesn't destroy the communicator since
- * it can only assume that it may also be
- * still used by other objects in the
- * program. Consequently, we have to take
- * care of destroying it ourselves,
- * explicitly.
+ * It is necessary to call this function at the time when the result of
+ * duplicate_communicator() is no longer needed. The reason is that in
+ * that function, we first create a new MPI_Comm object and then create an
+ * Epetra_Comm around it. While we can take care of destroying the latter,
+ * it doesn't destroy the communicator since it can only assume that it
+ * may also be still used by other objects in the program. Consequently,
+ * we have to take care of destroying it ourselves, explicitly.
*
- * This function does exactly
- * that. Because this has to happen while
- * the Epetra_Comm object is still
- * around, it first resets the latter and
- * then destroys the communicator object.
+ * This function does exactly that. Because this has to happen while the
+ * Epetra_Comm object is still around, it first resets the latter and then
+ * destroys the communicator object.
*
- * @note If you call this function on an
- * Epetra_Comm object that is not created
- * by duplicate_communicator(), you are
- * likely doing something quite
- * wrong. Don't do this.
+ * @note If you call this function on an Epetra_Comm object that is not
+ * created by duplicate_communicator(), you are likely doing something
+ * quite wrong. Don't do this.
*/
void
destroy_communicator (Epetra_Comm &communicator);
/**
- * Return the number of MPI processes
- * there exist in the given communicator
- * object. If this is a sequential job,
- * it returns 1.
+ * Return the number of MPI processes there exist in the given
+ * communicator object. If this is a sequential job, it returns 1.
*/
unsigned int get_n_mpi_processes (const Epetra_Comm &mpi_communicator);
/**
- * Return the number of the present MPI
- * process in the space of processes
- * described by the given
- * communicator. This will be a unique
- * value for each process between zero
- * and (less than) the number of all
- * processes (given by
- * get_n_mpi_processes()).
+ * Return the number of the present MPI process in the space of processes
+ * described by the given communicator. This will be a unique value for
+ * each process between zero and (less than) the number of all processes
+ * (given by get_n_mpi_processes()).
*/
unsigned int get_this_mpi_process (const Epetra_Comm &mpi_communicator);
/**
- * Given a Trilinos Epetra map, create a
- * new map that has the same subdivision
- * of elements to processors but uses the
- * given communicator object instead of
- * the one stored in the first
- * argument. In essence, this means that
- * we create a map that communicates
- * among the same processors in the same
- * way, but using a separate channel.
+ * Given a Trilinos Epetra map, create a new map that has the same
+ * subdivision of elements to processors but uses the given communicator
+ * object instead of the one stored in the first argument. In essence,
+ * this means that we create a map that communicates among the same
+ * processors in the same way, but using a separate channel.
*
- * This function is typically used with a
- * communicator that has been obtained by
- * the duplicate_communicator() function.
+ * This function is typically used with a communicator that has been
+ * obtained by the duplicate_communicator() function.
*/
Epetra_Map
duplicate_map (const Epetra_BlockMap &map,
* Filter a range out of any object having a random access <tt>operator[]
* (unsigned int)</tt> and a function <tt>size() const</tt>.
*
- * The use of this object is straightforward. It duplicates the
- * random access operator of the <tt>VECTOR</tt> and adds an offset to
- * every index.
+ * The use of this object is straightforward. It duplicates the random access
+ * operator of the <tt>VECTOR</tt> and adds an offset to every index.
*
- * Some precautions have to be taken if it is used for a constant
- * vector: the VectorSlice object has to be constant, too. The
- * appropriate initalization sequence is like this:
+ * Some precautions have to be taken if it is used for a constant vector: the
+ * VectorSlice object has to be constant, too. The appropriate initalization
+ * sequence is like this:
*
* @code
* void f(const std::vector<int>& v)
{
public:
/**
- * Construct a vector slice
- * containing the whole
- * vector. Comes handy, if you
- * did not want to have a slice
- * at all, but the function you
- * call wants it: just put in the
- * vector itself as argument and
- * let this constructor make a
+ * Construct a vector slice containing the whole vector. Comes handy, if you
+ * did not want to have a slice at all, but the function you call wants it:
+ * just put in the vector itself as argument and let this constructor make a
* slice for you.
*/
VectorSlice(VECTOR &v);
/**
- * The real constructor for a
- * vector slice, allowing you to
- * specify the start index and
- * the length of the slice.
+ * The real constructor for a vector slice, allowing you to specify the
+ * start index and the length of the slice.
*/
VectorSlice(VECTOR &v,
unsigned int start,
unsigned int length);
/**
- * Return the length of the slice
- * using the same interface as
+ * Return the length of the slice using the same interface as
* <tt>std::vector</tt>.
*/
unsigned int size() const;
/**
- * Access an element of the slice
- * using the same interface as
+ * Access an element of the slice using the same interface as
* <tt>std::vector</tt>.
*/
typename VECTOR::reference operator[] (unsigned int i);
/**
- * Access an element of a
- * constant slice using the same
- * interface as
+ * Access an element of a constant slice using the same interface as
* <tt>std::vector</tt>.
*/
typename VECTOR::const_reference operator[] (unsigned int i) const;
/**
- * Helper function for creating temporary objects without typing
- * template arguments.
+ * Helper function for creating temporary objects without typing template
+ * arguments.
*
* @relates VectorSlice
* @author Guido Kanschat, 2004
/**
- * Helper function for creating temporary objects without typing
- * template arguments.
+ * Helper function for creating temporary objects without typing template
+ * arguments.
*
* @relates VectorSlice
* @author Guido Kanschat, 2004
/**
- * This generic class defines a unified interface to a vectorized data
- * type. For general template arguments, this class simply corresponds to
- * the template argument. For example, VectorizedArray<long double> is
- * nothing else but a wrapper around <tt>long double</tt> with exactly one
- * data field of type <tt>long double</tt> and overloaded arithmetic
- * operations. This means that <tt>VectorizedArray<ComplicatedType></tt> has
- * a similar layout as ComplicatedType, provided that ComplicatedType
- * defines basic arithmetic operations. For floats and doubles, an array of
- * numbers are packed together, though. The number of elements packed
- * together depend on the computer system and compiler flags that are used
- * for compilation of deal.II. The fundamental idea of these packed data
- * types is to use one single CPU instruction to perform arithmetic
- * operations on the whole array using the processor's vector units. Most
- * computer systems by 2010 standards will use an array of two doubles and
- * four floats, respectively (this corresponds to the SSE/SSE2 data sets)
- * when compiling deal.II on 64-bit operating systems. On Intel Sandy Bridge
- * processors and newer or AMD Bulldozer processors and newer, four doubles
- * and eight floats are used when deal.II is configured e.g. using gcc with
- * --with-cpu=native or --with-cpu=corei7-avx. On compilations with AVX-512
- * support, eight doubles and sixteen floats are used.
+ * This generic class defines a unified interface to a vectorized data type.
+ * For general template arguments, this class simply corresponds to the
+ * template argument. For example, VectorizedArray<long double> is nothing
+ * else but a wrapper around <tt>long double</tt> with exactly one data field
+ * of type <tt>long double</tt> and overloaded arithmetic operations. This
+ * means that <tt>VectorizedArray<ComplicatedType></tt> has a similar layout
+ * as ComplicatedType, provided that ComplicatedType defines basic arithmetic
+ * operations. For floats and doubles, an array of numbers are packed
+ * together, though. The number of elements packed together depend on the
+ * computer system and compiler flags that are used for compilation of
+ * deal.II. The fundamental idea of these packed data types is to use one
+ * single CPU instruction to perform arithmetic operations on the whole array
+ * using the processor's vector units. Most computer systems by 2010 standards
+ * will use an array of two doubles and four floats, respectively (this
+ * corresponds to the SSE/SSE2 data sets) when compiling deal.II on 64-bit
+ * operating systems. On Intel Sandy Bridge processors and newer or AMD
+ * Bulldozer processors and newer, four doubles and eight floats are used when
+ * deal.II is configured e.g. using gcc with --with-cpu=native or --with-
+ * cpu=corei7-avx. On compilations with AVX-512 support, eight doubles and
+ * sixteen floats are used.
*
- * This behavior of this class is made similar to the basic data types
- * double and float. The definition of a vectorized array does not
- * initialize the data field but rather leaves it undefined, as is the case
- * for double and float. However, when calling something like
- * VectorizedArray<double> a = VectorizedArray<double>(), it sets all numbers in this
- * field to zero. In other words, this class is a plain old data (POD) type
- * which has an equivalent C representation and can e.g. be safely copied
- * with std::memcpy. This POD layout is also necessary for ensuring correct
- * alignment of data with address boundaries when collected in a vector
- * (i.e., when the first element in a vector is properly aligned, all
- * subsequent elements will be correctly aligned, too).
+ * This behavior of this class is made similar to the basic data types double
+ * and float. The definition of a vectorized array does not initialize the
+ * data field but rather leaves it undefined, as is the case for double and
+ * float. However, when calling something like VectorizedArray<double> a =
+ * VectorizedArray<double>(), it sets all numbers in this field to zero. In
+ * other words, this class is a plain old data (POD) type which has an
+ * equivalent C representation and can e.g. be safely copied with std::memcpy.
+ * This POD layout is also necessary for ensuring correct alignment of data
+ * with address boundaries when collected in a vector (i.e., when the first
+ * element in a vector is properly aligned, all subsequent elements will be
+ * correctly aligned, too).
*
* Note that for proper functioning of this class, certain data alignment
- * rules must be respected. This is because the computer expects the
- * starting address of a VectorizedArray<double> field at specific addresses
- * in memory (usually, the address of the vectorized array should be a
- * multiple of the length of the array in bytes). Otherwise, a segmentation
- * fault or a severe loss of performance might occur. When creating a single
- * data field on the stack like <tt>VectorizedArray<double> a =
- * VectorizedArray<double>()</tt>, the compiler will take care of data
- * alignment automatically. However, when allocating a long vector of
- * VectorizedArray<double> data, one needs to respect these rules. Use the
- * class AlignedVector or data containers based on AlignedVector (such as
- * Table) for this purpose. It is a class very similar to
- * std::vector otherwise but always makes sure that data is correctly
- * aligned.
+ * rules must be respected. This is because the computer expects the starting
+ * address of a VectorizedArray<double> field at specific addresses in memory
+ * (usually, the address of the vectorized array should be a multiple of the
+ * length of the array in bytes). Otherwise, a segmentation fault or a severe
+ * loss of performance might occur. When creating a single data field on the
+ * stack like <tt>VectorizedArray<double> a = VectorizedArray<double>()</tt>,
+ * the compiler will take care of data alignment automatically. However, when
+ * allocating a long vector of VectorizedArray<double> data, one needs to
+ * respect these rules. Use the class AlignedVector or data containers based
+ * on AlignedVector (such as Table) for this purpose. It is a class very
+ * similar to std::vector otherwise but always makes sure that data is
+ * correctly aligned.
*
* @author Katharina Kormann, Martin Kronbichler, 2010, 2011
*/
/**
- * Computes the tangent of a vectorized data field. The result is returned as
- * vectorized array in the form <tt>{tan(x[0]), tan(x[1]), ...,
+ * Computes the tangent of a vectorized data field. The result is returned
+ * as vectorized array in the form <tt>{tan(x[0]), tan(x[1]), ...,
* tan(x[n_array_elements-1])}</tt>.
*
* @relates VectorizedArray
/**
- * Computes the exponential of a vectorized data field. The result is returned
- * as vectorized array in the form <tt>{exp(x[0]), exp(x[1]), ...,
+ * Computes the exponential of a vectorized data field. The result is
+ * returned as vectorized array in the form <tt>{exp(x[0]), exp(x[1]), ...,
* exp(x[n_array_elements-1])}</tt>.
*
* @relates VectorizedArray
/**
- * Computes the square root of a vectorized data field. The result is returned
- * as vectorized array in the form <tt>{sqrt(x[0]), sqrt(x[1]), ...,
- * sqrt(x[n_array_elements-1])}</tt>.
+ * Computes the square root of a vectorized data field. The result is
+ * returned as vectorized array in the form <tt>{sqrt(x[0]), sqrt(x[1]),
+ * ..., sqrt(x[n_array_elements-1])}</tt>.
*
* @relates VectorizedArray
*/
/**
- * A namespace whose main template function supports running multiple
- * threads each of which operates on a subset of the given range of
- * objects. The class uses the Intel Threading Building Blocks (TBB)
- * to load balance the individual subranges onto the available
- * threads. For a lengthy discussion of the rationale of this class,
- * see the @ref threads "Parallel computing with multiple processors"
- * module. It is used in the tutorial first in step-9, and again in
- * step-13, step-14, step-32 and others.
+ * A namespace whose main template function supports running multiple threads
+ * each of which operates on a subset of the given range of objects. The class
+ * uses the Intel Threading Building Blocks (TBB) to load balance the
+ * individual subranges onto the available threads. For a lengthy discussion
+ * of the rationale of this class, see the @ref threads "Parallel computing
+ * with multiple processors" module. It is used in the tutorial first in
+ * step-9, and again in step-13, step-14, step-32 and others.
*
* The class is built on the following premise: One frequently has some work
* that needs to be done on a sequence of objects; a prototypical example is
* shared memory. However, some other part of this work may need to be
* synchronised and be done in order. In the example of assembling a matrix,
* the computation of local contributions can be done entirely in parallel,
- * but copying the local contributions into the global matrix requires
- * some care: First, several threads can't write at the same time, but need to
+ * but copying the local contributions into the global matrix requires some
+ * care: First, several threads can't write at the same time, but need to
* synchronise writing using a mutex; secondly, we want the order in which
* local contributions are added to the global matrix to be always the same
* because floating point addition is not commutative and adding local
* contributions to the global matrix in different orders leads to subtly
* different results that can affect the number of iterations for iterative
- * solvers as well as the round-off error in the solution in random
- * ways. Consequently, we want to ensure that only one thread at a time writes
- * into the global matrix, and that results are copied in a stable and
- * reproducible order.
+ * solvers as well as the round-off error in the solution in random ways.
+ * Consequently, we want to ensure that only one thread at a time writes into
+ * the global matrix, and that results are copied in a stable and reproducible
+ * order.
*
* This class implements a framework for this work model. It works with a
* stream of objects given by an iterator range, runs a worker function in
* created (typically as many as there are processor cores), but the number of
* items that may be active at any given time is specified by the argument to
* the constructor. It should be bigger or equal to the number of processor
- * cores - the default is four times the number of cores on the current system.
+ * cores - the default is four times the number of cores on the current
+ * system.
*
* Items are created upon request by the TBB whenever one of the worker
* threads is idle or is expected to become idle. It is then handed off to a
* Typically, worker functions need additional data, for example FEValues
* objects, input data vectors, etc, some of which can not be shared among
* threads. To this end, the run() function takes another template argument,
- * ScratchData, which designates a type objects of which are stored with
- * each item and which threads can use as private data without having to
- * share them with other threads. The run() function takes an additional
- * argument with an object of type ScratchData that is going to be copied
- * for the arguments passed to each of the worker functions.
+ * ScratchData, which designates a type objects of which are stored with each
+ * item and which threads can use as private data without having to share them
+ * with other threads. The run() function takes an additional argument with an
+ * object of type ScratchData that is going to be copied for the arguments
+ * passed to each of the worker functions.
*
- * In addition, worker functions store their results in objects of template type
- * CopyData. These are then handed off to a separate function, called copier,
- * that may use the stored results to transfer them into permanent
+ * In addition, worker functions store their results in objects of template
+ * type CopyData. These are then handed off to a separate function, called
+ * copier, that may use the stored results to transfer them into permanent
* storage. For example, it may copy the results of local contributions to a
* matrix computed by a worker function into the global matrix. In contrast to
* the worker function, however, only one instance of the copier is run at any
* given time; it can therefore safely copy local contributions into the
* global matrix without the need to lock the global object using a mutex or
* similar means. Furthermore, it is guaranteed that the copier is run with
- * CopyData objects in the same order in which their associated items
- * were created; consequently, even if worker threads may compute results in
+ * CopyData objects in the same order in which their associated items were
+ * created; consequently, even if worker threads may compute results in
* unspecified order, the copier always receives the results in exactly the
* same order as the items were created.
*
- * Once an item is processed by the copier, it is deleted and the
- * ScratchData and CopyData objects that were used in its computation
- * are considered unused and may be re-used for the next invokation of
- * the worker function, on this or another thread.
+ * Once an item is processed by the copier, it is deleted and the ScratchData
+ * and CopyData objects that were used in its computation are considered
+ * unused and may be re-used for the next invokation of the worker function,
+ * on this or another thread.
*
* The functions in this namespace only really work in parallel when
* multithread mode was selected during deal.II configuration. Otherwise they
* Bangerth (see @ref workstream_paper).
*
* Even though this implementation is slower than the third implementation
- * discussed in that paper, we need to keep it around for two reasons:
- * (i) a user may not give us a graph coloring, (ii) we want to use
- * this implementation for colors that are just too small.
+ * discussed in that paper, we need to keep it around for two reasons: (i)
+ * a user may not give us a graph coloring, (ii) we want to use this
+ * implementation for colors that are just too small.
*/
namespace Implementation2
{
struct ItemType
{
/**
- * A structure that contains a pointer to a scratch data object along
- * with a flag that indicates whether this object is currently in use.
+ * A structure that contains a pointer to a scratch data object
+ * along with a flag that indicates whether this object is currently
+ * in use.
*/
struct ScratchDataObject
{
std::vector<Iterator> work_items;
/**
- * The CopyData objects that the Worker part of the pipeline
- * fills for each work item. Again, only the first n_items
- * elements are what we care about.
+ * The CopyData objects that the Worker part of the pipeline fills
+ * for each work item. Again, only the first n_items elements are
+ * what we care about.
*/
std::vector<CopyData> copy_datas;
unsigned int n_items;
/**
- * Pointer to a thread local variable identifying the scratch data objects
- * this thread will use. The initial implementation of this
- * class using thread local variables provided only a single
- * scratch object per thread. This doesn't work, because
- * the worker functions may start tasks itself and then call
+ * Pointer to a thread local variable identifying the scratch data
+ * objects this thread will use. The initial implementation of this
+ * class using thread local variables provided only a single scratch
+ * object per thread. This doesn't work, because the worker
+ * functions may start tasks itself and then call
* Threads::TaskGroup::join_all() or a similar function, which the
- * TBB scheduler may use to run something else on the current
- * thread -- for example another instance of the worker function.
- * Consequently, there would be two instances of the worker
- * function that use the same scratch object if we only
- * provided a single scratch object per thread. The solution is
- * to provide a list of scratch objects for each thread, together
- * with a flag indicating whether this scratch object is currently
- * used. If a thread needs a scratch object, it walks this list
- * until it finds an unused object, or, if there is none, creates one
- * itself. Note that we need not use synchronization primitives
- * for this process since the lists are thread-local and
- * we are guaranteed that only a single thread accesses them as long
- * as we have no yield point in between the accesses to the list.
+ * TBB scheduler may use to run something else on the current thread
+ * -- for example another instance of the worker function.
+ * Consequently, there would be two instances of the worker function
+ * that use the same scratch object if we only provided a single
+ * scratch object per thread. The solution is to provide a list of
+ * scratch objects for each thread, together with a flag indicating
+ * whether this scratch object is currently used. If a thread needs
+ * a scratch object, it walks this list until it finds an unused
+ * object, or, if there is none, creates one itself. Note that we
+ * need not use synchronization primitives for this process since
+ * the lists are thread-local and we are guaranteed that only a
+ * single thread accesses them as long as we have no yield point in
+ * between the accesses to the list.
*
- * The pointers to scratch objects stored in each of these lists must
- * be so that they are deleted on all threads when the thread
+ * The pointers to scratch objects stored in each of these lists
+ * must be so that they are deleted on all threads when the thread
* local object is destroyed. This is achieved by using shared_ptr.
*
- * Note that when a worker needs to create a scratch object, it allocates
- * it using sample_scratch_data to copy from. This has
- * the advantage of a first-touch initialization, i.e., the
- * memory for the scratch data object is allocated and initialized
- * by the same thread that will later use it.
+ * Note that when a worker needs to create a scratch object, it
+ * allocates it using sample_scratch_data to copy from. This has the
+ * advantage of a first-touch initialization, i.e., the memory for
+ * the scratch data object is allocated and initialized by the same
+ * thread that will later use it.
*/
Threads::ThreadLocalStorage<ScratchDataList> *scratch_data;
/**
- * Default constructor.
- * Initialize everything that doesn't have a default constructor
- * itself.
+ * Default constructor. Initialize everything that doesn't have a
+ * default constructor itself.
*/
ItemType ()
:
/**
* Constructor. Take an iterator range, the size of a buffer that can
- * hold items, and the sample additional data object that will be passed
- * to each worker and copier function invokation.
+ * hold items, and the sample additional data object that will be
+ * passed to each worker and copier function invokation.
*/
IteratorRangeToItemStream (const Iterator &begin,
const Iterator &end,
/**
- * Create an item and return a
- * pointer to it.
+ * Create an item and return a pointer to it.
*/
virtual void *operator () (void *)
{
private:
/**
- * The interval of iterators still to
- * be worked on. This range will shrink
- * over time.
+ * The interval of iterators still to be worked on. This range will
+ * shrink over time.
*/
std::pair<Iterator,Iterator> remaining_iterator_range;
std::vector<ItemType> item_buffer;
/**
- * Pointer to a thread local variable identifying the scratch data objects
- * this thread will use. The initial implementation of this
- * class using thread local variables provided only a single
- * scratch object per thread. This doesn't work, because
- * the worker functions may start tasks itself and then call
- * Threads::TaskGroup::join_all() or a similar function, which the
- * TBB scheduler may use to run something else on the current
- * thread -- for example another instance of the worker function.
- * Consequently, there would be two instances of the worker
- * function that use the same scratch object if we only
- * provided a single scratch object per thread. The solution is
- * to provide a list of scratch objects for each thread, together
- * with a flag indicating whether this scratch object is currently
- * used. If a thread needs a scratch object, it walks this list
- * until it finds an unused object, or, if there is none, creates one
- * itself. Note that we need not use synchronization primitives
- * for this process since the lists are thread-local and
- * we are guaranteed that only a single thread accesses them as long
- * as we have no yield point in between the accesses to the list.
+ * Pointer to a thread local variable identifying the scratch data
+ * objects this thread will use. The initial implementation of this
+ * class using thread local variables provided only a single scratch
+ * object per thread. This doesn't work, because the worker functions
+ * may start tasks itself and then call Threads::TaskGroup::join_all()
+ * or a similar function, which the TBB scheduler may use to run
+ * something else on the current thread -- for example another
+ * instance of the worker function. Consequently, there would be two
+ * instances of the worker function that use the same scratch object
+ * if we only provided a single scratch object per thread. The
+ * solution is to provide a list of scratch objects for each thread,
+ * together with a flag indicating whether this scratch object is
+ * currently used. If a thread needs a scratch object, it walks this
+ * list until it finds an unused object, or, if there is none, creates
+ * one itself. Note that we need not use synchronization primitives
+ * for this process since the lists are thread-local and we are
+ * guaranteed that only a single thread accesses them as long as we
+ * have no yield point in between the accesses to the list.
*
* The pointers to scratch objects stored in each of these lists must
- * be so that they are deleted on all threads when the thread
- * local object is destroyed. This is achieved by using shared_ptr.
+ * be so that they are deleted on all threads when the thread local
+ * object is destroyed. This is achieved by using shared_ptr.
*
- * Note that when a worker needs to create a scratch object, it allocates
- * it using sample_scratch_data to copy from. This has
- * the advantage of a first-touch initialization, i.e., the
- * memory for the scratch data object is allocated and initialized
- * by the same thread that will later use it.
+ * Note that when a worker needs to create a scratch object, it
+ * allocates it using sample_scratch_data to copy from. This has the
+ * advantage of a first-touch initialization, i.e., the memory for the
+ * scratch data object is allocated and initialized by the same thread
+ * that will later use it.
*/
Threads::ThreadLocalStorage<typename ItemType::ScratchDataList> thread_local_scratch;
/**
* A reference to a sample scratch data that will be used to
- * initialize the thread-local pointers to a scratch data object
- * each of the worker tasks uses.
+ * initialize the thread-local pointers to a scratch data object each
+ * of the worker tasks uses.
*/
const ScratchData &sample_scratch_data;
/**
- * Number of elements of the
- * iterator range that each
- * thread should work on
- * sequentially; a large number
- * makes sure that each thread
- * gets a significant amount of
- * work before the next task
- * switch happens, whereas a
- * small number is better for
- * load balancing.
+ * Number of elements of the iterator range that each thread should
+ * work on sequentially; a large number makes sure that each thread
+ * gets a significant amount of work before the next task switch
+ * happens, whereas a small number is better for load balancing.
*/
const unsigned int chunk_size;
/**
- * Initialize the pointers and vector
- * elements in the specified entry of
- * the item_buffer.
+ * Initialize the pointers and vector elements in the specified entry
+ * of the item_buffer.
*/
void init_buffer_elements (const unsigned int element,
const CopyData &sample_copy_data)
/**
- * A class that manages calling the
- * worker function on a number of
- * parallel threads. Note that it is, in
- * the TBB notation, a filter that can
- * run in parallel.
+ * A class that manages calling the worker function on a number of
+ * parallel threads. Note that it is, in the TBB notation, a filter that
+ * can run in parallel.
*/
template <typename Iterator,
typename ScratchData,
{
public:
/**
- * Constructor. Takes a
- * reference to the object on
- * which we will operate as
- * well as a pointer to the
- * function that will do the
+ * Constructor. Takes a reference to the object on which we will
+ * operate as well as a pointer to the function that will do the
* assembly.
*/
Worker (const std_cxx11::function<void (const Iterator &,
private:
/**
- * Pointer to the function
- * that does the assembling
- * on the sequence of cells.
+ * Pointer to the function that does the assembling on the sequence of
+ * cells.
*/
const std_cxx11::function<void (const Iterator &,
ScratchData &,
CopyData &)> worker;
/**
- * This flag is true if the copier stage exist. If it does not,
- * the worker has to free the buffer. Otherwise the copier will do it.
+ * This flag is true if the copier stage exist. If it does not, the
+ * worker has to free the buffer. Otherwise the copier will do it.
*/
bool copier_exist;
};
/**
- * A class that manages calling the
- * copier function. Note that it is, in
- * the TBB notation, a filter that runs
- * sequentially, ensuring that all items
- * are copied in the same order in which
- * they are created.
+ * A class that manages calling the copier function. Note that it is, in
+ * the TBB notation, a filter that runs sequentially, ensuring that all
+ * items are copied in the same order in which they are created.
*/
template <typename Iterator,
typename ScratchData,
{
public:
/**
- * Constructor. Takes a
- * reference to the object on
- * which we will operate as
- * well as a pointer to the
- * function that will do the
- * copying from the
- * additional data object to
- * the global matrix or
+ * Constructor. Takes a reference to the object on which we will
+ * operate as well as a pointer to the function that will do the
+ * copying from the additional data object to the global matrix or
* similar.
*/
Copier (const std_cxx11::function<void (const CopyData &)> &copier)
namespace Implementation3
{
/**
- * A structure that contains a pointer to scratch and copy data objects along
- * with a flag that indicates whether this object is currently in use.
+ * A structure that contains a pointer to scratch and copy data objects
+ * along with a flag that indicates whether this object is currently in
+ * use.
*/
template <typename Iterator,
typename ScratchData,
/**
- * A class that manages calling the worker and copier functions. Unlike the
- * other implementations, parallel_for is used instead of a pipeline.
+ * A class that manages calling the worker and copier functions. Unlike
+ * the other implementations, parallel_for is used instead of a
+ * pipeline.
*/
template <typename Iterator,
typename ScratchData,
Threads::ThreadLocalStorage<ScratchAndCopyDataList> data;
/**
- * Pointer to the function
- * that does the assembling
- * on the sequence of cells.
+ * Pointer to the function that does the assembling on the sequence of
+ * cells.
*/
const std_cxx11::function<void (const Iterator &,
ScratchData &,
CopyData &)> worker;
/**
- * Pointer to the function that does the copying from
- * local contribution to global object.
+ * Pointer to the function that does the copying from local
+ * contribution to global object.
*/
const std_cxx11::function<void (const CopyData &)> copier;
/**
- * References to sample scratch and copy data for
- * when we need them.
+ * References to sample scratch and copy data for when we need them.
*/
const ScratchData &sample_scratch_data;
const CopyData &sample_copy_data;
/**
- * This is one of two main functions of the WorkStream concept, doing work as
- * described in the introduction to this namespace. It corresponds to
- * implementation 3 of the paper by Turcksin, Kronbichler and Bangerth,
- * see @ref workstream_paper .
- * As such, it takes not a range of iterators described by a begin
- * and end iterator, but a "colored" graph of iterators where each
- * color represents cells for which writing the cell contributions into
- * the global object does not conflict (in other words, these cells
- * are not neighbors). Each "color" is represented by std::vectors of cells.
- * The first argument to this function, a set of sets of cells (which are
- * represent as a vector of vectors, for efficiency), is typically
- * constructed by calling GraphColoring::make_graph_coloring(). See there
- * for more information.
+ * This is one of two main functions of the WorkStream concept, doing work
+ * as described in the introduction to this namespace. It corresponds to
+ * implementation 3 of the paper by Turcksin, Kronbichler and Bangerth, see
+ * @ref workstream_paper . As such, it takes not a range of iterators
+ * described by a begin and end iterator, but a "colored" graph of iterators
+ * where each color represents cells for which writing the cell
+ * contributions into the global object does not conflict (in other words,
+ * these cells are not neighbors). Each "color" is represented by
+ * std::vectors of cells. The first argument to this function, a set of sets
+ * of cells (which are represent as a vector of vectors, for efficiency), is
+ * typically constructed by calling GraphColoring::make_graph_coloring().
+ * See there for more information.
*
- * This function that can be used for worker and copier objects that
- * are either pointers to non-member functions or objects that allow to be
+ * This function that can be used for worker and copier objects that are
+ * either pointers to non-member functions or objects that allow to be
* called with an operator(), for example objects created by std::bind.
*
* The two data types <tt>ScratchData</tt> and <tt>CopyData</tt> need to
/**
- * This is one of two main functions of the WorkStream concept, doing work as
- * described in the introduction to this namespace. It corresponds to
- * implementation 2 of the paper by Turcksin, Kronbichler and Bangerth
- * (see @ref workstream_paper).
+ * This is one of two main functions of the WorkStream concept, doing work
+ * as described in the introduction to this namespace. It corresponds to
+ * implementation 2 of the paper by Turcksin, Kronbichler and Bangerth (see
+ * @ref workstream_paper).
*
- * This function that can be used for worker and copier objects that
- * are either pointers to non-member functions or objects that allow to be
+ * This function that can be used for worker and copier objects that are
+ * either pointers to non-member functions or objects that allow to be
* called with an operator(), for example objects created by std::bind. If
* the copier is an empty function, it is ignored in the pipeline.
*
/**
* Collection of functions controlling refinement and coarsening of
- * parallel::distributed::Triangulation objects. This namespace
- * provides similar functionality to the dealii::GridRefinement
- * namespace, except that it works for meshes that are parallel and
- * distributed.
+ * parallel::distributed::Triangulation objects. This namespace provides
+ * similar functionality to the dealii::GridRefinement namespace, except
+ * that it works for meshes that are parallel and distributed.
*
* @ingroup grid
* @author Wolfgang Bangerth, 2009
namespace GridRefinement
{
/**
- * Like
- * dealii::GridRefinement::refine_and_coarsen_fixed_number,
- * but for parallel distributed
- * triangulation.
+ * Like dealii::GridRefinement::refine_and_coarsen_fixed_number, but for
+ * parallel distributed triangulation.
*
- * The vector of criteria needs to be a
- * vector of refinement criteria for
- * all cells active on the current
- * triangulation,
- * i.e. <code>tria.n_active_cells()</code>
- * (and not
- * <code>tria.n_locally_owned_active_cells()</code>). However,
- * the function will only look at the
- * indicators that correspond to those
- * cells that are actually locally
- * owned, and ignore the indicators for
- * all other cells. The function will
- * then coordinate among all processors
- * that store part of the triangulation
- * so that at the end @p
- * top_fraction_of_cells are refined,
- * where the fraction is enforced as a
- * fraction of
- * Triangulation::n_global_active_cells,
- * not
- * Triangulation::n_locally_active_cells
- * on each processor individually. In
- * other words, it may be that on some
- * processors, no cells are refined at
- * all.
+ * The vector of criteria needs to be a vector of refinement criteria
+ * for all cells active on the current triangulation, i.e.
+ * <code>tria.n_active_cells()</code> (and not
+ * <code>tria.n_locally_owned_active_cells()</code>). However, the
+ * function will only look at the indicators that correspond to those
+ * cells that are actually locally owned, and ignore the indicators for
+ * all other cells. The function will then coordinate among all
+ * processors that store part of the triangulation so that at the end @p
+ * top_fraction_of_cells are refined, where the fraction is enforced as
+ * a fraction of Triangulation::n_global_active_cells, not
+ * Triangulation::n_locally_active_cells on each processor individually.
+ * In other words, it may be that on some processors, no cells are
+ * refined at all.
*
- * The same is true for the fraction of
- * cells that is coarsened.
+ * The same is true for the fraction of cells that is coarsened.
*/
template <int dim, class Vector, int spacedim>
void
const double bottom_fraction_of_cells);
/**
- * Like
- * dealii::GridRefinement::refine_and_coarsen_fixed_fraction,
- * but for parallel distributed
- * triangulation.
+ * Like dealii::GridRefinement::refine_and_coarsen_fixed_fraction, but
+ * for parallel distributed triangulation.
*
- * The vector of criteria needs to be a
- * vector of refinement criteria for
- * all cells active on the current
- * triangulation,
- * <code>tria.n_active_cells()</code>
- * (and not
- * <code>tria.n_locally_owned_active_cells()</code>). However,
- * the function will only look at the
- * indicators that correspond to those
- * cells that are actually locally
- * owned, and ignore the indicators for
- * all other cells. The function will
- * then coordinate among all processors
- * that store part of the triangulation
- * so that at the end the smallest
- * fraction of
- * Triangulation::n_global_active_cells
- * (not
- * Triangulation::n_locally_active_cells
- * on each processor individually) is
- * refined that together make up a
- * total of @p top_fraction_of_error of
- * the total error. In other words, it
- * may be that on some processors, no
- * cells are refined at all.
+ * The vector of criteria needs to be a vector of refinement criteria
+ * for all cells active on the current triangulation,
+ * <code>tria.n_active_cells()</code> (and not
+ * <code>tria.n_locally_owned_active_cells()</code>). However, the
+ * function will only look at the indicators that correspond to those
+ * cells that are actually locally owned, and ignore the indicators for
+ * all other cells. The function will then coordinate among all
+ * processors that store part of the triangulation so that at the end
+ * the smallest fraction of Triangulation::n_global_active_cells (not
+ * Triangulation::n_locally_active_cells on each processor individually)
+ * is refined that together make up a total of @p top_fraction_of_error
+ * of the total error. In other words, it may be that on some
+ * processors, no cells are refined at all.
*
- * The same is true for the fraction of
- * cells that is coarsened.
+ * The same is true for the fraction of cells that is coarsened.
*/
template <int dim, class Vector, int spacedim>
void
{
/**
* Transfers a discrete FE function (like a solution vector) by
- * interpolation while refining and/or
- * coarsening a distributed grid and
+ * interpolation while refining and/or coarsening a distributed grid and
* handles the necessary communication.
*
* @note It is important to note, that if you use more than one
- * SolutionTransfer object at the same time, that the calls to
- * prepare_*() and interpolate()/deserialize() need to be in the same order.
+ * SolutionTransfer object at the same time, that the calls to prepare_*()
+ * and interpolate()/deserialize() need to be in the same order.
*
- * <h3>Note on ghost elements</h3>
- * In a parallel computation PETSc or Trilinos vector may contain ghost
- * elements or not. For reading in information with
- * prepare_for_coarsening_and_refinement() or prepare_serialization() you need
- * to supply vectors with ghost elements, so that all locally_active elements
- * can be read. On the other hand, ghosted vectors are generally not writable,
- * so for calls to interpolate() or deserialize() you need to supply
- * distributed vectors without ghost elements.
+ * <h3>Note on ghost elements</h3> In a parallel computation PETSc or
+ * Trilinos vector may contain ghost elements or not. For reading in
+ * information with prepare_for_coarsening_and_refinement() or
+ * prepare_serialization() you need to supply vectors with ghost elements,
+ * so that all locally_active elements can be read. On the other hand,
+ * ghosted vectors are generally not writable, so for calls to
+ * interpolate() or deserialize() you need to supply distributed vectors
+ * without ghost elements.
*
- * <h3>Transfering a solution</h3>
- * Here VECTOR is your favorite vector type, e.g. PETScWrappers::MPI::Vector,
- * TrilinosWrappers::MPI::Vector, or corresponding blockvectors.
+ * <h3>Transfering a solution</h3> Here VECTOR is your favorite vector
+ * type, e.g. PETScWrappers::MPI::Vector, TrilinosWrappers::MPI::Vector,
+ * or corresponding blockvectors.
* @code
- SolutionTransfer<dim, VECTOR> soltrans(dof_handler);
- // flag some cells for refinement
- // and coarsening, e.g.
- GridRefinement::refine_and_coarsen_fixed_fraction(
- tria, error_indicators, 0.3, 0.05);
- // prepare the triangulation,
- tria.prepare_coarsening_and_refinement();
- // prepare the SolutionTransfer object
- // for coarsening and refinement and give
- // the solution vector that we intend to
- // interpolate later,
- soltrans.prepare_for_coarsening_and_refinement(solution);
- // actually execute the refinement,
- tria.execute_coarsening_and_refinement ();
- // redistribute dofs,
- dof_handler.distribute_dofs (fe);
- // and interpolate the solution
- VECTOR interpolated_solution;
- //create VECTOR in the right size here
- soltrans.interpolate(interpolated_solution);
- @endcode
+ * SolutionTransfer<dim, VECTOR> soltrans(dof_handler);
+ * // flag some cells for refinement
+ * // and coarsening, e.g.
+ * GridRefinement::refine_and_coarsen_fixed_fraction(
+ * tria, error_indicators, 0.3, 0.05);
+ * // prepare the triangulation,
+ * tria.prepare_coarsening_and_refinement();
+ * // prepare the SolutionTransfer object
+ * // for coarsening and refinement and give
+ * // the solution vector that we intend to
+ * // interpolate later,
+ * soltrans.prepare_for_coarsening_and_refinement(solution);
+ * // actually execute the refinement,
+ * tria.execute_coarsening_and_refinement ();
+ * // redistribute dofs,
+ * dof_handler.distribute_dofs (fe);
+ * // and interpolate the solution
+ * VECTOR interpolated_solution;
+ * //create VECTOR in the right size here
+ * soltrans.interpolate(interpolated_solution);
+ * @endcode
*
* <h3>Use for Serialization</h3>
*
- * This class can be used to serialize and later deserialize a distributed mesh with solution vectors
- * to a file. If you use more than one DoFHandler and therefore more than one SolutionTransfer object, they need to be serialized and deserialized in the same order.
+ * This class can be used to serialize and later deserialize a distributed
+ * mesh with solution vectors to a file. If you use more than one
+ * DoFHandler and therefore more than one SolutionTransfer object, they
+ * need to be serialized and deserialized in the same order.
*
- * If vector has the locally relevant DoFs, serialization works as follows:
- *@code
-
- parallel::distributed::SolutionTransfer<dim,VECTOR> sol_trans(dof_handler);
- sol_trans.prepare_serialization (vector);
-
- triangulation.save(filename);
- @endcode
- * For deserialization the vector needs to be a distributed vector (without ghost elements):
- * @code
- //[create coarse mesh...]
- triangulation.load(filename);
-
- parallel::distributed::SolutionTransfer<dim,VECTOR> sol_trans(dof_handler);
- sol_trans.deserialize (distributed_vector);
- @endcode
+ * If vector has the locally relevant DoFs, serialization works as
+ * follows:
+ * *@code
+ *
+ * parallel::distributed::SolutionTransfer<dim,VECTOR> sol_trans(dof_handler);
+ * sol_trans.prepare_serialization (vector);
+ *
+ * triangulation.save(filename);
+ * @endcode
+ * For deserialization the vector needs to be a distributed vector
+ * (without ghost elements):
+ * @code
+ * //[create coarse mesh...]
+ * triangulation.load(filename);
+ *
+ * parallel::distributed::SolutionTransfer<dim,VECTOR> sol_trans(dof_handler);
+ * sol_trans.deserialize (distributed_vector);
+ * @endcode
*
*
* <h3>Interaction with hanging nodes</h3>
{
public:
/**
- * Constructor, takes the current DoFHandler
- * as argument.
+ * Constructor, takes the current DoFHandler as argument.
*/
SolutionTransfer(const DH &dof);
/**
~SolutionTransfer();
/**
- * Prepares the @p SolutionTransfer for
- * coarsening and refinement. It
- * stores the dof indices of each cell and
- * stores the dof values of the vectors in
- * @p all_in in each cell that'll be coarsened.
- * @p all_in includes all vectors
- * that are to be interpolated
- * onto the new (refined and/or
- * coarsenend) grid.
+ * Prepares the @p SolutionTransfer for coarsening and refinement. It
+ * stores the dof indices of each cell and stores the dof values of the
+ * vectors in @p all_in in each cell that'll be coarsened. @p all_in
+ * includes all vectors that are to be interpolated onto the new
+ * (refined and/or coarsenend) grid.
*/
void prepare_for_coarsening_and_refinement (const std::vector<const VECTOR *> &all_in);
/**
- * Same as previous function
- * but for only one discrete function
- * to be interpolated.
+ * Same as previous function but for only one discrete function to be
+ * interpolated.
*/
void prepare_for_coarsening_and_refinement (const VECTOR &in);
/**
- * Interpolate the data previously stored in this object before
- * the mesh was refined or coarsened onto the current set of
- * cells. Do so for each of the vectors provided to
- * prepare_for_coarsening_and_refinement() and write the result into
- * the given set of vectors.
+ * Interpolate the data previously stored in this object before the mesh
+ * was refined or coarsened onto the current set of cells. Do so for
+ * each of the vectors provided to
+ * prepare_for_coarsening_and_refinement() and write the result into the
+ * given set of vectors.
*/
void interpolate (std::vector<VECTOR *> &all_out);
/**
- * Same as the previous function.
- * It interpolates only one function.
- * It assumes the vectors having the
- * right sizes (i.e. <tt>in.size()==n_dofs_old</tt>,
- * <tt>out.size()==n_dofs_refined</tt>)
+ * Same as the previous function. It interpolates only one function. It
+ * assumes the vectors having the right sizes (i.e.
+ * <tt>in.size()==n_dofs_old</tt>, <tt>out.size()==n_dofs_refined</tt>)
*
- * Multiple calling of this function is
- * NOT allowed. Interpolating
- * several functions can be performed
- * in one step by using
+ * Multiple calling of this function is NOT allowed. Interpolating
+ * several functions can be performed in one step by using
* <tt>interpolate (all_in, all_out)</tt>
*/
void interpolate (VECTOR &out);
/**
- * Return the size in bytes that need
- * to be stored per cell.
+ * Return the size in bytes that need to be stored per cell.
*/
unsigned int get_data_size() const;
/**
- * Prepare the serialization of the
- * given vector. The serialization is
- * done by Triangulation::save(). The
- * given vector needs all information
- * on the locally active DoFs (it must
- * be ghosted). See documentation of
- * this class for more information.
- */
+ * Prepare the serialization of the given vector. The serialization is
+ * done by Triangulation::save(). The given vector needs all information
+ * on the locally active DoFs (it must be ghosted). See documentation of
+ * this class for more information.
+ */
void prepare_serialization(const VECTOR &in);
/**
- * Same as the function above, only
- * for a list of vectors.
+ * Same as the function above, only for a list of vectors.
*/
void prepare_serialization(const std::vector<const VECTOR *> &all_in);
/**
- * Execute the deserialization of the
- * given vector. This needs to be
- * done after calling
- * Triangulation::load(). The given
- * vector must be a fully distributed
- * vector without ghost elements. See
- * documentation of this class for
- * more information.
+ * Execute the deserialization of the given vector. This needs to be
+ * done after calling Triangulation::load(). The given vector must be a
+ * fully distributed vector without ghost elements. See documentation of
+ * this class for more information.
*/
void deserialize(VECTOR &in);
/**
- * Same as the function above, only
- * for a list of vectors.
+ * Same as the function above, only for a list of vectors.
*/
void deserialize(std::vector<VECTOR *> &all_in);
private:
/**
- * Pointer to the degree of
- * freedom handler to work
- * with.
+ * Pointer to the degree of freedom handler to work with.
*/
SmartPointer<const DH,SolutionTransfer<dim,VECTOR,DH> > dof_handler;
/**
- * A vector that stores
- * pointers to all the
- * vectors we are supposed to
- * copy over from the old to
- * the new mesh.
+ * A vector that stores pointers to all the vectors we are supposed to
+ * copy over from the old to the new mesh.
*/
std::vector<const VECTOR *> input_vectors;
/**
- * The offset that the
- * Triangulation has assigned
- * to this object starting at
- * which we are allowed to
- * write.
+ * The offset that the Triangulation has assigned to this object
+ * starting at which we are allowed to write.
*/
unsigned int offset;
/**
- * A callback function used
- * to pack the data on the
- * current mesh into objects
- * that can later be
- * retrieved after
- * refinement, coarsening and
+ * A callback function used to pack the data on the current mesh into
+ * objects that can later be retrieved after refinement, coarsening and
* repartitioning.
*/
void pack_callback(const typename Triangulation<dim,dim>::cell_iterator &cell,
void *data);
/**
- * A callback function used
- * to unpack the data on the
- * current mesh that has been
- * packed up previously on
- * the mesh before
- * refinement, coarsening and
- * repartitioning.
+ * A callback function used to unpack the data on the current mesh that
+ * has been packed up previously on the mesh before refinement,
+ * coarsening and repartitioning.
*/
void unpack_callback(const typename Triangulation<dim,dim>::cell_iterator &cell,
const typename Triangulation<dim,dim>::CellStatus status,
namespace p4est
{
/**
- * A structure whose explicit specializations contain typedefs to
- * the relevant p4est_* and p8est_* types. Using this structure,
- * for example by saying <code>types@<dim@>::connectivity</code>
- * we can write code in a dimension independent way, either
- * referring to p4est_connectivity_t or p8est_connectivity_t,
- * depending on template argument.
+ * A structure whose explicit specializations contain typedefs to the
+ * relevant p4est_* and p8est_* types. Using this structure, for example
+ * by saying <code>types@<dim@>::connectivity</code> we can write code in
+ * a dimension independent way, either referring to p4est_connectivity_t
+ * or p8est_connectivity_t, depending on template argument.
*/
template <int> struct types;
/**
- * Initialize the GeometryInfo<dim>::max_children_per_cell
- * children of the cell p4est_cell.
+ * Initialize the GeometryInfo<dim>::max_children_per_cell children of the
+ * cell p4est_cell.
*/
template <int dim>
void
/**
* This class acts like the dealii::Triangulation class, but it
- * distributes the mesh across a number of different processors when
- * using MPI. The class's interface does not add a lot to the
+ * distributes the mesh across a number of different processors when using
+ * MPI. The class's interface does not add a lot to the
* dealii::Triangulation class but there are a number of difficult
- * algorithms under the hood that ensure we always have a
- * load-balanced, fully distributed mesh. Use of this class is
- * explained in step-40, step-32, the @ref distributed documentation
- * module, as well as the @ref distributed_paper . See there for more
- * information. This class satisfies the requirements outlined in
- * @ref GlossMeshAsAContainer "Meshes as containers".
+ * algorithms under the hood that ensure we always have a load-balanced,
+ * fully distributed mesh. Use of this class is explained in step-40,
+ * step-32, the @ref distributed documentation module, as well as the @ref
+ * distributed_paper . See there for more information. This class
+ * satisfies the requirements outlined in @ref GlossMeshAsAContainer
+ * "Meshes as containers".
*
- * @note This class does not support anisotropic refinement, because
- * it relies on the p4est library that does not support this. Attempts
- * to refine cells anisotropically will result in errors.
- * @note There is currently no support for distributing 1d triangulations.
+ * @note This class does not support anisotropic refinement, because it
+ * relies on the p4est library that does not support this. Attempts to
+ * refine cells anisotropically will result in errors. @note There is
+ * currently no support for distributing 1d triangulations.
*
*
* <h3> Interaction with boundary description </h3>
* Refining and coarsening a distributed triangulation is a complicated
* process because cells may have to be migrated from one processor to
* another. On a single processor, materializing that part of the global
- * mesh that we want to store here from what we have stored before therefore
- * may involve several cycles of refining and coarsening the locally stored
- * set of cells until we have finally gotten from the previous to the next
- * triangulation. (This process is described in more detail in the
- * @ref distributed_paper.) Unfortunately, in this process, some information
- * can get lost relating to flags that are set by user code and that are
- * inherited from mother to child cell but that are not moved along with
- * a cell if that cell is migrated from one processor to another.
+ * mesh that we want to store here from what we have stored before
+ * therefore may involve several cycles of refining and coarsening the
+ * locally stored set of cells until we have finally gotten from the
+ * previous to the next triangulation. (This process is described in more
+ * detail in the @ref distributed_paper.) Unfortunately, in this process,
+ * some information can get lost relating to flags that are set by user
+ * code and that are inherited from mother to child cell but that are not
+ * moved along with a cell if that cell is migrated from one processor to
+ * another.
*
* An example are boundary indicators. Assume, for example, that you start
- * with a single cell that is refined once globally, yielding four children.
- * If you have four processors, each one owns one cell. Assume now that processor
- * 1 sets the boundary indicators of the external boundaries of the cell it owns
- * to 42. Since processor 0 does not own this cell, it doesn't set the boundary
- * indicators of its ghost cell copy of this cell. Now, assume we do several mesh
- * refinement cycles and end up with a configuration where this processor suddenly finds itself
- * as the owner of this cell. If boundary indicator 42 means that we need to
- * integrate Neumann boundary conditions along this boundary, then processor 0
- * will forget to do so because it has never set the boundary indicator along
- * this cell's boundary to 42.
+ * with a single cell that is refined once globally, yielding four
+ * children. If you have four processors, each one owns one cell. Assume
+ * now that processor 1 sets the boundary indicators of the external
+ * boundaries of the cell it owns to 42. Since processor 0 does not own
+ * this cell, it doesn't set the boundary indicators of its ghost cell
+ * copy of this cell. Now, assume we do several mesh refinement cycles and
+ * end up with a configuration where this processor suddenly finds itself
+ * as the owner of this cell. If boundary indicator 42 means that we need
+ * to integrate Neumann boundary conditions along this boundary, then
+ * processor 0 will forget to do so because it has never set the boundary
+ * indicator along this cell's boundary to 42.
*
* The way to avoid this dilemma is to make sure that things like setting
- * boundary indicators or material ids is done immediately
- * every time a parallel triangulation is refined. This is not necessary
- * for sequential triangulations because, there, these flags are inherited
- * from mother to child cell and remain with a cell even if it is refined
- * and the children are later coarsened again, but this does not hold for
+ * boundary indicators or material ids is done immediately every time a
+ * parallel triangulation is refined. This is not necessary for sequential
+ * triangulations because, there, these flags are inherited from mother to
+ * child cell and remain with a cell even if it is refined and the
+ * children are later coarsened again, but this does not hold for
* distributed triangulations. It is made even more difficult by the fact
* that in the process of refining a parallel distributed triangulation,
- * the triangulation may call dealii::Triangulation::execute_coarsening_and_refinement
- * multiple times and this function needs to know about boundaries. In
- * other words, it is <i>not</i> enough to just set boundary indicators on
- * newly created faces only <i>after</i> calling
- * distributed::parallel::Triangulation::execute_coarsening_and_refinement:
- * it actually has to happen while that function is still running.
+ * the triangulation may call
+ * dealii::Triangulation::execute_coarsening_and_refinement multiple times
+ * and this function needs to know about boundaries. In other words, it is
+ * <i>not</i> enough to just set boundary indicators on newly created
+ * faces only <i>after</i> calling distributed::parallel::Triangulation::e
+ * xecute_coarsening_and_refinement: it actually has to happen while that
+ * function is still running.
*
* The way to do this is by writing a function that sets boundary
- * indicators and that will be called by the dealii::Triangulation class. The
- * triangulation does not provide a pointer to itself to the function being
- * called, nor any other information, so the trick is to get this information
- * into the function. C++ provides a nice mechanism for this that is best
- * explained using an example:
+ * indicators and that will be called by the dealii::Triangulation class.
+ * The triangulation does not provide a pointer to itself to the function
+ * being called, nor any other information, so the trick is to get this
+ * information into the function. C++ provides a nice mechanism for this
+ * that is best explained using an example:
* @code
* #include <deal.II/base/std_cxx11/bind.h>
*
* }
* @endcode
*
- * What the call to <code>std_cxx11::bind</code> does is to produce an object that
- * can be called like a function with no arguments. It does so by taking the
- * address of a function that does, in fact, take an argument but permanently fix
- * this one argument to a reference to the coarse grid triangulation. After each
- * refinement step, the triangulation will then call the object so created which
- * will in turn call <code>set_boundary_indicators<dim></code> with the reference
- * to the coarse grid as argument.
+ * What the call to <code>std_cxx11::bind</code> does is to produce an
+ * object that can be called like a function with no arguments. It does so
+ * by taking the address of a function that does, in fact, take an
+ * argument but permanently fix this one argument to a reference to the
+ * coarse grid triangulation. After each refinement step, the
+ * triangulation will then call the object so created which will in turn
+ * call <code>set_boundary_indicators<dim></code> with the reference to
+ * the coarse grid as argument.
*
- * This approach can be generalized. In the example above, we have used a global
- * function that will be called. However, sometimes it is necessary that this
- * function is in fact a member function of the class that generates the mesh,
- * for example because it needs to access run-time parameters. This can be
- * achieved as follows: assuming the <code>set_boundary_indicators()</code>
- * function has been declared as a (non-static, but possibly private) member
- * function of the <code>MyClass</code> class, then the following will work:
+ * This approach can be generalized. In the example above, we have used a
+ * global function that will be called. However, sometimes it is necessary
+ * that this function is in fact a member function of the class that
+ * generates the mesh, for example because it needs to access run-time
+ * parameters. This can be achieved as follows: assuming the
+ * <code>set_boundary_indicators()</code> function has been declared as a
+ * (non-static, but possibly private) member function of the
+ * <code>MyClass</code> class, then the following will work:
* @code
* #include <deal.II/base/std_cxx11/bind.h>
*
* std_cxx11::ref(coarse_grid)));
* }
* @endcode
- * Here, like any other member function, <code>set_boundary_indicators</code>
- * implicitly takes a pointer or reference to the object it belongs to as first
- * argument. <code>std::bind</code> again creates an object that can be called like a
- * global function with no arguments, and this object in turn calls
- * <code>set_boundary_indicators</code> with a pointer to the current object and a
- * reference to the triangulation to work on. Note that because the
- * <code>create_coarse_mesh</code> function is declared as <code>const</code>, it is
- * necessary that the <code>set_boundary_indicators</code> function is also
- * declared <code>const</code>.
+ * Here, like any other member function,
+ * <code>set_boundary_indicators</code> implicitly takes a pointer or
+ * reference to the object it belongs to as first argument.
+ * <code>std::bind</code> again creates an object that can be called like
+ * a global function with no arguments, and this object in turn calls
+ * <code>set_boundary_indicators</code> with a pointer to the current
+ * object and a reference to the triangulation to work on. Note that
+ * because the <code>create_coarse_mesh</code> function is declared as
+ * <code>const</code>, it is necessary that the
+ * <code>set_boundary_indicators</code> function is also declared
+ * <code>const</code>.
*
* <b>Note:</b>For reasons that have to do with the way the
- * parallel::distributed::Triangulation is implemented, functions that
- * have been attached to the post-refinement signal of the triangulation are
- * called more than once, sometimes several times, every time the triangulation
- * is actually refined.
+ * parallel::distributed::Triangulation is implemented, functions that
+ * have been attached to the post-refinement signal of the triangulation
+ * are called more than once, sometimes several times, every time the
+ * triangulation is actually refined.
*
*
* @author Wolfgang Bangerth, Timo Heister 2008, 2009, 2010, 2011
{
public:
/**
- * A typedef that is used to to identify cell iterators. The
- * concept of iterators is discussed at length in the
- * @ref Iterators "iterators documentation module".
+ * A typedef that is used to to identify cell iterators. The concept of
+ * iterators is discussed at length in the @ref Iterators "iterators
+ * documentation module".
*
- * The current typedef identifies cells in a triangulation. You
- * can find the exact type it refers to in the base class's own
- * typedef, but it should be TriaIterator<CellAccessor<dim,spacedim> >. The
- * TriaIterator class works like a pointer that when you
- * dereference it yields an object of type CellAccessor.
- * CellAccessor is a class that identifies properties that
- * are specific to cells in a triangulation, but it is derived
- * (and consequently inherits) from TriaAccessor that describes
- * what you can ask of more general objects (lines, faces, as
- * well as cells) in a triangulation.
+ * The current typedef identifies cells in a triangulation. You can find
+ * the exact type it refers to in the base class's own typedef, but it
+ * should be TriaIterator<CellAccessor<dim,spacedim> >. The TriaIterator
+ * class works like a pointer that when you dereference it yields an
+ * object of type CellAccessor. CellAccessor is a class that identifies
+ * properties that are specific to cells in a triangulation, but it is
+ * derived (and consequently inherits) from TriaAccessor that describes
+ * what you can ask of more general objects (lines, faces, as well as
+ * cells) in a triangulation.
*
* @ingroup Iterators
*/
typedef typename dealii::Triangulation<dim,spacedim>::cell_iterator cell_iterator;
/**
- * A typedef that is used to to identify
- * @ref GlossActive "active cell iterators". The
- * concept of iterators is discussed at length in the
+ * A typedef that is used to to identify @ref GlossActive "active cell
+ * iterators". The concept of iterators is discussed at length in the
* @ref Iterators "iterators documentation module".
*
* The current typedef identifies active cells in a triangulation. You
- * can find the exact type it refers to in the base class's own
- * typedef, but it should be TriaActiveIterator<CellAccessor<dim,spacedim> >. The
- * TriaActiveIterator class works like a pointer to active objects that when you
- * dereference it yields an object of type CellAccessor.
- * CellAccessor is a class that identifies properties that
- * are specific to cells in a triangulation, but it is derived
- * (and consequently inherits) from TriaAccessor that describes
- * what you can ask of more general objects (lines, faces, as
- * well as cells) in a triangulation.
+ * can find the exact type it refers to in the base class's own typedef,
+ * but it should be TriaActiveIterator<CellAccessor<dim,spacedim> >. The
+ * TriaActiveIterator class works like a pointer to active objects that
+ * when you dereference it yields an object of type CellAccessor.
+ * CellAccessor is a class that identifies properties that are specific
+ * to cells in a triangulation, but it is derived (and consequently
+ * inherits) from TriaAccessor that describes what you can ask of more
+ * general objects (lines, faces, as well as cells) in a triangulation.
*
* @ingroup Iterators
*/
/**
* Generic settings for distributed Triangulations. If
- * mesh_reconstruction_after_repartitioning is set, the deal.II
- * mesh will be reconstructed from the coarse mesh every time a
- * repartioning in p4est happens. This can be a bit more
- * expensive, but guarantees the same memory layout and
- * therefore cell ordering in the deal.II mesh. As assembly is
- * done in the deal.II cell ordering, this flag is required to
- * get reproducible behaviour after snapshot/resume.
+ * mesh_reconstruction_after_repartitioning is set, the deal.II mesh
+ * will be reconstructed from the coarse mesh every time a repartioning
+ * in p4est happens. This can be a bit more expensive, but guarantees
+ * the same memory layout and therefore cell ordering in the deal.II
+ * mesh. As assembly is done in the deal.II cell ordering, this flag is
+ * required to get reproducible behaviour after snapshot/resume.
*
- * The flag construct_multigrid_hierarchy needs to be set to use
- * the geometric multigrid functionality. This option requires
- * additional computation and communication. Note: geometric
- * multigrid is still a work in progress.
+ * The flag construct_multigrid_hierarchy needs to be set to use the
+ * geometric multigrid functionality. This option requires additional
+ * computation and communication. Note: geometric multigrid is still a
+ * work in progress.
*/
enum Settings
{
/**
* Constructor.
*
- * @param mpi_communicator denotes the MPI communicator to be
- * used for the triangulation.
+ * @param mpi_communicator denotes the MPI communicator to be used for
+ * the triangulation.
*
- * @param smooth_grid Degree and kind of mesh smoothing to be
- * applied to the mesh. See the dealii::Triangulation class for
- * a description of the kinds of smoothing operations that can
- * be applied.
+ * @param smooth_grid Degree and kind of mesh smoothing to be applied to
+ * the mesh. See the dealii::Triangulation class for a description of
+ * the kinds of smoothing operations that can be applied.
*
- * @param settings See the description of the Settings
- * enumerator.
+ * @param settings See the description of the Settings enumerator.
*
* @note This class does not currently support the
- * <code>check_for_distorted_cells</code> argument provided by
- * the base class.
+ * <code>check_for_distorted_cells</code> argument provided by the base
+ * class.
*
- * @note While it is possible to pass all of the mesh smoothing
- * flags listed in the base class to objects of this type, it is
- * not always possible to honor all of these smoothing options
- * if they would require knowledge of refinement/coarsening
- * flags on cells not locally owned by this processor. As a
- * consequence, for some of these flags, the ultimate number of
- * cells of the parallel triangulation may depend on the number
- * of processors into which it is partitioned. On the other
- * hand, if no smoothing flags are passed, if you always mark
- * the same cells of the mesh, you will always get the exact
- * same refined mesh independent of the number of processors
- * into which the triangulation is partitioned.
+ * @note While it is possible to pass all of the mesh smoothing flags
+ * listed in the base class to objects of this type, it is not always
+ * possible to honor all of these smoothing options if they would
+ * require knowledge of refinement/coarsening flags on cells not locally
+ * owned by this processor. As a consequence, for some of these flags,
+ * the ultimate number of cells of the parallel triangulation may depend
+ * on the number of processors into which it is partitioned. On the
+ * other hand, if no smoothing flags are passed, if you always mark the
+ * same cells of the mesh, you will always get the exact same refined
+ * mesh independent of the number of processors into which the
+ * triangulation is partitioned.
*/
Triangulation (MPI_Comm mpi_communicator,
const typename dealii::Triangulation<dim,spacedim>::MeshSmoothing
virtual ~Triangulation ();
/**
- * Reset this triangulation into a virgin state by deleting all
- * data.
+ * Reset this triangulation into a virgin state by deleting all data.
*
- * Note that this operation is only allowed if no subscriptions
- * to this object exist any more, such as DoFHandler objects
- * using it.
+ * Note that this operation is only allowed if no subscriptions to this
+ * object exist any more, such as DoFHandler objects using it.
*/
virtual void clear ();
/**
* Create a triangulation as documented in the base class.
*
- * This function also sets up the various data structures
- * necessary to distribute a mesh across a number of
- * processors. This will be necessary once the mesh is being
- * refined, though we will always keep the entire coarse mesh
- * that is generated by this function on all processors.
+ * This function also sets up the various data structures necessary to
+ * distribute a mesh across a number of processors. This will be
+ * necessary once the mesh is being refined, though we will always keep
+ * the entire coarse mesh that is generated by this function on all
+ * processors.
*/
virtual void create_triangulation (const std::vector<Point<spacedim> > &vertices,
const std::vector<CellData<dim> > &cells,
const SubCellData &subcelldata);
/**
- * Coarsen and refine the mesh according to refinement and
- * coarsening flags set.
+ * Coarsen and refine the mesh according to refinement and coarsening
+ * flags set.
*
- * Since the current processor only has control over those cells
- * it owns (i.e. the ones for which <code>cell-@>subdomain_id() ==
- * this-@>locally_owned_subdomain()</code>), refinement and
- * coarsening flags are only respected for those locally owned
- * cells. Flags may be set on other cells as well (and may
- * often, in fact, if you call
- * dealii::Triangulation::prepare_coarsening_and_refinement) but
- * will be largely ignored: the decision to refine the global
- * mesh will only be affected by flags set on locally owned
- * cells.
+ * Since the current processor only has control over those cells it owns
+ * (i.e. the ones for which <code>cell-@>subdomain_id() ==
+ * this-@>locally_owned_subdomain()</code>), refinement and coarsening
+ * flags are only respected for those locally owned cells. Flags may be
+ * set on other cells as well (and may often, in fact, if you call
+ * dealii::Triangulation::prepare_coarsening_and_refinement) but will be
+ * largely ignored: the decision to refine the global mesh will only be
+ * affected by flags set on locally owned cells.
*/
virtual void execute_coarsening_and_refinement ();
/**
- * When vertices have been moved locally, for example using code
- * like
+ * When vertices have been moved locally, for example using code like
* @code
* cell->vertex(0) = new_location;
* @endcode
- * then this function can be used to update the location of
- * vertices between MPI processes.
+ * then this function can be used to update the location of vertices
+ * between MPI processes.
*
* All the vertices that have been moved and might be in the ghost layer
- * of a process have to be reported in the @p vertex_locally_moved argument.
- * This ensures that that part of the information that has to be send
- * between processes is actually sent. Additionally, it is quite important that vertices
- * on the boundary between processes are reported on exactly one process
- * (e.g. the one with the highest id). Otherwise we could expect
- * undesirable results if multiple processes move a vertex differently.
- * A typical strategy is to let processor $i$ move those vertices that
- * are adjacent to cells whose owners include processor $i$ but no
- * other processor $j$ with $j<i$; in other words, for vertices
- * at the boundary of a subdomain, the processor with the lowest subdomain
- * id "owns" a vertex.
+ * of a process have to be reported in the @p vertex_locally_moved
+ * argument. This ensures that that part of the information that has to
+ * be send between processes is actually sent. Additionally, it is quite
+ * important that vertices on the boundary between processes are
+ * reported on exactly one process (e.g. the one with the highest id).
+ * Otherwise we could expect undesirable results if multiple processes
+ * move a vertex differently. A typical strategy is to let processor $i$
+ * move those vertices that are adjacent to cells whose owners include
+ * processor $i$ but no other processor $j$ with $j<i$; in other words,
+ * for vertices at the boundary of a subdomain, the processor with the
+ * lowest subdomain id "owns" a vertex.
*
- * @note It only makes sense to move vertices that are either located
- * on locally owned cells or on cells in the ghost layer. This is
- * because you can be sure that these vertices indeed exist on the
- * finest mesh aggregated over all processors, whereas vertices on
- * artificial cells but not at least in the ghost layer may or may
- * not exist on the globally finest mesh. Consequently, the
- * @p vertex_locally_moved argument may not contain vertices that
- * aren't at least on ghost cells.
+ * @note It only makes sense to move vertices that are either located on
+ * locally owned cells or on cells in the ghost layer. This is because
+ * you can be sure that these vertices indeed exist on the finest mesh
+ * aggregated over all processors, whereas vertices on artificial cells
+ * but not at least in the ghost layer may or may not exist on the
+ * globally finest mesh. Consequently, the @p vertex_locally_moved
+ * argument may not contain vertices that aren't at least on ghost
+ * cells.
*
- * @note This function moves vertices in such a way that on every processor,
- * the vertices of every locally owned and ghost cell is consistent with
- * the corresponding location of these cells on other processors. On the
- * other hand, the locations of artificial cells will in general be wrong
- * since artificial cells may or may not exist on other processors
- * and consequently it is not possible to determine their location
- * in any way. This is not usually a problem since one never does anything
- * on artificial cells. However, it may lead to problems if the mesh
- * with moved vertices is refined in a later step. If that's what you
- * want to do, the right way to do it is to save the offset applied to
- * every vertex, call this function, and before refining or coarsening
- * the mesh apply the opposite offset and call this function again.
+ * @note This function moves vertices in such a way that on every
+ * processor, the vertices of every locally owned and ghost cell is
+ * consistent with the corresponding location of these cells on other
+ * processors. On the other hand, the locations of artificial cells will
+ * in general be wrong since artificial cells may or may not exist on
+ * other processors and consequently it is not possible to determine
+ * their location in any way. This is not usually a problem since one
+ * never does anything on artificial cells. However, it may lead to
+ * problems if the mesh with moved vertices is refined in a later step.
+ * If that's what you want to do, the right way to do it is to save the
+ * offset applied to every vertex, call this function, and before
+ * refining or coarsening the mesh apply the opposite offset and call
+ * this function again.
*
* @param vertex_locally_moved A bitmap indicating which vertices have
- * been moved. The size of this array must be equal to
- * Triangulation::n_vertices() and must be a subset of those vertices
- * flagged by GridTools::get_locally_owned_vertices().
+ * been moved. The size of this array must be equal to
+ * Triangulation::n_vertices() and must be a subset of those vertices
+ * flagged by GridTools::get_locally_owned_vertices().
*
- * @see This function is used, for example, in GridTools::distort_random().
+ * @see This function is used, for example, in
+ * GridTools::distort_random().
*/
void
communicate_locally_moved_vertices (const std::vector<bool> &vertex_locally_moved);
/**
- * Return the subdomain id of those cells that are owned by the
- * current processor. All cells in the triangulation that do not
- * have this subdomain id are either owned by another processor
- * or have children that only exist on other processors.
+ * Return the subdomain id of those cells that are owned by the current
+ * processor. All cells in the triangulation that do not have this
+ * subdomain id are either owned by another processor or have children
+ * that only exist on other processors.
*/
types::subdomain_id locally_owned_subdomain () const;
/**
- * Return the number of active cells in the triangulation that
- * are locally owned, i.e. that have a subdomain_id equal to
- * locally_owned_subdomain(). Note that there may be more active
- * cells in the triangulation stored on the present processor,
- * such as for example ghost cells, or cells further away from
- * the locally owned block of cells but that are needed to
- * ensure that the triangulation that stores this processor's
- * set of active cells still remains balanced with respect to
- * the 2:1 size ratio of adjacent cells.
+ * Return the number of active cells in the triangulation that are
+ * locally owned, i.e. that have a subdomain_id equal to
+ * locally_owned_subdomain(). Note that there may be more active cells
+ * in the triangulation stored on the present processor, such as for
+ * example ghost cells, or cells further away from the locally owned
+ * block of cells but that are needed to ensure that the triangulation
+ * that stores this processor's set of active cells still remains
+ * balanced with respect to the 2:1 size ratio of adjacent cells.
*
- * As a consequence of the remark above, the result of this
- * function is always smaller or equal to the result of the
- * function with the same name in the ::Triangulation base
- * class, which includes the active ghost and artificial cells
- * (see also @ref GlossArtificialCell and @ref GlossGhostCell).
+ * As a consequence of the remark above, the result of this function is
+ * always smaller or equal to the result of the function with the same
+ * name in the ::Triangulation base class, which includes the active
+ * ghost and artificial cells (see also @ref GlossArtificialCell and
+ * @ref GlossGhostCell).
*/
unsigned int n_locally_owned_active_cells () const;
/**
- * Return the sum over all processors of the number of active
- * cells owned by each processor. This equals the overall number
- * of active cells in the distributed triangulation.
+ * Return the sum over all processors of the number of active cells
+ * owned by each processor. This equals the overall number of active
+ * cells in the distributed triangulation.
*/
virtual types::global_dof_index n_global_active_cells () const;
/**
- * Returns the global maximum level. This may be bigger than
- * the number dealii::Triangulation::n_levels() (a function in this
- * class's base class) returns if the current processor only stores
- * cells in parts of the domain that are not very refined, but
- * if other processors store cells in more deeply refined parts of
- * the domain.
+ * Returns the global maximum level. This may be bigger than the number
+ * dealii::Triangulation::n_levels() (a function in this class's base
+ * class) returns if the current processor only stores cells in parts of
+ * the domain that are not very refined, but if other processors store
+ * cells in more deeply refined parts of the domain.
*/
virtual unsigned int n_global_levels () const;
* Returns true if the triangulation has hanging nodes.
*
* In the context of parallel distributed triangulations, every
- * processor stores only that part of the triangulation it
- * locally owns. However, it also stores the entire coarse
- * mesh, and to guarantee the 2:1 relationship between cells,
- * this may mean that there are hanging nodes between cells that
- * are not locally owned or ghost cells (i.e., between ghost cells
- * and artificial cells, or between artificial and artificial cells;
- * see @ref GlossArtificialCell "the glossary").
- * One is not typically interested in this case, so the function
- * returns whether there are hanging nodes between any two cells
- * of the "global" mesh, i.e., the union of locally owned cells
- * on all processors.
+ * processor stores only that part of the triangulation it locally owns.
+ * However, it also stores the entire coarse mesh, and to guarantee the
+ * 2:1 relationship between cells, this may mean that there are hanging
+ * nodes between cells that are not locally owned or ghost cells (i.e.,
+ * between ghost cells and artificial cells, or between artificial and
+ * artificial cells; see @ref GlossArtificialCell "the glossary"). One
+ * is not typically interested in this case, so the function returns
+ * whether there are hanging nodes between any two cells of the "global"
+ * mesh, i.e., the union of locally owned cells on all processors.
*/
virtual
bool has_hanging_nodes() const;
/**
- * Return the number of active cells owned by each of the MPI
- * processes that contribute to this triangulation. The element
- * of this vector indexed by locally_owned_subdomain() equals
- * the result of n_locally_owned_active_cells().
+ * Return the number of active cells owned by each of the MPI processes
+ * that contribute to this triangulation. The element of this vector
+ * indexed by locally_owned_subdomain() equals the result of
+ * n_locally_owned_active_cells().
*/
const std::vector<unsigned int> &
n_locally_owned_active_cells_per_processor () const;
virtual std::size_t memory_consumption () const;
/**
- * Return the local memory consumption contained in the p4est
- * data structures alone. This is already contained in
- * memory_consumption() but made available separately for
- * debugging purposes.
+ * Return the local memory consumption contained in the p4est data
+ * structures alone. This is already contained in memory_consumption()
+ * but made available separately for debugging purposes.
*/
virtual std::size_t memory_consumption_p4est () const;
/**
- * A collective operation that produces a sequence of output
- * files with the given file base name that contain the mesh in
- * VTK format.
+ * A collective operation that produces a sequence of output files with
+ * the given file base name that contain the mesh in VTK format.
*
- * More than anything else, this function is useful for
- * debugging the interface between deal.II and p4est.
+ * More than anything else, this function is useful for debugging the
+ * interface between deal.II and p4est.
*/
void write_mesh_vtk (const char *file_basename) const;
/**
- * Produce a check sum of the triangulation. This is a
- * collective operation and is mostly useful for debugging
- * purposes.
+ * Produce a check sum of the triangulation. This is a collective
+ * operation and is mostly useful for debugging purposes.
*/
unsigned int get_checksum () const;
/**
* Save the refinement information from the coarse mesh into the given
- * file. This file needs to be reachable from all nodes in the computation
- * on a shared network file system. See the SolutionTransfer class
- * on how to store solution vectors into this file. Additional cell-based data can be saved
- * using register_data_attach().
+ * file. This file needs to be reachable from all nodes in the
+ * computation on a shared network file system. See the SolutionTransfer
+ * class on how to store solution vectors into this file. Additional
+ * cell-based data can be saved using register_data_attach().
*/
void save(const char *filename) const;
/**
- * Load the refinement information saved with save() back in. The
- * mesh must contain the same coarse mesh that was used in save()
- * before calling this function.
+ * Load the refinement information saved with save() back in. The mesh
+ * must contain the same coarse mesh that was used in save() before
+ * calling this function.
*
* You do not need to load with the same number of MPI processes that
- * you saved with. Rather, if a mesh is loaded with a different
- * number of MPI processes than used at the time of saving, the mesh
- * is repartitioned appropriately. Cell-based data that was saved
- * with register_data_attach() can be read in with
- * notify_ready_to_unpack() after calling load().
+ * you saved with. Rather, if a mesh is loaded with a different number
+ * of MPI processes than used at the time of saving, the mesh is
+ * repartitioned appropriately. Cell-based data that was saved with
+ * register_data_attach() can be read in with notify_ready_to_unpack()
+ * after calling load().
*
* If you use p4est version > 0.3.4.2 the @p autopartition flag tells
- * p4est to ignore the partitioning that the triangulation had when
- * it was saved and make it uniform upon loading. If @p autopartition
- * is set to false, the triangulation is only repartitioned if needed
- * (i.e. if a different number of MPI processes is encountered).
+ * p4est to ignore the partitioning that the triangulation had when it
+ * was saved and make it uniform upon loading. If @p autopartition is
+ * set to false, the triangulation is only repartitioned if needed (i.e.
+ * if a different number of MPI processes is encountered).
*/
void load(const char *filename,
const bool autopartition = true);
/**
* Used to inform in the callbacks of register_data_attach() and
- * notify_ready_to_unpack() how the cell with the given
- * cell_iterator is going to change. Note that this may me
- * different than the refine_flag() and coarsen_flag() in the
- * cell_iterator because of refinement constraints that this
- * machine does not see.
+ * notify_ready_to_unpack() how the cell with the given cell_iterator is
+ * going to change. Note that this may me different than the
+ * refine_flag() and coarsen_flag() in the cell_iterator because of
+ * refinement constraints that this machine does not see.
*/
enum CellStatus
{
/**
- * The cell will not be refined or coarsened and might or might
- * not move to a different processor.
+ * The cell will not be refined or coarsened and might or might not
+ * move to a different processor.
*/
CELL_PERSIST,
/**
};
/**
- * Register a function with the current Triangulation object
- * that will be used to attach data to active cells before
+ * Register a function with the current Triangulation object that will
+ * be used to attach data to active cells before
* execute_coarsening_and_refinement(). In
- * execute_coarsening_and_refinement() the Triangulation will
- * call the given function pointer and provide @p size bytes to
- * store data. If necessary, this data will be transferred to
- * the new owner of that cell during repartitioning the
- * tree. See notify_ready_to_unpack() on how to retrieve the
- * data.
+ * execute_coarsening_and_refinement() the Triangulation will call the
+ * given function pointer and provide @p size bytes to store data. If
+ * necessary, this data will be transferred to the new owner of that
+ * cell during repartitioning the tree. See notify_ready_to_unpack() on
+ * how to retrieve the data.
*
- * Callers need to store the return value. It specifies an
- * offset of the position at which data can later be retrieved
- * during a call to notify_ready_to_unpack().
+ * Callers need to store the return value. It specifies an offset of
+ * the position at which data can later be retrieved during a call to
+ * notify_ready_to_unpack().
*
* The CellStatus argument in the callback function will tell you if the
* given cell will be coarsened, refined, or will persist as is (this
* is
*
* - CELL_PERIST: the cell won't be refined/coarsened, but might be
- * moved to a different processor
- * - CELL_REFINE: this cell will be refined into 4/8 cells, you can not
- * access the children (because they don't exist yet)
- * - CELL_COARSEN: the children of this cell will be coarsened into the
- * given cell (you can access the active children!)
+ * moved to a different processor - CELL_REFINE: this cell will be
+ * refined into 4/8 cells, you can not access the children (because they
+ * don't exist yet) - CELL_COARSEN: the children of this cell will be
+ * coarsened into the given cell (you can access the active children!)
*
* When unpacking the data with notify_ready_to_unpack() you can access
* the children of the cell if the status is CELL_REFINE but not for
* The CellStatus will indicate if the cell was refined, coarsened, or
* persisted unchanged. The cell_iterator will either by an active,
* locally owned cell (if the cell was not refined), or the immediate
- * parent if it was refined during
- * execute_coarsening_and_refinement(). Therefore, contrary to during
- * register_data_attach(), you can now access the children if the status
- * is CELL_REFINE but no longer for callbacks with status CELL_COARSEN.
+ * parent if it was refined during execute_coarsening_and_refinement().
+ * Therefore, contrary to during register_data_attach(), you can now
+ * access the children if the status is CELL_REFINE but no longer for
+ * callbacks with status CELL_COARSEN.
*/
void
notify_ready_to_unpack (const unsigned int offset,
const void *)> &unpack_callback);
/**
- * Return a permutation vector for the order the coarse cells
- * are handed off to p4est. For example the value of the $i$th element
- * in this vector is the index of the deal.II coarse cell (counting
- * from begin(0)) that corresponds to the $i$th tree managed by p4est.
+ * Return a permutation vector for the order the coarse cells are handed
+ * off to p4est. For example the value of the $i$th element in this
+ * vector is the index of the deal.II coarse cell (counting from
+ * begin(0)) that corresponds to the $i$th tree managed by p4est.
*/
const std::vector<types::global_dof_index> &
get_p4est_tree_to_coarse_cell_permutation() const;
/**
- * Return a permutation vector for the mapping from the
- * coarse deal cells to the p4est trees. This is the inverse
- * of get_p4est_tree_to_coarse_cell_permutation.
+ * Return a permutation vector for the mapping from the coarse deal
+ * cells to the p4est trees. This is the inverse of
+ * get_p4est_tree_to_coarse_cell_permutation.
*/
const std::vector<types::global_dof_index> &
get_coarse_cell_to_p4est_tree_permutation() const;
/**
- * Join faces in the p4est forest for periodic boundary
- * conditions. As a result, each pair of faces will differ by at
- * most one refinement level and ghost neighbors will be
- * available across these faces.
+ * Join faces in the p4est forest for periodic boundary conditions. As a
+ * result, each pair of faces will differ by at most one refinement
+ * level and ghost neighbors will be available across these faces.
*
* The vector can be filled by the function
* GridTools::collect_periodic_faces.
* @todo At the moment just default orientation is implemented.
*
* @note Before this function can be used the Triangulation has to be
- * initialized and must not be refined.
- * Calling this function more than once is possible, but not recommended:
- * The function destroys and rebuilds the p4est forest each time it is
- * called.
+ * initialized and must not be refined. Calling this function more than
+ * once is possible, but not recommended: The function destroys and
+ * rebuilds the p4est forest each time it is called.
*/
void
add_periodicity
private:
/**
- * MPI communicator to be used for the triangulation. We create
- * a unique communicator for this class, which is a duplicate of
- * the one passed to the constructor.
+ * MPI communicator to be used for the triangulation. We create a unique
+ * communicator for this class, which is a duplicate of the one passed
+ * to the constructor.
*/
MPI_Comm mpi_communicator;
types::subdomain_id my_subdomain;
/**
- * A flag that indicates whether the triangulation has actual
- * content.
+ * A flag that indicates whether the triangulation has actual content.
*/
bool triangulation_has_content;
NumberCache number_cache;
/**
- * A data structure that holds the connectivity between
- * trees. Since each tree is rooted in a coarse grid cell, this
- * data structure holds the connectivity between the cells of
- * the coarse grid.
+ * A data structure that holds the connectivity between trees. Since
+ * each tree is rooted in a coarse grid cell, this data structure holds
+ * the connectivity between the cells of the coarse grid.
*/
typename dealii::internal::p4est::types<dim>::connectivity *connectivity;
*/
typename dealii::internal::p4est::types<dim>::forest *parallel_forest;
/**
- * A data structure that holds some information about the ghost
- * cells of the triangulation.
+ * A data structure that holds some information about the ghost cells of
+ * the triangulation.
*/
typename dealii::internal::p4est::types<dim>::ghost *parallel_ghost;
/**
- * A flag that indicates whether refinement of a triangulation
- * is currently in progress. This flag is used to disambiguate
- * whether a call to execute_coarsening_and_triangulation came
- * from the outside or through a recursive call. While the first
- * time we want to take over work to copy things from a refined
- * p4est, the other times we don't want to get in the way as
- * these latter calls to
- * Triangulation::execute_coarsening_and_refinement() are simply
- * there in order to re-create a triangulation that matches the
- * p4est.
+ * A flag that indicates whether refinement of a triangulation is
+ * currently in progress. This flag is used to disambiguate whether a
+ * call to execute_coarsening_and_triangulation came from the outside or
+ * through a recursive call. While the first time we want to take over
+ * work to copy things from a refined p4est, the other times we don't
+ * want to get in the way as these latter calls to
+ * Triangulation::execute_coarsening_and_refinement() are simply there
+ * in order to re-create a triangulation that matches the p4est.
*/
bool refinement_in_progress;
/**
- * number of bytes that get attached to the Triangulation
- * through register_data_attach() for example SolutionTransfer.
+ * number of bytes that get attached to the Triangulation through
+ * register_data_attach() for example SolutionTransfer.
*/
unsigned int attached_data_size;
/**
- * number of functions that get attached to the Triangulation
- * through register_data_attach() for example SolutionTransfer.
+ * number of functions that get attached to the Triangulation through
+ * register_data_attach() for example SolutionTransfer.
*/
unsigned int n_attached_datas;
/**
- * number of functions that need to unpack their data after a
- * call from load()
+ * number of functions that need to unpack their data after a call from
+ * load()
*/
unsigned int n_attached_deserialize;
typedef std::list<callback_pair_t> callback_list_t;
/**
- * List of callback functions registered by
- * register_data_attach() that are going to be called for
- * packing data.
+ * List of callback functions registered by register_data_attach() that
+ * are going to be called for packing data.
*/
callback_list_t attached_data_pack_callbacks;
/**
- * Two arrays that store which p4est tree corresponds to which
- * coarse grid cell and vice versa. We need these arrays because
- * p4est goes with the original order of coarse cells when it
- * sets up its forest, and then applies the Morton ordering
- * within each tree. But if coarse grid cells are badly ordered
- * this may mean that individual parts of the forest stored on a
- * local machine may be split across coarse grid cells that are
- * not geometrically close. Consequently, we apply a
- * Cuthill-McKee preordering to ensure that the part of the
- * forest stored by p4est is located on geometrically close
- * coarse grid cells.
+ * Two arrays that store which p4est tree corresponds to which coarse
+ * grid cell and vice versa. We need these arrays because p4est goes
+ * with the original order of coarse cells when it sets up its forest,
+ * and then applies the Morton ordering within each tree. But if coarse
+ * grid cells are badly ordered this may mean that individual parts of
+ * the forest stored on a local machine may be split across coarse grid
+ * cells that are not geometrically close. Consequently, we apply a
+ * Cuthill-McKee preordering to ensure that the part of the forest
+ * stored by p4est is located on geometrically close coarse grid cells.
*/
std::vector<types::global_dof_index> coarse_cell_to_p4est_tree_permutation;
std::vector<types::global_dof_index> p4est_tree_to_coarse_cell_permutation;
init_tree(const int dealii_coarse_cell_index) const;
/**
- * The function that computes the permutation between the two
- * data storage schemes.
+ * The function that computes the permutation between the two data
+ * storage schemes.
*/
void setup_coarse_cell_to_p4est_tree_permutation ();
/**
- * Take the contents of a newly created triangulation we are
- * attached to and copy it to p4est data structures.
+ * Take the contents of a newly created triangulation we are attached to
+ * and copy it to p4est data structures.
*
* This function exists in 2d and 3d variants.
*/
/**
- * Update the number_cache variable after mesh creation or
- * refinement.
+ * Update the number_cache variable after mesh creation or refinement.
*/
void update_number_cache ();
/**
- * Internal function notifying all registered classes to attach
- * their data before repartitioning occurs. Called from
+ * Internal function notifying all registered classes to attach their
+ * data before repartitioning occurs. Called from
* execute_coarsening_and_refinement().
*/
void attach_mesh_data();
/**
- * Specialization of the general template for the 1d case. There
- * is currently no support for distributing 1d
- * triangulations. Consequently, all this class does is throw an
- * exception.
+ * Specialization of the general template for the 1d case. There is
+ * currently no support for distributing 1d triangulations. Consequently,
+ * all this class does is throw an exception.
*/
template <int spacedim>
class Triangulation<1,spacedim> : public dealii::Triangulation<1,spacedim>
{
public:
/**
- * Constructor. The argument denotes the MPI communicator to be
- * used for the triangulation.
+ * Constructor. The argument denotes the MPI communicator to be used for
+ * the triangulation.
*/
Triangulation (MPI_Comm mpi_communicator);
MPI_Comm get_communicator () const;
/**
- * Return the sum over all processors of the number of active
- * cells owned by each processor. This equals the overall number
- * of active cells in the distributed triangulation.
+ * Return the sum over all processors of the number of active cells
+ * owned by each processor. This equals the overall number of active
+ * cells in the distributed triangulation.
*/
types::global_dof_index n_global_active_cells () const;
virtual unsigned int n_global_levels () const;
/**
- * Returns a permutation vector for the order the coarse cells
- * are handed of to p4est. For example the first element i in
- * this vector denotes that the first cell in hierarchical
- * ordering is the ith deal cell starting from begin(0).
+ * Returns a permutation vector for the order the coarse cells are
+ * handed of to p4est. For example the first element i in this vector
+ * denotes that the first cell in hierarchical ordering is the ith deal
+ * cell starting from begin(0).
*/
const std::vector<types::global_dof_index> &
get_p4est_tree_to_coarse_cell_permutation() const;
/**
- * When vertices have been moved locally, for example using code
- * like
+ * When vertices have been moved locally, for example using code like
* @code
* cell->vertex(0) = new_location;
* @endcode
- * then this function can be used to update the location of
- * vertices between MPI processes.
+ * then this function can be used to update the location of vertices
+ * between MPI processes.
*
* All the vertices that have been moved and might be in the ghost layer
- * of a process have to be reported in the @p vertex_locally_moved argument.
- * This ensures that that part of the information that has to be send
- * between processes is actually sent. Additionally, it is quite important that vertices
- * on the boundary between processes are reported on exactly one process
- * (e.g. the one with the highest id). Otherwise we could expect
- * undesirable results if multiple processes move a vertex differently.
- * A typical strategy is to let processor $i$ move those vertices that
- * are adjacent to cells whose owners include processor $i$ but no
- * other processor $j$ with $j<i$; in other words, for vertices
- * at the boundary of a subdomain, the processor with the lowest subdomain
- * id "owns" a vertex.
+ * of a process have to be reported in the @p vertex_locally_moved
+ * argument. This ensures that that part of the information that has to
+ * be send between processes is actually sent. Additionally, it is quite
+ * important that vertices on the boundary between processes are
+ * reported on exactly one process (e.g. the one with the highest id).
+ * Otherwise we could expect undesirable results if multiple processes
+ * move a vertex differently. A typical strategy is to let processor $i$
+ * move those vertices that are adjacent to cells whose owners include
+ * processor $i$ but no other processor $j$ with $j<i$; in other words,
+ * for vertices at the boundary of a subdomain, the processor with the
+ * lowest subdomain id "owns" a vertex.
*
- * @note It only makes sense to move vertices that are either located
- * on locally owned cells or on cells in the ghost layer. This is
- * because you can be sure that these vertices indeed exist on the
- * finest mesh aggregated over all processors, whereas vertices on
- * artificial cells but not at least in the ghost layer may or may
- * not exist on the globally finest mesh. Consequently, the
- * @p vertex_locally_moved argument may not contain vertices that
- * aren't at least on ghost cells.
+ * @note It only makes sense to move vertices that are either located on
+ * locally owned cells or on cells in the ghost layer. This is because
+ * you can be sure that these vertices indeed exist on the finest mesh
+ * aggregated over all processors, whereas vertices on artificial cells
+ * but not at least in the ghost layer may or may not exist on the
+ * globally finest mesh. Consequently, the @p vertex_locally_moved
+ * argument may not contain vertices that aren't at least on ghost
+ * cells.
*
- * @see This function is used, for example, in GridTools::distort_random().
+ * @see This function is used, for example, in
+ * GridTools::distort_random().
*/
void
communicate_locally_moved_vertices (const std::vector<bool> &vertex_locally_moved);
/**
- * Return the subdomain id of those cells that are owned by the
- * current processor. All cells in the triangulation that do not
- * have this subdomain id are either owned by another processor
- * or have children that only exist on other processors.
+ * Return the subdomain id of those cells that are owned by the current
+ * processor. All cells in the triangulation that do not have this
+ * subdomain id are either owned by another processor or have children
+ * that only exist on other processors.
*/
types::subdomain_id locally_owned_subdomain () const;
/**
- * Dummy arrays. This class isn't usable but the compiler wants
- * to see these variables at a couple places anyway.
+ * Dummy arrays. This class isn't usable but the compiler wants to see
+ * these variables at a couple places anyway.
*/
std::vector<types::global_dof_index> coarse_cell_to_p4est_tree_permutation;
std::vector<types::global_dof_index> p4est_tree_to_coarse_cell_permutation;
{
/**
* Dummy class the compiler chooses for parallel distributed
- * triangulations if we didn't actually configure deal.II with the
- * p4est library. The existence of this class allows us to refer
- * to parallel::distributed::Triangulation objects throughout the
- * library even if it is disabled.
+ * triangulations if we didn't actually configure deal.II with the p4est
+ * library. The existence of this class allows us to refer to
+ * parallel::distributed::Triangulation objects throughout the library
+ * even if it is disabled.
*
- * Since the constructor of this class is private, no such objects
- * can actually be created if we don't have p4est available.
+ * Since the constructor of this class is private, no such objects can
+ * actually be created if we don't have p4est available.
*/
template <int dim, int spacedim = dim>
class Triangulation : public dealii::Triangulation<dim,spacedim>
virtual ~Triangulation ();
/**
- * Return the subdomain id of those cells that are owned by the
- * current processor. All cells in the triangulation that do not
- * have this subdomain id are either owned by another processor
- * or have children that only exist on other processors.
+ * Return the subdomain id of those cells that are owned by the current
+ * processor. All cells in the triangulation that do not have this
+ * subdomain id are either owned by another processor or have children
+ * that only exist on other processors.
*/
types::subdomain_id locally_owned_subdomain () const;
* @brief A small class collecting the different BlockIndices involved in
* global, multilevel and local computations.
*
- * Once a DoFHandler has been initialized with an FESystem, a data
- * object of type BlockInfo (accessed by DoFHandler::block_info() ) is
- * filled, which reflects the block structure of the degrees of
- * freedom.
+ * Once a DoFHandler has been initialized with an FESystem, a data object of
+ * type BlockInfo (accessed by DoFHandler::block_info() ) is filled, which
+ * reflects the block structure of the degrees of freedom.
*
- * BlockInfo consists of several BlockIndices objects. The member
- * global() reflects the block structure of the system on the active
- * cell level, usually referred to as the global system. As soon as
+ * BlockInfo consists of several BlockIndices objects. The member global()
+ * reflects the block structure of the system on the active cell level,
+ * usually referred to as the global system. As soon as
* DoFHandler::distribute_dofs() has been called, the function
- * BlockIndices::block_size() in global() will return the correct
- * sizes of each block. After DoFRenumbering::block_wise(),
- * BlockIndices::block_start() will return the start index for each of
- * the blocks.
+ * BlockIndices::block_size() in global() will return the correct sizes of
+ * each block. After DoFRenumbering::block_wise(), BlockIndices::block_start()
+ * will return the start index for each of the blocks.
*
* When a DoFHandler with levels is used, the same structure is automatically
- * generated for each level. The level blocks can be accessed through
- * level().
+ * generated for each level. The level blocks can be accessed through level().
*
- * Finally, there are local() BlockIndices, which describe the block
- * structure on a single cell. This is used for instance by
- * MeshWorker::Assembler::MatrixLocalBlocksToGlobalBlocks. The local
- * indices are not filled automatically, since they change the
- * behavior of the MeshWorker::Assembler classes relying on
- * BlockInfo. They must be initialized by hand through initialize_local().
+ * Finally, there are local() BlockIndices, which describe the block structure
+ * on a single cell. This is used for instance by
+ * MeshWorker::Assembler::MatrixLocalBlocksToGlobalBlocks. The local indices
+ * are not filled automatically, since they change the behavior of the
+ * MeshWorker::Assembler classes relying on BlockInfo. They must be
+ * initialized by hand through initialize_local().
*
* <h3>Usage</h3>
*
- * The most common usage for this object is initializing vectors as in
- * the following code:
+ * The most common usage for this object is initializing vectors as in the
+ * following code:
*
- * <code>
- * MGDofHandler<dim> dof_handler(triangulation);
+ * <code> MGDofHandler<dim> dof_handler(triangulation);
* dof_handler.distribute_dofs(fesystem);
* DoFRenumbering::block_wise(dof_handler);
*
* BlockVector<double> solution(dof_handler.block_info().global());
*
- * MGLevelObject<BlockVector<double> > mg_vector(0, triangulation.n_levels()-1);
- * for (unsigned int i=0;i<triangulation.n_levels();++i)
- * mg_vector[i].reinit(dof_handler.block_info().level(i));
- *</code>
- * In this example, <tt>solution</tt> obtains the block structure needed to
- * represent a finite element function on the DoFHandler. Similarly,
- * all levels of <tt>mg_vector</tt> will have the block structure
- * needed on that level.
+ * MGLevelObject<BlockVector<double> > mg_vector(0,
+ * triangulation.n_levels()-1); for (unsigned int
+ * i=0;i<triangulation.n_levels();++i)
+ * mg_vector[i].reinit(dof_handler.block_info().level(i)); </code> In this
+ * example, <tt>solution</tt> obtains the block structure needed to represent
+ * a finite element function on the DoFHandler. Similarly, all levels of
+ * <tt>mg_vector</tt> will have the block structure needed on that level.
*
* @todo Extend the functions local() and renumber() to the concept to
* hpDoFHandler.
{
public:
/**
- * @brief Fill the object with values
- * describing block structure
- * of the DoFHandler.
+ * @brief Fill the object with values describing block structure of the
+ * DoFHandler.
*
- * By default, this function will
- * attempt to initialize whatever
- * is possible. If active dofs
- * have been assigned int the
- * DoFHandler argument, they
- * BlockIndices for those will be
- * generated. The same for level
- * dofs.
- *
- * This default behavior can be
- * overridden by the two
- * parameters, which can switch
- * off active dofs or level dofs.
- *
- * This function will also clear
- * the local() indices.
+ * By default, this function will attempt to initialize whatever is
+ * possible. If active dofs have been assigned int the DoFHandler argument,
+ * they BlockIndices for those will be generated. The same for level dofs.
+ *
+ * This default behavior can be overridden by the two parameters, which can
+ * switch off active dofs or level dofs.
+ *
+ * This function will also clear the local() indices.
*/
template <int dim, int spacedim>
void initialize(const DoFHandler<dim, spacedim> &, bool levels_only = false, bool active_only = false);
/**
- * @brief Initialize block structure
- * on cells and compute
- * renumbering between cell
- * dofs and block cell dofs.
+ * @brief Initialize block structure on cells and compute renumbering
+ * between cell dofs and block cell dofs.
*/
template <int dim, int spacedim>
void initialize_local(const DoFHandler<dim, spacedim> &);
/**
- * Access the BlockIndices
- * structure of the global
- * system.
+ * Access the BlockIndices structure of the global system.
*/
const BlockIndices &global() const;
/**
- * Access BlockIndices for the
- * local system on a cell.
+ * Access BlockIndices for the local system on a cell.
*/
const BlockIndices &local() const;
/**
- * Access the BlockIndices
- * structure of a level in the
- * multilevel hierarchy.
+ * Access the BlockIndices structure of a level in the multilevel hierarchy.
*/
const BlockIndices &level(unsigned int level) const;
/**
- * Return the index after local
- * renumbering.
+ * Return the index after local renumbering.
*
- * The input of this function is
- * an index between zero and the
- * number of dofs per cell,
- * numbered in local block
- * ordering, that is first all
- * indices of the first system
- * block, then all of the second
- * block and so forth. The
- * function then outputs the index
- * in the standard local
+ * The input of this function is an index between zero and the number of
+ * dofs per cell, numbered in local block ordering, that is first all
+ * indices of the first system block, then all of the second block and so
+ * forth. The function then outputs the index in the standard local
* numbering of DoFAccessor.
*/
types::global_dof_index renumber (const unsigned int i) const;
unsigned int n_base_elements() const;
/**
- * Return the base element of
- * this index.
+ * Return the base element of this index.
*/
unsigned int base_element (const unsigned int i) const;
/**
- * Write a summary of the block
- * structure to the stream.
+ * Write a summary of the block structure to the stream.
*/
template <class OS>
void
print(OS &stream) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the purpose
+ * of serialization
*/
template <class Archive>
void serialize (Archive &ar,
private:
/**
- * @brief The block structure
- * of the global system.
+ * @brief The block structure of the global system.
*/
BlockIndices bi_global;
/**
std::vector<BlockIndices> levels;
/**
- * @brief The block structure
- * of the cell systems.
+ * @brief The block structure of the cell systems.
*/
BlockIndices bi_local;
/**
- * The base element associated
- * with each block.
+ * The base element associated with each block.
*/
std::vector<unsigned int> base_elements;
/**
- * A vector containing the
- * renumbering from the
- * standard order of degrees of
- * freedom on a cell to a
- * component wise
- * ordering. Filled by
- * initialize().
+ * A vector containing the renumbering from the standard order of degrees of
+ * freedom on a cell to a component wise ordering. Filled by initialize().
*/
std::vector<types::global_dof_index> local_renumbering;
};
/**
* This is a switch class which only declares a @p typedef. It is meant to
* determine which class a DoFAccessor class is to be derived from. By
- * default, <tt>DoFAccessor@<structdim,dim,spacedim@></tt> derives from the
- * typedef in the general
+ * default, <tt>DoFAccessor@<structdim,dim,spacedim@></tt> derives from
+ * the typedef in the general
* <tt>Inheritance@<structdim,dim,spacedim@></tt> class, which is
* <tt>TriaAccessor@<structdim,dim,spacedim@></tt>, but if
* <tt>structdim==dim</tt>, then the specialization
- * <tt>Inheritance@<dim,dim,spacedim@></tt> is used which declares
- * its local type to be <tt>CellAccessor@<dim,spacedim@></tt>. Therefore, the
- * inheritance is automatically chosen to be from CellAccessor if the object
- * under consideration has full dimension, i.e. constitutes a cell.
+ * <tt>Inheritance@<dim,dim,spacedim@></tt> is used which declares its
+ * local type to be <tt>CellAccessor@<dim,spacedim@></tt>. Therefore, the
+ * inheritance is automatically chosen to be from CellAccessor if the
+ * object under consideration has full dimension, i.e. constitutes a cell.
*
* @ingroup dofs
* @ingroup Accessors
struct Inheritance
{
/**
- * Declaration of the @p typedef. See the full documentation
- * for more information.
+ * Declaration of the @p typedef. See the full documentation for more
+ * information.
*/
typedef dealii::TriaAccessor<structdim,dim,spacedim> BaseClass;
};
/**
- * This is the specialization of the general template used for the case where
- * an object has full dimension, i.e. is a cell. See the general template for
- * more details.
+ * This is the specialization of the general template used for the case
+ * where an object has full dimension, i.e. is a cell. See the general
+ * template for more details.
*/
template <int dim, int spacedim>
struct Inheritance<dim,dim,spacedim>
{
/**
- * Declaration of the @p typedef. See the full documentation
- * for more information.
+ * Declaration of the @p typedef. See the full documentation for more
+ * information.
*/
typedef dealii::CellAccessor<dim,spacedim> BaseClass;
};
/**
* A class that gives access to the degrees of freedom stored in a DoFHandler,
- * MGSoDHandler, or hp::DoFHandler object. Accessors are used to, access the data that
- * pertains to edges, faces, and cells of a triangulation. The concept is
- * explained in more detail in connection to @ref Iterators.
+ * MGSoDHandler, or hp::DoFHandler object. Accessors are used to, access the
+ * data that pertains to edges, faces, and cells of a triangulation. The
+ * concept is explained in more detail in connection to @ref Iterators.
*
- * This class follows mainly the route laid out by the accessor
- * library declared in the triangulation library (TriaAccessor). It
- * enables the user to access the degrees of freedom on lines, quads,
- * or hexes. The first template argument of this class determines the
- * dimensionality of the object under consideration: 1 for lines, 2
- * for quads, and 3 for hexes. The second argument denotes the type of
- * DoF handler we should work on. It can either be ::DoFHandler or
- * hp::DoFHandler. From the second template argument we also deduce
- * the dimension of the Triangulation this object refers to as well as
- * the dimension of the space into which it is embedded. Finally, the
- * template argument <code>level_dof_access</code> governs the
- * behavior of the function get_active_or_mg_dof_indices(). See the section on Generic loops below.
+ * This class follows mainly the route laid out by the accessor library
+ * declared in the triangulation library (TriaAccessor). It enables the user
+ * to access the degrees of freedom on lines, quads, or hexes. The first
+ * template argument of this class determines the dimensionality of the object
+ * under consideration: 1 for lines, 2 for quads, and 3 for hexes. The second
+ * argument denotes the type of DoF handler we should work on. It can either
+ * be ::DoFHandler or hp::DoFHandler. From the second template argument we
+ * also deduce the dimension of the Triangulation this object refers to as
+ * well as the dimension of the space into which it is embedded. Finally, the
+ * template argument <code>level_dof_access</code> governs the behavior of the
+ * function get_active_or_mg_dof_indices(). See the section on Generic loops
+ * below.
*
* <h3>Typedefs</h3>
*
- * Usage is best to happen through the typedefs to the various kinds
- * of iterators provided by the DoFHandler and hp::DoFHandler classes,
- * since they are more secure to changes in the class naming and
- * template interface as well as providing easier typing (much less
- * complicated names!).
+ * Usage is best to happen through the typedefs to the various kinds of
+ * iterators provided by the DoFHandler and hp::DoFHandler classes, since they
+ * are more secure to changes in the class naming and template interface as
+ * well as providing easier typing (much less complicated names!).
*
* <h3>Generic loops and the third template argument</h3>
*
- * Many loops look very similar, whether they operate on the active
- * dofs of the active cells of the Triangulation or on the level dodfs
- * of a single level or the whole grid hierarchy. In order to use
- * polymorphism in such loops, they access degrees of freedom through
- * the function get_active_or_mg_dof_indices(), which changes behavior according to the
- * third template argument. If the argument is false, then the active
- * dofs of active cells are accessed. If it is true, the level dofs
- * are used. DoFHandler has functions, for instance begin() and
- * begin_mg(), which return either type or the other. Additionally,
- * they can be cast into each other, in case this is needed, since
- * they access the same data.
+ * Many loops look very similar, whether they operate on the active dofs of
+ * the active cells of the Triangulation or on the level dodfs of a single
+ * level or the whole grid hierarchy. In order to use polymorphism in such
+ * loops, they access degrees of freedom through the function
+ * get_active_or_mg_dof_indices(), which changes behavior according to the
+ * third template argument. If the argument is false, then the active dofs of
+ * active cells are accessed. If it is true, the level dofs are used.
+ * DoFHandler has functions, for instance begin() and begin_mg(), which return
+ * either type or the other. Additionally, they can be cast into each other,
+ * in case this is needed, since they access the same data.
*
- * It is highly recommended to use the function get_active_or_mg_dof_indices() in
- * generic loops in lieu of get_dof_indices() or get_mg_dof_indices().
+ * It is highly recommended to use the function get_active_or_mg_dof_indices()
+ * in generic loops in lieu of get_dof_indices() or get_mg_dof_indices().
*
* <h3>Inheritance</h3>
*
- * If the structural dimension given by the first template argument
- * equals the dimension of the DoFHandler (given as the second
- * template argument), then we are obviously dealing with cells,
- * rather than lower-dimensional objects. In that case, inheritance is
- * from CellAccessor, to provide access to all the cell specific
- * information afforded by that class. Otherwise, i.e. for
+ * If the structural dimension given by the first template argument equals the
+ * dimension of the DoFHandler (given as the second template argument), then
+ * we are obviously dealing with cells, rather than lower-dimensional objects.
+ * In that case, inheritance is from CellAccessor, to provide access to all
+ * the cell specific information afforded by that class. Otherwise, i.e. for
* lower-dimensional objects, inheritance is from TriaAccessor.
*
- * There is a DoFCellAccessor class that provides the
- * equivalent to the CellAccessor class.
+ * There is a DoFCellAccessor class that provides the equivalent to the
+ * CellAccessor class.
*
* @ingroup dofs
* @ingroup Accessors
- * @author Wolfgang Bangerth, 1998, 2006, 2008, Timo Heister, Guido Kanschat, 2012, 2013
+ * @author Wolfgang Bangerth, 1998, 2006, 2008, Timo Heister, Guido Kanschat,
+ * 2012, 2013
*/
template <int structdim, class DH, bool level_dof_access>
class DoFAccessor : public dealii::internal::DoFAccessor::Inheritance<structdim, DH::dimension, DH::space_dimension>::BaseClass
public:
/**
- * A static variable that allows users of this class to discover the
- * value of the second template argument.
+ * A static variable that allows users of this class to discover the value
+ * of the second template argument.
*/
static const unsigned int dimension=DH::dimension;
/**
- * A static variable that allows users of this class to discover the
- * value of the third template argument.
+ * A static variable that allows users of this class to discover the value
+ * of the third template argument.
*/
static const unsigned int space_dimension=DH::space_dimension;
/**
* Conversion constructor. This constructor exists to make certain
- * constructs simpler to write in dimension independent code. For
- * example, it allows assigning a face iterator to a line iterator,
- * an operation that is useful in 2d but doesn't make any sense in
- * 3d. The constructor here exists for the purpose of making the
- * code conform to C++ but it will unconditionally abort; in other
- * words, assigning a face iterator to a line iterator is better put
- * into an if-statement that checks that the dimension is two, and
- * assign to a quad iterator in 3d (an operator that, without this
- * constructor would be illegal if we happen to compile for 2d).
+ * constructs simpler to write in dimension independent code. For example,
+ * it allows assigning a face iterator to a line iterator, an operation that
+ * is useful in 2d but doesn't make any sense in 3d. The constructor here
+ * exists for the purpose of making the code conform to C++ but it will
+ * unconditionally abort; in other words, assigning a face iterator to a
+ * line iterator is better put into an if-statement that checks that the
+ * dimension is two, and assign to a quad iterator in 3d (an operator that,
+ * without this constructor would be illegal if we happen to compile for
+ * 2d).
*/
template <int structdim2, int dim2, int spacedim2>
DoFAccessor (const InvalidAccessor<structdim2,dim2,spacedim2> &);
/**
- * Another conversion operator between objects that don't make
- * sense, just like the previous one.
+ * Another conversion operator between objects that don't make sense, just
+ * like the previous one.
*/
template <int dim2, class DH2, bool level_dof_access2>
DoFAccessor (const DoFAccessor<dim2, DH2, level_dof_access2> &);
/**
- * Copy constructor allowing to switch level access and active
- * access.
+ * Copy constructor allowing to switch level access and active access.
*/
template <bool level_dof_access2>
DoFAccessor(const DoFAccessor<structdim, DH, level_dof_access2> &);
void copy_from (const DoFAccessor<structdim, DH, level_dof_access2> &a);
/**
- * Copy operator used by the iterator class. Keeps the previously
- * set dof handler, but sets the object coordinates of the
- * TriaAccessor.
+ * Copy operator used by the iterator class. Keeps the previously set dof
+ * handler, but sets the object coordinates of the TriaAccessor.
*/
void copy_from (const TriaAccessorBase<structdim, DH::dimension, DH::space_dimension> &da);
/**
- * Tell the caller whether get_active_or_mg_dof_indices() accesses
- * active or level dofs.
+ * Tell the caller whether get_active_or_mg_dof_indices() accesses active or
+ * level dofs.
*/
static bool is_level_cell();
/**
- * @name Accessing sub-objects
+ * @name Accessing sub-objects
*/
/**
* @{
child (const unsigned int c) const;
/**
- * Pointer to the @p ith line bounding this object. If the current
- * object is a line itself, then the only valid index is @p i equals
- * to zero, and the function returns an iterator to itself.
+ * Pointer to the @p ith line bounding this object. If the current object is
+ * a line itself, then the only valid index is @p i equals to zero, and the
+ * function returns an iterator to itself.
*/
typename dealii::internal::DoFHandler::Iterators<DH, level_dof_access>::line_iterator
line (const unsigned int i) const;
/**
- * Pointer to the @p ith quad bounding this object. If the current
- * object is a quad itself, then the only valid index is @p i equals
- * to zero, and the function returns an iterator to itself.
+ * Pointer to the @p ith quad bounding this object. If the current object is
+ * a quad itself, then the only valid index is @p i equals to zero, and the
+ * function returns an iterator to itself.
*/
typename dealii::internal::DoFHandler::Iterators<DH, level_dof_access>::quad_iterator
quad (const unsigned int i) const;
*/
/**
- * @name Accessing the DoF indices of this object
+ * @name Accessing the DoF indices of this object
*/
/**
* @{
* etc, dofs on quad 0, etc.) This function is only available on
* <i>active</i> objects (see @ref GlossActive "this glossary entry").
*
- * The cells needs to be an active cell (and not artificial in a
- * parallel distributed computation).
+ * The cells needs to be an active cell (and not artificial in a parallel
+ * distributed computation).
*
* The vector has to have the right size before being passed to this
* function.
*
- * The last argument denotes the finite element index. For the
- * standard ::DoFHandler class, this value must be equal to its
- * default value since that class only supports the same finite
- * element on all cells anyway.
- *
- * However, for hp objects (i.e. the hp::DoFHandler class),
- * different finite element objects may be used on different
- * cells. On faces between two cells, as well as vertices, there may
- * therefore be two sets of degrees of freedom, one for each of the
- * finite elements used on the adjacent cells. In order to specify
- * which set of degrees of freedom to work on, the last argument is
- * used to disambiguate. Finally, if this function is called for a
- * cell object, there can only be a single set of degrees of
- * freedom, and fe_index has to match the result of
- * active_fe_index().
- *
- * For cells, there is only a single possible finite element index
- * (namely the one for that cell, returned by
- * <code>cell-@>active_fe_index</code>. Consequently, the derived
- * DoFCellAccessor class has an overloaded version of this function
- * that calls the present function with
+ * The last argument denotes the finite element index. For the standard
+ * ::DoFHandler class, this value must be equal to its default value since
+ * that class only supports the same finite element on all cells anyway.
+ *
+ * However, for hp objects (i.e. the hp::DoFHandler class), different finite
+ * element objects may be used on different cells. On faces between two
+ * cells, as well as vertices, there may therefore be two sets of degrees of
+ * freedom, one for each of the finite elements used on the adjacent cells.
+ * In order to specify which set of degrees of freedom to work on, the last
+ * argument is used to disambiguate. Finally, if this function is called for
+ * a cell object, there can only be a single set of degrees of freedom, and
+ * fe_index has to match the result of active_fe_index().
+ *
+ * For cells, there is only a single possible finite element index (namely
+ * the one for that cell, returned by <code>cell-@>active_fe_index</code>.
+ * Consequently, the derived DoFCellAccessor class has an overloaded version
+ * of this function that calls the present function with
* <code>cell-@>active_fe_index</code> as last argument.
*
*/
const unsigned int fe_index = DH::default_fe_index);
/**
- * Global DoF index of the <i>i</i> degree associated with the @p
- * vertexth vertex of the present cell.
+ * Global DoF index of the <i>i</i> degree associated with the @p vertexth
+ * vertex of the present cell.
*
- * The last argument denotes the finite element index. For the
- * standard ::DoFHandler class, this value must be equal to its
- * default value since that class only supports the same finite
- * element on all cells anyway.
+ * The last argument denotes the finite element index. For the standard
+ * ::DoFHandler class, this value must be equal to its default value since
+ * that class only supports the same finite element on all cells anyway.
*
- * However, for hp objects (i.e. the hp::DoFHandler class),
- * different finite element objects may be used on different
- * cells. On faces between two cells, as well as vertices, there may
- * therefore be two sets of degrees of freedom, one for each of the
- * finite elements used on the adjacent cells. In order to specify
- * which set of degrees of freedom to work on, the last argument is
- * used to disambiguate. Finally, if this function is called for a
- * cell object, there can only be a single set of degrees of
- * freedom, and fe_index has to match the result of
- * active_fe_index().
+ * However, for hp objects (i.e. the hp::DoFHandler class), different finite
+ * element objects may be used on different cells. On faces between two
+ * cells, as well as vertices, there may therefore be two sets of degrees of
+ * freedom, one for each of the finite elements used on the adjacent cells.
+ * In order to specify which set of degrees of freedom to work on, the last
+ * argument is used to disambiguate. Finally, if this function is called for
+ * a cell object, there can only be a single set of degrees of freedom, and
+ * fe_index has to match the result of active_fe_index().
*/
types::global_dof_index vertex_dof_index (const unsigned int vertex,
const unsigned int i,
const unsigned int fe_index = DH::default_fe_index) const;
/**
- * Returns the global DoF index of the <code>i</code>th degree of
- * freedom associated with the <code>vertex</code>th vertex on level
- * @p level. Also see vertex_dof_index().
+ * Returns the global DoF index of the <code>i</code>th degree of freedom
+ * associated with the <code>vertex</code>th vertex on level @p level. Also
+ * see vertex_dof_index().
*/
types::global_dof_index mg_vertex_dof_index (const int level,
const unsigned int vertex,
/**
* Index of the <i>i</i>th degree of freedom of this object.
*
- * The last argument denotes the finite element index. For the
- * standard ::DoFHandler class, this value must be equal to its
- * default value since that class only supports the same finite
- * element on all cells anyway.
- *
- * However, for hp objects (i.e. the hp::DoFHandler class),
- * different finite element objects may be used on different
- * cells. On faces between two cells, as well as vertices, there may
- * therefore be two sets of degrees of freedom, one for each of the
- * finite elements used on the adjacent cells. In order to specify
- * which set of degrees of freedom to work on, the last argument is
- * used to disambiguate. Finally, if this function is called for a
- * cell object, there can only be a single set of degrees of
- * freedom, and fe_index has to match the result of
- * active_fe_index().
- *
- * @note While the get_dof_indices() function returns an array that
- * contains the indices of all degrees of freedom that somehow live
- * on this object (i.e. on the vertices, edges or interior of this
- * object), the current dof_index() function only considers the DoFs
- * that really belong to this particular object's interior. In other
- * words, as an example, if the current object refers to a quad (a
- * cell in 2d, a face in 3d) and the finite element associated with
- * it is a bilinear one, then the get_dof_indices() will return an
- * array of size 4 while dof_index() will produce an exception
- * because no degrees are defined in the interior of the face.
+ * The last argument denotes the finite element index. For the standard
+ * ::DoFHandler class, this value must be equal to its default value since
+ * that class only supports the same finite element on all cells anyway.
+ *
+ * However, for hp objects (i.e. the hp::DoFHandler class), different finite
+ * element objects may be used on different cells. On faces between two
+ * cells, as well as vertices, there may therefore be two sets of degrees of
+ * freedom, one for each of the finite elements used on the adjacent cells.
+ * In order to specify which set of degrees of freedom to work on, the last
+ * argument is used to disambiguate. Finally, if this function is called for
+ * a cell object, there can only be a single set of degrees of freedom, and
+ * fe_index has to match the result of active_fe_index().
+ *
+ * @note While the get_dof_indices() function returns an array that contains
+ * the indices of all degrees of freedom that somehow live on this object
+ * (i.e. on the vertices, edges or interior of this object), the current
+ * dof_index() function only considers the DoFs that really belong to this
+ * particular object's interior. In other words, as an example, if the
+ * current object refers to a quad (a cell in 2d, a face in 3d) and the
+ * finite element associated with it is a bilinear one, then the
+ * get_dof_indices() will return an array of size 4 while dof_index() will
+ * produce an exception because no degrees are defined in the interior of
+ * the face.
*/
types::global_dof_index dof_index (const unsigned int i,
const unsigned int fe_index = DH::default_fe_index) const;
*/
/**
- * @name Accessing the finite element associated with this object
+ * @name Accessing the finite element associated with this object
*/
/**
* @{
*/
/**
- * Return the number of finite elements that are active on a given
- * object.
+ * Return the number of finite elements that are active on a given object.
*
- * For non-hp DoFHandler objects, the answer is of course always
- * one. However, for hp::DoFHandler objects, this isn't the case: If
- * this is a cell, the answer is of course one. If it is a face, the
- * answer may be one or two, depending on whether the two adjacent
- * cells use the same finite element or not. If it is an edge in 3d,
- * the possible return value may be one or any other value larger
- * than that.
+ * For non-hp DoFHandler objects, the answer is of course always one.
+ * However, for hp::DoFHandler objects, this isn't the case: If this is a
+ * cell, the answer is of course one. If it is a face, the answer may be one
+ * or two, depending on whether the two adjacent cells use the same finite
+ * element or not. If it is an edge in 3d, the possible return value may be
+ * one or any other value larger than that.
*/
unsigned int
n_active_fe_indices () const;
/**
- * Return the @p n-th active fe index on this object. For cells and
- * all non-hp objects, there is only a single active fe index, so
- * the argument must be equal to zero. For lower-dimensional hp
- * objects, there are n_active_fe_indices() active finite elements,
- * and this function can be queried for their indices.
+ * Return the @p n-th active fe index on this object. For cells and all non-
+ * hp objects, there is only a single active fe index, so the argument must
+ * be equal to zero. For lower-dimensional hp objects, there are
+ * n_active_fe_indices() active finite elements, and this function can be
+ * queried for their indices.
*/
unsigned int
nth_active_fe_index (const unsigned int n) const;
/**
- * Return true if the finite element with given index is active on
- * the present object. For non-hp DoF accessors, this is of course
- * the case only if @p fe_index equals zero. For cells, it is the
- * case if @p fe_index equals active_fe_index() of this cell. For
- * faces and other lower-dimensional objects, there may be more than
- * one @p fe_index that are active on any given object (see
- * n_active_fe_indices()).
+ * Return true if the finite element with given index is active on the
+ * present object. For non-hp DoF accessors, this is of course the case only
+ * if @p fe_index equals zero. For cells, it is the case if @p fe_index
+ * equals active_fe_index() of this cell. For faces and other lower-
+ * dimensional objects, there may be more than one @p fe_index that are
+ * active on any given object (see n_active_fe_indices()).
*/
bool
fe_index_is_active (const unsigned int fe_index) const;
/**
- * Return a reference to the finite element used on this object with
- * the given @p fe_index. @p fe_index must be used on this object,
- * i.e. <code>fe_index_is_active(fe_index)</code> must return true.
+ * Return a reference to the finite element used on this object with the
+ * given @p fe_index. @p fe_index must be used on this object, i.e.
+ * <code>fe_index_is_active(fe_index)</code> must return true.
*/
const FiniteElement<DH::dimension,DH::space_dimension> &
get_fe (const unsigned int fe_index) const;
*/
DeclException0 (ExcMatrixDoesNotMatch);
/**
- * A function has been called for
- * a cell which should be active,
- * but is refined. @ref GlossActive
+ * A function has been called for a cell which should be active, but is
+ * refined. @ref GlossActive
*
* @ingroup Exceptions
*/
protected:
/**
- * Store the address of the DoFHandler object
- * to be accessed.
+ * Store the address of the DoFHandler object to be accessed.
*/
DH *dof_handler;
public:
/**
- * Compare for equality. Return <tt>true</tt> if the two accessors
- * refer to the same object.
+ * Compare for equality. Return <tt>true</tt> if the two accessors refer to
+ * the same object.
*
- * The template parameters of this function allow for a comparison
- * of very different objects. Therefore, some of them are disabled.
- * Namely, if the dimension, or the dof handler of the two objects
- * differ, an exception is generated. It can be expected that this
- * is an unwanted comparison.
+ * The template parameters of this function allow for a comparison of very
+ * different objects. Therefore, some of them are disabled. Namely, if the
+ * dimension, or the dof handler of the two objects differ, an exception is
+ * generated. It can be expected that this is an unwanted comparison.
*
- * The template parameter <tt>level_dof_access2</tt> is ignored,
- * such that an iterator with level access can be equal to one with
- * access to the active degrees of freedom.
+ * The template parameter <tt>level_dof_access2</tt> is ignored, such that
+ * an iterator with level access can be equal to one with access to the
+ * active degrees of freedom.
*/
template <int dim2, class DH2, bool level_dof_access2>
bool operator == (const DoFAccessor<dim2,DH2,level_dof_access2> &) const;
void set_dof_handler (DH *dh);
/**
- * Set the index of the <i>i</i>th degree of freedom of this object
- * to @p index.
+ * Set the index of the <i>i</i>th degree of freedom of this object to @p
+ * index.
*
- * The last argument denotes the finite element index. For the
- * standard ::DoFHandler class, this value must be equal to its
- * default value since that class only supports the same finite
- * element on all cells anyway.
+ * The last argument denotes the finite element index. For the standard
+ * ::DoFHandler class, this value must be equal to its default value since
+ * that class only supports the same finite element on all cells anyway.
*
- * However, for hp objects (i.e. the hp::DoFHandler class),
- * different finite element objects may be used on different
- * cells. On faces between two cells, as well as vertices, there may
- * therefore be two sets of degrees of freedom, one for each of the
- * finite elements used on the adjacent cells. In order to specify
- * which set of degrees of freedom to work on, the last argument is
- * used to disambiguate. Finally, if this function is called for a
- * cell object, there can only be a single set of degrees of
- * freedom, and fe_index has to match the result of
- * active_fe_index().
+ * However, for hp objects (i.e. the hp::DoFHandler class), different finite
+ * element objects may be used on different cells. On faces between two
+ * cells, as well as vertices, there may therefore be two sets of degrees of
+ * freedom, one for each of the finite elements used on the adjacent cells.
+ * In order to specify which set of degrees of freedom to work on, the last
+ * argument is used to disambiguate. Finally, if this function is called for
+ * a cell object, there can only be a single set of degrees of freedom, and
+ * fe_index has to match the result of active_fe_index().
*/
void set_dof_index (const unsigned int i,
const types::global_dof_index index,
void set_mg_dof_index (const int level, const unsigned int i, const types::global_dof_index index) const;
/**
- * Set the global index of the <i>i</i> degree on the @p vertex-th
- * vertex of the present cell to @p index.
+ * Set the global index of the <i>i</i> degree on the @p vertex-th vertex of
+ * the present cell to @p index.
*
- * The last argument denotes the finite element index. For the
- * standard ::DoFHandler class, this value must be equal to its
- * default value since that class only supports the same finite
- * element on all cells anyway.
+ * The last argument denotes the finite element index. For the standard
+ * ::DoFHandler class, this value must be equal to its default value since
+ * that class only supports the same finite element on all cells anyway.
*
- * However, for hp objects (i.e. the hp::DoFHandler class),
- * different finite element objects may be used on different
- * cells. On faces between two cells, as well as vertices, there may
- * therefore be two sets of degrees of freedom, one for each of the
- * finite elements used on the adjacent cells. In order to specify
- * which set of degrees of freedom to work on, the last argument is
- * used to disambiguate. Finally, if this function is called for a
- * cell object, there can only be a single set of degrees of
- * freedom, and fe_index has to match the result of
- * active_fe_index().
+ * However, for hp objects (i.e. the hp::DoFHandler class), different finite
+ * element objects may be used on different cells. On faces between two
+ * cells, as well as vertices, there may therefore be two sets of degrees of
+ * freedom, one for each of the finite elements used on the adjacent cells.
+ * In order to specify which set of degrees of freedom to work on, the last
+ * argument is used to disambiguate. Finally, if this function is called for
+ * a cell object, there can only be a single set of degrees of freedom, and
+ * fe_index has to match the result of active_fe_index().
*/
void set_vertex_dof_index (const unsigned int vertex,
const unsigned int i,
private:
/**
- * Copy operator. This is normally used in a context like
- * <tt>iterator a,b; *a=*b;</tt>. Presumably, the intent here is to
- * copy the object pointed to by @p b to the object pointed to by
- * @p a. However, the result of dereferencing an iterator is not an
- * object but an accessor; consequently, this operation is not
- * useful for iterators on triangulations. We declare this function
- * here private, thus it may not be used from outside. Furthermore
- * it is not implemented and will give a linker error if used
- * anyway.
+ * Copy operator. This is normally used in a context like <tt>iterator a,b;
+ * *a=*b;</tt>. Presumably, the intent here is to copy the object pointed to
+ * by @p b to the object pointed to by @p a. However, the result of
+ * dereferencing an iterator is not an object but an accessor; consequently,
+ * this operation is not useful for iterators on triangulations. We declare
+ * this function here private, thus it may not be used from outside.
+ * Furthermore it is not implemented and will give a linker error if used
+ * anyway.
*/
DoFAccessor<structdim,DH, level_dof_access> &
operator = (const DoFAccessor<structdim,DH, level_dof_access> &da);
/**
- * Make the DoFHandler class a friend so that it can call the
- * set_xxx() functions.
+ * Make the DoFHandler class a friend so that it can call the set_xxx()
+ * functions.
*/
template <int dim, int spacedim> friend class DoFHandler;
template <int dim, int spacedim> friend class hp::DoFHandler;
/**
- * Specialization of the general DoFAccessor class template for the
- * case of zero-dimensional objects (a vertex) that are the face of a
- * one-dimensional cell in spacedim space dimensions. Since vertices
- * function differently than general faces, this class does a few
- * things differently than the general template, but the interface
- * should look the same.
+ * Specialization of the general DoFAccessor class template for the case of
+ * zero-dimensional objects (a vertex) that are the face of a one-dimensional
+ * cell in spacedim space dimensions. Since vertices function differently than
+ * general faces, this class does a few things differently than the general
+ * template, but the interface should look the same.
*
* @author Wolfgang Bangerth, 2010
*/
public:
/**
- * A static variable that allows users of this class to discover the
- * value of the second template argument.
+ * A static variable that allows users of this class to discover the value
+ * of the second template argument.
*/
static const unsigned int dimension=1;
/**
- * A static variable that allows users of this class to discover the
- * value of the third template argument.
+ * A static variable that allows users of this class to discover the value
+ * of the third template argument.
*/
static const unsigned int space_dimension=spacedim;
DoFAccessor ();
/**
- * Constructor to be used if the object here refers to a vertex of a
- * one-dimensional triangulation, i.e. a face of the triangulation.
+ * Constructor to be used if the object here refers to a vertex of a one-
+ * dimensional triangulation, i.e. a face of the triangulation.
*
- * Since there is no mapping from vertices to cells, an accessor
- * object for a point has no way to figure out whether it is at the
- * boundary of the domain or not. Consequently, the second argument
- * must be passed by the object that generates this accessor --
- * e.g. a 1d cell that can figure out whether its left or right
- * vertex are at the boundary.
+ * Since there is no mapping from vertices to cells, an accessor object for
+ * a point has no way to figure out whether it is at the boundary of the
+ * domain or not. Consequently, the second argument must be passed by the
+ * object that generates this accessor -- e.g. a 1d cell that can figure out
+ * whether its left or right vertex are at the boundary.
*
* The third argument is the global index of the vertex we point to.
*
* The fourth argument is a pointer to the DoFHandler object.
*
- * This iterator can only be called for one-dimensional
- * triangulations.
+ * This iterator can only be called for one-dimensional triangulations.
*/
DoFAccessor (const Triangulation<1,spacedim> *tria,
const typename TriaAccessor<0,1,spacedim>::VertexKind vertex_kind,
const DH<1,spacedim> *dof_handler);
/**
- * Constructor. This constructor exists in order to maintain
- * interface compatibility with the other accessor classes. However,
- * it doesn't do anything useful here and so may not actually be
- * called.
+ * Constructor. This constructor exists in order to maintain interface
+ * compatibility with the other accessor classes. However, it doesn't do
+ * anything useful here and so may not actually be called.
*/
DoFAccessor (const Triangulation<1,spacedim> *,
const int = 0,
/**
* Conversion constructor. This constructor exists to make certain
- * constructs simpler to write in dimension independent code. For
- * example, it allows assigning a face iterator to a line iterator,
- * an operation that is useful in 2d but doesn't make any sense in
- * 3d. The constructor here exists for the purpose of making the
- * code conform to C++ but it will unconditionally abort; in other
- * words, assigning a face iterator to a line iterator is better put
- * into an if-statement that checks that the dimension is two, and
- * assign to a quad iterator in 3d (an operator that, without this
- * constructor would be illegal if we happen to compile for 2d).
+ * constructs simpler to write in dimension independent code. For example,
+ * it allows assigning a face iterator to a line iterator, an operation that
+ * is useful in 2d but doesn't make any sense in 3d. The constructor here
+ * exists for the purpose of making the code conform to C++ but it will
+ * unconditionally abort; in other words, assigning a face iterator to a
+ * line iterator is better put into an if-statement that checks that the
+ * dimension is two, and assign to a quad iterator in 3d (an operator that,
+ * without this constructor would be illegal if we happen to compile for
+ * 2d).
*/
template <int structdim2, int dim2, int spacedim2>
DoFAccessor (const InvalidAccessor<structdim2,dim2,spacedim2> &);
/**
- * Another conversion operator between objects that don't make
- * sense, just like the previous one.
+ * Another conversion operator between objects that don't make sense, just
+ * like the previous one.
*/
template <int dim2, class DH2, bool level_dof_access2>
DoFAccessor (const DoFAccessor<dim2, DH2, level_dof_access2> &);
void copy_from (const DoFAccessor<0, DH<1,spacedim>, level_dof_access2> &a);
/**
- * Copy operator used by the iterator class. Keeps the previously
- * set dof handler, but sets the object coordinates of the
- * TriaAccessor.
+ * Copy operator used by the iterator class. Keeps the previously set dof
+ * handler, but sets the object coordinates of the TriaAccessor.
*/
void copy_from (const TriaAccessorBase<0, 1, spacedim> &da);
/**
- * @name Accessing sub-objects
+ * @name Accessing sub-objects
*/
/**
* @{
child (const unsigned int c) const;
/**
- * Pointer to the @p ith line bounding this object. If the current
- * object is a line itself, then the only valid index is @p i equals
- * to zero, and the function returns an iterator to itself.
+ * Pointer to the @p ith line bounding this object. If the current object is
+ * a line itself, then the only valid index is @p i equals to zero, and the
+ * function returns an iterator to itself.
*/
typename dealii::internal::DoFHandler::Iterators<DH<1,spacedim>, level_dof_access>::line_iterator
line (const unsigned int i) const;
/**
- * Pointer to the @p ith quad bounding this object. If the current
- * object is a quad itself, then the only valid index is @p i equals
- * to zero, and the function returns an iterator to itself.
+ * Pointer to the @p ith quad bounding this object. If the current object is
+ * a quad itself, then the only valid index is @p i equals to zero, and the
+ * function returns an iterator to itself.
*/
typename dealii::internal::DoFHandler::Iterators<DH<1,spacedim>, level_dof_access>::quad_iterator
quad (const unsigned int i) const;
*/
/**
- * @name Accessing the DoF indices of this object
+ * @name Accessing the DoF indices of this object
*/
/**
* @{
*/
/**
- * Return the <i>global</i> indices of the degrees of freedom
- * located on this object in the standard ordering defined by the
- * finite element (i.e., dofs on vertex 0, dofs on vertex 1, etc,
- * dofs on line 0, dofs on line 1, etc, dofs on quad 0, etc.) This
- * function is only available on <i>active</i> objects (see @ref
- * GlossActive "this glossary entry").
+ * Return the <i>global</i> indices of the degrees of freedom located on
+ * this object in the standard ordering defined by the finite element (i.e.,
+ * dofs on vertex 0, dofs on vertex 1, etc, dofs on line 0, dofs on line 1,
+ * etc, dofs on quad 0, etc.) This function is only available on
+ * <i>active</i> objects (see @ref GlossActive "this glossary entry").
*
- * The cells needs to be an active cell (and not artificial in a
- * parallel distributed computation).
+ * The cells needs to be an active cell (and not artificial in a parallel
+ * distributed computation).
*
* The vector has to have the right size before being passed to this
* function.
*
- * The last argument denotes the finite element index. For the
- * standard ::DoFHandler class, this value must be equal to its
- * default value since that class only supports the same finite
- * element on all cells anyway.
- *
- * However, for hp objects (i.e. the hp::DoFHandler class),
- * different finite element objects may be used on different
- * cells. On faces between two cells, as well as vertices, there may
- * therefore be two sets of degrees of freedom, one for each of the
- * finite elements used on the adjacent cells. In order to specify
- * which set of degrees of freedom to work on, the last argument is
- * used to disambiguate. Finally, if this function is called for a
- * cell object, there can only be a single set of degrees of
- * freedom, and fe_index has to match the result of
- * active_fe_index().
- *
- * For cells, there is only a single possible finite element index
- * (namely the one for that cell, returned by
- * <code>cell-@>active_fe_index</code>. Consequently, the derived
- * DoFCellAccessor class has an overloaded version of this function
- * that calls the present function with
+ * The last argument denotes the finite element index. For the standard
+ * ::DoFHandler class, this value must be equal to its default value since
+ * that class only supports the same finite element on all cells anyway.
+ *
+ * However, for hp objects (i.e. the hp::DoFHandler class), different finite
+ * element objects may be used on different cells. On faces between two
+ * cells, as well as vertices, there may therefore be two sets of degrees of
+ * freedom, one for each of the finite elements used on the adjacent cells.
+ * In order to specify which set of degrees of freedom to work on, the last
+ * argument is used to disambiguate. Finally, if this function is called for
+ * a cell object, there can only be a single set of degrees of freedom, and
+ * fe_index has to match the result of active_fe_index().
+ *
+ * For cells, there is only a single possible finite element index (namely
+ * the one for that cell, returned by <code>cell-@>active_fe_index</code>.
+ * Consequently, the derived DoFCellAccessor class has an overloaded version
+ * of this function that calls the present function with
* <code>cell-@>active_fe_index</code> as last argument.
*/
void get_dof_indices (std::vector<types::global_dof_index> &dof_indices,
const unsigned int fe_index = AccessorData::default_fe_index) const;
/**
- * Global DoF index of the <i>i</i> degree associated with the @p
- * vertexth vertex of the present cell.
+ * Global DoF index of the <i>i</i> degree associated with the @p vertexth
+ * vertex of the present cell.
*
- * The last argument denotes the finite element index. For the
- * standard ::DoFHandler class, this value must be equal to its
- * default value since that class only supports the same finite
- * element on all cells anyway.
+ * The last argument denotes the finite element index. For the standard
+ * ::DoFHandler class, this value must be equal to its default value since
+ * that class only supports the same finite element on all cells anyway.
*
- * However, for hp objects (i.e. the hp::DoFHandler class),
- * different finite element objects may be used on different
- * cells. On faces between two cells, as well as vertices, there may
- * therefore be two sets of degrees of freedom, one for each of the
- * finite elements used on the adjacent cells. In order to specify
- * which set of degrees of freedom to work on, the last argument is
- * used to disambiguate. Finally, if this function is called for a
- * cell object, there can only be a single set of degrees of
- * freedom, and fe_index has to match the result of
- * active_fe_index().
+ * However, for hp objects (i.e. the hp::DoFHandler class), different finite
+ * element objects may be used on different cells. On faces between two
+ * cells, as well as vertices, there may therefore be two sets of degrees of
+ * freedom, one for each of the finite elements used on the adjacent cells.
+ * In order to specify which set of degrees of freedom to work on, the last
+ * argument is used to disambiguate. Finally, if this function is called for
+ * a cell object, there can only be a single set of degrees of freedom, and
+ * fe_index has to match the result of active_fe_index().
*/
types::global_dof_index vertex_dof_index (const unsigned int vertex,
const unsigned int i,
/**
* Index of the <i>i</i>th degree of freedom of this object.
*
- * The last argument denotes the finite element index. For the
- * standard ::DoFHandler class, this value must be equal to its
- * default value since that class only supports the same finite
- * element on all cells anyway.
- *
- * However, for hp objects (i.e. the hp::DoFHandler class),
- * different finite element objects may be used on different
- * cells. On faces between two cells, as well as vertices, there may
- * therefore be two sets of degrees of freedom, one for each of the
- * finite elements used on the adjacent cells. In order to specify
- * which set of degrees of freedom to work on, the last argument is
- * used to disambiguate. Finally, if this function is called for a
- * cell object, there can only be a single set of degrees of
- * freedom, and fe_index has to match the result of
- * active_fe_index().
- *
- * @note While the get_dof_indices() function returns an array that
- * contains the indices of all degrees of freedom that somehow live
- * on this object (i.e. on the vertices, edges or interior of this
- * object), the current dof_index() function only considers the DoFs
- * that really belong to this particular object's interior. In other
- * words, as an example, if the current object refers to a quad (a
- * cell in 2d, a face in 3d) and the finite element associated with
- * it is a bilinear one, then the get_dof_indices() will return an
- * array of size 4 while dof_index() will produce an exception
- * because no degrees are defined in the interior of the face.
+ * The last argument denotes the finite element index. For the standard
+ * ::DoFHandler class, this value must be equal to its default value since
+ * that class only supports the same finite element on all cells anyway.
+ *
+ * However, for hp objects (i.e. the hp::DoFHandler class), different finite
+ * element objects may be used on different cells. On faces between two
+ * cells, as well as vertices, there may therefore be two sets of degrees of
+ * freedom, one for each of the finite elements used on the adjacent cells.
+ * In order to specify which set of degrees of freedom to work on, the last
+ * argument is used to disambiguate. Finally, if this function is called for
+ * a cell object, there can only be a single set of degrees of freedom, and
+ * fe_index has to match the result of active_fe_index().
+ *
+ * @note While the get_dof_indices() function returns an array that contains
+ * the indices of all degrees of freedom that somehow live on this object
+ * (i.e. on the vertices, edges or interior of this object), the current
+ * dof_index() function only considers the DoFs that really belong to this
+ * particular object's interior. In other words, as an example, if the
+ * current object refers to a quad (a cell in 2d, a face in 3d) and the
+ * finite element associated with it is a bilinear one, then the
+ * get_dof_indices() will return an array of size 4 while dof_index() will
+ * produce an exception because no degrees are defined in the interior of
+ * the face.
*/
types::global_dof_index dof_index (const unsigned int i,
const unsigned int fe_index = AccessorData::default_fe_index) const;
*/
/**
- * @name Accessing the finite element associated with this object
+ * @name Accessing the finite element associated with this object
*/
/**
* @{
*/
/**
- * Return the number of finite elements that are active on a given
- * object.
+ * Return the number of finite elements that are active on a given object.
*
- * For non-hp DoFHandler objects, the answer is of course always
- * one. However, for hp::DoFHandler objects, this isn't the case: If
- * this is a cell, the answer is of course one. If it is a face, the
- * answer may be one or two, depending on whether the two adjacent
- * cells use the same finite element or not. If it is an edge in 3d,
- * the possible return value may be one or any other value larger
- * than that.
+ * For non-hp DoFHandler objects, the answer is of course always one.
+ * However, for hp::DoFHandler objects, this isn't the case: If this is a
+ * cell, the answer is of course one. If it is a face, the answer may be one
+ * or two, depending on whether the two adjacent cells use the same finite
+ * element or not. If it is an edge in 3d, the possible return value may be
+ * one or any other value larger than that.
*/
unsigned int
n_active_fe_indices () const;
/**
- * Return the @p n-th active fe index on this object. For cells and
- * all non-hp objects, there is only a single active fe index, so
- * the argument must be equal to zero. For lower-dimensional hp
- * objects, there are n_active_fe_indices() active finite elements,
- * and this function can be queried for their indices.
+ * Return the @p n-th active fe index on this object. For cells and all non-
+ * hp objects, there is only a single active fe index, so the argument must
+ * be equal to zero. For lower-dimensional hp objects, there are
+ * n_active_fe_indices() active finite elements, and this function can be
+ * queried for their indices.
*/
unsigned int
nth_active_fe_index (const unsigned int n) const;
/**
- * Return true if the finite element with given index is active on
- * the present object. For non-hp DoF accessors, this is of course
- * the case only if @p fe_index equals zero. For cells, it is the
- * case if @p fe_index equals active_fe_index() of this cell. For
- * faces and other lower-dimensional objects, there may be more than
- * one @p fe_index that are active on any given object (see
- * n_active_fe_indices()).
+ * Return true if the finite element with given index is active on the
+ * present object. For non-hp DoF accessors, this is of course the case only
+ * if @p fe_index equals zero. For cells, it is the case if @p fe_index
+ * equals active_fe_index() of this cell. For faces and other lower-
+ * dimensional objects, there may be more than one @p fe_index that are
+ * active on any given object (see n_active_fe_indices()).
*/
bool
fe_index_is_active (const unsigned int fe_index) const;
/**
- * Return a reference to the finite element used on this object with
- * the given @p fe_index. @p fe_index must be used on this object,
- * i.e. <code>fe_index_is_active(fe_index)</code> must return true.
+ * Return a reference to the finite element used on this object with the
+ * given @p fe_index. @p fe_index must be used on this object, i.e.
+ * <code>fe_index_is_active(fe_index)</code> must return true.
*/
const FiniteElement<DH<1,spacedim>::dimension,DH<1,spacedim>::space_dimension> &
get_fe (const unsigned int fe_index) const;
*/
DeclException0 (ExcMatrixDoesNotMatch);
/**
- * A function has been called for a cell which should be active, but
- * is refined. @ref GlossActive
+ * A function has been called for a cell which should be active, but is
+ * refined. @ref GlossActive
*
* @ingroup Exceptions
*/
protected:
/**
- * Store the address of the DoFHandler object
- * to be accessed.
+ * Store the address of the DoFHandler object to be accessed.
*/
DH<1,spacedim> *dof_handler;
/**
- * Compare for equality.
+ * Compare for equality.
*/
template <int dim2, class DH2, bool level_dof_access2>
bool operator == (const DoFAccessor<dim2,DH2,level_dof_access2> &) const;
void set_dof_handler (DH<1,spacedim> *dh);
/**
- * Set the index of the <i>i</i>th degree of freedom of this object
- * to @p index.
+ * Set the index of the <i>i</i>th degree of freedom of this object to @p
+ * index.
*
- * The last argument denotes the finite element index. For the
- * standard ::DoFHandler class, this value must be equal to its
- * default value since that class only supports the same finite
- * element on all cells anyway.
+ * The last argument denotes the finite element index. For the standard
+ * ::DoFHandler class, this value must be equal to its default value since
+ * that class only supports the same finite element on all cells anyway.
*
- * However, for hp objects (i.e. the hp::DoFHandler class),
- * different finite element objects may be used on different
- * cells. On faces between two cells, as well as vertices, there may
- * therefore be two sets of degrees of freedom, one for each of the
- * finite elements used on the adjacent cells. In order to specify
- * which set of degrees of freedom to work on, the last argument is
- * used to disambiguate. Finally, if this function is called for a
- * cell object, there can only be a single set of degrees of
- * freedom, and fe_index has to match the result of
- * active_fe_index().
+ * However, for hp objects (i.e. the hp::DoFHandler class), different finite
+ * element objects may be used on different cells. On faces between two
+ * cells, as well as vertices, there may therefore be two sets of degrees of
+ * freedom, one for each of the finite elements used on the adjacent cells.
+ * In order to specify which set of degrees of freedom to work on, the last
+ * argument is used to disambiguate. Finally, if this function is called for
+ * a cell object, there can only be a single set of degrees of freedom, and
+ * fe_index has to match the result of active_fe_index().
*/
void set_dof_index (const unsigned int i,
const types::global_dof_index index,
const unsigned int fe_index = AccessorData::default_fe_index) const;
/**
- * Set the global index of the <i>i</i> degree on the @p vertex-th
- * vertex of the present cell to @p index.
+ * Set the global index of the <i>i</i> degree on the @p vertex-th vertex of
+ * the present cell to @p index.
*
- * The last argument denotes the finite element index. For the
- * standard ::DoFHandler class, this value must be equal to its
- * default value since that class only supports the same finite
- * element on all cells anyway.
+ * The last argument denotes the finite element index. For the standard
+ * ::DoFHandler class, this value must be equal to its default value since
+ * that class only supports the same finite element on all cells anyway.
*
- * However, for hp objects (i.e. the hp::DoFHandler class),
- * different finite element objects may be used on different
- * cells. On faces between two cells, as well as vertices, there may
- * therefore be two sets of degrees of freedom, one for each of the
- * finite elements used on the adjacent cells. In order to specify
- * which set of degrees of freedom to work on, the last argument is
- * used to disambiguate. Finally, if this function is called for a
- * cell object, there can only be a single set of degrees of
- * freedom, and fe_index has to match the result of
- * active_fe_index().
+ * However, for hp objects (i.e. the hp::DoFHandler class), different finite
+ * element objects may be used on different cells. On faces between two
+ * cells, as well as vertices, there may therefore be two sets of degrees of
+ * freedom, one for each of the finite elements used on the adjacent cells.
+ * In order to specify which set of degrees of freedom to work on, the last
+ * argument is used to disambiguate. Finally, if this function is called for
+ * a cell object, there can only be a single set of degrees of freedom, and
+ * fe_index has to match the result of active_fe_index().
*/
void set_vertex_dof_index (const unsigned int vertex,
const unsigned int i,
/**
- * Make the DoFHandler class a friend so that it can call the
- * set_xxx() functions.
+ * Make the DoFHandler class a friend so that it can call the set_xxx()
+ * functions.
*/
template <int, int> friend class DoFHandler;
template <int, int> friend class hp::DoFHandler;
/**
* Grant access to the degrees of freedom on a cell.
*
- * Note that since for the class we derive from, i.e. <tt>DoFAccessor<dim></tt>,
- * the two template parameters are equal, the base class is actually derived from
- * CellAccessor, which makes the functions of this class available to the
- * DoFCellAccessor class as well.
+ * Note that since for the class we derive from, i.e.
+ * <tt>DoFAccessor<dim></tt>, the two template parameters are equal, the base
+ * class is actually derived from CellAccessor, which makes the functions of
+ * this class available to the DoFCellAccessor class as well.
*
* @ingroup dofs
* @ingroup Accessors
typedef DH Container;
/**
- * A type for an iterator over the faces of a cell. This is
- * what the face() function returns.
+ * A type for an iterator over the faces of a cell. This is what the face()
+ * function returns.
*/
typedef
TriaIterator<DoFAccessor<DH::dimension-1, DH, level_dof_access> >
/**
* Conversion constructor. This constructor exists to make certain
- * constructs simpler to write in dimension independent code. For
- * example, it allows assigning a face iterator to a line iterator,
- * an operation that is useful in 2d but doesn't make any sense in
- * 3d. The constructor here exists for the purpose of making the
- * code conform to C++ but it will unconditionally abort; in other
- * words, assigning a face iterator to a line iterator is better put
- * into an if-statement that checks that the dimension is two, and
- * assign to a quad iterator in 3d (an operator that, without this
- * constructor would be illegal if we happen to compile for 2d).
+ * constructs simpler to write in dimension independent code. For example,
+ * it allows assigning a face iterator to a line iterator, an operation that
+ * is useful in 2d but doesn't make any sense in 3d. The constructor here
+ * exists for the purpose of making the code conform to C++ but it will
+ * unconditionally abort; in other words, assigning a face iterator to a
+ * line iterator is better put into an if-statement that checks that the
+ * dimension is two, and assign to a quad iterator in 3d (an operator that,
+ * without this constructor would be illegal if we happen to compile for
+ * 2d).
*/
template <int structdim2, int dim2, int spacedim2>
DoFCellAccessor (const InvalidAccessor<structdim2,dim2,spacedim2> &);
/**
- * Another conversion operator between objects that don't make
- * sense, just like the previous one.
+ * Another conversion operator between objects that don't make sense, just
+ * like the previous one.
*/
template <int dim2, class DH2, bool level_dof_access2>
explicit
*/
/**
- * Return the parent of this cell as a DoF cell iterator.
- * If the parent does not exist (i.e., if the object is at the coarsest level of
- * the mesh hierarchy), an exception is generated.
+ * Return the parent of this cell as a DoF cell iterator. If the parent does
+ * not exist (i.e., if the object is at the coarsest level of the mesh
+ * hierarchy), an exception is generated.
*
- * This function is needed
- * since the parent function of the base class CellAccessor returns a triangulation
- * cell accessor without access to the DoF data.
+ * This function is needed since the parent function of the base class
+ * CellAccessor returns a triangulation cell accessor without access to the
+ * DoF data.
*/
TriaIterator<DoFCellAccessor<DH, level_dof_access> >
parent () const;
/**
- * @name Accessing sub-objects and neighbors
+ * @name Accessing sub-objects and neighbors
*/
/**
* @{
*/
/**
- * Return the @p ith neighbor as a DoF cell iterator. This function
- * is needed since the neighbor function of the base class returns a
- * cell accessor without access to the DoF data.
+ * Return the @p ith neighbor as a DoF cell iterator. This function is
+ * needed since the neighbor function of the base class returns a cell
+ * accessor without access to the DoF data.
*/
TriaIterator<DoFCellAccessor<DH, level_dof_access> >
neighbor (const unsigned int) const;
/**
- * Return the @p ith child as a DoF cell iterator. This function is
- * needed since the child function of the base class returns a cell
- * accessor without access to the DoF data.
+ * Return the @p ith child as a DoF cell iterator. This function is needed
+ * since the child function of the base class returns a cell accessor
+ * without access to the DoF data.
*/
TriaIterator<DoFCellAccessor<DH, level_dof_access> >
child (const unsigned int) const;
/**
* Return an iterator to the @p ith face of this cell.
*
- * This function is not implemented in 1D, and returns
- * DoFAccessor::line in 2D and DoFAccessor::quad in 3d.
+ * This function is not implemented in 1D, and returns DoFAccessor::line in
+ * 2D and DoFAccessor::quad in 3d.
*/
face_iterator
face (const unsigned int i) const;
/**
- * Return the result of the @p neighbor_child_on_subface function of
- * the base class, but convert it so that one can also access the
- * DoF data (the function in the base class only returns an iterator
- * with access to the triangulation data).
+ * Return the result of the @p neighbor_child_on_subface function of the
+ * base class, but convert it so that one can also access the DoF data (the
+ * function in the base class only returns an iterator with access to the
+ * triangulation data).
*/
TriaIterator<DoFCellAccessor<DH, level_dof_access> >
neighbor_child_on_subface (const unsigned int face_no,
*/
/**
- * @name Extracting values from global vectors
+ * @name Extracting values from global vectors
*/
/**
* @{
*/
/**
- * Return the values of the given vector restricted to the dofs of
- * this cell in the standard ordering: dofs on vertex 0, dofs on
- * vertex 1, etc, dofs on line 0, dofs on line 1, etc, dofs on quad
- * 0, etc.
+ * Return the values of the given vector restricted to the dofs of this cell
+ * in the standard ordering: dofs on vertex 0, dofs on vertex 1, etc, dofs
+ * on line 0, dofs on line 1, etc, dofs on quad 0, etc.
*
* The vector has to have the right size before being passed to this
* function. This function is only callable for active cells.
*
- * The input vector may be either a <tt>Vector<float></tt>,
- * Vector<double>, or a BlockVector<double>, or a PETSc or Trilinos
- * vector if deal.II is compiled to support these libraries. It is
- * in the responsibility of the caller to assure that the types of
- * the numbers stored in input and output vectors are compatible and
- * with similar accuracy.
+ * The input vector may be either a <tt>Vector<float></tt>, Vector<double>,
+ * or a BlockVector<double>, or a PETSc or Trilinos vector if deal.II is
+ * compiled to support these libraries. It is in the responsibility of the
+ * caller to assure that the types of the numbers stored in input and output
+ * vectors are compatible and with similar accuracy.
*/
template <class InputVector, typename number>
void get_dof_values (const InputVector &values,
Vector<number> &local_values) const;
/**
- * Return the values of the given vector restricted to the dofs of
- * this cell in the standard ordering: dofs on vertex 0, dofs on
- * vertex 1, etc, dofs on line 0, dofs on line 1, etc, dofs on quad
- * 0, etc.
+ * Return the values of the given vector restricted to the dofs of this cell
+ * in the standard ordering: dofs on vertex 0, dofs on vertex 1, etc, dofs
+ * on line 0, dofs on line 1, etc, dofs on quad 0, etc.
*
* The vector has to have the right size before being passed to this
* function. This function is only callable for active cells.
*
- * The input vector may be either a <tt>Vector<float></tt>,
- * Vector<double>, or a BlockVector<double>, or a PETSc or Trilinos
- * vector if deal.II is compiled to support these libraries. It is
- * in the responsibility of the caller to assure that the types of
- * the numbers stored in input and output vectors are compatible and
- * with similar accuracy.
+ * The input vector may be either a <tt>Vector<float></tt>, Vector<double>,
+ * or a BlockVector<double>, or a PETSc or Trilinos vector if deal.II is
+ * compiled to support these libraries. It is in the responsibility of the
+ * caller to assure that the types of the numbers stored in input and output
+ * vectors are compatible and with similar accuracy.
*/
template <class InputVector, typename ForwardIterator>
void get_dof_values (const InputVector &values,
ForwardIterator local_values_end) const;
/**
- * Return the values of the given vector restricted to the dofs of
- * this cell in the standard ordering: dofs on vertex 0, dofs on
- * vertex 1, etc, dofs on line 0, dofs on line 1, etc, dofs on quad
- * 0, etc.
+ * Return the values of the given vector restricted to the dofs of this cell
+ * in the standard ordering: dofs on vertex 0, dofs on vertex 1, etc, dofs
+ * on line 0, dofs on line 1, etc, dofs on quad 0, etc.
*
* The vector has to have the right size before being passed to this
* function. This function is only callable for active cells.
*
- * The input vector may be either a <tt>Vector<float></tt>,
- * Vector<double>, or a BlockVector<double>, or a PETSc or Trilinos
- * vector if deal.II is compiled to support these libraries. It is
- * in the responsibility of the caller to assure that the types of
- * the numbers stored in input and output vectors are compatible and
- * with similar accuracy. The ConstraintMatrix passed as an argument
- * to this function makes sure that constraints are correctly
- * distributed when the dof values are calculated.
+ * The input vector may be either a <tt>Vector<float></tt>, Vector<double>,
+ * or a BlockVector<double>, or a PETSc or Trilinos vector if deal.II is
+ * compiled to support these libraries. It is in the responsibility of the
+ * caller to assure that the types of the numbers stored in input and output
+ * vectors are compatible and with similar accuracy. The ConstraintMatrix
+ * passed as an argument to this function makes sure that constraints are
+ * correctly distributed when the dof values are calculated.
*/
template <class InputVector, typename ForwardIterator>
void get_dof_values (const ConstraintMatrix &constraints,
ForwardIterator local_values_end) const;
/**
- * This function is the counterpart to get_dof_values(): it takes a
- * vector of values for the degrees of freedom of the cell pointed
- * to by this iterator and writes these values into the global data
- * vector @p values. This function is only callable for active
- * cells.
+ * This function is the counterpart to get_dof_values(): it takes a vector
+ * of values for the degrees of freedom of the cell pointed to by this
+ * iterator and writes these values into the global data vector @p values.
+ * This function is only callable for active cells.
*
- * Note that for continuous finite elements, calling this function
- * affects the dof values on neighboring cells as well. It may also
- * violate continuity requirements for hanging nodes, if neighboring
- * cells are less refined than the present one. These requirements
- * are not taken care of and must be enforced by the user
- * afterwards.
+ * Note that for continuous finite elements, calling this function affects
+ * the dof values on neighboring cells as well. It may also violate
+ * continuity requirements for hanging nodes, if neighboring cells are less
+ * refined than the present one. These requirements are not taken care of
+ * and must be enforced by the user afterwards.
*
* The vector has to have the right size before being passed to this
* function.
*
- * The output vector may be either a Vector<float>, Vector<double>,
- * or a BlockVector<double>, or a PETSc vector if deal.II is
- * compiled to support these libraries. It is in the responsibility
- * of the caller to assure that the types of the numbers stored in
- * input and output vectors are compatible and with similar
- * accuracy.
+ * The output vector may be either a Vector<float>, Vector<double>, or a
+ * BlockVector<double>, or a PETSc vector if deal.II is compiled to support
+ * these libraries. It is in the responsibility of the caller to assure that
+ * the types of the numbers stored in input and output vectors are
+ * compatible and with similar accuracy.
*/
template <class OutputVector, typename number>
void set_dof_values (const Vector<number> &local_values,
OutputVector &values) const;
/**
- * Return the interpolation of the given finite element function to
- * the present cell. In the simplest case, the cell is a terminal
- * one, i.e., it has no children; then, the returned value is the vector
- * of nodal values on that cell. You could as well get the
- * desired values through the @p get_dof_values function. In the
- * other case, when the cell has children, we use the restriction
- * matrices provided by the finite element class to compute the
- * interpolation from the children to the present cell.
+ * Return the interpolation of the given finite element function to the
+ * present cell. In the simplest case, the cell is a terminal one, i.e., it
+ * has no children; then, the returned value is the vector of nodal values
+ * on that cell. You could as well get the desired values through the @p
+ * get_dof_values function. In the other case, when the cell has children,
+ * we use the restriction matrices provided by the finite element class to
+ * compute the interpolation from the children to the present cell.
*
* If the cell is part of a hp::DoFHandler object, cells only have an
* associated finite element space if they are active. However, this
- * function is supposed to also provide information on inactive cells
- * with children. Consequently, it carries a third argument that can be
- * used in the hp context that denotes the finite element space we are
- * supposed to interpolate onto. If the cell is active, this function
- * then obtains the finite element function from the <code>values</code>
- * vector on this cell and interpolates it onto the space described
- * by the <code>fe_index</code>th element of the hp::FECollection associated
- * with the hp::DoFHandler of which this cell is a part of. If the cell
- * is not active, then we first perform this interpolation on all of its
- * terminal children and then interpolate this function down to the
- * cell requested keeping the function space the same.
+ * function is supposed to also provide information on inactive cells with
+ * children. Consequently, it carries a third argument that can be used in
+ * the hp context that denotes the finite element space we are supposed to
+ * interpolate onto. If the cell is active, this function then obtains the
+ * finite element function from the <code>values</code> vector on this cell
+ * and interpolates it onto the space described by the
+ * <code>fe_index</code>th element of the hp::FECollection associated with
+ * the hp::DoFHandler of which this cell is a part of. If the cell is not
+ * active, then we first perform this interpolation on all of its terminal
+ * children and then interpolate this function down to the cell requested
+ * keeping the function space the same.
*
* It is assumed that both input vectors already have the right size
* beforehand.
*
- * @note Unlike the get_dof_values() function, this function is only available
- * on cells, rather than on lines, quads, and hexes, since interpolation
- * is presently only provided for cells by the finite element
+ * @note Unlike the get_dof_values() function, this function is only
+ * available on cells, rather than on lines, quads, and hexes, since
+ * interpolation is presently only provided for cells by the finite element
* classes.
*/
template <class InputVector, typename number>
const unsigned int fe_index = DH::default_fe_index) const;
/**
- * This function is the counterpart to get_interpolated_dof_values():
- * you specify the dof values on a cell and these are interpolated
- * to the children of the present cell and set on the terminal
- * cells.
+ * This function is the counterpart to get_interpolated_dof_values(): you
+ * specify the dof values on a cell and these are interpolated to the
+ * children of the present cell and set on the terminal cells.
*
- * In principle, it works as follows: if the cell pointed to by this
- * object is terminal (i.e., has no children), then the dof values are set in the global
- * data vector by calling the set_dof_values() function; otherwise,
- * the values are prolonged to each of the children and this
- * function is called for each of them.
+ * In principle, it works as follows: if the cell pointed to by this object
+ * is terminal (i.e., has no children), then the dof values are set in the
+ * global data vector by calling the set_dof_values() function; otherwise,
+ * the values are prolonged to each of the children and this function is
+ * called for each of them.
*
- * Using the get_interpolated_dof_values() and this function, you
- * can compute the interpolation of a finite element function to a
- * coarser grid by first getting the interpolated solution on a cell
- * of the coarse grid and afterwards redistributing it using this
- * function.
+ * Using the get_interpolated_dof_values() and this function, you can
+ * compute the interpolation of a finite element function to a coarser grid
+ * by first getting the interpolated solution on a cell of the coarse grid
+ * and afterwards redistributing it using this function.
*
- * Note that for continuous finite elements, calling this function
- * affects the dof values on neighboring cells as well. It may also
- * violate continuity requirements for hanging nodes, if neighboring
- * cells are less refined than the present one, or if their children
- * are less refined than the children of this cell. These
- * requirements are not taken care of and must be enforced by the
- * user afterward.
+ * Note that for continuous finite elements, calling this function affects
+ * the dof values on neighboring cells as well. It may also violate
+ * continuity requirements for hanging nodes, if neighboring cells are less
+ * refined than the present one, or if their children are less refined than
+ * the children of this cell. These requirements are not taken care of and
+ * must be enforced by the user afterward.
*
* If the cell is part of a hp::DoFHandler object, cells only have an
* associated finite element space if they are active. However, this
- * function is supposed to also work on inactive cells
- * with children. Consequently, it carries a third argument that can be
- * used in the hp context that denotes the finite element space we are
- * supposed to interpret the input vector of this function in.
- * If the cell is active, this function
- * then interpolates the input vector interpreted as an element of the space described
- * by the <code>fe_index</code>th element of the hp::FECollection associated
- * with the hp::DoFHandler of which this cell is a part of, and interpolates
- * it into the space that is associated with this cell. On the other hand, if the cell
- * is not active, then we first perform this interpolation from this cell
- * to its children using the given <code>fe_index</code> until we end
- * up on an active cell, at which point we follow the procedure outlined
- * at the beginning of the paragraph.
- *
- * It is assumed that both vectors already have the right size
- * beforehand. This function relies on the existence of a natural
- * interpolation property of finite element spaces of a cell to its
- * children, denoted by the prolongation matrices of finite element
- * classes. For some elements, the spaces on coarse and fine grids
- * are not nested, in which case the interpolation to a child is not
- * the identity; refer to the documentation of the respective finite
- * element class for a description of what the prolongation matrices
- * represent in this case.
- *
- * @note Unlike the get_dof_values() function, this function is only available
- * on cells, rather than on lines, quads, and hexes, since interpolation
- * is presently only provided for cells by the finite element
+ * function is supposed to also work on inactive cells with children.
+ * Consequently, it carries a third argument that can be used in the hp
+ * context that denotes the finite element space we are supposed to
+ * interpret the input vector of this function in. If the cell is active,
+ * this function then interpolates the input vector interpreted as an
+ * element of the space described by the <code>fe_index</code>th element of
+ * the hp::FECollection associated with the hp::DoFHandler of which this
+ * cell is a part of, and interpolates it into the space that is associated
+ * with this cell. On the other hand, if the cell is not active, then we
+ * first perform this interpolation from this cell to its children using the
+ * given <code>fe_index</code> until we end up on an active cell, at which
+ * point we follow the procedure outlined at the beginning of the paragraph.
+ *
+ * It is assumed that both vectors already have the right size beforehand.
+ * This function relies on the existence of a natural interpolation property
+ * of finite element spaces of a cell to its children, denoted by the
+ * prolongation matrices of finite element classes. For some elements, the
+ * spaces on coarse and fine grids are not nested, in which case the
+ * interpolation to a child is not the identity; refer to the documentation
+ * of the respective finite element class for a description of what the
+ * prolongation matrices represent in this case.
+ *
+ * @note Unlike the get_dof_values() function, this function is only
+ * available on cells, rather than on lines, quads, and hexes, since
+ * interpolation is presently only provided for cells by the finite element
* classes.
*/
template <class OutputVector, typename number>
const unsigned int fe_index = DH::default_fe_index) const;
/**
- * Distribute a local (cell based) vector to a global one by mapping
- * the local numbering of the degrees of freedom to the global one
- * and entering the local values into the global vector.
+ * Distribute a local (cell based) vector to a global one by mapping the
+ * local numbering of the degrees of freedom to the global one and entering
+ * the local values into the global vector.
*
- * The elements are <em>added</em> up to the elements in the global
- * vector, rather than just set, since this is usually what one
- * wants.
+ * The elements are <em>added</em> up to the elements in the global vector,
+ * rather than just set, since this is usually what one wants.
*/
template <typename number, typename OutputVector>
void
OutputVector &global_destination) const;
/**
- * Distribute a local (cell based) vector in iterator format to a
- * global one by mapping the local numbering of the degrees of
- * freedom to the global one and entering the local values into the
- * global vector.
+ * Distribute a local (cell based) vector in iterator format to a global one
+ * by mapping the local numbering of the degrees of freedom to the global
+ * one and entering the local values into the global vector.
*
- * The elements are <em>added</em> up to the elements in the global
- * vector, rather than just set, since this is usually what one
- * wants.
+ * The elements are <em>added</em> up to the elements in the global vector,
+ * rather than just set, since this is usually what one wants.
*/
template <typename ForwardIterator, typename OutputVector>
void
OutputVector &global_destination) const;
/**
- * Distribute a local (cell based) vector in iterator format to a
- * global one by mapping the local numbering of the degrees of
- * freedom to the global one and entering the local values into the
- * global vector.
+ * Distribute a local (cell based) vector in iterator format to a global one
+ * by mapping the local numbering of the degrees of freedom to the global
+ * one and entering the local values into the global vector.
*
- * The elements are <em>added</em> up to the elements in the global
- * vector, rather than just set, since this is usually what one
- * wants. Moreover, the ConstraintMatrix passed to this function
- * makes sure that also constraints are eliminated in this process.
+ * The elements are <em>added</em> up to the elements in the global vector,
+ * rather than just set, since this is usually what one wants. Moreover, the
+ * ConstraintMatrix passed to this function makes sure that also constraints
+ * are eliminated in this process.
*/
template <typename ForwardIterator, typename OutputVector>
void
/**
* This function does much the same as the
- * <tt>distribute_local_to_global(Vector,Vector)</tt> function, but
- * operates on matrices instead of vectors. If the matrix type is a
- * sparse matrix then it is supposed to have non-zero entry slots
- * where required.
+ * <tt>distribute_local_to_global(Vector,Vector)</tt> function, but operates
+ * on matrices instead of vectors. If the matrix type is a sparse matrix
+ * then it is supposed to have non-zero entry slots where required.
*/
template <typename number, typename OutputMatrix>
void
OutputMatrix &global_destination) const;
/**
- * This function does what the two
- * <tt>distribute_local_to_global</tt> functions with vector and
- * matrix argument do, but all at once.
+ * This function does what the two <tt>distribute_local_to_global</tt>
+ * functions with vector and matrix argument do, but all at once.
*/
template <typename number, typename OutputMatrix, typename OutputVector>
void
*/
/**
- * @name Accessing the DoF indices of this object
+ * @name Accessing the DoF indices of this object
*/
/**
/**
* Obtain the global indices of the local degrees of freedom on this cell.
*
- * If this object accesses a level cell (indicated by the third
- * template argument or #is_level_cell), then return the result of
+ * If this object accesses a level cell (indicated by the third template
+ * argument or #is_level_cell), then return the result of
* get_mg_dof_indices(), else return get_dof_indices().
*
- * You will get a level_cell_iterator when calling begin_mg() and a
- * normal one otherwise.
+ * You will get a level_cell_iterator when calling begin_mg() and a normal
+ * one otherwise.
*
* Examples for this use are in the implementation of DoFRenumbering.
*/
* <i>active</i> objects (see @ref GlossActive "this glossary entry").
*
* @param[out] dof_indices The vector into which the indices will be
- * written. It has to have the right size (namely,
- * <code>fe.dofs_per_cell</code>, <code>fe.dofs_per_face</code>,
- * or <code>fe.dofs_per_line</code>, depending on which kind of
- * object this function is called) before being passed to this
- * function.
- *
- * This function reimplements the same function in the base class.
- * In contrast to the function in the base class, we do not need the
+ * written. It has to have the right size (namely,
+ * <code>fe.dofs_per_cell</code>, <code>fe.dofs_per_face</code>, or
+ * <code>fe.dofs_per_line</code>, depending on which kind of object this
+ * function is called) before being passed to this function.
+ *
+ * This function reimplements the same function in the base class. In
+ * contrast to the function in the base class, we do not need the
* <code>fe_index</code> here because there is always a unique finite
* element index on cells.
*
*
* Also see get_active_or_mg_dof_indices().
*
- * @note In many places in the tutorial and elsewhere in the library,
- * the argument to this function is called <code>local_dof_indices</code>
- * by convention. The name is not meant to indicate the <i>local</i>
- * numbers of degrees of freedom (which are always between zero and
- * <code>fe.dofs_per_cell</code>) but instead that the returned values
- * are the <i>global</i> indices of those degrees of freedom that
- * are located locally on the current cell.
+ * @note In many places in the tutorial and elsewhere in the library, the
+ * argument to this function is called <code>local_dof_indices</code> by
+ * convention. The name is not meant to indicate the <i>local</i> numbers of
+ * degrees of freedom (which are always between zero and
+ * <code>fe.dofs_per_cell</code>) but instead that the returned values are
+ * the <i>global</i> indices of those degrees of freedom that are located
+ * locally on the current cell.
*
- * @deprecated Currently, this function can also be called for non-active cells, if all degrees of freedom of the FiniteElement are located in vertices. This functionality will vanish in a future release.
+ * @deprecated Currently, this function can also be called for non-active
+ * cells, if all degrees of freedom of the FiniteElement are located in
+ * vertices. This functionality will vanish in a future release.
*/
void get_dof_indices (std::vector<types::global_dof_index> &dof_indices) const;
/**
- * @deprecated Use get_active_or_mg_dof_indices() with level_cell_iterator returned from begin_mg().
+ * @deprecated Use get_active_or_mg_dof_indices() with level_cell_iterator
+ * returned from begin_mg().
*
* Retrieve the global indices of the degrees of freedom on this cell in the
* level vector associated to the level of the cell.
*/
/**
- * @name Accessing the finite element associated with this object
+ * @name Accessing the finite element associated with this object
*/
/**
* @{
*/
/**
- * Return the finite element that is used on the cell pointed to by
- * this iterator. For non-hp DoF handlers, this is of course always
- * the same element, independent of the cell we are presently on,
- * but for hp DoF handlers, this may change from cell to cell.
+ * Return the finite element that is used on the cell pointed to by this
+ * iterator. For non-hp DoF handlers, this is of course always the same
+ * element, independent of the cell we are presently on, but for hp DoF
+ * handlers, this may change from cell to cell.
*
- * @note Since degrees of freedoms only exist on active cells
- * for hp::DoFHandler (i.e., there is currently no implementation
- * of multilevel hp::DoFHandler objects), it does not make sense
- * to query the finite element on non-active cells since they
- * do not have finite element spaces associated with them without
- * having any degrees of freedom. Consequently, this function will
- * produce an exception when called on non-active cells.
+ * @note Since degrees of freedoms only exist on active cells for
+ * hp::DoFHandler (i.e., there is currently no implementation of multilevel
+ * hp::DoFHandler objects), it does not make sense to query the finite
+ * element on non-active cells since they do not have finite element spaces
+ * associated with them without having any degrees of freedom. Consequently,
+ * this function will produce an exception when called on non-active cells.
*/
const FiniteElement<DH::dimension,DH::space_dimension> &
get_fe () const;
/**
- * Returns the index inside the hp::FECollection of the
- * FiniteElement used for this cell. This function is
- * only useful if the DoF handler object associated with
- * the current cell is an hp::DoFHandler.
+ * Returns the index inside the hp::FECollection of the FiniteElement used
+ * for this cell. This function is only useful if the DoF handler object
+ * associated with the current cell is an hp::DoFHandler.
*
- * @note Since degrees of freedoms only exist on active cells
- * for hp::DoFHandler (i.e., there is currently no implementation
- * of multilevel hp::DoFHandler objects), it does not make sense
- * to query active FE indices on non-active cells since they
- * do not have finite element spaces associated with them without
- * having any degrees of freedom. Consequently, this function will
- * produce an exception when called on non-active cells.
+ * @note Since degrees of freedoms only exist on active cells for
+ * hp::DoFHandler (i.e., there is currently no implementation of multilevel
+ * hp::DoFHandler objects), it does not make sense to query active FE
+ * indices on non-active cells since they do not have finite element spaces
+ * associated with them without having any degrees of freedom. Consequently,
+ * this function will produce an exception when called on non-active cells.
*/
unsigned int active_fe_index () const;
/**
- * Sets the index of the FiniteElement used for this cell. This
- * determines which element in an hp::FECollection to use. This function is
- * only useful if the DoF handler object associated with
- * the current cell is an hp::DoFHandler.
+ * Sets the index of the FiniteElement used for this cell. This determines
+ * which element in an hp::FECollection to use. This function is only useful
+ * if the DoF handler object associated with the current cell is an
+ * hp::DoFHandler.
*
- * @note Since degrees of freedoms only exist on active cells
- * for hp::DoFHandler (i.e., there is currently no implementation
- * of multilevel hp::DoFHandler objects), it does not make sense
- * to assign active FE indices to non-active cells since they
- * do not have finite element spaces associated with them without
- * having any degrees of freedom. Consequently, this function will
- * produce an exception when called on non-active cells.
+ * @note Since degrees of freedoms only exist on active cells for
+ * hp::DoFHandler (i.e., there is currently no implementation of multilevel
+ * hp::DoFHandler objects), it does not make sense to assign active FE
+ * indices to non-active cells since they do not have finite element spaces
+ * associated with them without having any degrees of freedom. Consequently,
+ * this function will produce an exception when called on non-active cells.
*/
void set_active_fe_index (const unsigned int i);
/**
*/
/**
- * Set the DoF indices of this cell to the given values. This
- * function bypasses the DoF cache, if one exists for the given DoF
- * handler class.
+ * Set the DoF indices of this cell to the given values. This function
+ * bypasses the DoF cache, if one exists for the given DoF handler class.
*/
void set_dof_indices (const std::vector<types::global_dof_index> &dof_indices);
private:
/**
- * Copy operator. This is normally used in a context like
- * <tt>iterator a,b; *a=*b;</tt>. Presumably, the intent here is to
- * copy the object pointed to by @p b to the object pointed to by
- * @p a. However, the result of dereferencing an iterator is not an
- * object but an accessor; consequently, this operation is not
- * useful for iterators on triangulations. We declare this function
- * here private, thus it may not be used from outside. Furthermore
- * it is not implemented and will give a linker error if used
- * anyway.
+ * Copy operator. This is normally used in a context like <tt>iterator a,b;
+ * *a=*b;</tt>. Presumably, the intent here is to copy the object pointed to
+ * by @p b to the object pointed to by @p a. However, the result of
+ * dereferencing an iterator is not an object but an accessor; consequently,
+ * this operation is not useful for iterators on triangulations. We declare
+ * this function here private, thus it may not be used from outside.
+ * Furthermore it is not implemented and will give a linker error if used
+ * anyway.
*/
DoFCellAccessor<DH, level_dof_access> &
operator = (const DoFCellAccessor<DH, level_dof_access> &da);
namespace DoFAccessor
{
/**
- * A class like the one with same
- * name in tria.cc. See there for
- * more information.
+ * A class like the one with same name in tria.cc. See there for more
+ * information.
*/
struct Implementation
{
/**
- * Implementations of the
- * get_dof_index/set_dof_index functions.
+ * Implementations of the get_dof_index/set_dof_index functions.
*/
template <int spacedim>
static
}
/**
- * Set the @p local_index-th
- * degree of freedom
- * corresponding to the finite
- * element specified by @p
- * fe_index on the vertex with
- * global number @p
- * vertex_index to @p
- * global_index.
+ * Set the @p local_index-th degree of freedom corresponding to the
+ * finite element specified by @p fe_index on the vertex with global
+ * number @p vertex_index to @p global_index.
*/
template <int dim, int spacedim>
static
/**
- * Get the @p local_index-th
- * degree of freedom
- * corresponding to the finite
- * element specified by @p
- * fe_index on the vertex with
- * global number @p
- * vertex_index to @p
- * global_index.
+ * Get the @p local_index-th degree of freedom corresponding to the
+ * finite element specified by @p fe_index on the vertex with global
+ * number @p vertex_index to @p global_index.
*/
template <int dim, int spacedim>
/**
- * Return the number of
- * different finite elements
- * that are active on a given
- * vertex.
+ * Return the number of different finite elements that are active on a
+ * given vertex.
*/
template<int dim, int spacedim>
static
/**
- * Return the fe index of the
- * n-th finite element active
- * on a given vertex.
+ * Return the fe index of the n-th finite element active on a given
+ * vertex.
*/
template<int dim, int spacedim>
static
/**
- * Return whether a particular
- * finite element index is
- * active on the specified
- * vertex.
+ * Return whether a particular finite element index is active on the
+ * specified vertex.
*/
template<int dim, int spacedim>
static
struct Implementation
{
/**
- * Implement the updating of the
- * cache. Currently not
- * implemented for hp::DoFHandler
- * objects.
+ * Implement the updating of the cache. Currently not implemented for
+ * hp::DoFHandler objects.
*/
template <int spacedim, bool level_dof_access>
static
/**
- * Implement setting dof
- * indices on a
- * cell. Currently not
- * implemented for
- * hp::DoFHandler objects.
+ * Implement setting dof indices on a cell. Currently not implemented
+ * for hp::DoFHandler objects.
*/
template <int spacedim, bool level_dof_access>
static
/**
- * Do what the active_fe_index
- * function in the parent class
- * is supposed to do.
+ * Do what the active_fe_index function in the parent class is supposed
+ * to do.
*/
template <int dim, int spacedim, bool level_dof_access>
static
/**
- * Do what the
- * set_active_fe_index function
- * in the parent class is
+ * Do what the set_active_fe_index function in the parent class is
* supposed to do.
*/
template <int dim, int spacedim, bool level_dof_access>
namespace internal
{
/**
- * A namespace for internal data structures of the DoFHandler group of classes.
+ * A namespace for internal data structures of the DoFHandler group of
+ * classes.
*
* @ingroup dofs
*/
*
* <h4>DoFFaces</h4>
*
- * These classes are similar to the DoFLevel classes. We here store information
- * that is associated with faces, rather than cells, as this information is independent of
- * the hierarchical structure of cells, which are organized in levels. In 2D we store
- * information on degrees of freedom located on lines whereas in 3D we store information on
- * degrees of freedom located on quads and lines. In 1D we do nothing, as the faces of
- * lines are vertices which are treated separately.
+ * These classes are similar to the DoFLevel classes. We here store
+ * information that is associated with faces, rather than cells, as this
+ * information is independent of the hierarchical structure of cells,
+ * which are organized in levels. In 2D we store information on degrees of
+ * freedom located on lines whereas in 3D we store information on degrees
+ * of freedom located on quads and lines. In 1D we do nothing, as the
+ * faces of lines are vertices which are treated separately.
*
- * Apart from the DoFObjects object containing the data to store (degree of freedom
- * indices) we do not store any data or provide any functionality. However, we do implement
- * a function to determine an estimate of the memory consumption of the contained
- * DoFObjects object(s).
+ * Apart from the DoFObjects object containing the data to store (degree
+ * of freedom indices) we do not store any data or provide any
+ * functionality. However, we do implement a function to determine an
+ * estimate of the memory consumption of the contained DoFObjects
+ * object(s).
*
- * The data contained isn't usually directly accessed. Rather, except for some access from
- * the DoFHandler class, access is usually through the DoFAccessor::set_dof_index() and
- * DoFAccessor::dof_index() functions or similar functions of derived classes that in turn
- * access the member variables using the DoFHandler::get_dof_index() and corresponding
- * setter functions. Knowledge of the actual data format is therefore encapsulated to the
- * present hierarchy of classes as well as the dealii::DoFHandler class.
+ * The data contained isn't usually directly accessed. Rather, except for
+ * some access from the DoFHandler class, access is usually through the
+ * DoFAccessor::set_dof_index() and DoFAccessor::dof_index() functions or
+ * similar functions of derived classes that in turn access the member
+ * variables using the DoFHandler::get_dof_index() and corresponding
+ * setter functions. Knowledge of the actual data format is therefore
+ * encapsulated to the present hierarchy of classes as well as the
+ * dealii::DoFHandler class.
*
* @author Tobias Leicht, 2006
*/
class DoFFaces
{
/**
- * Make the constructor private to prevent the use
- * of this template, only the specializations
- * should be used
+ * Make the constructor private to prevent the use of this template,
+ * only the specializations should be used
*/
private:
DoFFaces();
};
/**
- * Store the indices of degrees of freedom on faces in 1D. As these would be vertices, which
- * are treted separately, don't do anything.
+ * Store the indices of degrees of freedom on faces in 1D. As these would
+ * be vertices, which are treted separately, don't do anything.
*
* @author Tobias Leicht, 2006
*/
{
public:
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
*/
template <class Archive>
void serialize(Archive &ar,
};
/**
- * Store the indices of degrees of freedom on faces in 2D, which are lines.
+ * Store the indices of degrees of freedom on faces in 2D, which are
+ * lines.
*
* @author Tobias Leicht, 2006
*/
{
public:
/**
- * The object containing the
- * data of DoFs on lines.
+ * The object containing the data of DoFs on lines.
*/
internal::DoFHandler::DoFObjects<1> lines;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
*/
template <class Archive>
void serialize(Archive &ar,
};
/**
- * Store the indices of degrees of freedom on faces in 3D, which are quads, additionally also on lines.
+ * Store the indices of degrees of freedom on faces in 3D, which are
+ * quads, additionally also on lines.
*
* @author Tobias Leicht, 2006
*/
{
public:
/**
- * The object containing the
- * data of DoFs on lines.
+ * The object containing the data of DoFs on lines.
*/
internal::DoFHandler::DoFObjects<1> lines;
/**
- * The object containing the
- * data of DoFs on quads.
+ * The object containing the data of DoFs on quads.
*/
internal::DoFHandler::DoFObjects<2> quads;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
*/
template <class Archive>
void serialize(Archive &ar,
/**
- * Manage the distribution and numbering of the degrees of freedom for
- * non-multigrid algorithms. This class satisfies the requirements outlined in
+ * Manage the distribution and numbering of the degrees of freedom for non-
+ * multigrid algorithms. This class satisfies the requirements outlined in
* @ref GlossMeshAsAContainer "Meshes as containers". It is first used in the
* step-2 tutorial program.
*
- * For each vertex, line, quad, etc, this class stores a list of the
- * indices of degrees of freedom living on this object. These indices refer
- * to the unconstrained degrees of freedom, i.e. constrained degrees of
- * freedom are numbered in the same way as unconstrained ones, and are only
- * later eliminated. This leads to the fact that indices in global vectors
- * and matrices also refer to all degrees of freedom and some kind of
- * condensation is needed to restrict the systems of equations to the
- * unconstrained degrees of freedom only. The actual layout of storage of
- * the indices is described in the dealii::internal::DoFHandler::DoFLevel
- * class documentation.
+ * For each vertex, line, quad, etc, this class stores a list of the indices
+ * of degrees of freedom living on this object. These indices refer to the
+ * unconstrained degrees of freedom, i.e. constrained degrees of freedom are
+ * numbered in the same way as unconstrained ones, and are only later
+ * eliminated. This leads to the fact that indices in global vectors and
+ * matrices also refer to all degrees of freedom and some kind of condensation
+ * is needed to restrict the systems of equations to the unconstrained degrees
+ * of freedom only. The actual layout of storage of the indices is described
+ * in the dealii::internal::DoFHandler::DoFLevel class documentation.
*
- * The class offers iterators to traverse all cells, in much the same way
- * as the Triangulation class does. Using the begin() and end() functions
- * (and companions, like begin_active()), one can obtain iterators to walk
- * over cells, and query the degree of freedom structures as well as the
+ * The class offers iterators to traverse all cells, in much the same way as
+ * the Triangulation class does. Using the begin() and end() functions (and
+ * companions, like begin_active()), one can obtain iterators to walk over
+ * cells, and query the degree of freedom structures as well as the
* triangulation data. These iterators are built on top of those of the
* Triangulation class, but offer the additional information on degrees of
- * freedom functionality compared to pure triangulation iterators. The
- * order in which dof iterators are presented by the <tt>++</tt> and
- * <tt>--</tt> operators is the same as that for the corresponding
- * iterators traversing the triangulation on which this DoFHandler is
- * constructed.
+ * freedom functionality compared to pure triangulation iterators. The order
+ * in which dof iterators are presented by the <tt>++</tt> and <tt>--</tt>
+ * operators is the same as that for the corresponding iterators traversing
+ * the triangulation on which this DoFHandler is constructed.
*
* The <tt>spacedim</tt> parameter has to be used if one wants to solve
* problems on surfaces. If not specified, this parameter takes the default
* value <tt>=dim</tt> implying that we want to solve problems in a domain
- * whose dimension equals the dimension of the space in which it is
- * embedded.
+ * whose dimension equals the dimension of the space in which it is embedded.
*
*
* <h3>Distribution of indices for degrees of freedom</h3>
* children, i.e. they are the most refined ones.
*
* Since the triangulation is traversed starting with the cells of the
- * coarsest active level and going to more refined levels, the lowest
- * numbers for dofs are given to the largest cells as well as their
- * bounding lines and vertices, with the dofs of more refined cells getting
- * higher numbers.
+ * coarsest active level and going to more refined levels, the lowest numbers
+ * for dofs are given to the largest cells as well as their bounding lines and
+ * vertices, with the dofs of more refined cells getting higher numbers.
*
- * This numbering implies very large bandwiths of the resulting matrices
- * and is thus vastly suboptimal for some solution algorithms. For this
- * reason, the DoFRenumbering class offers several algorithms to reorder
- * the dof numbering according. See there for a discussion of the
- * implemented algorithms.
+ * This numbering implies very large bandwiths of the resulting matrices and
+ * is thus vastly suboptimal for some solution algorithms. For this reason,
+ * the DoFRenumbering class offers several algorithms to reorder the dof
+ * numbering according. See there for a discussion of the implemented
+ * algorithms.
*
*
* <h3>Interaction with distributed meshes</h3>
*
- * Upon construction, this class takes a reference to a triangulation
- * object. In most cases, this will be a reference to an object of type
- * Triangulation, i.e. the class that represents triangulations that
- * entirely reside on a single processor. However, it can also be of type
+ * Upon construction, this class takes a reference to a triangulation object.
+ * In most cases, this will be a reference to an object of type Triangulation,
+ * i.e. the class that represents triangulations that entirely reside on a
+ * single processor. However, it can also be of type
* parallel::distributed::Triangulation (see, for example, step-32, step-40
- * and in particular the @ref distributed module) in which case the
- * DoFHandler object will proceed to only manage degrees of freedom on
- * locally owned and ghost cells. This process is entirely transparent to
- * the used.
+ * and in particular the @ref distributed module) in which case the DoFHandler
+ * object will proceed to only manage degrees of freedom on locally owned and
+ * ghost cells. This process is entirely transparent to the used.
*
*
* <h3>User defined renumbering schemes</h3>
*
* The DoFRenumbering class offers a number of renumbering schemes like the
- * Cuthill-McKey scheme. Basically, the function sets up an array in which
- * for each degree of freedom we store the new index this DoF should have
- * after renumbering. Using this array, the renumber_dofs() function of the
- * present class is called, which actually performs the change from old DoF
- * indices to the ones given in the array. In some cases, however, a user
- * may want to compute her own renumbering order; in this case, one can
- * allocate an array with one element per degree of freedom and fill it
- * with the number that the respective degree of freedom shall be assigned.
- * This number may, for example, be obtained by sorting the support points
- * of the degrees of freedom in downwind direction. Then call the
- * <tt>renumber_dofs(vector<types::global_dof_index>)</tt> function with
- * the array, which converts old into new degree of freedom indices.
+ * Cuthill-McKey scheme. Basically, the function sets up an array in which for
+ * each degree of freedom we store the new index this DoF should have after
+ * renumbering. Using this array, the renumber_dofs() function of the present
+ * class is called, which actually performs the change from old DoF indices to
+ * the ones given in the array. In some cases, however, a user may want to
+ * compute her own renumbering order; in this case, one can allocate an array
+ * with one element per degree of freedom and fill it with the number that the
+ * respective degree of freedom shall be assigned. This number may, for
+ * example, be obtained by sorting the support points of the degrees of
+ * freedom in downwind direction. Then call the
+ * <tt>renumber_dofs(vector<types::global_dof_index>)</tt> function with the
+ * array, which converts old into new degree of freedom indices.
*
*
* <h3>Serializing (loading or storing) DoFHandler objects</h3>
*
- * Like many other classes in deal.II, the DoFHandler class can stream
- * its contents to an archive using BOOST's serialization facilities. The
- * data so stored can later be retrieved again from the archive to restore
- * the contents of this object. This facility is frequently used to save the
- * state of a program to disk for possible later resurrection, often in the
- * context of checkpoint/restart strategies for long running computations or
- * on computers that aren't very reliable (e.g. on very large clusters where
- * individual nodes occasionally fail and then bring down an entire MPI
- * job).
+ * Like many other classes in deal.II, the DoFHandler class can stream its
+ * contents to an archive using BOOST's serialization facilities. The data so
+ * stored can later be retrieved again from the archive to restore the
+ * contents of this object. This facility is frequently used to save the state
+ * of a program to disk for possible later resurrection, often in the context
+ * of checkpoint/restart strategies for long running computations or on
+ * computers that aren't very reliable (e.g. on very large clusters where
+ * individual nodes occasionally fail and then bring down an entire MPI job).
*
- * The model for doing so is similar for the DoFHandler class as it is for
- * the Triangulation class (see the section in the general documentation of
- * that class). In particular, the load() function does not exactly restore
- * the same state as was stored previously using the save() function. Rather,
- * the function assumes that you load data into a DoFHandler object that is
- * already associated with a triangulation that has a content that matches
- * the one that was used when the data was saved. Likewise, the load() function
+ * The model for doing so is similar for the DoFHandler class as it is for the
+ * Triangulation class (see the section in the general documentation of that
+ * class). In particular, the load() function does not exactly restore the
+ * same state as was stored previously using the save() function. Rather, the
+ * function assumes that you load data into a DoFHandler object that is
+ * already associated with a triangulation that has a content that matches the
+ * one that was used when the data was saved. Likewise, the load() function
* assumes that the current object is already associated with a finite element
* object that matches the one that was associated with it when data was
* saved; the latter can be achieved by calling DoFHandler::distribute_dofs()
typedef typename ActiveSelector::active_hex_iterator active_hex_iterator;
/**
- * A typedef that is used to to identify
- * @ref GlossActive "active cell iterators".
- * The concept of iterators is discussed at length in the
- * @ref Iterators "iterators documentation module".
+ * A typedef that is used to to identify @ref GlossActive "active cell
+ * iterators". The concept of iterators is discussed at length in the @ref
+ * Iterators "iterators documentation module".
*
- * The current typedef identifies active cells in a DoFHandler object.
- * While the actual data type of the typedef is hidden behind a few
- * layers of (unfortunately necessary) indirections, it is in essence
- * TriaActiveIterator<DoFCellAccessor>. The TriaActiveIterator class
- * works like a pointer to active objects that when you dereference it
- * yields an object of type DoFCellAccessor. DoFCellAccessor is a class
- * that identifies properties that are specific to cells in a DoFHandler,
- * but it is derived (and consequently inherits) from both DoFAccessor,
- * TriaCellAccessor and TriaAccessor that describe what you can ask of
- * more general objects (lines, faces, as well as cells) in a
- * triangulation and DoFHandler objects.
+ * The current typedef identifies active cells in a DoFHandler object. While
+ * the actual data type of the typedef is hidden behind a few layers of
+ * (unfortunately necessary) indirections, it is in essence
+ * TriaActiveIterator<DoFCellAccessor>. The TriaActiveIterator class works
+ * like a pointer to active objects that when you dereference it yields an
+ * object of type DoFCellAccessor. DoFCellAccessor is a class that
+ * identifies properties that are specific to cells in a DoFHandler, but it
+ * is derived (and consequently inherits) from both DoFAccessor,
+ * TriaCellAccessor and TriaAccessor that describe what you can ask of more
+ * general objects (lines, faces, as well as cells) in a triangulation and
+ * DoFHandler objects.
*
* @ingroup Iterators
*/
/**
* A typedef that is used to to identify cell iterators. The concept of
- * iterators is discussed at length in the
- * @ref Iterators "iterators documentation module".
+ * iterators is discussed at length in the @ref Iterators "iterators
+ * documentation module".
*
* The current typedef identifies cells in a DoFHandler object. Some of
- * these cells may in fact be active (see
- * @ref GlossActive "active cell iterators")
- * in which case they can in fact be asked for the degrees of freedom
- * that live on them. On the other hand, if the cell is not active, any
- * such query will result in an error. Note that this is what
+ * these cells may in fact be active (see @ref GlossActive "active cell
+ * iterators") in which case they can in fact be asked for the degrees of
+ * freedom that live on them. On the other hand, if the cell is not active,
+ * any such query will result in an error. Note that this is what
* distinguishes this typedef from the level_cell_iterator typedef.
*
- * While the actual data type of the typedef is hidden behind a few
- * layers of (unfortunately necessary) indirections, it is in essence
+ * While the actual data type of the typedef is hidden behind a few layers
+ * of (unfortunately necessary) indirections, it is in essence
* TriaIterator<DoFCellAccessor>. The TriaIterator class works like a
- * pointer to objects that when you dereference it yields an object of
- * type DoFCellAccessor. DoFCellAccessor is a class that identifies
- * properties that are specific to cells in a DoFHandler, but it is
- * derived (and consequently inherits) from both DoFAccessor,
- * TriaCellAccessor and TriaAccessor that describe what you can ask of
- * more general objects (lines, faces, as well as cells) in a
- * triangulation and DoFHandler objects.
+ * pointer to objects that when you dereference it yields an object of type
+ * DoFCellAccessor. DoFCellAccessor is a class that identifies properties
+ * that are specific to cells in a DoFHandler, but it is derived (and
+ * consequently inherits) from both DoFAccessor, TriaCellAccessor and
+ * TriaAccessor that describe what you can ask of more general objects
+ * (lines, faces, as well as cells) in a triangulation and DoFHandler
+ * objects.
*
* @ingroup Iterators
*/
static const unsigned int space_dimension = spacedim;
/**
- * When the arrays holding the DoF indices are set up, but before they
- * are filled with actual values, they are set to an invalid value, in
- * order to monitor possible problems. This invalid value is the constant
- * defined here.
+ * When the arrays holding the DoF indices are set up, but before they are
+ * filled with actual values, they are set to an invalid value, in order to
+ * monitor possible problems. This invalid value is the constant defined
+ * here.
*
* Please note that you should not rely on it having a certain value, but
* rather take its symbolic name.
static const types::global_dof_index invalid_dof_index = numbers::invalid_dof_index;
/**
- * The default index of the finite element to be used on a given cell.
- * Since the present class only supports the same finite element to be
- * used on all cells, the index of the finite element needs to be the
- * same on all cells anyway, and by convention we pick zero for this
- * value. The situation is different for hp objects (i.e. the
- * hp::DoFHandler class) where different finite element indices may be
- * used on different cells, and the default index there corresponds to an
- * invalid value.
+ * The default index of the finite element to be used on a given cell. Since
+ * the present class only supports the same finite element to be used on all
+ * cells, the index of the finite element needs to be the same on all cells
+ * anyway, and by convention we pick zero for this value. The situation is
+ * different for hp objects (i.e. the hp::DoFHandler class) where different
+ * finite element indices may be used on different cells, and the default
+ * index there corresponds to an invalid value.
*/
static const unsigned int default_fe_index = 0;
virtual ~DoFHandler ();
/**
- * Assign a Triangulation and a FiniteElement to the DoFHandler and
- * compute the distribution of degrees of freedom over the mesh.
+ * Assign a Triangulation and a FiniteElement to the DoFHandler and compute
+ * the distribution of degrees of freedom over the mesh.
*/
void initialize(const Triangulation<dim,spacedim> &tria,
const FiniteElement<dim,spacedim> &fe);
* needed for the given finite element. "Distributing" degrees of freedom
* involved allocating memory to store the information that describes it
* (e.g., whether it is located on a vertex, edge, face, etc) and to
- * sequentially enumerate all degrees of freedom. In other words, while
- * the mesh and the finite element object by themselves simply define a
- * finite element space $V_h$, the process of distributing degrees of
- * freedom makes sure that there is a basis for this space and that the
- * shape functions of this basis are enumerated in an indexable,
- * predictable way.
+ * sequentially enumerate all degrees of freedom. In other words, while the
+ * mesh and the finite element object by themselves simply define a finite
+ * element space $V_h$, the process of distributing degrees of freedom makes
+ * sure that there is a basis for this space and that the shape functions of
+ * this basis are enumerated in an indexable, predictable way.
*
* The purpose of this function is first discussed in the introduction to
* the step-2 tutorial program.
*
* @note A pointer of the finite element given as argument is stored.
- * Therefore, the lifetime of the finite element object shall be longer
- * than that of this object. If you don't want this behavior, you may
- * want to call the @p clear member function which also releases the lock
- * of this object to the finite element.
+ * Therefore, the lifetime of the finite element object shall be longer than
+ * that of this object. If you don't want this behavior, you may want to
+ * call the @p clear member function which also releases the lock of this
+ * object to the finite element.
*/
virtual void distribute_dofs (const FiniteElement<dim,spacedim> &fe);
/**
* Distribute level degrees of freedom on each level for geometric
- * multigrid. The active DoFs need to be distributed using
- * distribute_dofs() before calling this function and the @p fe needs to
- * be identical to the finite element passed to distribute_dofs().
+ * multigrid. The active DoFs need to be distributed using distribute_dofs()
+ * before calling this function and the @p fe needs to be identical to the
+ * finite element passed to distribute_dofs().
*
* This replaces the functionality of the old MGDoFHandler.
*/
/**
* This function returns whether this DoFHandler has DoFs distributed on
- * each multigrid level or in other words if distribute_mg_dofs() has
- * been called.
+ * each multigrid level or in other words if distribute_mg_dofs() has been
+ * called.
*/
bool has_level_dofs() const;
* distributed actually has degrees of freedom (which is not the case for
* FE_Nothing, for example).
*
- * If this object is based on a parallel::distributed::Triangulation,
- * then the current function returns true if <i>any</i> partition of the
- * parallel DoFHandler object has any degrees of freedom. In other words,
- * the function returns true even if the Triangulation does not own any
- * active cells on the current MPI process, but at least one process owns
- * cells and at least this one process has any degrees of freedom
- * associated with it.
+ * If this object is based on a parallel::distributed::Triangulation, then
+ * the current function returns true if <i>any</i> partition of the parallel
+ * DoFHandler object has any degrees of freedom. In other words, the
+ * function returns true even if the Triangulation does not own any active
+ * cells on the current MPI process, but at least one process owns cells and
+ * at least this one process has any degrees of freedom associated with it.
*/
bool has_active_dofs() const;
/**
- * After distribute_dofs() with an FESystem element, the block structure
- * of global and level vectors is stored in a BlockInfo object accessible
- * with block_info(). This function initializes the local block structure
- * on each cell in the same object.
+ * After distribute_dofs() with an FESystem element, the block structure of
+ * global and level vectors is stored in a BlockInfo object accessible with
+ * block_info(). This function initializes the local block structure on each
+ * cell in the same object.
*/
void initialize_local_block_info();
/**
- * Clear all data of this object and especially delete the lock this
- * object has to the finite element used the last time when
- * @p distribute_dofs was called.
+ * Clear all data of this object and especially delete the lock this object
+ * has to the finite element used the last time when @p distribute_dofs was
+ * called.
*/
virtual void clear ();
* Renumber degrees of freedom based on a list of new dof numbers for all
* the dofs.
*
- * This function is called by the functions in DoFRenumbering function
- * after computing the ordering of the degrees of freedom. This function
- * is called, for example, by the functions in the DoFRenumbering
- * namespace, but it can of course also be called from user code.
+ * This function is called by the functions in DoFRenumbering function after
+ * computing the ordering of the degrees of freedom. This function is
+ * called, for example, by the functions in the DoFRenumbering namespace,
+ * but it can of course also be called from user code.
*
* @arg new_number This array must have a size equal to the number of
- * degrees of freedom owned by the current processor, i.e. the size must
- * be equal to what n_locally_owned_dofs() returns. If only one processor
+ * degrees of freedom owned by the current processor, i.e. the size must be
+ * equal to what n_locally_owned_dofs() returns. If only one processor
* participates in storing the current mesh, then this equals the total
- * number of degrees of freedom, i.e. the result of n_dofs(). The
- * contents of this array are the new global indices for each freedom
- * listed in the IndexSet returned by locally_owned_dofs(). In the case
- * of a sequential mesh this means that the array is a list of new
- * indices for each of the degrees of freedom on the current mesh. In the
- * case that we have a parallel::distributed::Triangulation underlying
- * this DoFHandler object, the array is a list of new indices for all the
- * locally owned degrees of freedom, enumerated in the same order as the
- * currently locally owned DoFs. In other words, assume that degree of
- * freedom <code>i</code> is currently locally owned, then
+ * number of degrees of freedom, i.e. the result of n_dofs(). The contents
+ * of this array are the new global indices for each freedom listed in the
+ * IndexSet returned by locally_owned_dofs(). In the case of a sequential
+ * mesh this means that the array is a list of new indices for each of the
+ * degrees of freedom on the current mesh. In the case that we have a
+ * parallel::distributed::Triangulation underlying this DoFHandler object,
+ * the array is a list of new indices for all the locally owned degrees of
+ * freedom, enumerated in the same order as the currently locally owned
+ * DoFs. In other words, assume that degree of freedom <code>i</code> is
+ * currently locally owned, then
* <code>new_numbers[locally_owned_dofs().index_within_set(i)]</code>
- * returns the new global DoF index of <code>i</code>. Since the IndexSet
- * of locally_owned_dofs() is complete in the sequential case, the latter
- * convention for the content of the array reduces to the former in the
- * case that only one processor participates in the mesh.
+ * returns the new global DoF index of <code>i</code>. Since the IndexSet of
+ * locally_owned_dofs() is complete in the sequential case, the latter
+ * convention for the content of the array reduces to the former in the case
+ * that only one processor participates in the mesh.
*/
void renumber_dofs (const std::vector<types::global_dof_index> &new_numbers);
/**
* Return the maximum number of degrees of freedom a degree of freedom in
* the given triangulation with the given finite element may couple with.
- * This is the maximum number of entries per line in the system matrix;
- * this information can therefore be used upon construction of the
+ * This is the maximum number of entries per line in the system matrix; this
+ * information can therefore be used upon construction of the
* SparsityPattern object.
*
* The returned number is not really the maximum number but an estimate
- * based on the finite element and the maximum number of cells meeting at
- * a vertex. The number holds for the constrained matrix as well.
+ * based on the finite element and the maximum number of cells meeting at a
+ * vertex. The number holds for the constrained matrix as well.
*
* The determination of the number of couplings can be done by simple
* picture drawing. An example can be found in the implementation of this
* function.
*
* @note This function is most often used to determine the maximal row
- * length for sparsity patterns. Unfortunately, while the estimates
- * returned by this function are rather accurate in 1d and 2d, they are
- * often significantly too high in 3d, leading the SparsityPattern class
- * to allocate much too much memory in some cases. Unless someone comes
- * around to improving the present function for 3d, there is not very
- * much one can do about these cases. The typical way to work around this
- * problem is to use an intermediate compressed sparsity pattern that
- * only allocates memory on demand. Refer to the step-2 and step-11
- * example programs on how to do this. The problem is also discussed in
- * the documentation of the module on @ref Sparsity.
+ * length for sparsity patterns. Unfortunately, while the estimates returned
+ * by this function are rather accurate in 1d and 2d, they are often
+ * significantly too high in 3d, leading the SparsityPattern class to
+ * allocate much too much memory in some cases. Unless someone comes around
+ * to improving the present function for 3d, there is not very much one can
+ * do about these cases. The typical way to work around this problem is to
+ * use an intermediate compressed sparsity pattern that only allocates
+ * memory on demand. Refer to the step-2 and step-11 example programs on how
+ * to do this. The problem is also discussed in the documentation of the
+ * module on @ref Sparsity.
*/
unsigned int max_couplings_between_dofs () const;
/**
- * Return the number of degrees of freedom located on the boundary
- * another dof on the boundary can couple with.
+ * Return the number of degrees of freedom located on the boundary another
+ * dof on the boundary can couple with.
*
* The number is the same as for max_couplings_between_dofs() in one
* dimension less.
*
- * @note The same applies to this function as to max_couplings_per_dofs()
- * as regards the performance of this function. Think about one of the
- * dynamic sparsity pattern classes instead (see @ref Sparsity).
+ * @note The same applies to this function as to max_couplings_per_dofs() as
+ * regards the performance of this function. Think about one of the dynamic
+ * sparsity pattern classes instead (see @ref Sparsity).
*/
unsigned int max_couplings_between_boundary_dofs () const;
cell_iterator begin (const unsigned int level = 0) const;
/**
- * Iterator to the first active cell on level @p level. If the
- * given level does not contain any active cells (i.e., all cells
- * on this level are further refined, then this function returns
- * <code>end_active(level)</code> so that loops of the kind
+ * Iterator to the first active cell on level @p level. If the given level
+ * does not contain any active cells (i.e., all cells on this level are
+ * further refined, then this function returns
+ * <code>end_active(level)</code> so that loops of the kind
* @code
* for (cell=dof_handler.begin_active(level); cell!=dof_handler.end_active(level); ++cell)
* ...
* @endcode
- * have zero iterations, as may be expected if there are no active
- * cells on this level.
+ * have zero iterations, as may be expected if there are no active cells on
+ * this level.
*/
active_cell_iterator begin_active(const unsigned int level = 0) const;
/**
- * Iterator past the end; this iterator serves for comparisons of
- * iterators with past-the-end or before-the-beginning states.
+ * Iterator past the end; this iterator serves for comparisons of iterators
+ * with past-the-end or before-the-beginning states.
*/
cell_iterator end () const;
/**
- * Return an iterator which is the first iterator not on the given level.
- * If @p level is the last level, then this returns <tt>end()</tt>.
+ * Return an iterator which is the first iterator not on the given level. If
+ * @p level is the last level, then this returns <tt>end()</tt>.
*/
cell_iterator end (const unsigned int level) const;
/**
- * Return an active iterator which is the first active iterator not on
- * the given level. If @p level is the last level, then this returns
+ * Return an active iterator which is the first active iterator not on the
+ * given level. If @p level is the last level, then this returns
* <tt>end()</tt>.
*/
active_cell_iterator end_active (const unsigned int level) const;
/**
* Iterator to the first used cell on level @p level. This returns a
- * level_cell_iterator that returns level dofs when dof_indices() is
- * called.
+ * level_cell_iterator that returns level dofs when dof_indices() is called.
*/
level_cell_iterator begin_mg (const unsigned int level = 0) const;
/**
* Iterator past the last cell on level @p level. This returns a
- * level_cell_iterator that returns level dofs when dof_indices() is
- * called.
+ * level_cell_iterator that returns level dofs when dof_indices() is called.
*/
level_cell_iterator end_mg (const unsigned int level) const;
/**
- * Iterator past the end; this iterator serves for comparisons of
- * iterators with past-the-end or before-the-beginning states.
+ * Iterator past the end; this iterator serves for comparisons of iterators
+ * with past-the-end or before-the-beginning states.
*/
level_cell_iterator end_mg () const;
/**
- * @name Cell iterator functions returning ranges of iterators
+ * @name Cell iterator functions returning ranges of iterators
*/
/**
* Return an iterator range that contains all cells (active or not) that
- * make up this DoFHandler. Such a range is useful to initialize
- * range-based for loops as supported by C++11. See the example in the
- * documentation of active_cell_iterators().
+ * make up this DoFHandler. Such a range is useful to initialize range-based
+ * for loops as supported by C++11. See the example in the documentation of
+ * active_cell_iterators().
*
* @return The half open range <code>[this->begin(), this->end())</code>
*
IteratorRange<cell_iterator> cell_iterators () const;
/**
- * Return an iterator range that contains all active cells
- * that make up this DoFHandler. Such a range is useful to
- * initialize range-based for loops as supported by C++11,
- * see also @ref CPP11 "C++11 standard".
+ * Return an iterator range that contains all active cells that make up this
+ * DoFHandler. Such a range is useful to initialize range-based for loops as
+ * supported by C++11, see also @ref CPP11 "C++11 standard".
*
- * Range-based for loops are useful in that they require much less
- * code than traditional loops (see
- * <a href="http://en.wikipedia.org/wiki/C%2B%2B11#Range-based_for_loop">here</a>
- * for a discussion of how they work). An example is that without
- * range-based for loops, one often writes code such as the following:
+ * Range-based for loops are useful in that they require much less code than
+ * traditional loops (see <a href="http://en.wikipedia.org/wiki/C%2B%2B11
+ * #Range-based_for_loop">here</a> for a discussion of how they work). An
+ * example is that without range-based for loops, one often writes code such
+ * as the following:
* @code
* DoFHandler<dim> dof_handler;
* ...
* ...do the local integration on 'cell'...;
* }
* @endcode
- * Using C++11's range-based for loops, this is now entirely
- * equivalent to the following:
+ * Using C++11's range-based for loops, this is now entirely equivalent to
+ * the following:
* @code
* DoFHandler<dim> dof_handler;
* ...
* @endcode
* To use this feature, you need a compiler that supports C++11.
*
- * @return The half open range <code>[this->begin_active(), this->end())</code>
+ * @return The half open range <code>[this->begin_active(),
+ * this->end())</code>
*
* @ingroup CPP11
*/
/**
* Return an iterator range that contains all cells (active or not) that
- * make up this DoFHandler in their level-cell form. Such a range is
- * useful to initialize range-based for loops as supported by C++11. See
- * the example in the documentation of active_cell_iterators().
+ * make up this DoFHandler in their level-cell form. Such a range is useful
+ * to initialize range-based for loops as supported by C++11. See the
+ * example in the documentation of active_cell_iterators().
*
- * @return The half open range <code>[this->begin_mg(), this->end_mg())</code>
+ * @return The half open range <code>[this->begin_mg(),
+ * this->end_mg())</code>
*
* @ingroup CPP11
*/
IteratorRange<level_cell_iterator> mg_cell_iterators () const;
/**
- * Return an iterator range that contains all cells (active or not)
- * that make up the given level of this DoFHandler. Such a range is useful to
- * initialize range-based for loops as supported by C++11. See the
- * example in the documentation of active_cell_iterators().
+ * Return an iterator range that contains all cells (active or not) that
+ * make up the given level of this DoFHandler. Such a range is useful to
+ * initialize range-based for loops as supported by C++11. See the example
+ * in the documentation of active_cell_iterators().
*
* @param[in] level A given level in the refinement hierarchy of this
- * triangulation.
- * @return The half open range <code>[this->begin(level),
- * this->end(level))</code>
+ * triangulation. @return The half open range <code>[this->begin(level),
+ * this->end(level))</code>
*
* @pre level must be less than this->n_levels().
*
IteratorRange<cell_iterator> cell_iterators_on_level (const unsigned int level) const;
/**
- * Return an iterator range that contains all active cells that make up
- * the given level of this DoFHandler. Such a range is useful to
- * initialize range-based for loops as supported by C++11. See the
- * example in the documentation of active_cell_iterators().
+ * Return an iterator range that contains all active cells that make up the
+ * given level of this DoFHandler. Such a range is useful to initialize
+ * range-based for loops as supported by C++11. See the example in the
+ * documentation of active_cell_iterators().
*
* @param[in] level A given level in the refinement hierarchy of this
- * triangulation.
- * @return The half open range <code>[this->begin_active(level), this->end(level))</code>
+ * triangulation. @return The half open range
+ * <code>[this->begin_active(level), this->end(level))</code>
*
* @pre level must be less than this->n_levels().
*
/**
* Return an iterator range that contains all cells (active or not) that
- * make up the given level of this DoFHandler in their level-cell form.
- * Such a range is useful to initialize range-based for loops as
- * supported by C++11. See the example in the documentation of
- * active_cell_iterators().
+ * make up the given level of this DoFHandler in their level-cell form. Such
+ * a range is useful to initialize range-based for loops as supported by
+ * C++11. See the example in the documentation of active_cell_iterators().
*
* @param[in] level A given level in the refinement hierarchy of this
- * triangulation.
- * @return The half open range <code>[this->begin_mg(level), this->end_mg(level))</code>
+ * triangulation. @return The half open range <code>[this->begin_mg(level),
+ * this->end_mg(level))</code>
*
* @pre level must be less than this->n_levels().
*
/**
* Return the global number of degrees of freedom. If the current object
* handles all degrees of freedom itself (even if you may intend to solve
- * your linear system in parallel, such as in step-17 or step-18), then
- * this number equals the number of locally owned degrees of freedom
- * since this object doesn't know anything about what you want to do with
- * it and believes that it owns every degree of freedom it knows about.
+ * your linear system in parallel, such as in step-17 or step-18), then this
+ * number equals the number of locally owned degrees of freedom since this
+ * object doesn't know anything about what you want to do with it and
+ * believes that it owns every degree of freedom it knows about.
*
* On the other hand, if this object operates on a
- * parallel::distributed::Triangulation object, then this function
- * returns the global number of degrees of freedom, accumulated over all
- * processors.
+ * parallel::distributed::Triangulation object, then this function returns
+ * the global number of degrees of freedom, accumulated over all processors.
*
- * In either case, included in the returned number are those DoFs which
- * are constrained by hanging nodes, see @ref constraints.
+ * In either case, included in the returned number are those DoFs which are
+ * constrained by hanging nodes, see @ref constraints.
*/
types::global_dof_index n_dofs () const;
/**
* The (global) number of multilevel degrees of freedom on a given level.
*
- * If no level degrees of freedom have been assigned to this level,
- * returns numbers::invalid_dof_index. Else returns the number of degrees
- * of freedom on this level.
+ * If no level degrees of freedom have been assigned to this level, returns
+ * numbers::invalid_dof_index. Else returns the number of degrees of freedom
+ * on this level.
*/
types::global_dof_index n_dofs (const unsigned int level) const;
n_boundary_dofs (const std::set<types::boundary_id> &boundary_indicators) const;
/**
- * Access to an object informing of the block structure of the dof
- * handler.
+ * Access to an object informing of the block structure of the dof handler.
*
- * If an FESystem is used in distribute_dofs(), degrees of freedom
- * naturally split into several @ref GlossBlock "blocks". For each base
- * element as many blocks appear as its multiplicity.
+ * If an FESystem is used in distribute_dofs(), degrees of freedom naturally
+ * split into several @ref GlossBlock "blocks". For each base element as
+ * many blocks appear as its multiplicity.
*
- * At the end of distribute_dofs(), the number of degrees of freedom in
- * each block is counted, and stored in a BlockInfo object, which can be
- * accessed here. In an MGDoFHandler, the same is done on each level.
- * Additionally, the block structure on each cell can be generated in
- * this object by calling initialize_local_block_info().
+ * At the end of distribute_dofs(), the number of degrees of freedom in each
+ * block is counted, and stored in a BlockInfo object, which can be accessed
+ * here. In an MGDoFHandler, the same is done on each level. Additionally,
+ * the block structure on each cell can be generated in this object by
+ * calling initialize_local_block_info().
*/
const BlockInfo &block_info() const;
*
* If this is a sequential job, then the result equals that produced by
* n_dofs(). On the other hand, if we are operating on a
- * parallel::distributed::Triangulation, then it includes only the
- * degrees of freedom that the current processor owns. Note that in this
- * case this does not include all degrees of freedom that have been
- * distributed on the current processor's image of the mesh: in
- * particular, some of the degrees of freedom on the interface between
- * the cells owned by this processor and cells owned by other processors
- * may be theirs, and degrees of freedom on ghost cells are also not
- * necessarily included.
+ * parallel::distributed::Triangulation, then it includes only the degrees
+ * of freedom that the current processor owns. Note that in this case this
+ * does not include all degrees of freedom that have been distributed on the
+ * current processor's image of the mesh: in particular, some of the degrees
+ * of freedom on the interface between the cells owned by this processor and
+ * cells owned by other processors may be theirs, and degrees of freedom on
+ * ghost cells are also not necessarily included.
*/
unsigned int n_locally_owned_dofs() const;
/**
- * Return an IndexSet describing the set of locally owned DoFs as a
- * subset of 0..n_dofs(). The number of elements of this set equals
+ * Return an IndexSet describing the set of locally owned DoFs as a subset
+ * of 0..n_dofs(). The number of elements of this set equals
* n_locally_owned_dofs().
*/
const IndexSet &locally_owned_dofs() const;
/**
- * Returns an IndexSet describing the set of locally owned DoFs used for
- * the given multigrid level as a subset of 0..n_dofs(level).
+ * Returns an IndexSet describing the set of locally owned DoFs used for the
+ * given multigrid level as a subset of 0..n_dofs(level).
*/
const IndexSet &locally_owned_mg_dofs(const unsigned int level) const;
/**
- * Returns a vector that stores the locally owned DoFs of each processor.
- * If you are only interested in the number of elements each processor
- * owns then n_locally_owned_dofs_per_processor() is a better choice.
+ * Returns a vector that stores the locally owned DoFs of each processor. If
+ * you are only interested in the number of elements each processor owns
+ * then n_locally_owned_dofs_per_processor() is a better choice.
*
* If this is a sequential job, then the vector has a single element that
* equals the IndexSet representing the entire range [0,n_dofs()].
/**
* Return a vector that stores the number of degrees of freedom each
- * processor that participates in this triangulation owns locally. The
- * sum of all these numbers equals the number of degrees of freedom that
- * exist globally, i.e. what n_dofs() returns.
+ * processor that participates in this triangulation owns locally. The sum
+ * of all these numbers equals the number of degrees of freedom that exist
+ * globally, i.e. what n_dofs() returns.
*
- * Each element of the vector returned by this function equals the number
- * of elements of the corresponding sets returned by
- * global_dof_indices().
+ * Each element of the vector returned by this function equals the number of
+ * elements of the corresponding sets returned by global_dof_indices().
*
- * If this is a sequential job, then the vector has a single element
- * equal to n_dofs().
+ * If this is a sequential job, then the vector has a single element equal
+ * to n_dofs().
*/
const std::vector<types::global_dof_index> &
n_locally_owned_dofs_per_processor () const;
const FiniteElement<dim,spacedim> &get_fe () const;
/**
- * Return a constant reference to the triangulation underlying this
- * object.
+ * Return a constant reference to the triangulation underlying this object.
*/
const Triangulation<dim,spacedim> &get_tria () const;
*/
DeclException0 (ExcFacesHaveNoLevel);
/**
- * The triangulation level you
- * accessed is empty.
+ * The triangulation level you accessed is empty.
* @ingroup Exceptions
*/
DeclException1 (ExcEmptyLevel,
private:
/**
- * Copy constructor. I can see no reason why someone might want to use
- * it, so I don't provide it. Since this class has pointer members,
- * making it private prevents the compiler to provide it's own, incorrect
- * one if anyone chose to copy such an object.
+ * Copy constructor. I can see no reason why someone might want to use it,
+ * so I don't provide it. Since this class has pointer members, making it
+ * private prevents the compiler to provide it's own, incorrect one if
+ * anyone chose to copy such an object.
*/
DoFHandler (const DoFHandler &);
/**
- * Copy operator. I can see no reason why someone might want to use it,
- * so I don't provide it. Since this class has pointer members, making it
- * private prevents the compiler to provide it's own, incorrect one if
- * anyone chose to copy such an object.
+ * Copy operator. I can see no reason why someone might want to use it, so I
+ * don't provide it. Since this class has pointer members, making it private
+ * prevents the compiler to provide it's own, incorrect one if anyone chose
+ * to copy such an object.
*/
DoFHandler &operator = (const DoFHandler &);
tria;
/**
- * Store a pointer to the finite element given latest for the
- * distribution of dofs. In order to avoid destruction of the object
- * before the lifetime of the DoF handler, we subscribe to the finite
- * element object. To unlock the FE before the end of the lifetime of
- * this DoF handler, use the <tt>clear()</tt> function (this clears all
- * data of this object as well, though).
+ * Store a pointer to the finite element given latest for the distribution
+ * of dofs. In order to avoid destruction of the object before the lifetime
+ * of the DoF handler, we subscribe to the finite element object. To unlock
+ * the FE before the end of the lifetime of this DoF handler, use the
+ * <tt>clear()</tt> function (this clears all data of this object as well,
+ * though).
*/
SmartPointer<const FiniteElement<dim,spacedim>,DoFHandler<dim,spacedim> >
selected_fe;
/**
- * An object that describes how degrees of freedom should be distributed
- * and renumbered.
+ * An object that describes how degrees of freedom should be distributed and
+ * renumbered.
*/
std_cxx11::shared_ptr<dealii::internal::DoFHandler::Policy::PolicyBase<dim,spacedim> > policy;
* A structure that contains all sorts of numbers that characterize the
* degrees of freedom this object works on.
*
- * For most members of this structure, there is an accessor function in
- * this class that returns its value.
+ * For most members of this structure, there is an accessor function in this
+ * class that returns its value.
*/
dealii::internal::DoFHandler::NumberCache number_cache;
std::vector<dealii::internal::DoFHandler::NumberCache> mg_number_cache;
/**
- * A data structure that is used to store the DoF indices associated with
- * a particular vertex. Unlike cells, vertices live on several levels of
- * a multigrid hierarchy; consequently, we need to store DoF indices for
- * each vertex for each of the levels it lives on. This class does this.
+ * A data structure that is used to store the DoF indices associated with a
+ * particular vertex. Unlike cells, vertices live on several levels of a
+ * multigrid hierarchy; consequently, we need to store DoF indices for each
+ * vertex for each of the levels it lives on. This class does this.
*/
class MGVertexDoFs
{
~MGVertexDoFs ();
/**
- * A function that is called to allocate the necessary amount of memory
- * to store the indices of the DoFs that live on this vertex for the
- * given (inclusive) range of levels.
+ * A function that is called to allocate the necessary amount of memory to
+ * store the indices of the DoFs that live on this vertex for the given
+ * (inclusive) range of levels.
*/
void init (const unsigned int coarsest_level,
const unsigned int finest_level,
unsigned int get_finest_level () const;
/**
- * Return the index of the <code>dof_number</code>th degree of freedom
- * for the given level stored for the current vertex.
+ * Return the index of the <code>dof_number</code>th degree of freedom for
+ * the given level stored for the current vertex.
*/
types::global_dof_index
get_index (const unsigned int level,
unsigned int finest_level;
/**
- * A pointer to an array where we store the indices of the DoFs that
- * live on the various levels this vertex exists on.
+ * A pointer to an array where we store the indices of the DoFs that live
+ * on the various levels this vertex exists on.
*/
types::global_dof_index *indices;
/**
* This array stores, for each level starting with coarsest_level, the
- * offset in the <code>indices</code> array where the DoF indices for
- * each level are stored.
+ * offset in the <code>indices</code> array where the DoF indices for each
+ * level are stored.
*/
types::global_dof_index *indices_offset;
};
std::vector<MGVertexDoFs> mg_vertex_dofs;
/**
- * Space to store the DoF numbers for the different levels. Analogous to
- * the <tt>levels[]</tt> tree of the Triangulation objects.
+ * Space to store the DoF numbers for the different levels. Analogous to the
+ * <tt>levels[]</tt> tree of the Triangulation objects.
*/
std::vector<dealii::internal::DoFHandler::DoFLevel<dim>*> levels;
{
/**
* returns a string representing the dynamic type of the given argument.
- * This is basically the same what typeid(...).name() does, but it turns
- * out this is broken on Intel 13+.
+ * This is basically the same what typeid(...).name() does, but it turns out
+ * this is broken on Intel 13+.
*
* Defined in dof_handler.cc.
*/
struct NumberCache;
/**
- * A namespace in which we define
- * classes that describe how to
- * distribute and renumber
- * degrees of freedom.
+ * A namespace in which we define classes that describe how to distribute
+ * and renumber degrees of freedom.
*/
namespace Policy
{
struct Implementation;
/**
- * A class that implements policies for
- * how the DoFHandler::distribute_dofs
- * and DoFHandler::renumber_dofs
- * functions should work.
+ * A class that implements policies for how the
+ * DoFHandler::distribute_dofs and DoFHandler::renumber_dofs functions
+ * should work.
*/
template <int dim, int spacedim>
class PolicyBase
virtual ~PolicyBase ();
/**
- * Distribute degrees of freedom on
- * the object given as last argument.
+ * Distribute degrees of freedom on the object given as last argument.
*/
virtual
NumberCache
std::vector<NumberCache> &number_caches) const = 0;
/**
- * Renumber degrees of freedom as
- * specified by the first argument.
+ * Renumber degrees of freedom as specified by the first argument.
*/
virtual
NumberCache
/**
- * This class implements the
- * default policy for sequential
- * operations, i.e. for the case where
- * all cells get degrees of freedom.
+ * This class implements the default policy for sequential operations,
+ * i.e. for the case where all cells get degrees of freedom.
*/
template <int dim, int spacedim>
class Sequential : public PolicyBase<dim,spacedim>
{
public:
/**
- * Distribute degrees of freedom on
- * the object given as last argument.
+ * Distribute degrees of freedom on the object given as last argument.
*/
virtual
NumberCache
std::vector<NumberCache> &number_caches) const;
/**
- * Renumber degrees of freedom as
- * specified by the first argument.
+ * Renumber degrees of freedom as specified by the first argument.
*/
virtual
NumberCache
/**
- * This class implements the
- * policy for operations when
- * we use a
- * parallel::distributed::Triangulation
- * object.
+ * This class implements the policy for operations when we use a
+ * parallel::distributed::Triangulation object.
*/
template <int dim, int spacedim>
class ParallelDistributed : public PolicyBase<dim,spacedim>
{
public:
/**
- * Distribute degrees of freedom on
- * the object given as last argument.
+ * Distribute degrees of freedom on the object given as last argument.
*/
virtual
NumberCache
std::vector<NumberCache> &number_caches) const;
/**
- * Renumber degrees of freedom as
- * specified by the first argument.
+ * Renumber degrees of freedom as specified by the first argument.
*/
virtual
NumberCache
* templates is a little more complicated. See the @ref Iterators module
* for more information.
*
- * @author Wolfgang Bangerth, Oliver Kayser-Herold, Guido Kanschat, 1998, 2003, 2008, 2010
+ * @author Wolfgang Bangerth, Oliver Kayser-Herold, Guido Kanschat, 1998,
+ * 2003, 2008, 2010
*/
template <template <int, int> class DH, int spacedim, bool lda>
struct Iterators<DH<1, spacedim>, lda>
* templates is a little more complicated. See the @ref Iterators module
* for more information.
*
- * @author Wolfgang Bangerth, Oliver Kayser-Herold, Guido Kanschat, 1998, 2003, 2008, 2010
+ * @author Wolfgang Bangerth, Oliver Kayser-Herold, Guido Kanschat, 1998,
+ * 2003, 2008, 2010
*/
template <template <int, int> class DH, int spacedim, bool lda>
struct Iterators<DH<2, spacedim>, lda>
* templates is a little more complicated. See the @ref Iterators module
* for more information.
*
- * @author Wolfgang Bangerth, Oliver Kayser-Herold, Guido Kanschat, 1998, 2003, 2008, 2010
+ * @author Wolfgang Bangerth, Oliver Kayser-Herold, Guido Kanschat, 1998,
+ * 2003, 2008, 2010
*/
template <template <int, int> class DH, int spacedim, bool lda>
struct Iterators<DH<3, spacedim>, lda>
* Structure for storing degree of freedom information for cells,
* organized by levels.
*
- * We store are cached values for the DoF indices on
- * each cell in#cell_dof_indices_cache, since this is a frequently requested operation. The
- * values are set by DoFCellAccessor::update_cell_dof_indices_cache
- * and are used by DoFCellAccessor::get_dof_indices.
+ * We store are cached values for the DoF indices on each cell
+ * in#cell_dof_indices_cache, since this is a frequently requested
+ * operation. The values are set by
+ * DoFCellAccessor::update_cell_dof_indices_cache and are used by
+ * DoFCellAccessor::get_dof_indices.
*
- * Note that vertices are separate from, and in fact have nothing to
- * do with cells. The indices of degrees of freedom located on
- * vertices therefore are not stored here, but rather in member
- * variables of the dealii::DoFHandler class.
+ * Note that vertices are separate from, and in fact have nothing to do
+ * with cells. The indices of degrees of freedom located on vertices
+ * therefore are not stored here, but rather in member variables of the
+ * dealii::DoFHandler class.
*
- * The indices of degrees of freedom located on lower dimensional
- * objects, i.e. on lines for 2D and on quads and lines for 3D are
- * treated similarly than that on cells. However, these geometrical
- * objects, which are called faces as a generalisation, are not
- * organised in a hierarchical structure of levels. Therefore, the
- * degrees of freedom located on these objects are stored in separate
- * classes, namely the <tt>DoFFaces</tt> classes.
+ * The indices of degrees of freedom located on lower dimensional objects,
+ * i.e. on lines for 2D and on quads and lines for 3D are treated
+ * similarly than that on cells. However, these geometrical objects, which
+ * are called faces as a generalisation, are not organised in a
+ * hierarchical structure of levels. Therefore, the degrees of freedom
+ * located on these objects are stored in separate classes, namely the
+ * <tt>DoFFaces</tt> classes.
*
- * Access to this object is usually
- * through the DoFAccessor::set_dof_index() and
- * DoFAccessor::dof_index() functions or similar functions of derived
- * classes that in turn access the member variables using the
- * DoFHandler::get_dof_index() and corresponding setter functions.
- * Knowledge of the actual data format is therefore
+ * Access to this object is usually through the
+ * DoFAccessor::set_dof_index() and DoFAccessor::dof_index() functions or
+ * similar functions of derived classes that in turn access the member
+ * variables using the DoFHandler::get_dof_index() and corresponding
+ * setter functions. Knowledge of the actual data format is therefore
* encapsulated to the present hierarchy of classes as well as the
* dealii::DoFHandler class.
*
{
public:
/**
- * Cache for the DoF indices
- * on cells. The size of this
- * array equals the number of
- * cells on a given level
- * times
- * selected_fe.dofs_per_cell.
+ * Cache for the DoF indices on cells. The size of this array equals the
+ * number of cells on a given level times selected_fe.dofs_per_cell.
*/
std::vector<types::global_dof_index> cell_dof_indices_cache;
/**
- * The object containing dof-indices
- * and related access-functions
+ * The object containing dof-indices and related access-functions
*/
DoFObjects<dim> dof_object;
/**
- * Return a pointer to the beginning of the DoF indices cache
- * for a given cell.
+ * Return a pointer to the beginning of the DoF indices cache for a
+ * given cell.
*
* @param obj_index The number of the cell we are looking at.
* @param dofs_per_cell The number of DoFs per cell for this cell.
* @return A pointer to the first DoF index for the current cell. The
- * next dofs_per_cell indices are for the current cell.
+ * next dofs_per_cell indices are for the current cell.
*/
const types::global_dof_index *
get_cell_cache_start (const unsigned int obj_index,
const unsigned int dofs_per_cell) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
*/
template <class Archive>
void serialize(Archive &ar,
*
* <h3>Information for all DoFObjects classes</h3>
*
- * The DoFObjects classes store the global indices of the
- * degrees of freedom for each cell on a certain level. The global
- * index or number of a degree of freedom is the zero-based index of
- * the according value in the solution vector and the row and column
- * index in the global matrix or the multigrid matrix for this
- * level. These indices refer to the unconstrained vectors and
- * matrices, where we have not taken account of the constraints
- * introduced by hanging nodes.
+ * The DoFObjects classes store the global indices of the degrees of
+ * freedom for each cell on a certain level. The global index or number of
+ * a degree of freedom is the zero-based index of the according value in
+ * the solution vector and the row and column index in the global matrix
+ * or the multigrid matrix for this level. These indices refer to the
+ * unconstrained vectors and matrices, where we have not taken account of
+ * the constraints introduced by hanging nodes.
*
- * Since vertices are not associated with a particular level, the
- * indices associated with vertices are not stored in the DoFObjects
- * classes but rather in the DoFHandler::vertex_dofs array.
+ * Since vertices are not associated with a particular level, the indices
+ * associated with vertices are not stored in the DoFObjects classes but
+ * rather in the DoFHandler::vertex_dofs array.
*
- * The DoFObjects classes are not used directly, but objects
- * of theses classes are included in the DoFLevel and
- * DoFFaces classes.
+ * The DoFObjects classes are not used directly, but objects of theses
+ * classes are included in the DoFLevel and DoFFaces classes.
*
* @ingroup dofs
* @author Tobias Leicht, 2006
{
public:
/**
- * Store the global indices of
- * the degrees of freedom.
+ * Store the global indices of the degrees of freedom.
*/
std::vector<types::global_dof_index> dofs;
public:
/**
- * Set the global index of
- * the @p local_index-th
- * degree of freedom located
- * on the object with number @p
- * obj_index to the value
- * given by the last
- * argument. The @p
- * dof_handler argument is
- * used to access the finite
- * element that is to be used
- * to compute the location
- * where this data is stored.
+ * Set the global index of the @p local_index-th degree of freedom
+ * located on the object with number @p obj_index to the value given by
+ * the last argument. The @p dof_handler argument is used to access the
+ * finite element that is to be used to compute the location where this
+ * data is stored.
*
- * The third argument, @p
- * fe_index, must equal
- * zero. It is otherwise
- * unused, but we retain the
- * argument so that we can
- * use the same interface for
- * non-hp and hp finite
- * element methods, in effect
- * making it possible to
- * share the DoFAccessor
- * class hierarchy between hp
- * and non-hp classes.
+ * The third argument, @p fe_index, must equal zero. It is otherwise
+ * unused, but we retain the argument so that we can use the same
+ * interface for non-hp and hp finite element methods, in effect making
+ * it possible to share the DoFAccessor class hierarchy between hp and
+ * non-hp classes.
*/
template <int dh_dim, int spacedim>
void
const types::global_dof_index global_index);
/**
- * Return the global index of
- * the @p local_index-th
- * degree of freedom located
- * on the object with number @p
- * obj_index. The @p
- * dof_handler argument is
- * used to access the finite
- * element that is to be used
- * to compute the location
- * where this data is stored.
+ * Return the global index of the @p local_index-th degree of freedom
+ * located on the object with number @p obj_index. The @p dof_handler
+ * argument is used to access the finite element that is to be used to
+ * compute the location where this data is stored.
*
- * The third argument, @p
- * fe_index, must equal
- * zero. It is otherwise
- * unused, but we retain the
- * argument so that we can
- * use the same interface for
- * non-hp and hp finite
- * element methods, in effect
- * making it possible to
- * share the DoFAccessor
- * class hierarchy between hp
- * and non-hp classes.
+ * The third argument, @p fe_index, must equal zero. It is otherwise
+ * unused, but we retain the argument so that we can use the same
+ * interface for non-hp and hp finite element methods, in effect making
+ * it possible to share the DoFAccessor class hierarchy between hp and
+ * non-hp classes.
*/
template <int dh_dim, int spacedim>
types::global_dof_index
const unsigned int local_index) const;
/**
- * Return the value 1. The
- * meaning of this function
- * becomes clear by looking
- * at what the corresponding
- * functions in the classes
+ * Return the value 1. The meaning of this function becomes clear by
+ * looking at what the corresponding functions in the classes
* internal::hp::DoFObjects
*/
template <int dh_dim, int spacedim>
const types::global_dof_index index) const;
/**
- * Similar to the function
- * above. Assert that the
- * given index is zero, and
- * then return true.
+ * Similar to the function above. Assert that the given index is zero,
+ * and then return true.
*/
template <int dh_dim, int spacedim>
bool
const unsigned int fe_index) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
*/
template <class Archive>
void serialize(Archive &ar,
const unsigned int version);
/**
- * Make the DoFHandler and
- * MGDoFHandler classes a
- * friend, so that they can
- * resize arrays as
- * necessary.
+ * Make the DoFHandler and MGDoFHandler classes a friend, so that they
+ * can resize arrays as necessary.
*/
template <int> friend class DoFLevel;
template <int> friend class DoFFaces;
*
* <h3>Cuthill-McKee like algorithms</h3>
*
- * Within this class, the Cuthill-McKee algorithm is implemented. It
- * starts at a degree of freedom, searches the other DoFs for those
- * which are coupled with the one we started with and numbers these in
- * a certain way. It then finds the second level of DoFs, namely those
- * that couple with those of the previous level (which were those that
- * coupled with the initial DoF) and numbers these. And so on. For the
- * details of the algorithm, especially the numbering within each
- * level, please see H. R. Schwarz:
- * "Methode der finiten Elemente". The reverse Cuthill-McKee algorithm
- * does the same job, but numbers all elements in the reverse order.
+ * Within this class, the Cuthill-McKee algorithm is implemented. It starts at
+ * a degree of freedom, searches the other DoFs for those which are coupled
+ * with the one we started with and numbers these in a certain way. It then
+ * finds the second level of DoFs, namely those that couple with those of the
+ * previous level (which were those that coupled with the initial DoF) and
+ * numbers these. And so on. For the details of the algorithm, especially the
+ * numbering within each level, please see H. R. Schwarz: "Methode der finiten
+ * Elemente". The reverse Cuthill-McKee algorithm does the same job, but
+ * numbers all elements in the reverse order.
*
* These algorithms have one major drawback: they require a good starting
- * point, i.e. the degree of freedom index that will get a new index of
- * zero. The renumbering functions therefore allow the caller to specify such
- * an initial DoF, e.g. by exploiting knowledge of the actual topology of the
+ * point, i.e. the degree of freedom index that will get a new index of zero.
+ * The renumbering functions therefore allow the caller to specify such an
+ * initial DoF, e.g. by exploiting knowledge of the actual topology of the
* domain. It is also possible to give several starting indices, which may be
* used to simulate a simple upstream numbering (by giving the inflow dofs as
* starting values) or to make preconditioning faster (by letting the
* Dirichlet boundary indices be starting points).
*
- * If no starting index is given, one is chosen automatically, namely
- * one with the smallest coordination number (the coordination number
- * is the number of other dofs this dof couples with). This dof is
- * usually located on the boundary of the domain. There is, however,
- * large ambiguity in this when using the hierarchical meshes used in
- * this library, since in most cases the computational domain is not
- * approximated by tilting and deforming elements and by plugging
- * together variable numbers of elements at vertices, but rather by
- * hierarchical refinement. There is therefore a large number of dofs
- * with equal coordination numbers. The renumbering algorithms will
+ * If no starting index is given, one is chosen automatically, namely one with
+ * the smallest coordination number (the coordination number is the number of
+ * other dofs this dof couples with). This dof is usually located on the
+ * boundary of the domain. There is, however, large ambiguity in this when
+ * using the hierarchical meshes used in this library, since in most cases the
+ * computational domain is not approximated by tilting and deforming elements
+ * and by plugging together variable numbers of elements at vertices, but
+ * rather by hierarchical refinement. There is therefore a large number of
+ * dofs with equal coordination numbers. The renumbering algorithms will
* therefore not give optimal results.
*
- * In the book of Schwarz (H.R.Schwarz: Methode der finiten Elemente),
- * it is advised to test many starting points, if possible all with
- * the smallest coordination number and also those with slightly
- * higher numbers. However, this seems only possible for meshes with
- * at most several dozen or a few hundred elements found in small
- * engineering problems of the early 1980s (the second edition was
- * published in 1984), but certainly not with those used in this
- * library, featuring several 10,000 to a few 100,000 elements.
+ * In the book of Schwarz (H.R.Schwarz: Methode der finiten Elemente), it is
+ * advised to test many starting points, if possible all with the smallest
+ * coordination number and also those with slightly higher numbers. However,
+ * this seems only possible for meshes with at most several dozen or a few
+ * hundred elements found in small engineering problems of the early 1980s
+ * (the second edition was published in 1984), but certainly not with those
+ * used in this library, featuring several 10,000 to a few 100,000 elements.
*
*
* <h4>Implementation of renumbering schemes</h4>
*
- * The renumbering algorithms need quite a lot of memory, since they
- * have to store for each dof with which other dofs it couples. This
- * is done using a SparsityPattern object used to store the sparsity
- * pattern of matrices. It is not useful for the user to do anything
- * between distributing the dofs and renumbering, i.e. the calls to
- * DoFHandler::distribute_dofs and DoFHandler::renumber_dofs should
- * follow each other immediately. If you try to create a sparsity
- * pattern or anything else in between, these will be invalid
- * afterwards.
+ * The renumbering algorithms need quite a lot of memory, since they have to
+ * store for each dof with which other dofs it couples. This is done using a
+ * SparsityPattern object used to store the sparsity pattern of matrices. It
+ * is not useful for the user to do anything between distributing the dofs and
+ * renumbering, i.e. the calls to DoFHandler::distribute_dofs and
+ * DoFHandler::renumber_dofs should follow each other immediately. If you try
+ * to create a sparsity pattern or anything else in between, these will be
+ * invalid afterwards.
*
- * The renumbering may take care of dof-to-dof couplings only induced
- * by eliminating constraints. In addition to the memory consumption
- * mentioned above, this also takes quite some computational time, but
- * it may be switched off upon calling the @p renumber_dofs
- * function. This will then give inferior results, since knots in the
- * graph (representing dofs) are not found to be neighbors even if
- * they would be after condensation.
+ * The renumbering may take care of dof-to-dof couplings only induced by
+ * eliminating constraints. In addition to the memory consumption mentioned
+ * above, this also takes quite some computational time, but it may be
+ * switched off upon calling the @p renumber_dofs function. This will then
+ * give inferior results, since knots in the graph (representing dofs) are not
+ * found to be neighbors even if they would be after condensation.
*
- * The renumbering algorithms work on a purely algebraic basis, due to
- * the isomorphism between the graph theoretical groundwork underlying
- * the algorithms and binary matrices (matrices of which the entries
- * are binary values) represented by the sparsity patterns. In
- * special, the algorithms do not try to exploit topological knowledge
- * (e.g. corner detection) to find appropriate starting points. This
- * way, however, they work in arbitrary space dimension.
+ * The renumbering algorithms work on a purely algebraic basis, due to the
+ * isomorphism between the graph theoretical groundwork underlying the
+ * algorithms and binary matrices (matrices of which the entries are binary
+ * values) represented by the sparsity patterns. In special, the algorithms do
+ * not try to exploit topological knowledge (e.g. corner detection) to find
+ * appropriate starting points. This way, however, they work in arbitrary
+ * space dimension.
*
- * If you want to give starting points, you may give a list of dof
- * indices which will form the first step of the renumbering. The dofs
- * of the list will be consecutively numbered starting with zero,
- * i.e. this list is not renumbered according to the coordination
- * number of the nodes. Indices not in the allowed range are
- * deleted. If no index is allowed, the algorithm will search for its
- * own starting point.
+ * If you want to give starting points, you may give a list of dof indices
+ * which will form the first step of the renumbering. The dofs of the list
+ * will be consecutively numbered starting with zero, i.e. this list is not
+ * renumbered according to the coordination number of the nodes. Indices not
+ * in the allowed range are deleted. If no index is allowed, the algorithm
+ * will search for its own starting point.
*
*
* <h4>Results of renumbering</h4>
*
- * The renumbering schemes mentioned above do not lead to optimal
- * results. However, after all there is no algorithm that
- * accomplishes this within reasonable time. There are situations
- * where the lack of optimality even leads to worse results than with
- * the original, crude, levelwise numbering scheme; one of these
- * examples is a mesh of four cells of which always those cells are
- * refined which are neighbors to the center (you may call this mesh a
- * `zoom in' mesh). In one such example the bandwidth was increased by
- * about 50 per cent.
+ * The renumbering schemes mentioned above do not lead to optimal results.
+ * However, after all there is no algorithm that accomplishes this within
+ * reasonable time. There are situations where the lack of optimality even
+ * leads to worse results than with the original, crude, levelwise numbering
+ * scheme; one of these examples is a mesh of four cells of which always those
+ * cells are refined which are neighbors to the center (you may call this mesh
+ * a `zoom in' mesh). In one such example the bandwidth was increased by about
+ * 50 per cent.
*
* In most other cases, the bandwidth is reduced significantly. The reduction
* is the better the less structured the grid is. With one grid where the
* was reduced by a factor of six.
*
* Using the constraint information usually leads to reductions in bandwidth
- * of 10 or 20 per cent, but may for some very unstructured grids also lead
- * to an increase. You have to weigh the decrease in your case with the time
+ * of 10 or 20 per cent, but may for some very unstructured grids also lead to
+ * an increase. You have to weigh the decrease in your case with the time
* spent to use the constraint information, which usually is several times
* longer than the `pure' renumbering algorithm.
*
* In almost all cases, the renumbering scheme finds a corner to start with.
* Since there is more than one corner in most grids and since even an
* interior degree of freedom may be a better starting point, giving the
- * starting point by the user may be a viable way if you have a simple
- * scheme to derive a suitable point (e.g. by successively taking the
- * third child of the cell top left of the coarsest level, taking its
- * third vertex and the dof index thereof, if you want the top left corner
- * vertex). If you do not know beforehand what your grid will look like
- * (e.g. when using adaptive algorithms), searching a best starting point
- * may be difficult, however, and in many cases will not justify the effort.
+ * starting point by the user may be a viable way if you have a simple scheme
+ * to derive a suitable point (e.g. by successively taking the third child of
+ * the cell top left of the coarsest level, taking its third vertex and the
+ * dof index thereof, if you want the top left corner vertex). If you do not
+ * know beforehand what your grid will look like (e.g. when using adaptive
+ * algorithms), searching a best starting point may be difficult, however, and
+ * in many cases will not justify the effort.
*
*
* <h3>Component-wise and block-wise numberings</h3>
*
* For finite elements composed of several base elements using the FESystem
- * class, or for elements which provide several components themselves, it
- * may be of interest to sort the DoF indices by component. This will then
- * bring out the block matrix structure, since otherwise the degrees of freedom
- * are numbered cell-wise without taking into account that they may belong to
- * different components. For example, one may want to sort degree of freedom for
- * a Stokes discretization so that we first get all velocities and then all
- * the pressures so that the resulting matrix naturally decomposes into a
+ * class, or for elements which provide several components themselves, it may
+ * be of interest to sort the DoF indices by component. This will then bring
+ * out the block matrix structure, since otherwise the degrees of freedom are
+ * numbered cell-wise without taking into account that they may belong to
+ * different components. For example, one may want to sort degree of freedom
+ * for a Stokes discretization so that we first get all velocities and then
+ * all the pressures so that the resulting matrix naturally decomposes into a
* $2\times 2$ system.
*
- * This kind of numbering may be obtained by calling the
- * component_wise() function of this class. Since it does not touch
- * the order of indices within each component, it may be worthwhile to first
- * renumber using the Cuthill-McKee or a similar algorithm and
- * afterwards renumbering component-wise. This will bring out the
- * matrix structure and additionally have a good numbering within each
- * block.
+ * This kind of numbering may be obtained by calling the component_wise()
+ * function of this class. Since it does not touch the order of indices within
+ * each component, it may be worthwhile to first renumber using the Cuthill-
+ * McKee or a similar algorithm and afterwards renumbering component-wise.
+ * This will bring out the matrix structure and additionally have a good
+ * numbering within each block.
*
* The component_wise() function allows not only to honor enumeration based on
* vector components, but also allows to group together vector components into
- * "blocks" using a defaulted argument to the various DoFRenumber::component_wise()
- * functions (see @ref GlossComponent vs @ref GlossBlock for a description of
- * the difference). The blocks designated through this argument may, but do not
- * have to be, equal to the blocks that the finite element reports. For example,
- * a typical Stokes element would be
+ * "blocks" using a defaulted argument to the various
+ * DoFRenumber::component_wise() functions (see @ref GlossComponent vs @ref
+ * GlossBlock for a description of the difference). The blocks designated
+ * through this argument may, but do not have to be, equal to the blocks that
+ * the finite element reports. For example, a typical Stokes element would be
* @code
* FESystem<dim> stokes_fe (FE_Q<dim>(2), dim, // dim velocities
* FE_Q<dim>(1), 1); // one pressure
* @endcode
* This element has <code>dim+1</code> vector components and equally many
* blocks. However, one may want to consider the velocities as one logical
- * block so that all velocity degrees of freedom are enumerated the same
- * way, independent of whether they are $x$- or $y$-velocities. This is done,
- * for example, in step-20 and step-22 as well as several other tutorial programs.
+ * block so that all velocity degrees of freedom are enumerated the same way,
+ * independent of whether they are $x$- or $y$-velocities. This is done, for
+ * example, in step-20 and step-22 as well as several other tutorial programs.
*
- * On the other hand, if you really want to use block structure reported
- * by the finite element itself (a case that is often the case if you have
- * finite elements that have multiple vector components, e.g. the FE_RaviartThomas
- * or FE_Nedelec elements) then you can use the DoFRenumber::block_wise instead
+ * On the other hand, if you really want to use block structure reported by
+ * the finite element itself (a case that is often the case if you have finite
+ * elements that have multiple vector components, e.g. the FE_RaviartThomas or
+ * FE_Nedelec elements) then you can use the DoFRenumber::block_wise instead
* of the DoFRenumbering::component_wise functions.
*
*
* <h3>Cell-wise numbering</h3>
*
- * Given an ordered vector of cells, the function cell_wise()
- * sorts the degrees of freedom such that degrees on earlier cells of
- * this vector will occur before degrees on later cells.
+ * Given an ordered vector of cells, the function cell_wise() sorts the
+ * degrees of freedom such that degrees on earlier cells of this vector will
+ * occur before degrees on later cells.
*
* This rule produces a well-defined ordering for discontinuous Galerkin
- * methods (FE_DGP, FE_DGQ). For continuous methods, we use the
- * additional rule that each degree of freedom is ordered according to
- * the first cell in the ordered vector it belongs to.
+ * methods (FE_DGP, FE_DGQ). For continuous methods, we use the additional
+ * rule that each degree of freedom is ordered according to the first cell in
+ * the ordered vector it belongs to.
*
- * Applications of this scheme are downstream() and
- * clock_wise_dg(). The first orders the cells according to a
- * downstream direction and then applies cell_wise().
+ * Applications of this scheme are downstream() and clock_wise_dg(). The first
+ * orders the cells according to a downstream direction and then applies
+ * cell_wise().
*
* @note For DG elements, the internal numbering in each cell remains
- * unaffected. This cannot be guaranteed for continuous elements
- * anymore, since degrees of freedom shared with an earlier cell will
- * be accounted for by the other cell.
+ * unaffected. This cannot be guaranteed for continuous elements anymore,
+ * since degrees of freedom shared with an earlier cell will be accounted for
+ * by the other cell.
*
*
* <h3>Random renumbering</h3>
*
- * The random() function renumbers degrees of freedom randomly. This
- * function is probably seldom of use, except to check the dependence of
- * solvers (iterative or direct ones) on the numbering of the degrees
- * of freedom. It uses the @p random_shuffle function from the C++
- * standard library to do its work.
+ * The random() function renumbers degrees of freedom randomly. This function
+ * is probably seldom of use, except to check the dependence of solvers
+ * (iterative or direct ones) on the numbering of the degrees of freedom. It
+ * uses the @p random_shuffle function from the C++ standard library to do its
+ * work.
*
*
* <h3>A comparison of reordering strategies</h3>
*
- * As a benchmark of comparison, let us consider what the different
- * sparsity patterns produced by the various algorithms when using the
- * $Q_2^d\times Q_1$ element combination typically employed in the
- * discretization of Stokes equations, when used on the mesh obtained
- * in step-22 after one adaptive mesh refinement in
- * 3d. The space dimension together with the coupled finite element
- * leads to a rather dense system matrix with, on average around 180
- * nonzero entries per row. After applying each of the reordering
- * strategies shown below, the degrees of freedom are also sorted
- * using DoFRenumbering::component_wise into velocity and pressure
- * groups; this produces the $2\times 2$ block structure seen below
- * with the large velocity-velocity block at top left, small
- * pressure-pressure block at bottom right, and coupling blocks at top
- * right and bottom left.
+ * As a benchmark of comparison, let us consider what the different sparsity
+ * patterns produced by the various algorithms when using the $Q_2^d\times
+ * Q_1$ element combination typically employed in the discretization of Stokes
+ * equations, when used on the mesh obtained in step-22 after one adaptive
+ * mesh refinement in 3d. The space dimension together with the coupled finite
+ * element leads to a rather dense system matrix with, on average around 180
+ * nonzero entries per row. After applying each of the reordering strategies
+ * shown below, the degrees of freedom are also sorted using
+ * DoFRenumbering::component_wise into velocity and pressure groups; this
+ * produces the $2\times 2$ block structure seen below with the large
+ * velocity-velocity block at top left, small pressure-pressure block at
+ * bottom right, and coupling blocks at top right and bottom left.
*
- * The goal of reordering strategies is to improve the
- * preconditioner. In step-22 we use a SparseILU to
- * preconditioner for the velocity-velocity block at the top left. The
- * quality of the preconditioner can then be measured by the number of
- * CG iterations required to solve a linear system with this
- * block. For some of the reordering strategies below we record this
- * number for adaptive refinement cycle 3, with 93176 degrees of
- * freedom; because we solve several linear systems with the same
- * matrix in the Schur complement, the average number of iterations is
- * reported. The lower the number the better the preconditioner and
- * consequently the better the renumbering of degrees of freedom is
- * suited for this task. We also state the run-time of the program, in
- * part determined by the number of iterations needed, for the first 4
- * cycles on one of our machines. Note that the reported times
- * correspond to the run time of the entire program, not just the
- * affected solver; if a program runs twice as fast with one
- * particular ordering than with another one, then this means that the
- * actual solver is actually several times faster.
+ * The goal of reordering strategies is to improve the preconditioner. In
+ * step-22 we use a SparseILU to preconditioner for the velocity-velocity
+ * block at the top left. The quality of the preconditioner can then be
+ * measured by the number of CG iterations required to solve a linear system
+ * with this block. For some of the reordering strategies below we record this
+ * number for adaptive refinement cycle 3, with 93176 degrees of freedom;
+ * because we solve several linear systems with the same matrix in the Schur
+ * complement, the average number of iterations is reported. The lower the
+ * number the better the preconditioner and consequently the better the
+ * renumbering of degrees of freedom is suited for this task. We also state
+ * the run-time of the program, in part determined by the number of iterations
+ * needed, for the first 4 cycles on one of our machines. Note that the
+ * reported times correspond to the run time of the entire program, not just
+ * the affected solver; if a program runs twice as fast with one particular
+ * ordering than with another one, then this means that the actual solver is
+ * actually several times faster.
*
- * <table>
- * <tr>
- * <td>
- * @image html "reorder_sparsity_step_31_original.png"
- * </td>
- * <td>
- * @image html "reorder_sparsity_step_31_random.png"
- * </td>
- * <td>
- * @image html "reorder_sparsity_step_31_deal_cmk.png"
- * </td>
- * </tr>
- * <tr>
- * <td>
- * Enumeration as produced by deal.II's DoFHandler::distribute_dofs function
- * and no further reordering apart from the component-wise one.
+ * <table> <tr> <td> @image html "reorder_sparsity_step_31_original.png" </td>
+ * <td> @image html "reorder_sparsity_step_31_random.png" </td> <td> @image
+ * html "reorder_sparsity_step_31_deal_cmk.png" </td> </tr> <tr> <td>
+ * Enumeration as produced by deal.II's DoFHandler::distribute_dofs function
+ * and no further reordering apart from the component-wise one.
*
- * With this renumbering, we needed an average of 92.2 iterations for the
- * testcase outlined above, and a runtime of 7min53s.
- * </td>
- * <td>
- * Random enumeration as produced by applying DoFRenumbering::random
- * after calling DoFHandler::distribute_dofs. This enumeration produces
- * nonzero entries in matrices pretty much everywhere, appearing here as
- * an entirely unstructured matrix.
+ * With this renumbering, we needed an average of 92.2 iterations for the
+ * testcase outlined above, and a runtime of 7min53s. </td> <td> Random
+ * enumeration as produced by applying DoFRenumbering::random after calling
+ * DoFHandler::distribute_dofs. This enumeration produces nonzero entries in
+ * matrices pretty much everywhere, appearing here as an entirely unstructured
+ * matrix.
*
- * With this renumbering, we needed an average of 71 iterations for the
- * testcase outlined above, and a runtime of 10min55s. The longer runtime
- * despite less iterations compared to the default ordering may be due to
- * the fact that computing and applying the ILU requires us to jump back
- * and forth all through memory due to the lack of localization of
- * matrix entries around the diagonal; this then leads to many cache
- * misses and consequently bad timings.
- * </td>
- * <td>
- * Cuthill-McKee enumeration as produced by calling the deal.II implementation
- * of the algorithm provided by DoFRenumbering::Cuthill_McKee
- * after DoFHandler::distribute_dofs.
+ * With this renumbering, we needed an average of 71 iterations for the
+ * testcase outlined above, and a runtime of 10min55s. The longer runtime
+ * despite less iterations compared to the default ordering may be due to the
+ * fact that computing and applying the ILU requires us to jump back and forth
+ * all through memory due to the lack of localization of matrix entries around
+ * the diagonal; this then leads to many cache misses and consequently bad
+ * timings. </td> <td> Cuthill-McKee enumeration as produced by calling the
+ * deal.II implementation of the algorithm provided by
+ * DoFRenumbering::Cuthill_McKee after DoFHandler::distribute_dofs.
*
- * With this renumbering, we needed an average of 57.3 iterations for the
- * testcase outlined above, and a runtime of 6min10s.
- * </td>
- * </td>
- * </tr>
+ * With this renumbering, we needed an average of 57.3 iterations for the
+ * testcase outlined above, and a runtime of 6min10s. </td> </td> </tr>
*
- * <tr>
- * <td>
- * @image html "reorder_sparsity_step_31_boost_cmk.png"
- * </td>
- * <td>
- * @image html "reorder_sparsity_step_31_boost_king.png"
- * </td>
- * <td>
- * @image html "reorder_sparsity_step_31_boost_md.png"
- * </td>
- * </tr>
- * <tr>
- * <td>
- * Cuthill-McKee enumeration as produced by calling the BOOST implementation
- * of the algorithm provided by DoFRenumbering::boost::Cuthill_McKee
- * after DoFHandler::distribute_dofs.
+ * <tr> <td> @image html "reorder_sparsity_step_31_boost_cmk.png" </td> <td>
+ * @image html "reorder_sparsity_step_31_boost_king.png" </td> <td> @image
+ * html "reorder_sparsity_step_31_boost_md.png" </td> </tr> <tr> <td> Cuthill-
+ * McKee enumeration as produced by calling the BOOST implementation of the
+ * algorithm provided by DoFRenumbering::boost::Cuthill_McKee after
+ * DoFHandler::distribute_dofs.
*
- * With this renumbering, we needed an average of 51.7 iterations for the
- * testcase outlined above, and a runtime of 5min52s.
- * </td>
- * <td>
- * King enumeration as produced by calling the BOOST implementation
- * of the algorithm provided by DoFRenumbering::boost::king_ordering
- * after DoFHandler::distribute_dofs. The sparsity pattern appears
- * denser than with BOOST's Cuthill-McKee algorithm; however, this is
- * only an illusion: the number of nonzero entries is the same, they are
- * simply not as well clustered.
+ * With this renumbering, we needed an average of 51.7 iterations for the
+ * testcase outlined above, and a runtime of 5min52s. </td> <td> King
+ * enumeration as produced by calling the BOOST implementation of the
+ * algorithm provided by DoFRenumbering::boost::king_ordering after
+ * DoFHandler::distribute_dofs. The sparsity pattern appears denser than with
+ * BOOST's Cuthill-McKee algorithm; however, this is only an illusion: the
+ * number of nonzero entries is the same, they are simply not as well
+ * clustered.
*
- * With this renumbering, we needed an average of 51.0 iterations for the
- * testcase outlined above, and a runtime of 5min03s. Although the number
- * of iterations is only slightly less than with BOOST's Cuthill-McKee
- * implementation, runtime is significantly less. This, again, may be due
- * to cache effects. As a consequence, this is the algorithm best suited
- * to the testcase, and is in fact used in step-22.
- * </td>
- * <td>
- * Minimum degree enumeration as produced by calling the BOOST implementation
- * of the algorithm provided by DoFRenumbering::boost::minimum_degree
- * after DoFHandler::distribute_dofs. The minimum degree algorithm does not
- * attempt to minimize the bandwidth of a matrix but to minimize the amount
- * of fill-in a LU decomposition would produce, i.e. the number of places in
- * the matrix that would be occupied by elements of an LU decomposition that
- * are not already occupied by elements of the original matrix. The resulting
- * sparsity pattern obviously has an entirely different structure than the
- * ones produced by algorithms trying to minimize the bandwidth.
+ * With this renumbering, we needed an average of 51.0 iterations for the
+ * testcase outlined above, and a runtime of 5min03s. Although the number of
+ * iterations is only slightly less than with BOOST's Cuthill-McKee
+ * implementation, runtime is significantly less. This, again, may be due to
+ * cache effects. As a consequence, this is the algorithm best suited to the
+ * testcase, and is in fact used in step-22. </td> <td> Minimum degree
+ * enumeration as produced by calling the BOOST implementation of the
+ * algorithm provided by DoFRenumbering::boost::minimum_degree after
+ * DoFHandler::distribute_dofs. The minimum degree algorithm does not attempt
+ * to minimize the bandwidth of a matrix but to minimize the amount of fill-in
+ * a LU decomposition would produce, i.e. the number of places in the matrix
+ * that would be occupied by elements of an LU decomposition that are not
+ * already occupied by elements of the original matrix. The resulting sparsity
+ * pattern obviously has an entirely different structure than the ones
+ * produced by algorithms trying to minimize the bandwidth.
*
- * With this renumbering, we needed an average of 58.9 iterations for the
- * testcase outlined above, and a runtime of 6min11s.
- * </td>
- * </tr>
+ * With this renumbering, we needed an average of 58.9 iterations for the
+ * testcase outlined above, and a runtime of 6min11s. </td> </tr>
*
- * <tr>
- * <td>
- * @image html "reorder_sparsity_step_31_downstream.png"
- * </td>
- * <td>
- * </td>
- * <td>
- * </td>
- * </tr>
- * <tr>
- * <td>
- * Downstream enumeration using DoFRenumbering::downstream using a
- * direction that points diagonally through the domain.
+ * <tr> <td> @image html "reorder_sparsity_step_31_downstream.png" </td> <td>
+ * </td> <td> </td> </tr> <tr> <td> Downstream enumeration using
+ * DoFRenumbering::downstream using a direction that points diagonally through
+ * the domain.
*
- * With this renumbering, we needed an average of 90.5 iterations for the
- * testcase outlined above, and a runtime of 7min05s.
- * </td>
- * <td>
- * </td>
- * <td>
- * </td>
- * </tr>
- * </table>
+ * With this renumbering, we needed an average of 90.5 iterations for the
+ * testcase outlined above, and a runtime of 7min05s. </td> <td> </td> <td>
+ * </td> </tr> </table>
*
*
* <h3>Multigrid DoF numbering</h3>
*
- * Most of the algorithms listed above also work on multigrid degree of freedom
- * numberings. Refer to the actual function declarations to get more
+ * Most of the algorithms listed above also work on multigrid degree of
+ * freedom numberings. Refer to the actual function declarations to get more
* information on this.
*
* @ingroup dofs
- * @author Wolfgang Bangerth, Guido Kanschat, 1998, 1999, 2000, 2004, 2007, 2008
+ * @author Wolfgang Bangerth, Guido Kanschat, 1998, 1999, 2000, 2004, 2007,
+ * 2008
*/
namespace DoFRenumbering
{
/**
- * Direction based comparator for
- * cell iterators: it returns @p
- * true if the center of the second
- * cell is downstream of the center
- * of the first one with respect to
- * the direction given to the
- * constructor.
+ * Direction based comparator for cell iterators: it returns @p true if the
+ * center of the second cell is downstream of the center of the first one
+ * with respect to the direction given to the constructor.
*/
template <class Iterator, int dim>
struct CompareDownstream
const bool use_constraints = false);
/**
- * Computes the renumbering vector needed by the Cuthill_McKee()
- * function. Does not perform the renumbering on the DoFHandler dofs but
- * returns the renumbering vector.
+ * Computes the renumbering vector needed by the Cuthill_McKee() function.
+ * Does not perform the renumbering on the DoFHandler dofs but returns the
+ * renumbering vector.
*/
template <class DH>
void
const std::vector<types::global_dof_index> &starting_indices = std::vector<types::global_dof_index>());
/**
- * Computes the renumbering vector needed by the Cuthill_McKee()
- * function. Does not perform the renumbering on the DoFHandler dofs but
- * returns the renumbering vector.
+ * Computes the renumbering vector needed by the Cuthill_McKee() function.
+ * Does not perform the renumbering on the DoFHandler dofs but returns the
+ * renumbering vector.
*/
template <class DH>
void
* You can specify that the components are ordered in a different way than
* suggested by the FESystem object you use. To this end, set up the vector
* @p target_component such that the entry at index @p i denotes the number
- * of the target component for dofs with component @p i in the
- * FESystem. Naming the same target component more than once is possible and
- * results in a blocking of several components into one. This is discussed
- * in step-22. If you omit this argument, the same order as given by the
- * finite element is used.
+ * of the target component for dofs with component @p i in the FESystem.
+ * Naming the same target component more than once is possible and results
+ * in a blocking of several components into one. This is discussed in
+ * step-22. If you omit this argument, the same order as given by the finite
+ * element is used.
*
* If one of the base finite elements from which the global finite element
* under consideration here, is a non-primitive one, i.e. its shape
*
* For finite elements with only one component, or a single non-primitive
* base element, this function is the identity operation.
- *
- * @note A similar function, which renumbered all levels existed for
- * MGDoFHandler. This function was deleted. Thus, you have to call the level
- * function for each level now.
+ *
+ * @note A similar function, which renumbered all levels existed for
+ * MGDoFHandler. This function was deleted. Thus, you have to call the level
+ * function for each level now.
*/
template <int dim, int spacedim>
void
/**
* Sort the degrees of freedom by component. It does the same thing as the
- * above function, only that it does this for one single level of a
- * multi-level discretization. The non-multigrid part of the MGDoFHandler is
- * not touched.
+ * above function, only that it does this for one single level of a multi-
+ * level discretization. The non-multigrid part of the MGDoFHandler is not
+ * touched.
*/
template <class DH>
void
const std::vector<unsigned int> &target_component = std::vector<unsigned int>());
/**
- * Computes the renumbering vector needed by the component_wise()
- * functions. Does not perform the renumbering on the DoFHandler dofs but
- * returns the renumbering vector.
+ * Computes the renumbering vector needed by the component_wise() functions.
+ * Does not perform the renumbering on the DoFHandler dofs but returns the
+ * renumbering vector.
*/
template <int dim, int spacedim, class ITERATOR, class ENDITERATOR>
types::global_dof_index
block_wise (MGDoFHandler<dim> &dof_handler);
/**
- * Computes the renumbering vector needed by the block_wise()
- * functions. Does not perform the renumbering on the DoFHandler dofs but
- * returns the renumbering vector.
+ * Computes the renumbering vector needed by the block_wise() functions.
+ * Does not perform the renumbering on the DoFHandler dofs but returns the
+ * renumbering vector.
*/
template <int dim, int spacedim, class ITERATOR, class ENDITERATOR>
types::global_dof_index
* be guaranteed for all meshes.
*
* If the @p dof_wise_renumbering argument is set to @p false, this function
- * produces a downstream ordering of the mesh cells and calls
- * cell_wise(). Therefore, the output only makes sense for Discontinuous
- * Galerkin Finite Elements (all degrees of freedom have to be associated
- * with the interior of the cell in that case) in that case.
+ * produces a downstream ordering of the mesh cells and calls cell_wise().
+ * Therefore, the output only makes sense for Discontinuous Galerkin Finite
+ * Elements (all degrees of freedom have to be associated with the interior
+ * of the cell in that case) in that case.
*
* If @p dof_wise_renumbering is set to @p true, the degrees of freedom are
* renumbered based on the support point location of the individual degrees
const bool counter = false);
/**
- * Computes the renumbering vector needed by the clockwise_dg()
- * functions. Does not perform the renumbering on the DoFHandler dofs but
- * returns the renumbering vector.
+ * Computes the renumbering vector needed by the clockwise_dg() functions.
+ * Does not perform the renumbering on the DoFHandler dofs but returns the
+ * renumbering vector.
*/
template <class DH>
void
/**
* Sort those degrees of freedom which are tagged with @p true in the @p
- * selected_dofs array on the level @p level to the back of the DoF
- * numbers. The sorting is stable, i.e. the relative order within the tagged
- * degrees of freedom is preserved, as is the relative order within the
- * untagged ones.
+ * selected_dofs array on the level @p level to the back of the DoF numbers.
+ * The sorting is stable, i.e. the relative order within the tagged degrees
+ * of freedom is preserved, as is the relative order within the untagged
+ * ones.
*
* @pre The @p selected_dofs array must have as many elements as the @p
* dof_handler has degrees of freedom on the given level.
subdomain_wise (DH &dof_handler);
/**
- * Computes the renumbering vector needed by the subdomain_wise()
- * function. Does not perform the renumbering on the @p DoFHandler dofs but
- * returns the renumbering vector.
+ * Computes the renumbering vector needed by the subdomain_wise() function.
+ * Does not perform the renumbering on the @p DoFHandler dofs but returns
+ * the renumbering vector.
*/
template <class DH>
void
*/
DeclException0 (ExcInvalidComponentOrder);
/**
- * The function is only
- * implemented for Discontinuous
- * Galerkin Finite elements.
+ * The function is only implemented for Discontinuous Galerkin Finite
+ * elements.
*
* @ingroup Exceptions
*/
//TODO: map_support_points_to_dofs should generate a multimap, rather than just a map, since several dofs may be located at the same support point
/**
- * This is a collection of functions operating on, and manipulating
- * the numbers of degrees of freedom. The documentation of the member
- * functions will provide more information, but for functions that
- * exist in multiple versions, there are sections in this global
- * documentation stating some commonalities.
+ * This is a collection of functions operating on, and manipulating the
+ * numbers of degrees of freedom. The documentation of the member functions
+ * will provide more information, but for functions that exist in multiple
+ * versions, there are sections in this global documentation stating some
+ * commonalities.
*
- * All member functions are static, so there is no need to create an
- * object of class DoFTools.
+ * All member functions are static, so there is no need to create an object of
+ * class DoFTools.
*
*
* <h3>Setting up sparsity patterns</h3>
*
* When assembling system matrices, the entries are usually of the form
* $a_{ij} = a(\phi_i, \phi_j)$, where $a$ is a bilinear functional, often an
- * integral. When using sparse matrices, we therefore only need to reserve space
- * for those $a_{ij}$ only, which are nonzero, which is the same as to say that
- * the basis functions $\phi_i$ and $\phi_j$ have a nonempty intersection of
- * their support. Since the support of basis functions is bound only on cells
- * on which they are located or to which they are adjacent, to
- * determine the sparsity pattern it is sufficient to loop over all
- * cells and connect all basis functions on each cell with all other
- * basis functions on that cell. There may be finite elements for
- * which not all basis functions on a cell connect with each other,
- * but no use of this case is made since no examples where this occurs
- * are known to the author.
+ * integral. When using sparse matrices, we therefore only need to reserve
+ * space for those $a_{ij}$ only, which are nonzero, which is the same as to
+ * say that the basis functions $\phi_i$ and $\phi_j$ have a nonempty
+ * intersection of their support. Since the support of basis functions is
+ * bound only on cells on which they are located or to which they are
+ * adjacent, to determine the sparsity pattern it is sufficient to loop over
+ * all cells and connect all basis functions on each cell with all other basis
+ * functions on that cell. There may be finite elements for which not all
+ * basis functions on a cell connect with each other, but no use of this case
+ * is made since no examples where this occurs are known to the author.
*
*
* <h3>DoF numberings on boundaries</h3>
* i.e. the indices of degrees of freedom on different parts may be
* intermixed.
*
- * Degrees of freedom on the boundary but not on one of the specified
- * boundary parts are given the index DoFHandler::invalid_dof_index, as if
- * they were in the interior. If no boundary indicator was given or if
- * no face of a cell has a boundary indicator contained in the given
- * list, the vector of new indices consists solely of
- * DoFHandler::invalid_dof_index.
+ * Degrees of freedom on the boundary but not on one of the specified boundary
+ * parts are given the index DoFHandler::invalid_dof_index, as if they were in
+ * the interior. If no boundary indicator was given or if no face of a cell
+ * has a boundary indicator contained in the given list, the vector of new
+ * indices consists solely of DoFHandler::invalid_dof_index.
*
* (As a side note, for corner cases: The question what a degree of freedom on
* the boundary is, is not so easy. It should really be a degree of freedom
- * of which the respective basis function has nonzero values on the
- * boundary. At least for Lagrange elements this definition is equal to the
- * statement that the off-point, or what deal.II calls support_point, of the
- * shape function, i.e. the point where the function assumes its nominal value
- * (for Lagrange elements this is the point where it has the function value
- * 1), is located on the boundary. We do not check this directly, the
- * criterion is rather defined through the information the finite element
- * class gives: the FiniteElement class defines the numbers of basis functions
- * per vertex, per line, and so on and the basis functions are numbered after
- * this information; a basis function is to be considered to be on the face of
- * a cell (and thus on the boundary if the cell is at the boundary) according
- * to it belonging to a vertex, line, etc but not to the interior of the
- * cell. The finite element uses the same cell-wise numbering so that we can
- * say that if a degree of freedom was numbered as one of the dofs on lines,
- * we assume that it is located on the line. Where the off-point actually is,
- * is a secret of the finite element (well, you can ask it, but we don't do it
+ * of which the respective basis function has nonzero values on the boundary.
+ * At least for Lagrange elements this definition is equal to the statement
+ * that the off-point, or what deal.II calls support_point, of the shape
+ * function, i.e. the point where the function assumes its nominal value (for
+ * Lagrange elements this is the point where it has the function value 1), is
+ * located on the boundary. We do not check this directly, the criterion is
+ * rather defined through the information the finite element class gives: the
+ * FiniteElement class defines the numbers of basis functions per vertex, per
+ * line, and so on and the basis functions are numbered after this
+ * information; a basis function is to be considered to be on the face of a
+ * cell (and thus on the boundary if the cell is at the boundary) according to
+ * it belonging to a vertex, line, etc but not to the interior of the cell.
+ * The finite element uses the same cell-wise numbering so that we can say
+ * that if a degree of freedom was numbered as one of the dofs on lines, we
+ * assume that it is located on the line. Where the off-point actually is, is
+ * a secret of the finite element (well, you can ask it, but we don't do it
* here) and not relevant in this context.)
*
*
* <h3>Setting up sparsity patterns for boundary matrices</h3>
*
- * In some cases, one wants to only work with DoFs that sit on the
- * boundary. One application is, for example, if rather than interpolating
- * non-homogenous boundary values, one would like to project them. For this,
- * we need two things: a way to identify nodes that are located on (parts of)
- * the boundary, and a way to build matrices out of only degrees of freedom
- * that are on the boundary (i.e. much smaller matrices, in which we do not
- * even build the large zero block that stems from the fact that most degrees
- * of freedom have no support on the boundary of the domain). The first of
- * these tasks is done by the map_dof_to_boundary_indices() function of this
- * class (described above).
+ * In some cases, one wants to only work with DoFs that sit on the boundary.
+ * One application is, for example, if rather than interpolating non-
+ * homogenous boundary values, one would like to project them. For this, we
+ * need two things: a way to identify nodes that are located on (parts of) the
+ * boundary, and a way to build matrices out of only degrees of freedom that
+ * are on the boundary (i.e. much smaller matrices, in which we do not even
+ * build the large zero block that stems from the fact that most degrees of
+ * freedom have no support on the boundary of the domain). The first of these
+ * tasks is done by the map_dof_to_boundary_indices() function of this class
+ * (described above).
*
* The second part requires us first to build a sparsity pattern for the
* couplings between boundary nodes, and then to actually build the components
namespace DoFTools
{
/**
- * The flags used in tables by certain <tt>make_*_pattern</tt>
- * functions to describe whether two components of the solution
- * couple in the bilinear forms corresponding to cell or face
- * terms. An example of using these flags is shown in the
- * introduction of step-46.
+ * The flags used in tables by certain <tt>make_*_pattern</tt> functions to
+ * describe whether two components of the solution couple in the bilinear
+ * forms corresponding to cell or face terms. An example of using these
+ * flags is shown in the introduction of step-46.
*
- * In the descriptions of the individual elements below, remember
- * that these flags are used as elements of tables of size
- * FiniteElement::n_components times FiniteElement::n_components
- * where each element indicates whether two components do or do not
- * couple.
+ * In the descriptions of the individual elements below, remember that these
+ * flags are used as elements of tables of size FiniteElement::n_components
+ * times FiniteElement::n_components where each element indicates whether
+ * two components do or do not couple.
*/
enum Coupling
{
*/
always,
/**
- * Two components couple only if their shape functions are both
- * nonzero on a given face. This flag is only used when computing
- * integrals over faces of cells.
+ * Two components couple only if their shape functions are both nonzero on
+ * a given face. This flag is only used when computing integrals over
+ * faces of cells.
*/
nonzero
};
/**
- * @name Functions to support code that generically uses both DoFHandler and hp::DoFHandler
+ * @name Functions to support code that generically uses both DoFHandler and
+ * hp::DoFHandler
* @{
*/
/**
/**
* Maximal number of degrees of freedom on a face.
*
- * This function exists for both non-hp and hp DoFHandlers, to allow
- * for a uniform interface to query this property.
+ * This function exists for both non-hp and hp DoFHandlers, to allow for a
+ * uniform interface to query this property.
*
* @relates DoFHandler
*/
/**
* Maximal number of degrees of freedom on a face.
*
- * This function exists for both non-hp and hp DoFHandlers, to allow
- * for a uniform interface to query this property.
+ * This function exists for both non-hp and hp DoFHandlers, to allow for a
+ * uniform interface to query this property.
*
* @relates hp::DoFHandler
*/
/**
* Maximal number of degrees of freedom on a vertex.
*
- * This function exists for both non-hp and hp DoFHandlers, to allow
- * for a uniform interface to query this property.
+ * This function exists for both non-hp and hp DoFHandlers, to allow for a
+ * uniform interface to query this property.
*
* @relates DoFHandler
*/
/**
* Maximal number of degrees of freedom on a vertex.
*
- * This function exists for both non-hp and hp DoFHandlers, to allow
- * for a uniform interface to query this property.
+ * This function exists for both non-hp and hp DoFHandlers, to allow for a
+ * uniform interface to query this property.
*
* @relates hp::DoFHandler
*/
max_dofs_per_vertex (const hp::DoFHandler<dim,spacedim> &dh);
/**
- * Number of vector components in the finite element object used by
- * this DoFHandler.
+ * Number of vector components in the finite element object used by this
+ * DoFHandler.
*
- * This function exists for both non-hp and hp DoFHandlers, to allow
- * for a uniform interface to query this property.
+ * This function exists for both non-hp and hp DoFHandlers, to allow for a
+ * uniform interface to query this property.
*
* @relates DoFHandler
*/
n_components (const DoFHandler<dim,spacedim> &dh);
/**
- * Number of vector components in the finite element object used by
- * this DoFHandler.
+ * Number of vector components in the finite element object used by this
+ * DoFHandler.
*
- * This function exists for both non-hp and hp DoFHandlers, to allow
- * for a uniform interface to query this property.
+ * This function exists for both non-hp and hp DoFHandlers, to allow for a
+ * uniform interface to query this property.
*
* @relates hp::DoFHandler
*/
n_components (const hp::DoFHandler<dim,spacedim> &dh);
/**
- * Find out whether the FiniteElement used by this DoFHandler is
- * primitive or not.
+ * Find out whether the FiniteElement used by this DoFHandler is primitive
+ * or not.
*
- * This function exists for both non-hp and hp DoFHandlers, to allow
- * for a uniform interface to query this property.
+ * This function exists for both non-hp and hp DoFHandlers, to allow for a
+ * uniform interface to query this property.
*
* @relates DoFHandler
*/
fe_is_primitive (const DoFHandler<dim,spacedim> &dh);
/**
- * Find out whether the FiniteElement used by this DoFHandler is
- * primitive or not.
+ * Find out whether the FiniteElement used by this DoFHandler is primitive
+ * or not.
*
- * This function exists for both non-hp and hp DoFHandlers, to allow
- * for a uniform interface to query this property.
+ * This function exists for both non-hp and hp DoFHandlers, to allow for a
+ * uniform interface to query this property.
*
* @relates hp::DoFHandler
*/
/**
* Locate non-zero entries of the system matrix.
*
- * This function computes the possible positions of non-zero entries
- * in the global system matrix. We assume that a certain finite
- * element basis function is non-zero on a cell only if its degree
- * of freedom is associated with the interior, a face, an edge or a
- * vertex of this cell. As a result, the matrix entry between two
- * basis functions can be non-zero only if they correspond to
- * degrees of freedom of at least one common cell. Therefore, @p
- * make_sparsity_pattern just loops over all cells and enters all
- * couplings local to that cell. As the generation of the sparsity
- * pattern is irrespective of the equation which is solved later on,
- * the resulting sparsity pattern is symmetric.
- *
- * Remember using SparsityPattern::compress() after generating the
- * pattern.
+ * This function computes the possible positions of non-zero entries in the
+ * global system matrix. We assume that a certain finite element basis
+ * function is non-zero on a cell only if its degree of freedom is
+ * associated with the interior, a face, an edge or a vertex of this cell.
+ * As a result, the matrix entry between two basis functions can be non-zero
+ * only if they correspond to degrees of freedom of at least one common
+ * cell. Therefore, @p make_sparsity_pattern just loops over all cells and
+ * enters all couplings local to that cell. As the generation of the
+ * sparsity pattern is irrespective of the equation which is solved later
+ * on, the resulting sparsity pattern is symmetric.
+ *
+ * Remember using SparsityPattern::compress() after generating the pattern.
*
* The actual type of the sparsity pattern may be SparsityPattern,
* CompressedSparsityPattern, BlockSparsityPattern,
- * BlockCompressedSparsityPattern,
- * BlockCompressedSetSparsityPattern,
- * BlockCompressedSimpleSparsityPattern, or any other class that
- * satisfies similar requirements. It is assumed that the size of
- * the sparsity pattern matches the number of degrees of freedom and
- * that enough unused nonzero entries are left to fill the sparsity
- * pattern. The nonzero entries generated by this function are
- * overlaid to possible previous content of the object, that is
- * previously added entries are not deleted.
- *
- * Since this process is purely local, the sparsity pattern does not
- * provide for entries introduced by the elimination of hanging
- * nodes. They have to be taken care of by a call to
- * ConstraintMatrix::condense() afterwards.
- *
- * Alternatively, the constraints on degrees of freedom can already
- * be taken into account at the time of creating the sparsity
- * pattern. For this, pass the ConstraintMatrix object as the third
- * argument to the current function. No call to
- * ConstraintMatrix::condense() is then necessary. This process is
- * explained in step-27.
- *
- * In case the constraints are already taken care of in this
- * function, it is possible to neglect off-diagonal entries in the
- * sparsity pattern. When using
- * ConstraintMatrix::distribute_local_to_global during assembling,
- * no entries will ever be written into these matrix position, so
- * that one can save some computing time in matrix-vector products
- * by not even creating these elements. In that case, the variable
- * <tt>keep_constrained_dofs</tt> needs to be set to <tt>false</tt>.
- *
- * If the @p subdomain_id parameter is given, the sparsity pattern
- * is built only on cells that have a subdomain_id equal to the
- * given argument. This is useful in parallel contexts where the
- * matrix and sparsity pattern (for example a
- * TrilinosWrappers::SparsityPattern) may be distributed and not
- * every MPI process needs to build the entire sparsity pattern; in
- * that case, it is sufficient if every process only builds that
- * part of the sparsity pattern that corresponds to the subdomain_id
- * for which it is responsible. This feature is used in step-32.
+ * BlockCompressedSparsityPattern, BlockCompressedSetSparsityPattern,
+ * BlockCompressedSimpleSparsityPattern, or any other class that satisfies
+ * similar requirements. It is assumed that the size of the sparsity pattern
+ * matches the number of degrees of freedom and that enough unused nonzero
+ * entries are left to fill the sparsity pattern. The nonzero entries
+ * generated by this function are overlaid to possible previous content of
+ * the object, that is previously added entries are not deleted.
+ *
+ * Since this process is purely local, the sparsity pattern does not provide
+ * for entries introduced by the elimination of hanging nodes. They have to
+ * be taken care of by a call to ConstraintMatrix::condense() afterwards.
+ *
+ * Alternatively, the constraints on degrees of freedom can already be taken
+ * into account at the time of creating the sparsity pattern. For this, pass
+ * the ConstraintMatrix object as the third argument to the current
+ * function. No call to ConstraintMatrix::condense() is then necessary. This
+ * process is explained in step-27.
+ *
+ * In case the constraints are already taken care of in this function, it is
+ * possible to neglect off-diagonal entries in the sparsity pattern. When
+ * using ConstraintMatrix::distribute_local_to_global during assembling, no
+ * entries will ever be written into these matrix position, so that one can
+ * save some computing time in matrix-vector products by not even creating
+ * these elements. In that case, the variable <tt>keep_constrained_dofs</tt>
+ * needs to be set to <tt>false</tt>.
+ *
+ * If the @p subdomain_id parameter is given, the sparsity pattern is built
+ * only on cells that have a subdomain_id equal to the given argument. This
+ * is useful in parallel contexts where the matrix and sparsity pattern (for
+ * example a TrilinosWrappers::SparsityPattern) may be distributed and not
+ * every MPI process needs to build the entire sparsity pattern; in that
+ * case, it is sufficient if every process only builds that part of the
+ * sparsity pattern that corresponds to the subdomain_id for which it is
+ * responsible. This feature is used in step-32.
*
* @ingroup constraints
*/
const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id);
/**
- * Locate non-zero entries for vector valued finite elements. This
- * function does mostly the same as the previous
- * make_sparsity_pattern(), but it is specialized for vector finite
- * elements and allows to specify which variables couple in which
- * equation. For example, if wanted to solve the Stokes equations,
+ * Locate non-zero entries for vector valued finite elements. This function
+ * does mostly the same as the previous make_sparsity_pattern(), but it is
+ * specialized for vector finite elements and allows to specify which
+ * variables couple in which equation. For example, if wanted to solve the
+ * Stokes equations,
*
- * @f{align*}
- * -\Delta \mathbf u + \nabla p &= 0,\\
- * \text{div}\ u &= 0
- * @f}
+ * @f{align*} -\Delta \mathbf u + \nabla p &= 0,\\ \text{div}\ u
+ * &= 0 @f}
*
- * in two space dimensions, using stable Q2/Q1 mixed elements (using
- * the FESystem class), then you don't want all degrees of freedom
- * to couple in each equation. You rather may want to give the
- * following pattern of couplings:
+ * in two space dimensions, using stable Q2/Q1 mixed elements (using the
+ * FESystem class), then you don't want all degrees of freedom to couple in
+ * each equation. You rather may want to give the following pattern of
+ * couplings:
*
* @f[
* \left[
* \right]
* @f]
*
- * where "1" indicates that two variables (i.e. components of the
- * FESystem) couple in the respective equation, and a "0" means no
- * coupling, in which case it is not necessary to allocate space in
- * the matrix structure. Obviously, the mask refers to components of
- * the composed FESystem, rather than to the degrees of freedom
- * contained in there.
- *
- * This function is designed to accept a coupling pattern, like the
- * one shown above, through the @p couplings parameter, which
- * contains values of type #Coupling. It builds the matrix structure
- * just like the previous function, but does not create matrix
- * elements if not specified by the coupling pattern. If the
- * couplings are symmetric, then so will be the resulting sparsity
- * pattern.
+ * where "1" indicates that two variables (i.e. components of the FESystem)
+ * couple in the respective equation, and a "0" means no coupling, in which
+ * case it is not necessary to allocate space in the matrix structure.
+ * Obviously, the mask refers to components of the composed FESystem, rather
+ * than to the degrees of freedom contained in there.
+ *
+ * This function is designed to accept a coupling pattern, like the one
+ * shown above, through the @p couplings parameter, which contains values of
+ * type #Coupling. It builds the matrix structure just like the previous
+ * function, but does not create matrix elements if not specified by the
+ * coupling pattern. If the couplings are symmetric, then so will be the
+ * resulting sparsity pattern.
*
* The actual type of the sparsity pattern may be SparsityPattern,
* CompressedSparsityPattern, BlockSparsityPattern,
- * BlockCompressedSparsityPattern,
- * BlockCompressedSetSparsityPattern, or any other class that
- * satisfies similar requirements.
+ * BlockCompressedSparsityPattern, BlockCompressedSetSparsityPattern, or any
+ * other class that satisfies similar requirements.
*
- * There is a complication if some or all of the shape functions of
- * the finite element in use are non-zero in more than one component
- * (in deal.II speak: they are non-primitive). In this case, the
- * coupling element correspoding to the first non-zero component is
- * taken and additional ones for this component are ignored.
+ * There is a complication if some or all of the shape functions of the
+ * finite element in use are non-zero in more than one component (in deal.II
+ * speak: they are non-primitive). In this case, the coupling element
+ * correspoding to the first non-zero component is taken and additional ones
+ * for this component are ignored.
*
* @todo Not implemented for hp::DoFHandler.
*
- * As mentioned before, the creation of the sparsity pattern is a
- * purely local process and the sparsity pattern does not provide
- * for entries introduced by the elimination of hanging nodes. They
- * have to be taken care of by a call to
- * ConstraintMatrix::condense() afterwards.
- *
- * Alternatively, the constraints on degrees of freedom can already
- * be taken into account at the time of creating the sparsity
- * pattern. For this, pass the ConstraintMatrix object as the third
- * argument to the current function. No call to
- * ConstraintMatrix::condense() is then necessary. This process is
- * explained in @ref step_27 "step-27".
- *
- * In case the constraints are already taken care of in this
- * function, it is possible to neglect off-diagonal entries in the
- * sparsity pattern. When using
- * ConstraintMatrix::distribute_local_to_global during assembling,
- * no entries will ever be written into these matrix position, so
- * that one can save some computing time in matrix-vector products
- * by not even creating these elements. In that case, the variable
- * <tt>keep_constrained_dofs</tt> needs to be set to <tt>false</tt>.
- *
- * If the @p subdomain_id parameter is given, the sparsity pattern
- * is built only on cells that have a subdomain_id equal to the
- * given argument. This is useful in parallel contexts where the
- * matrix and sparsity pattern (for example a
- * TrilinosWrappers::SparsityPattern) may be distributed and not
- * every MPI process needs to build the entire sparsity pattern; in
- * that case, it is sufficient if every process only builds that
- * part of the sparsity pattern that corresponds to the subdomain_id
- * for which it is responsible. This feature is used in step-32.
+ * As mentioned before, the creation of the sparsity pattern is a purely
+ * local process and the sparsity pattern does not provide for entries
+ * introduced by the elimination of hanging nodes. They have to be taken
+ * care of by a call to ConstraintMatrix::condense() afterwards.
+ *
+ * Alternatively, the constraints on degrees of freedom can already be taken
+ * into account at the time of creating the sparsity pattern. For this, pass
+ * the ConstraintMatrix object as the third argument to the current
+ * function. No call to ConstraintMatrix::condense() is then necessary. This
+ * process is explained in @ref step_27 "step-27".
+ *
+ * In case the constraints are already taken care of in this function, it is
+ * possible to neglect off-diagonal entries in the sparsity pattern. When
+ * using ConstraintMatrix::distribute_local_to_global during assembling, no
+ * entries will ever be written into these matrix position, so that one can
+ * save some computing time in matrix-vector products by not even creating
+ * these elements. In that case, the variable <tt>keep_constrained_dofs</tt>
+ * needs to be set to <tt>false</tt>.
+ *
+ * If the @p subdomain_id parameter is given, the sparsity pattern is built
+ * only on cells that have a subdomain_id equal to the given argument. This
+ * is useful in parallel contexts where the matrix and sparsity pattern (for
+ * example a TrilinosWrappers::SparsityPattern) may be distributed and not
+ * every MPI process needs to build the entire sparsity pattern; in that
+ * case, it is sufficient if every process only builds that part of the
+ * sparsity pattern that corresponds to the subdomain_id for which it is
+ * responsible. This feature is used in step-32.
*
* @ingroup constraints
*/
const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id);
/**
- * @deprecated This is the old form of the previous function. It
- * generates a table of DoFTools::Coupling values (where a
- * <code>true</code> value in the mask is translated into a
- * Coupling::always value in the table) and calls the function
- * above.
+ * @deprecated This is the old form of the previous function. It generates a
+ * table of DoFTools::Coupling values (where a <code>true</code> value in
+ * the mask is translated into a Coupling::always value in the table) and
+ * calls the function above.
*/
template <class DH, class SparsityPattern>
void
SparsityPattern &sparsity_pattern) DEAL_II_DEPRECATED;
/**
- * Construct a sparsity pattern that allows coupling degrees of
- * freedom on two different but related meshes.
+ * Construct a sparsity pattern that allows coupling degrees of freedom on
+ * two different but related meshes.
*
- * The idea is that if the two given DoFHandler objects correspond
- * to two different meshes (and potentially to different finite
- * elements used on these cells), but that if the two triangulations
- * they are based on are derived from the same coarse mesh through
- * hierarchical refinement, then one may set up a problem where one
- * would like to test shape functions from one mesh against the
- * shape functions from another mesh. In particular, this means that
- * shape functions from a cell on the first mesh are tested against
- * those on the second cell that are located on the corresponding
- * cell; this correspondence is something that the IntergridMap
- * class can determine.
+ * The idea is that if the two given DoFHandler objects correspond to two
+ * different meshes (and potentially to different finite elements used on
+ * these cells), but that if the two triangulations they are based on are
+ * derived from the same coarse mesh through hierarchical refinement, then
+ * one may set up a problem where one would like to test shape functions
+ * from one mesh against the shape functions from another mesh. In
+ * particular, this means that shape functions from a cell on the first mesh
+ * are tested against those on the second cell that are located on the
+ * corresponding cell; this correspondence is something that the
+ * IntergridMap class can determine.
*
- * This function then constructs a sparsity pattern for which the
- * degrees of freedom that represent the rows come from the first
- * given DoFHandler, whereas the ones that correspond to columns
- * come from the second DoFHandler.
+ * This function then constructs a sparsity pattern for which the degrees of
+ * freedom that represent the rows come from the first given DoFHandler,
+ * whereas the ones that correspond to columns come from the second
+ * DoFHandler.
*/
template <class DH, class SparsityPattern>
void
SparsityPattern &sparsity);
/**
- * Create the sparsity pattern for boundary matrices. See the
- * general documentation of this class for more information.
+ * Create the sparsity pattern for boundary matrices. See the general
+ * documentation of this class for more information.
*
* The actual type of the sparsity pattern may be SparsityPattern,
* CompressedSparsityPattern, BlockSparsityPattern,
- * BlockCompressedSparsityPattern,
- * BlockCompressedSetSparsityPattern, or any other class that
- * satisfies similar requirements. It is assumed that the size of
- * the sparsity pattern is already correct.
+ * BlockCompressedSparsityPattern, BlockCompressedSetSparsityPattern, or any
+ * other class that satisfies similar requirements. It is assumed that the
+ * size of the sparsity pattern is already correct.
*/
template <class DH, class SparsityPattern>
void
/**
* Write the sparsity structure of the matrix composed of the basis
- * functions on the boundary into the matrix structure. In contrast
- * to the previous function, only those parts of the boundary are
- * considered of which the boundary indicator is listed in the set
- * of numbers passed to this function.
- *
- * In fact, rather than a @p set of boundary indicators, a @p map
- * needs to be passed, since most of the functions handling with
- * boundary indicators take a mapping of boundary indicators and the
- * respective boundary functions. The boundary function, however, is
- * ignored in this function. If you have no functions at hand, but
- * only the boundary indicators, set the function pointers to null
- * pointers.
- *
- * For the type of the sparsity pattern, the same holds as said
- * above.
+ * functions on the boundary into the matrix structure. In contrast to the
+ * previous function, only those parts of the boundary are considered of
+ * which the boundary indicator is listed in the set of numbers passed to
+ * this function.
+ *
+ * In fact, rather than a @p set of boundary indicators, a @p map needs to
+ * be passed, since most of the functions handling with boundary indicators
+ * take a mapping of boundary indicators and the respective boundary
+ * functions. The boundary function, however, is ignored in this function.
+ * If you have no functions at hand, but only the boundary indicators, set
+ * the function pointers to null pointers.
+ *
+ * For the type of the sparsity pattern, the same holds as said above.
*/
template <class DH, class SparsityPattern>
void
SparsityPattern &sparsity);
/**
- * Generate sparsity pattern for fluxes, i.e. formulations of the
- * discrete problem with discontinuous elements which couple across
- * faces of cells. This is a replacement of the function @p
- * make_sparsity_pattern for discontinuous methods. Since the fluxes
- * include couplings between neighboring elements, the normal
- * couplings and these extra matrix entries are considered.
+ * Generate sparsity pattern for fluxes, i.e. formulations of the discrete
+ * problem with discontinuous elements which couple across faces of cells.
+ * This is a replacement of the function @p make_sparsity_pattern for
+ * discontinuous methods. Since the fluxes include couplings between
+ * neighboring elements, the normal couplings and these extra matrix entries
+ * are considered.
*/
template<class DH, class SparsityPattern>
void
SparsityPattern &sparsity_pattern);
/**
- * This function does the same as the other with the same name, but
- * it gets a ConstraintMatrix additionally. This is for the case
- * where you have fluxes but constraints as well.
+ * This function does the same as the other with the same name, but it gets
+ * a ConstraintMatrix additionally. This is for the case where you have
+ * fluxes but constraints as well.
*
* @ingroup constraints
*/
const types::subdomain_id subdomain_id = numbers::invalid_unsigned_int);
/**
- * This function does the same as the other with the same name, but
- * it gets two additional coefficient matrices. A matrix entry will
- * only be generated for two basis functions, if there is a non-zero
- * entry linking their associated components in the coefficient
- * matrix.
+ * This function does the same as the other with the same name, but it gets
+ * two additional coefficient matrices. A matrix entry will only be
+ * generated for two basis functions, if there is a non-zero entry linking
+ * their associated components in the coefficient matrix.
*
- * There is one matrix for couplings in a cell and one for the
- * couplings occuring in fluxes.
+ * There is one matrix for couplings in a cell and one for the couplings
+ * occuring in fluxes.
*
* @todo Not implemented for hp::DoFHandler.
*/
*/
/**
- * Compute the constraints resulting from the presence of hanging
- * nodes. Hanging nodes are best explained using a small picture:
+ * Compute the constraints resulting from the presence of hanging nodes.
+ * Hanging nodes are best explained using a small picture:
*
* @image html hanging_nodes.png
*
- * In order to make a finite element function globally continuous,
- * we have to make sure that the dark red nodes have values that are
- * compatible with the adjacent yellow nodes, so that the function
- * has no jump when coming from the small cells to the large one at
- * the top right. We therefore have to add conditions that constrain
- * those "hanging nodes".
- *
- * The object into which these are inserted is later used to
- * condense the global system matrix and right hand side, and to
- * extend the solution vectors from the true degrees of freedom also
- * to the constraint nodes. This function is explained in detail in
- * the @ref step_6 "step-6" tutorial program and is used in almost
- * all following programs as well.
- *
- * This function does not clear the constraint matrix object before
- * use, in order to allow adding constraints from different sources
- * to the same object. You therefore need to make sure it contains
- * only constraints you still want; otherwise call the
- * ConstraintMatrix::clear() function. Likewise, this function does
- * not close the object since you may want to enter other
- * constraints later on yourself.
- *
- * In the hp-case, i.e. when the argument is of type hp::DoFHandler,
- * we consider constraints due to different finite elements used on
- * two sides of a face between cells as hanging nodes as well. In
- * other words, for hp finite elements, this function computes all
- * constraints due to differing mesh sizes (h) or polynomial degrees
- * (p) between adjacent cells.
- *
- * The template argument (and by consequence the type of the first
- * argument to this function) can be either ::DoFHandler or
- * hp::DoFHandler.
+ * In order to make a finite element function globally continuous, we have
+ * to make sure that the dark red nodes have values that are compatible with
+ * the adjacent yellow nodes, so that the function has no jump when coming
+ * from the small cells to the large one at the top right. We therefore have
+ * to add conditions that constrain those "hanging nodes".
+ *
+ * The object into which these are inserted is later used to condense the
+ * global system matrix and right hand side, and to extend the solution
+ * vectors from the true degrees of freedom also to the constraint nodes.
+ * This function is explained in detail in the @ref step_6 "step-6" tutorial
+ * program and is used in almost all following programs as well.
+ *
+ * This function does not clear the constraint matrix object before use, in
+ * order to allow adding constraints from different sources to the same
+ * object. You therefore need to make sure it contains only constraints you
+ * still want; otherwise call the ConstraintMatrix::clear() function.
+ * Likewise, this function does not close the object since you may want to
+ * enter other constraints later on yourself.
+ *
+ * In the hp-case, i.e. when the argument is of type hp::DoFHandler, we
+ * consider constraints due to different finite elements used on two sides
+ * of a face between cells as hanging nodes as well. In other words, for hp
+ * finite elements, this function computes all constraints due to differing
+ * mesh sizes (h) or polynomial degrees (p) between adjacent cells.
+ *
+ * The template argument (and by consequence the type of the first argument
+ * to this function) can be either ::DoFHandler or hp::DoFHandler.
*
* @ingroup constraints
*/
* T}_0$. Using the same finite element on both, there are function spaces
* ${\cal V}_0$ and ${\cal V}_1$ associated with these meshes. Then every
* function $v_0 \in {\cal V}_0$ can of course also be represented exactly
- * in ${\cal V}_1$ since by construction ${\cal V}_0 \subset {\cal
- * V}_1$. However, not every function in ${\cal V}_1$ can be expressed as a
- * linear combination of the shape functions of ${\cal V}_0$. The functions
- * that can be represented lie in a homogenous subspace of ${\cal V}_1$
- * (namely, ${\cal V}_0$, of course) and this subspace can be represented by
- * a linear constraint of the form $CV=0$ where $V$ is the vector of nodal
- * values of functions $v\in {\cal V}_1$. In other words, every function
- * $v_h=\sum_j V_j \varphi_j^{(1)} \in {\cal V}_1$ that also satisfies
- * $v_h\in {\cal V}_0$ automatically satisfies $CV=0$. This function
- * computes the matrix $C$ in the form of a ConstraintMatrix object.
- *
- * The construction of these constraints is done as follows: for
- * each of the degrees of freedom (i.e. shape functions) on the
- * coarse grid, we compute its representation on the fine grid,
- * i.e. how the linear combination of shape functions on the fine
- * grid looks like that resembles the shape function on the coarse
- * grid. From this information, we can then compute the constraints
- * which have to hold if a solution of a linear equation on the fine
- * grid shall be representable on the coarse grid. The exact
- * algorithm how these constraints can be computed is rather
- * complicated and is best understood by reading the source code,
- * which contains many comments.
+ * in ${\cal V}_1$ since by construction ${\cal V}_0 \subset {\cal V}_1$.
+ * However, not every function in ${\cal V}_1$ can be expressed as a linear
+ * combination of the shape functions of ${\cal V}_0$. The functions that
+ * can be represented lie in a homogenous subspace of ${\cal V}_1$ (namely,
+ * ${\cal V}_0$, of course) and this subspace can be represented by a linear
+ * constraint of the form $CV=0$ where $V$ is the vector of nodal values of
+ * functions $v\in {\cal V}_1$. In other words, every function $v_h=\sum_j
+ * V_j \varphi_j^{(1)} \in {\cal V}_1$ that also satisfies $v_h\in {\cal
+ * V}_0$ automatically satisfies $CV=0$. This function computes the matrix
+ * $C$ in the form of a ConstraintMatrix object.
+ *
+ * The construction of these constraints is done as follows: for each of the
+ * degrees of freedom (i.e. shape functions) on the coarse grid, we compute
+ * its representation on the fine grid, i.e. how the linear combination of
+ * shape functions on the fine grid looks like that resembles the shape
+ * function on the coarse grid. From this information, we can then compute
+ * the constraints which have to hold if a solution of a linear equation on
+ * the fine grid shall be representable on the coarse grid. The exact
+ * algorithm how these constraints can be computed is rather complicated and
+ * is best understood by reading the source code, which contains many
+ * comments.
*
* The use of this function is as follows: it accepts as parameters two DoF
* Handlers, the first of which refers to the coarse grid and the second of
/**
- * This function generates a matrix such that when a vector of data
- * with as many elements as there are degrees of freedom of this
- * component on the coarse grid is multiplied to this matrix, we
- * obtain a vector with as many elements as there are global
- * degrees of freedom on the fine grid. All the elements of the
- * other vector components of the finite element fields on the fine grid
- * are not touched.
+ * This function generates a matrix such that when a vector of data with as
+ * many elements as there are degrees of freedom of this component on the
+ * coarse grid is multiplied to this matrix, we obtain a vector with as many
+ * elements as there are global degrees of freedom on the fine grid. All the
+ * elements of the other vector components of the finite element fields on
+ * the fine grid are not touched.
*
- * The output of this function is a compressed format that can be
- * given to the @p reinit functions of the SparsityPattern ad
- * SparseMatrix classes.
+ * The output of this function is a compressed format that can be given to
+ * the @p reinit functions of the SparsityPattern ad SparseMatrix classes.
*/
template <int dim, int spacedim>
void
*/
/**
- * Insert the (algebraic) constraints due to periodic boundary
- * conditions into a ConstraintMatrix @p constraint_matrix.
+ * Insert the (algebraic) constraints due to periodic boundary conditions
+ * into a ConstraintMatrix @p constraint_matrix.
*
- * Given a pair of not necessarily active boundary faces @p face_1 and
- * @p face_2, this functions constrains all DoFs associated with the boundary
+ * Given a pair of not necessarily active boundary faces @p face_1 and @p
+ * face_2, this functions constrains all DoFs associated with the boundary
* described by @p face_1 to the respective DoFs of the boundary described
* by @p face_2. More precisely:
*
- * If @p face_1 and @p face_2 are both active faces it adds the DoFs
- * of @p face_1 to the list of constrained DoFs in @p constraint_matrix
- * and adds entries to constrain them to the corresponding values of the
- * DoFs on @p face_2. This happens on a purely algebraic level, meaning,
- * the global DoF with (local face) index <tt>i</tt> on @p face_1 gets
- * constraint to the DoF with (local face) index <tt>i</tt> on @p face_2
- * (possibly corrected for orientation, see below).
- *
- * Otherwise, if @p face_1 and @p face_2 are not active faces, this
- * function loops recursively over the children of @p face_1 and @p face_2.
- * If only one of the two faces is active, then we recursively iterate
- * over the children of the non-active ones and make sure that the
- * solution function on the refined side equals that on the non-refined
- * face in much the same way as we enforce hanging node constraints
- * at places where differently refined cells come together. (However,
- * unlike hanging nodes, we do not enforce the requirement that there
- * be only a difference of one refinement level between the two sides
- * of the domain you would like to be periodic).
- *
- * This routine only constrains DoFs that are not already constrained.
- * If this routine encounters a DoF that already is constrained (for
- * instance by Dirichlet boundary conditions), the old setting of the
- * constraint (dofs the entry is constrained to, inhomogeneities) is
- * kept and nothing happens.
- *
- * The flags in the @p component_mask (see @ref GlossComponentMask)
- * denote which components of the finite element space shall be
- * constrained with periodic boundary conditions. If it is left as
- * specified by the default value all components are constrained. If it
- * is different from the default value, it is assumed that the number of
- * entries equals the number of components of the finite element. This
- * can be used to enforce periodicity in only one variable in a system of
- * equations.
+ * If @p face_1 and @p face_2 are both active faces it adds the DoFs of @p
+ * face_1 to the list of constrained DoFs in @p constraint_matrix and adds
+ * entries to constrain them to the corresponding values of the DoFs on @p
+ * face_2. This happens on a purely algebraic level, meaning, the global DoF
+ * with (local face) index <tt>i</tt> on @p face_1 gets constraint to the
+ * DoF with (local face) index <tt>i</tt> on @p face_2 (possibly corrected
+ * for orientation, see below).
+ *
+ * Otherwise, if @p face_1 and @p face_2 are not active faces, this function
+ * loops recursively over the children of @p face_1 and @p face_2. If only
+ * one of the two faces is active, then we recursively iterate over the
+ * children of the non-active ones and make sure that the solution function
+ * on the refined side equals that on the non-refined face in much the same
+ * way as we enforce hanging node constraints at places where differently
+ * refined cells come together. (However, unlike hanging nodes, we do not
+ * enforce the requirement that there be only a difference of one refinement
+ * level between the two sides of the domain you would like to be periodic).
+ *
+ * This routine only constrains DoFs that are not already constrained. If
+ * this routine encounters a DoF that already is constrained (for instance
+ * by Dirichlet boundary conditions), the old setting of the constraint
+ * (dofs the entry is constrained to, inhomogeneities) is kept and nothing
+ * happens.
+ *
+ * The flags in the @p component_mask (see @ref GlossComponentMask) denote
+ * which components of the finite element space shall be constrained with
+ * periodic boundary conditions. If it is left as specified by the default
+ * value all components are constrained. If it is different from the default
+ * value, it is assumed that the number of entries equals the number of
+ * components of the finite element. This can be used to enforce periodicity
+ * in only one variable in a system of equations.
*
* @p face_orientation, @p face_flip and @p face_rotation describe an
* orientation that should be applied to @p face_1 prior to matching and
* the given faces in their respective cells (which for boundary faces is
* always the default) but instead how you want to see periodicity to be
* enforced. For example, by using these flags, you can enforce a condition
- * of the kind $u(0,y)=u(1,1-y)$ (i.e., a Moebius band) or in 3d
- * a twisted torus. More precisely, these flags match local face DoF indices
- * in the following manner:
+ * of the kind $u(0,y)=u(1,1-y)$ (i.e., a Moebius band) or in 3d a twisted
+ * torus. More precisely, these flags match local face DoF indices in the
+ * following manner:
*
* In 2d: <tt>face_orientation</tt> must always be <tt>true</tt>,
* <tt>face_rotation</tt> is always <tt>false</tt>, and face_flip has the
* and any combination of that...
* @endcode
*
- * Optionally a matrix @p matrix along with an std::vector
- * @p first_vector_components can be specified that describes how DoFs on
- * @p face_1 should be modified prior to constraining to the DoFs of
- * @p face_2. Here, two declarations are possible:
- * If the std::vector @p first_vector_components is non empty the
- * matrix is interpreted as a @p dim $\times$ @p dim rotation matrix that is
- * applied to all vector valued blocks listed in @p first_vector_components
- * of the FESystem. If @p first_vector_components is empty the matrix is
- * interpreted as an interpolation matrix with size no_face_dofs $\times$
- * no_face_dofs.
+ * Optionally a matrix @p matrix along with an std::vector @p
+ * first_vector_components can be specified that describes how DoFs on @p
+ * face_1 should be modified prior to constraining to the DoFs of @p face_2.
+ * Here, two declarations are possible: If the std::vector @p
+ * first_vector_components is non empty the matrix is interpreted as a @p
+ * dim $\times$ @p dim rotation matrix that is applied to all vector valued
+ * blocks listed in @p first_vector_components of the FESystem. If @p
+ * first_vector_components is empty the matrix is interpreted as an
+ * interpolation matrix with size no_face_dofs $\times$ no_face_dofs.
*
- * Detailed information can be found in the
- * @see @ref GlossPeriodicConstraints "Glossary entry on periodic boundary conditions".
+ * Detailed information can be found in the @see @ref
+ * GlossPeriodicConstraints "Glossary entry on periodic boundary
+ * conditions".
*
* @todo: Reference to soon be written example step and glossary article.
*
/**
- * Insert the (algebraic) constraints due to periodic boundary
- * conditions into a ConstraintMatrix @p constraint_matrix.
+ * Insert the (algebraic) constraints due to periodic boundary conditions
+ * into a ConstraintMatrix @p constraint_matrix.
*
* This is the main high level interface for above low level variant of
- * make_periodicity_constraints(). It takes an std::vector @p
- * periodic_faces as argument and applies above
- * make_periodicity_constraints on each entry. The std::vector @p
- * periodic_faces can be created by GridTools::collect_periodic_faces.
+ * make_periodicity_constraints(). It takes an std::vector @p periodic_faces
+ * as argument and applies above make_periodicity_constraints on each entry.
+ * The std::vector @p periodic_faces can be created by
+ * GridTools::collect_periodic_faces.
*
* @note For DoFHandler objects that are built on a
* parallel::distributed::Triangulation object
* parallel::distributed::Triangulation::add_periodicity has to be called
* before.
*
- * @see @ref GlossPeriodicConstraints "Glossary entry on periodic boundary conditions"
- * for further information.
+ * @see @ref GlossPeriodicConstraints "Glossary entry on periodic boundary
+ * conditions" for further information.
*
* @author Daniel Arndt, Matthias Maier, 2013, 2014
*/
/**
- * Insert the (algebraic) constraints due to periodic boundary
- * conditions into a ConstraintMatrix @p constraint_matrix.
+ * Insert the (algebraic) constraints due to periodic boundary conditions
+ * into a ConstraintMatrix @p constraint_matrix.
*
* This function serves as a high level interface for the
* make_periodicity_constraints() function.
*
- * Define a 'first' boundary as all boundary faces having boundary_id
- * @p b_id1 and a 'second' boundary consisting of all faces belonging
- * to @p b_id2.
+ * Define a 'first' boundary as all boundary faces having boundary_id @p
+ * b_id1 and a 'second' boundary consisting of all faces belonging to @p
+ * b_id2.
*
- * This function tries to match all faces belonging to the first
- * boundary with faces belonging to the second boundary with the help
- * of orthogonal_equality().
+ * This function tries to match all faces belonging to the first boundary
+ * with faces belonging to the second boundary with the help of
+ * orthogonal_equality().
*
- * If this matching is successful it constrains all DoFs associated
- * with the 'first' boundary to the respective DoFs of the 'second'
- * boundary respecting the relative orientation of the two faces.
+ * If this matching is successful it constrains all DoFs associated with the
+ * 'first' boundary to the respective DoFs of the 'second' boundary
+ * respecting the relative orientation of the two faces.
*
- * This routine only constrains DoFs that are not already constrained.
- * If this routine encounters a DoF that already is constrained (for
- * instance by Dirichlet boundary conditions), the old setting of the
- * constraint (dofs the entry is constrained to, inhomogeneities) is
- * kept and nothing happens.
+ * This routine only constrains DoFs that are not already constrained. If
+ * this routine encounters a DoF that already is constrained (for instance
+ * by Dirichlet boundary conditions), the old setting of the constraint
+ * (dofs the entry is constrained to, inhomogeneities) is kept and nothing
+ * happens.
*
* The flags in the last parameter, @p component_mask (see @ref
- * GlossComponentMask) denote which components of the finite element
- * space shall be constrained with periodic boundary conditions. If it is
- * left as specified by the default value all components are constrained.
- * If it is different from the default value, it is assumed that the
- * number of entries equals the number of components in the boundary
- * functions and the finite element, and those components in the given
- * boundary function will be used for which the respective flag was set
- * in the component mask.
+ * GlossComponentMask) denote which components of the finite element space
+ * shall be constrained with periodic boundary conditions. If it is left as
+ * specified by the default value all components are constrained. If it is
+ * different from the default value, it is assumed that the number of
+ * entries equals the number of components in the boundary functions and the
+ * finite element, and those components in the given boundary function will
+ * be used for which the respective flag was set in the component mask.
*
* @note: This function is a convenience wrapper. It internally calls
* GridTools::collect_periodic_faces() with the supplied paramaters and
- * feeds the output to above make_periodicity_constraints() variant. If
- * you need more functionality use GridTools::collect_periodic_faces()
- * directly.
+ * feeds the output to above make_periodicity_constraints() variant. If you
+ * need more functionality use GridTools::collect_periodic_faces() directly.
*
- * @see @ref GlossPeriodicConstraints "Glossary entry on periodic boundary conditions"
- * for further information.
+ * @see @ref GlossPeriodicConstraints "Glossary entry on periodic boundary
+ * conditions" for further information.
*
* @author Matthias Maier, 2012
*/
/**
- * This compatibility version of make_periodicity_constraints only works
- * on grids with cells in @ref GlossFaceOrientation "standard orientation".
+ * This compatibility version of make_periodicity_constraints only works on
+ * grids with cells in @ref GlossFaceOrientation "standard orientation".
*
- * Instead of defining a 'first' and 'second' boundary with the help of
- * two boundary_indicators this function defines a 'left' boundary as all
- * faces with local face index <code>2*dimension</code> and boundary
- * indicator @p b_id and, similarly, a 'right' boundary consisting of all
- * face with local face index <code>2*dimension+1</code> and boundary
- * indicator @p b_id.
+ * Instead of defining a 'first' and 'second' boundary with the help of two
+ * boundary_indicators this function defines a 'left' boundary as all faces
+ * with local face index <code>2*dimension</code> and boundary indicator @p
+ * b_id and, similarly, a 'right' boundary consisting of all face with local
+ * face index <code>2*dimension+1</code> and boundary indicator @p b_id.
*
* @note This version of make_periodicity_constraints will not work on
- * meshes with cells not in @ref GlossFaceOrientation
- * "standard orientation".
+ * meshes with cells not in @ref GlossFaceOrientation "standard
+ * orientation".
*
* @note: This function is a convenience wrapper. It internally calls
* GridTools::collect_periodic_faces() with the supplied paramaters and
- * feeds the output to above make_periodicity_constraints() variant. If
- * you need more functionality use GridTools::collect_periodic_faces()
- * directly.
+ * feeds the output to above make_periodicity_constraints() variant. If you
+ * need more functionality use GridTools::collect_periodic_faces() directly.
*
- * @see @ref GlossPeriodicConstraints "Glossary entry on periodic boundary conditions"
- * for further information.
+ * @see @ref GlossPeriodicConstraints "Glossary entry on periodic boundary
+ * conditions" for further information.
*/
template<typename DH>
void
/**
- * The @p offset is a vector tangential to the faces that is added to
- * the location of vertices of the 'first' boundary when attempting to
- * match them to the corresponding vertices of the 'second' boundary via
- * orthogonal_equality (). This can be used to implement conditions such
- * as $u(0,y)=u(1,y+1)$.
+ * The @p offset is a vector tangential to the faces that is added to the
+ * location of vertices of the 'first' boundary when attempting to match
+ * them to the corresponding vertices of the 'second' boundary via
+ * orthogonal_equality (). This can be used to implement conditions such as
+ * $u(0,y)=u(1,y+1)$.
*
* @deprecated This function is deprecated. Use
* GridTools::collect_periodic_faces in conjunction with
/**
- * The @p offset is a vector tangential to the faces that is added to
- * the location of vertices of the 'first' boundary when attempting to
- * match them to the corresponding vertices of the 'second' boundary via
- * orthogonal_equality(). This can be used to implement conditions such
- * as $u(0,y)=u(1,y+1)$.
+ * The @p offset is a vector tangential to the faces that is added to the
+ * location of vertices of the 'first' boundary when attempting to match
+ * them to the corresponding vertices of the 'second' boundary via
+ * orthogonal_equality(). This can be used to implement conditions such as
+ * $u(0,y)=u(1,y+1)$.
*
* @note This version of make_periodicity_constraints will not work on
- * meshes with cells not in @ref GlossFaceOrientation
- * "standard orientation".
+ * meshes with cells not in @ref GlossFaceOrientation "standard
+ * orientation".
*
* @deprecated This function is deprecated. Use
* GridTools::collect_periodic_faces in conjunction with
/**
- * Take a vector of values which live on cells (e.g. an error per
- * cell) and distribute it to the dofs in such a way that a finite
- * element field results, which can then be further processed,
- * e.g. for output. You should note that the resulting field will
- * not be continuous at hanging nodes. This can, however, easily be
- * arranged by calling the appropriate @p distribute function of a
- * ConstraintMatrix object created for this DoFHandler object, after
- * the vector has been fully assembled.
+ * Take a vector of values which live on cells (e.g. an error per cell) and
+ * distribute it to the dofs in such a way that a finite element field
+ * results, which can then be further processed, e.g. for output. You should
+ * note that the resulting field will not be continuous at hanging nodes.
+ * This can, however, easily be arranged by calling the appropriate @p
+ * distribute function of a ConstraintMatrix object created for this
+ * DoFHandler object, after the vector has been fully assembled.
*
- * It is assumed that the number of elements in @p cell_data equals
- * the number of active cells and that the number of elements in @p
- * dof_data equals <tt>dof_handler.n_dofs()</tt>.
+ * It is assumed that the number of elements in @p cell_data equals the
+ * number of active cells and that the number of elements in @p dof_data
+ * equals <tt>dof_handler.n_dofs()</tt>.
*
- * Note that the input vector may be a vector of any data type as
- * long as it is convertible to @p double. The output vector, being
- * a data vector on a DoF handler, always consists of elements of
- * type @p double.
+ * Note that the input vector may be a vector of any data type as long as it
+ * is convertible to @p double. The output vector, being a data vector on a
+ * DoF handler, always consists of elements of type @p double.
*
- * In case the finite element used by this DoFHandler consists of
- * more than one component, you need to specify which component in
- * the output vector should be used to store the finite element
- * field in; the default is zero (no other value is allowed if the
- * finite element consists only of one component). All other
- * components of the vector remain untouched, i.e. their contents
- * are not changed.
+ * In case the finite element used by this DoFHandler consists of more than
+ * one component, you need to specify which component in the output vector
+ * should be used to store the finite element field in; the default is zero
+ * (no other value is allowed if the finite element consists only of one
+ * component). All other components of the vector remain untouched, i.e.
+ * their contents are not changed.
*
- * This function cannot be used if the finite element in use has
- * shape functions that are non-zero in more than one vector
- * component (in deal.II speak: they are non-primitive).
+ * This function cannot be used if the finite element in use has shape
+ * functions that are non-zero in more than one vector component (in deal.II
+ * speak: they are non-primitive).
*/
template <class DH, typename Number>
void
*/
/**
- * @name Identifying subsets of degrees of freedom with particular properties
+ * @name Identifying subsets of degrees of freedom with particular
+ * properties
* @{
*/
/**
- * Extract the indices of the degrees of freedom belonging to
- * certain vector components of a vector-valued finite element. The
- * @p component_mask defines which components or blocks of an
- * FESystem are to be extracted from the DoFHandler @p dof. The
- * entries in the output array @p selected_dofs corresponding to
- * degrees of freedom belonging to these components are then flagged
- * @p true, while all others are set to @p false.
+ * Extract the indices of the degrees of freedom belonging to certain vector
+ * components of a vector-valued finite element. The @p component_mask
+ * defines which components or blocks of an FESystem are to be extracted
+ * from the DoFHandler @p dof. The entries in the output array @p
+ * selected_dofs corresponding to degrees of freedom belonging to these
+ * components are then flagged @p true, while all others are set to @p
+ * false.
*
- * The size of @p component_mask must be compatible with the number
- * of components in the FiniteElement used by @p dof. The size of @p
- * selected_dofs must equal DoFHandler::n_dofs(). Previous contents
- * of this array are overwritten.
+ * The size of @p component_mask must be compatible with the number of
+ * components in the FiniteElement used by @p dof. The size of @p
+ * selected_dofs must equal DoFHandler::n_dofs(). Previous contents of this
+ * array are overwritten.
*
- * If the finite element under consideration is not primitive, i.e.,
- * some or all of its shape functions are non-zero in more than one
- * vector component (which holds, for example, for FE_Nedelec or
- * FE_RaviartThomas elements), then shape functions cannot be
- * associated with a single vector component. In this case, if
- * <em>one</em> shape vector component of this element is flagged in
- * @p component_mask (see @ref GlossComponentMask), then this is
- * equivalent to selecting <em>all</em> vector components
- * corresponding to this non-primitive base element.
+ * If the finite element under consideration is not primitive, i.e., some or
+ * all of its shape functions are non-zero in more than one vector component
+ * (which holds, for example, for FE_Nedelec or FE_RaviartThomas elements),
+ * then shape functions cannot be associated with a single vector component.
+ * In this case, if <em>one</em> shape vector component of this element is
+ * flagged in @p component_mask (see @ref GlossComponentMask), then this is
+ * equivalent to selecting <em>all</em> vector components corresponding to
+ * this non-primitive base element.
*
* @note If the @p blocks argument is true,
*/
std::vector<bool> &selected_dofs);
/**
- * This function is the equivalent to the DoFTools::extract_dofs() functions above
- * except that the selection of which degrees of freedom to extract is not done
- * based on components (see @ref GlossComponent) but instead based on whether they
- * are part of a particular block (see @ref GlossBlock). Consequently, the second
- * argument is not a ComponentMask but a BlockMask object.
+ * This function is the equivalent to the DoFTools::extract_dofs() functions
+ * above except that the selection of which degrees of freedom to extract is
+ * not done based on components (see @ref GlossComponent) but instead based
+ * on whether they are part of a particular block (see @ref GlossBlock).
+ * Consequently, the second argument is not a ComponentMask but a BlockMask
+ * object.
*
- * @param dof_handler The DoFHandler object from which to extract degrees of freedom
- * @param block_mask The block mask that describes which blocks to consider (see
- * @ref GlossBlockMask)
- * @param selected_dofs A vector of length DoFHandler::n_dofs() in which those
- * entries are true that correspond to the selected blocks.
+ * @param dof_handler The DoFHandler object from which to extract degrees of
+ * freedom
+ * @param block_mask The block mask that describes which blocks to consider
+ * (see @ref GlossBlockMask)
+ * @param selected_dofs A vector of length DoFHandler::n_dofs() in which
+ * those entries are true that correspond to the selected blocks.
*/
template <int dim, int spacedim>
void
std::vector<bool> &selected_dofs);
/**
- * Do the same thing as the corresponding extract_dofs() function
- * for one level of a multi-grid DoF numbering.
+ * Do the same thing as the corresponding extract_dofs() function for one
+ * level of a multi-grid DoF numbering.
*/
template <class DH>
void
std::vector<bool> &selected_dofs);
/**
- * Do the same thing as the corresponding extract_dofs() function
- * for one level of a multi-grid DoF numbering.
+ * Do the same thing as the corresponding extract_dofs() function for one
+ * level of a multi-grid DoF numbering.
*/
template <class DH>
void
std::vector<bool> &selected_dofs);
/**
- * Extract all degrees of freedom which are at the boundary and
- * belong to specified components of the solution. The function
- * returns its results in the last non-default-valued parameter
- * which contains @p true if a degree of freedom is at the boundary
- * and belongs to one of the selected components, and @p false
- * otherwise. The function is used in step-15.
- *
- * By specifying the @p boundary_indicator variable, you can select
- * which boundary indicators the faces have to have on which the
- * degrees of freedom are located that shall be extracted. If it is
- * an empty list, then all boundary indicators are accepted.
- *
- * The size of @p component_mask (see @ref GlossComponentMask) shall
- * equal the number of components in the finite element used by @p
- * dof. The size of @p selected_dofs shall equal
- * <tt>dof_handler.n_dofs()</tt>. Previous contents of this array or
- * overwritten.
- *
- * Using the usual convention, if a shape function is non-zero in
- * more than one component (i.e. it is non-primitive), then the
- * element in the component mask is used that corresponds to the
- * first non-zero components. Elements in the mask corresponding to
- * later components are ignored.
- *
- * @note This function will not work for DoFHandler objects that are
- * built on a parallel::distributed::Triangulation object. The
- * reasons is that the output argument @p selected_dofs has to have
- * a length equal to <i>all</i> global degrees of freedom.
- * Consequently, this does not scale to very large problems. If you
- * need the functionality of this function for parallel
- * triangulations, then you need to use the other
+ * Extract all degrees of freedom which are at the boundary and belong to
+ * specified components of the solution. The function returns its results in
+ * the last non-default-valued parameter which contains @p true if a degree
+ * of freedom is at the boundary and belongs to one of the selected
+ * components, and @p false otherwise. The function is used in step-15.
+ *
+ * By specifying the @p boundary_indicator variable, you can select which
+ * boundary indicators the faces have to have on which the degrees of
+ * freedom are located that shall be extracted. If it is an empty list, then
+ * all boundary indicators are accepted.
+ *
+ * The size of @p component_mask (see @ref GlossComponentMask) shall equal
+ * the number of components in the finite element used by @p dof. The size
+ * of @p selected_dofs shall equal <tt>dof_handler.n_dofs()</tt>. Previous
+ * contents of this array or overwritten.
+ *
+ * Using the usual convention, if a shape function is non-zero in more than
+ * one component (i.e. it is non-primitive), then the element in the
+ * component mask is used that corresponds to the first non-zero components.
+ * Elements in the mask corresponding to later components are ignored.
+ *
+ * @note This function will not work for DoFHandler objects that are built
+ * on a parallel::distributed::Triangulation object. The reasons is that the
+ * output argument @p selected_dofs has to have a length equal to <i>all</i>
+ * global degrees of freedom. Consequently, this does not scale to very
+ * large problems. If you need the functionality of this function for
+ * parallel triangulations, then you need to use the other
* DoFTools::extract_boundary_dofs function.
*
* @param dof_handler The object that describes which degrees of freedom
- * live on which cell
- * @param component_mask A mask denoting the vector components of the
- * finite element that should be considered (see also
- * @ref GlossComponentMask).
- * @param selected_dofs The IndexSet object that is returned and that
- * will contain the indices of degrees of freedom that are
- * located on the boundary (and correspond to the selected
- * vector components and boundary indicators, depending on
- * the values of the @p component_mask and @p boundary_indicators
- * arguments).
- * @param boundary_indicators If empty, this function extracts the
- * indices of the degrees of freedom for all parts of the boundary.
- * If it is a non-empty list, then the function only considers
- * boundary faces with the boundary indicators listed in this
- * argument.
+ * live on which cell
+ * @param component_mask A mask denoting the vector components of the finite
+ * element that should be considered (see also @ref GlossComponentMask).
+ * @param selected_dofs The IndexSet object that is returned and that will
+ * contain the indices of degrees of freedom that are located on the
+ * boundary (and correspond to the selected vector components and boundary
+ * indicators, depending on the values of the @p component_mask and @p
+ * boundary_indicators arguments).
+ * @param boundary_indicators If empty, this function extracts the indices
+ * of the degrees of freedom for all parts of the boundary. If it is a non-
+ * empty list, then the function only considers boundary faces with the
+ * boundary indicators listed in this argument.
*
* @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
*/
const std::set<types::boundary_id> &boundary_indicators = std::set<types::boundary_id>());
/**
- * This function does the same as the previous one but it
- * returns its result as an IndexSet rather than a std::vector@<bool@>.
- * Thus, it can also be called for DoFHandler objects that are
- * defined on parallel::distributed::Triangulation objects.
+ * This function does the same as the previous one but it returns its result
+ * as an IndexSet rather than a std::vector@<bool@>. Thus, it can also be
+ * called for DoFHandler objects that are defined on
+ * parallel::distributed::Triangulation objects.
*
* @note If the DoFHandler object is indeed defined on a
- * parallel::distributed::Triangulation, then the @p selected_dofs
- * index set will contain only those degrees of freedom on the
- * boundary that belong to the locally relevant set (see
- * @ref GlossLocallyRelevantDof "locally relevant DoFs").
+ * parallel::distributed::Triangulation, then the @p selected_dofs index set
+ * will contain only those degrees of freedom on the boundary that belong to
+ * the locally relevant set (see @ref GlossLocallyRelevantDof "locally
+ * relevant DoFs").
*
* @param dof_handler The object that describes which degrees of freedom
- * live on which cell
- * @param component_mask A mask denoting the vector components of the
- * finite element that should be considered (see also
- * @ref GlossComponentMask).
- * @param selected_dofs The IndexSet object that is returned and that
- * will contain the indices of degrees of freedom that are
- * located on the boundary (and correspond to the selected
- * vector components and boundary indicators, depending on
- * the values of the @p component_mask and @p boundary_indicators
- * arguments).
- * @param boundary_indicators If empty, this function extracts the
- * indices of the degrees of freedom for all parts of the boundary.
- * If it is a non-empty list, then the function only considers
- * boundary faces with the boundary indicators listed in this
- * argument.
+ * live on which cell
+ * @param component_mask A mask denoting the vector components of the finite
+ * element that should be considered (see also @ref GlossComponentMask).
+ * @param selected_dofs The IndexSet object that is returned and that will
+ * contain the indices of degrees of freedom that are located on the
+ * boundary (and correspond to the selected vector components and boundary
+ * indicators, depending on the values of the @p component_mask and @p
+ * boundary_indicators arguments).
+ * @param boundary_indicators If empty, this function extracts the indices
+ * of the degrees of freedom for all parts of the boundary. If it is a non-
+ * empty list, then the function only considers boundary faces with the
+ * boundary indicators listed in this argument.
*
* @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
*/
const std::set<types::boundary_id> &boundary_indicators = std::set<types::boundary_id>());
/**
- * This function is similar to the extract_boundary_dofs() function
- * but it extracts those degrees of freedom whose shape functions
- * are nonzero on at least part of the selected boundary. For
- * continuous elements, this is exactly the set of shape functions
- * whose degrees of freedom are defined on boundary faces. On the
- * other hand, if the finite element in used is a discontinuous
- * element, all degrees of freedom are defined in the inside of
- * cells and consequently none would be boundary degrees of
- * freedom. Several of those would have shape functions that are
- * nonzero on the boundary, however. This function therefore
- * extracts all those for which the
- * FiniteElement::has_support_on_face function says that it is
- * nonzero on any face on one of the selected boundary parts.
+ * This function is similar to the extract_boundary_dofs() function but it
+ * extracts those degrees of freedom whose shape functions are nonzero on at
+ * least part of the selected boundary. For continuous elements, this is
+ * exactly the set of shape functions whose degrees of freedom are defined
+ * on boundary faces. On the other hand, if the finite element in used is a
+ * discontinuous element, all degrees of freedom are defined in the inside
+ * of cells and consequently none would be boundary degrees of freedom.
+ * Several of those would have shape functions that are nonzero on the
+ * boundary, however. This function therefore extracts all those for which
+ * the FiniteElement::has_support_on_face function says that it is nonzero
+ * on any face on one of the selected boundary parts.
*
* @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
*/
const std::set<types::boundary_id> &boundary_indicators = std::set<types::boundary_id>());
/**
- * Extract a vector that represents the constant modes of the
- * DoFHandler for the components chosen by <tt>component_mask</tt>
- * (see @ref GlossComponentMask). The constant modes on a
- * discretization are the null space of a Laplace operator on the
- * selected components with Neumann boundary conditions applied. The
- * null space is a necessary ingredient for obtaining a good AMG
- * preconditioner when using the class
- * TrilinosWrappers::PreconditionAMG. Since the ML AMG package only
- * works on algebraic properties of the respective matrix, it has no
- * chance to detect whether the matrix comes from a scalar or a
- * vector valued problem. However, a near null space supplies
- * exactly the needed information about the components placement of vector
- * components within the matrix. The null space (or rather, the constant
- * modes) is provided by the finite element underlying the given DoFHandler
- * and for most elements, the null space will consist of as many vectors as
- * there are true arguments in <tt>component_mask</tt> (see @ref
- * GlossComponentMask), each of which will be one in one vector component
- * and zero in all others. However, the representation of the constant
- * function for e.g. FE_DGP is different (the first component on each
- * element one, all other components zero), and some scalar elements may
- * even have two constant modes (FE_Q_DG0). Therefore, we store this object
- * in a vector of vectors, where the outer vector contains the collection of
- * the actual constant modes on the DoFHandler. Each inner vector has as
- * many components as there are (locally owned) degrees of freedom in the
- * selected components. Note that any matrix associated with this null space
- * must have been constructed using the same <tt>component_mask</tt>
- * argument, since the numbering of DoFs is done relative to the selected
- * dofs, not to all dofs.
- *
- * The main reason for this program is the use of the null space
- * with the AMG preconditioner.
+ * Extract a vector that represents the constant modes of the DoFHandler for
+ * the components chosen by <tt>component_mask</tt> (see @ref
+ * GlossComponentMask). The constant modes on a discretization are the null
+ * space of a Laplace operator on the selected components with Neumann
+ * boundary conditions applied. The null space is a necessary ingredient for
+ * obtaining a good AMG preconditioner when using the class
+ * TrilinosWrappers::PreconditionAMG. Since the ML AMG package only works
+ * on algebraic properties of the respective matrix, it has no chance to
+ * detect whether the matrix comes from a scalar or a vector valued problem.
+ * However, a near null space supplies exactly the needed information about
+ * the components placement of vector components within the matrix. The null
+ * space (or rather, the constant modes) is provided by the finite element
+ * underlying the given DoFHandler and for most elements, the null space
+ * will consist of as many vectors as there are true arguments in
+ * <tt>component_mask</tt> (see @ref GlossComponentMask), each of which will
+ * be one in one vector component and zero in all others. However, the
+ * representation of the constant function for e.g. FE_DGP is different (the
+ * first component on each element one, all other components zero), and some
+ * scalar elements may even have two constant modes (FE_Q_DG0). Therefore,
+ * we store this object in a vector of vectors, where the outer vector
+ * contains the collection of the actual constant modes on the DoFHandler.
+ * Each inner vector has as many components as there are (locally owned)
+ * degrees of freedom in the selected components. Note that any matrix
+ * associated with this null space must have been constructed using the same
+ * <tt>component_mask</tt> argument, since the numbering of DoFs is done
+ * relative to the selected dofs, not to all dofs.
+ *
+ * The main reason for this program is the use of the null space with the
+ * AMG preconditioner.
*/
template <class DH>
void
*/
/**
- * Select all dofs that will be constrained by interface
- * constraints, i.e. all hanging nodes.
+ * Select all dofs that will be constrained by interface constraints, i.e.
+ * all hanging nodes.
*
- * The size of @p selected_dofs shall equal
- * <tt>dof_handler.n_dofs()</tt>. Previous contents of this array or
- * overwritten.
+ * The size of @p selected_dofs shall equal <tt>dof_handler.n_dofs()</tt>.
+ * Previous contents of this array or overwritten.
*/
template <int dim, int spacedim>
void
* @{
*/
/**
- * Flag all those degrees of freedom which are on cells with the
- * given subdomain id. Note that DoFs on faces can belong to cells
- * with differing subdomain ids, so the sets of flagged degrees of
- * freedom are not mutually exclusive for different subdomain ids.
+ * Flag all those degrees of freedom which are on cells with the given
+ * subdomain id. Note that DoFs on faces can belong to cells with differing
+ * subdomain ids, so the sets of flagged degrees of freedom are not mutually
+ * exclusive for different subdomain ids.
*
* If you want to get a unique association of degree of freedom with
* subdomains, use the @p get_subdomain_association function.
/**
- * Extract the set of global DoF indices that are owned by the
- * current processor. For regular DoFHandler objects, this set is
- * the complete set with all DoF indices. In either case, it equals
- * what DoFHandler::locally_owned_dofs() returns.
+ * Extract the set of global DoF indices that are owned by the current
+ * processor. For regular DoFHandler objects, this set is the complete set
+ * with all DoF indices. In either case, it equals what
+ * DoFHandler::locally_owned_dofs() returns.
*/
template <class DH>
void
/**
- * Extract the set of global DoF indices that are active on the
- * current DoFHandler. For regular DoFHandlers, these are all DoF
- * indices, but for DoFHandler objects built on
- * parallel::distributed::Triangulation this set is a superset of
- * DoFHandler::locally_owned_dofs() and contains all DoF indices
- * that live on all locally owned cells (including on the interface
- * to ghost cells). However, it does not contain the DoF indices
- * that are exclusively defined on ghost or artificial cells (see
- * @ref GlossArtificialCell "the glossary").
+ * Extract the set of global DoF indices that are active on the current
+ * DoFHandler. For regular DoFHandlers, these are all DoF indices, but for
+ * DoFHandler objects built on parallel::distributed::Triangulation this set
+ * is a superset of DoFHandler::locally_owned_dofs() and contains all DoF
+ * indices that live on all locally owned cells (including on the interface
+ * to ghost cells). However, it does not contain the DoF indices that are
+ * exclusively defined on ghost or artificial cells (see @ref
+ * GlossArtificialCell "the glossary").
*
- * The degrees of freedom identified by this function equal those
- * obtained from the dof_indices_with_subdomain_association()
- * function when called with the locally owned subdomain id.
+ * The degrees of freedom identified by this function equal those obtained
+ * from the dof_indices_with_subdomain_association() function when called
+ * with the locally owned subdomain id.
*/
template <class DH>
void
IndexSet &dof_set);
/**
- * Extract the set of global DoF indices that are active on the
- * current DoFHandler. For regular DoFHandlers, these are all DoF
- * indices, but for DoFHandler objects built on
- * parallel::distributed::Triangulation this set is the union of
- * DoFHandler::locally_owned_dofs() and the DoF indices on all ghost
- * cells. In essence, it is the DoF indices on all cells that are
+ * Extract the set of global DoF indices that are active on the current
+ * DoFHandler. For regular DoFHandlers, these are all DoF indices, but for
+ * DoFHandler objects built on parallel::distributed::Triangulation this set
+ * is the union of DoFHandler::locally_owned_dofs() and the DoF indices on
+ * all ghost cells. In essence, it is the DoF indices on all cells that are
* not artificial (see @ref GlossArtificialCell "the glossary").
*/
template <class DH>
IndexSet &dof_set);
/**
- * For each DoF, return in the output array to which subdomain (as
- * given by the <tt>cell->subdomain_id()</tt> function) it
- * belongs. The output array is supposed to have the right size
- * already when calling this function.
- *
- * Note that degrees of freedom associated with faces, edges, and
- * vertices may be associated with multiple subdomains if they are
- * sitting on partition boundaries. In these cases, we put them into
- * one of the associated partitions in an undefined way. This may
- * sometimes lead to different numbers of degrees of freedom in
- * partitions, even if the number of cells is perfectly
- * equidistributed. While this is regrettable, it is not a problem
- * in practice since the number of degrees of freedom on partition
- * boundaries is asymptotically vanishing as we refine the mesh as
+ * For each DoF, return in the output array to which subdomain (as given by
+ * the <tt>cell->subdomain_id()</tt> function) it belongs. The output array
+ * is supposed to have the right size already when calling this function.
+ *
+ * Note that degrees of freedom associated with faces, edges, and vertices
+ * may be associated with multiple subdomains if they are sitting on
+ * partition boundaries. In these cases, we put them into one of the
+ * associated partitions in an undefined way. This may sometimes lead to
+ * different numbers of degrees of freedom in partitions, even if the number
+ * of cells is perfectly equidistributed. While this is regrettable, it is
+ * not a problem in practice since the number of degrees of freedom on
+ * partition boundaries is asymptotically vanishing as we refine the mesh as
* long as the number of partitions is kept constant.
*
- * This function returns the association of each DoF with one
- * subdomain. If you are looking for the association of each @em
- * cell with a subdomain, either query the
- * <tt>cell->subdomain_id()</tt> function, or use the
+ * This function returns the association of each DoF with one subdomain. If
+ * you are looking for the association of each @em cell with a subdomain,
+ * either query the <tt>cell->subdomain_id()</tt> function, or use the
* <tt>GridTools::get_subdomain_association</tt> function.
*
- * Note that this function is of questionable use for DoFHandler
- * objects built on parallel::distributed::Triangulation since in
- * that case ownership of individual degrees of freedom by MPI
- * processes is controlled by the DoF handler object, not based on
- * some geometric algorithm in conjunction with subdomain id. In
- * particular, the degrees of freedom identified by the functions in
- * this namespace as associated with a subdomain are not the same
- * the DoFHandler class identifies as those it owns.
+ * Note that this function is of questionable use for DoFHandler objects
+ * built on parallel::distributed::Triangulation since in that case
+ * ownership of individual degrees of freedom by MPI processes is controlled
+ * by the DoF handler object, not based on some geometric algorithm in
+ * conjunction with subdomain id. In particular, the degrees of freedom
+ * identified by the functions in this namespace as associated with a
+ * subdomain are not the same the DoFHandler class identifies as those it
+ * owns.
*/
template <class DH>
void
std::vector<types::subdomain_id> &subdomain);
/**
- * Count how many degrees of freedom are uniquely associated with
- * the given @p subdomain index.
+ * Count how many degrees of freedom are uniquely associated with the given
+ * @p subdomain index.
*
- * Note that there may be rare cases where cells with the given @p
- * subdomain index exist, but none of its degrees of freedom are
- * actually associated with it. In that case, the returned value
- * will be zero.
+ * Note that there may be rare cases where cells with the given @p subdomain
+ * index exist, but none of its degrees of freedom are actually associated
+ * with it. In that case, the returned value will be zero.
*
- * This function will generate an exception if there are no cells
- * with the given @p subdomain index.
+ * This function will generate an exception if there are no cells with the
+ * given @p subdomain index.
*
- * This function returns the number of DoFs associated with one
- * subdomain. If you are looking for the association of @em cells
- * with this subdomain, use the
- * <tt>GridTools::count_cells_with_subdomain_association</tt>
+ * This function returns the number of DoFs associated with one subdomain.
+ * If you are looking for the association of @em cells with this subdomain,
+ * use the <tt>GridTools::count_cells_with_subdomain_association</tt>
* function.
*
- * Note that this function is of questionable use for DoFHandler
- * objects built on parallel::distributed::Triangulation since in
- * that case ownership of individual degrees of freedom by MPI
- * processes is controlled by the DoF handler object, not based on
- * some geometric algorithm in conjunction with subdomain id. In
- * particular, the degrees of freedom identified by the functions in
- * this namespace as associated with a subdomain are not the same
- * the DoFHandler class identifies as those it owns.
+ * Note that this function is of questionable use for DoFHandler objects
+ * built on parallel::distributed::Triangulation since in that case
+ * ownership of individual degrees of freedom by MPI processes is controlled
+ * by the DoF handler object, not based on some geometric algorithm in
+ * conjunction with subdomain id. In particular, the degrees of freedom
+ * identified by the functions in this namespace as associated with a
+ * subdomain are not the same the DoFHandler class identifies as those it
+ * owns.
*/
template <class DH>
unsigned int
const types::subdomain_id subdomain);
/**
- * Count how many degrees of freedom are uniquely associated with
- * the given @p subdomain index.
+ * Count how many degrees of freedom are uniquely associated with the given
+ * @p subdomain index.
*
- * This function does what the previous one does except that it
- * splits the result among the vector components of the finite
- * element in use by the DoFHandler object. The last argument (which
- * must have a length equal to the number of vector components) will
- * therefore store how many degrees of freedom of each vector
- * component are associated with the given subdomain.
+ * This function does what the previous one does except that it splits the
+ * result among the vector components of the finite element in use by the
+ * DoFHandler object. The last argument (which must have a length equal to
+ * the number of vector components) will therefore store how many degrees of
+ * freedom of each vector component are associated with the given subdomain.
*
- * Note that this function is of questionable use for DoFHandler
- * objects built on parallel::distributed::Triangulation since in
- * that case ownership of individual degrees of freedom by MPI
- * processes is controlled by the DoF handler object, not based on
- * some geometric algorithm in conjunction with subdomain id. In
- * particular, the degrees of freedom identified by the functions in
- * this namespace as associated with a subdomain are not the same
- * the DoFHandler class identifies as those it owns.
+ * Note that this function is of questionable use for DoFHandler objects
+ * built on parallel::distributed::Triangulation since in that case
+ * ownership of individual degrees of freedom by MPI processes is controlled
+ * by the DoF handler object, not based on some geometric algorithm in
+ * conjunction with subdomain id. In particular, the degrees of freedom
+ * identified by the functions in this namespace as associated with a
+ * subdomain are not the same the DoFHandler class identifies as those it
+ * owns.
*/
template <class DH>
void
std::vector<unsigned int> &n_dofs_on_subdomain);
/**
- * Return a set of indices that denotes the degrees of freedom that
- * live on the given subdomain, i.e. that are on cells owned by the
- * current processor. Note that this includes the ones that this
- * subdomain "owns" (i.e. the ones for which
- * get_subdomain_association() returns a value equal to the
- * subdomain given here and that are selected by the
- * extract_locally_owned() function) but also all of those that sit
- * on the boundary between the given subdomain and other
- * subdomain. In essence, degrees of freedom that sit on boundaries
- * between subdomain will be in the index sets returned by this
- * function for more than one subdomain.
- *
- * Note that this function is of questionable use for DoFHandler
- * objects built on parallel::distributed::Triangulation since in
- * that case ownership of individual degrees of freedom by MPI
- * processes is controlled by the DoF handler object, not based on
- * some geometric algorithm in conjunction with subdomain id. In
- * particular, the degrees of freedom identified by the functions in
- * this namespace as associated with a subdomain are not the same
- * the DoFHandler class identifies as those it owns.
+ * Return a set of indices that denotes the degrees of freedom that live on
+ * the given subdomain, i.e. that are on cells owned by the current
+ * processor. Note that this includes the ones that this subdomain "owns"
+ * (i.e. the ones for which get_subdomain_association() returns a value
+ * equal to the subdomain given here and that are selected by the
+ * extract_locally_owned() function) but also all of those that sit on the
+ * boundary between the given subdomain and other subdomain. In essence,
+ * degrees of freedom that sit on boundaries between subdomain will be in
+ * the index sets returned by this function for more than one subdomain.
+ *
+ * Note that this function is of questionable use for DoFHandler objects
+ * built on parallel::distributed::Triangulation since in that case
+ * ownership of individual degrees of freedom by MPI processes is controlled
+ * by the DoF handler object, not based on some geometric algorithm in
+ * conjunction with subdomain id. In particular, the degrees of freedom
+ * identified by the functions in this namespace as associated with a
+ * subdomain are not the same the DoFHandler class identifies as those it
+ * owns.
*/
template <class DH>
IndexSet
/**
* @name DoF indices on patches of cells
*
- * Create structures containing a large set of degrees of freedom
- * for small patches of cells. The resulting objects can be used in
- * RelaxationBlockSOR and related classes to implement Schwarz
- * preconditioners and smoothers, where the subdomains consist of
- * small numbers of cells only.
+ * Create structures containing a large set of degrees of freedom for small
+ * patches of cells. The resulting objects can be used in RelaxationBlockSOR
+ * and related classes to implement Schwarz preconditioners and smoothers,
+ * where the subdomains consist of small numbers of cells only.
*/
//@{
/**
- * Create an incidence matrix that for every cell on a given level
- * of a multilevel DoFHandler flags which degrees of freedom are
- * associated with the corresponding cell. This data structure is a
- * matrix with as many rows as there are cells on a given level, as
- * many columns as there are degrees of freedom on this level, and
- * entries that are either true or false. This data structure is
- * conveniently represented by a SparsityPattern object.
+ * Create an incidence matrix that for every cell on a given level of a
+ * multilevel DoFHandler flags which degrees of freedom are associated with
+ * the corresponding cell. This data structure is a matrix with as many rows
+ * as there are cells on a given level, as many columns as there are degrees
+ * of freedom on this level, and entries that are either true or false. This
+ * data structure is conveniently represented by a SparsityPattern object.
*
- * @note The ordering of rows (cells) follows the ordering of the
- * standard cell iterators.
+ * @note The ordering of rows (cells) follows the ordering of the standard
+ * cell iterators.
*/
template <class DH, class Sparsity>
void make_cell_patches(Sparsity &block_list,
types::global_dof_index offset = 0);
/**
- * Create an incidence matrix that for every vertex on a given level
- * of a multilevel DoFHandler flags which degrees of freedom are
- * associated with the adjacent cells. This data structure is a matrix
- * with as many rows as there are vertices on a given level, as many
- * columns as there are degrees of freedom on this level, and entries
- * that are either true or false. This data structure is
- * conveniently represented by a SparsityPattern object. The
- * sparsity pattern may be empty when entering this function and
- * will be reinitialized to the correct size.
+ * Create an incidence matrix that for every vertex on a given level of a
+ * multilevel DoFHandler flags which degrees of freedom are associated with
+ * the adjacent cells. This data structure is a matrix with as many rows as
+ * there are vertices on a given level, as many columns as there are degrees
+ * of freedom on this level, and entries that are either true or false. This
+ * data structure is conveniently represented by a SparsityPattern object.
+ * The sparsity pattern may be empty when entering this function and will be
+ * reinitialized to the correct size.
*
- * The function has some boolean arguments (listed below)
- * controlling details of the generated patches. The default
- * settings are those for Arnold-Falk-Winther type smoothers for
- * divergence and curl conforming finite elements with essential
- * boundary conditions. Other applications are possible, in
- * particular changing <tt>boundary_patches</tt> for non-essential
- * boundary conditions.
+ * The function has some boolean arguments (listed below) controlling
+ * details of the generated patches. The default settings are those for
+ * Arnold-Falk-Winther type smoothers for divergence and curl conforming
+ * finite elements with essential boundary conditions. Other applications
+ * are possible, in particular changing <tt>boundary_patches</tt> for non-
+ * essential boundary conditions.
*
- * @arg <tt>block_list</tt>: the SparsityPattern into which the
- * patches will be stored.
+ * @arg <tt>block_list</tt>: the SparsityPattern into which the patches will
+ * be stored.
*
- * @arg <tt>dof_handler</tt>: The multilevel dof handler providing
- * the topology operated on.
+ * @arg <tt>dof_handler</tt>: The multilevel dof handler providing the
+ * topology operated on.
*
- * @arg <tt>interior_dofs_only</tt>: for each patch of cells around
- * a vertex, collect only the interior degrees of freedom of the
- * patch and disregard those on the boundary of the patch. This is
- * for instance the setting for smoothers of Arnold-Falk-Winther
- * type.
+ * @arg <tt>interior_dofs_only</tt>: for each patch of cells around a
+ * vertex, collect only the interior degrees of freedom of the patch and
+ * disregard those on the boundary of the patch. This is for instance the
+ * setting for smoothers of Arnold-Falk-Winther type.
*
- * @arg <tt>boundary_patches</tt>: include patches around vertices
- * at the boundary of the domain. If not, only patches around
- * interior vertices will be generated.
+ * @arg <tt>boundary_patches</tt>: include patches around vertices at the
+ * boundary of the domain. If not, only patches around interior vertices
+ * will be generated.
*
- * @arg <tt>level_boundary_patches</tt>: same for refinement edges
- * towards coarser cells.
+ * @arg <tt>level_boundary_patches</tt>: same for refinement edges towards
+ * coarser cells.
*
- * @arg <tt>single_cell_patches</tt>: if not true, patches
- * containing a single cell are eliminated.
+ * @arg <tt>single_cell_patches</tt>: if not true, patches containing a
+ * single cell are eliminated.
*/
template <class DH>
void make_vertex_patches(SparsityPattern &block_list,
const bool single_cell_patches = false);
/**
- * Create an incidence matrix that for every cell on a given level
- * of a multilevel DoFHandler flags which degrees of freedom are
- * associated with children of this cell. This data structure is
- * conveniently represented by a SparsityPattern object.
+ * Create an incidence matrix that for every cell on a given level of a
+ * multilevel DoFHandler flags which degrees of freedom are associated with
+ * children of this cell. This data structure is conveniently represented by
+ * a SparsityPattern object.
*
- * The function thus creates a sparsity pattern which in each row
- * (with rows corresponding to the cells on this level) lists the degrees of
- * freedom associated to the cells that are the children of this
- * cell. The DoF indices used here are level dof indices of a multilevel
- * hierarchy, i.e., they may be associated with children that are
- * not themselves active. The sparsity pattern may be empty when entering this
- * function and will be reinitialized to the correct size.
+ * The function thus creates a sparsity pattern which in each row (with rows
+ * corresponding to the cells on this level) lists the degrees of freedom
+ * associated to the cells that are the children of this cell. The DoF
+ * indices used here are level dof indices of a multilevel hierarchy, i.e.,
+ * they may be associated with children that are not themselves active. The
+ * sparsity pattern may be empty when entering this function and will be
+ * reinitialized to the correct size.
*
- * The function has some boolean arguments (listed below)
- * controlling details of the generated patches. The default
- * settings are those for Arnold-Falk-Winther type smoothers for
- * divergence and curl conforming finite elements with essential
- * boundary conditions. Other applications are possible, in
- * particular changing <tt>boundary_dofs</tt> for non-essential
- * boundary conditions.
+ * The function has some boolean arguments (listed below) controlling
+ * details of the generated patches. The default settings are those for
+ * Arnold-Falk-Winther type smoothers for divergence and curl conforming
+ * finite elements with essential boundary conditions. Other applications
+ * are possible, in particular changing <tt>boundary_dofs</tt> for non-
+ * essential boundary conditions.
*
* Since the patches are defined through refinement, th
*
- * @arg <tt>block_list</tt>: the SparsityPattern into which the
- * patches will be stored.
+ * @arg <tt>block_list</tt>: the SparsityPattern into which the patches will
+ * be stored.
*
- * @arg <tt>dof_handler</tt>: The multilevel dof handler providing
- * the topology operated on.
+ * @arg <tt>dof_handler</tt>: The multilevel dof handler providing the
+ * topology operated on.
*
- * @arg <tt>interior_dofs_only</tt>: for each patch of cells around
- * a vertex, collect only the interior degrees of freedom of the
- * patch and disregard those on the boundary of the patch. This is
- * for instance the setting for smoothers of Arnold-Falk-Winther
- * type.
+ * @arg <tt>interior_dofs_only</tt>: for each patch of cells around a
+ * vertex, collect only the interior degrees of freedom of the patch and
+ * disregard those on the boundary of the patch. This is for instance the
+ * setting for smoothers of Arnold-Falk-Winther type.
*
- * @arg <tt>boundary_dofs</tt>: include degrees of freedom, which
- * would have excluded by <tt>interior_dofs_only</tt>, but are lying
- * on the boundary of the domain, and thus need smoothing. This
- * parameter has no effect if <tt>interior_dofs_only</tt> is false.
+ * @arg <tt>boundary_dofs</tt>: include degrees of freedom, which would have
+ * excluded by <tt>interior_dofs_only</tt>, but are lying on the boundary of
+ * the domain, and thus need smoothing. This parameter has no effect if
+ * <tt>interior_dofs_only</tt> is false.
*/
template <class DH>
void make_child_patches(SparsityPattern &block_list,
const bool boundary_dofs = false);
/**
- * Create a block list with only a single patch, which in turn
- * contains all degrees of freedom on the given level.
+ * Create a block list with only a single patch, which in turn contains all
+ * degrees of freedom on the given level.
*
* This function is mostly a closure on level 0 for functions like
- * make_child_patches() and make_vertex_patches(), which may produce
- * an empty patch list.
+ * make_child_patches() and make_vertex_patches(), which may produce an
+ * empty patch list.
*
- * @arg <tt>block_list</tt>: the SparsityPattern into which the
- * patches will be stored.
+ * @arg <tt>block_list</tt>: the SparsityPattern into which the patches will
+ * be stored.
*
- * @arg <tt>dof_handler</tt>: The multilevel dof handler providing
- * the topology operated on.
+ * @arg <tt>dof_handler</tt>: The multilevel dof handler providing the
+ * topology operated on.
*
* @arg <tt>level</tt> The grid level used for building the list.
*
- * @arg <tt>interior_dofs_only</tt>: if true, exclude degrees of
- * freedom on the boundary of the domain.
+ * @arg <tt>interior_dofs_only</tt>: if true, exclude degrees of freedom on
+ * the boundary of the domain.
*/
template <class DH>
void make_single_patch(SparsityPattern &block_list,
*/
/**
- * Count how many degrees of freedom out of the total number belong
- * to each component. If the number of components the finite element
- * has is one (i.e. you only have one scalar variable), then the
- * number in this component obviously equals the total number of
- * degrees of freedom. Otherwise, the sum of the DoFs in all the
- * components needs to equal the total number.
+ * Count how many degrees of freedom out of the total number belong to each
+ * component. If the number of components the finite element has is one
+ * (i.e. you only have one scalar variable), then the number in this
+ * component obviously equals the total number of degrees of freedom.
+ * Otherwise, the sum of the DoFs in all the components needs to equal the
+ * total number.
*
- * However, the last statement does not hold true if the finite
- * element is not primitive, i.e. some or all of its shape functions
- * are non-zero in more than one vector component. This applies, for
- * example, to the Nedelec or Raviart-Thomas elements. In this case,
- * a degree of freedom is counted in each component in which it is
- * non-zero, so that the sum mentioned above is greater than the
- * total number of degrees of freedom.
+ * However, the last statement does not hold true if the finite element is
+ * not primitive, i.e. some or all of its shape functions are non-zero in
+ * more than one vector component. This applies, for example, to the Nedelec
+ * or Raviart-Thomas elements. In this case, a degree of freedom is counted
+ * in each component in which it is non-zero, so that the sum mentioned
+ * above is greater than the total number of degrees of freedom.
*
* This behavior can be switched off by the optional parameter
- * <tt>vector_valued_once</tt>. If this is <tt>true</tt>, the number
- * of components of a nonprimitive vector valued element is
- * collected only in the first component. All other components will
- * have a count of zero.
- *
- * The additional optional argument @p target_component allows for a
- * re-sorting and grouping of components. To this end, it contains
- * for each component the component number it shall be counted
- * as. Having the same number entered several times sums up several
- * components as the same. One of the applications of this argument
- * is when you want to form block matrices and vectors, but want to
- * pack several components into the same block (for example, when
- * you have @p dim velocities and one pressure, to put all
- * velocities into one block, and the pressure into another).
- *
- * The result is returned in @p dofs_per_component. Note that the
- * size of @p dofs_per_component needs to be enough to hold all the
- * indices specified in @p target_component. If this is not the
- * case, an assertion is thrown. The indices not targeted by
- * target_components are left untouched.
+ * <tt>vector_valued_once</tt>. If this is <tt>true</tt>, the number of
+ * components of a nonprimitive vector valued element is collected only in
+ * the first component. All other components will have a count of zero.
+ *
+ * The additional optional argument @p target_component allows for a re-
+ * sorting and grouping of components. To this end, it contains for each
+ * component the component number it shall be counted as. Having the same
+ * number entered several times sums up several components as the same. One
+ * of the applications of this argument is when you want to form block
+ * matrices and vectors, but want to pack several components into the same
+ * block (for example, when you have @p dim velocities and one pressure, to
+ * put all velocities into one block, and the pressure into another).
+ *
+ * The result is returned in @p dofs_per_component. Note that the size of @p
+ * dofs_per_component needs to be enough to hold all the indices specified
+ * in @p target_component. If this is not the case, an assertion is thrown.
+ * The indices not targeted by target_components are left untouched.
*/
template <class DH>
void
= std::vector<unsigned int>());
/**
- * Count the degrees of freedom in each block. This function is
- * similar to count_dofs_per_component(), with the difference that
- * the counting is done by blocks. See @ref GlossBlock "blocks" in
- * the glossary for details. Again the vectors are assumed to have
- * the correct size before calling this function. If this is not the
- * case, an assertion is thrown.
+ * Count the degrees of freedom in each block. This function is similar to
+ * count_dofs_per_component(), with the difference that the counting is done
+ * by blocks. See @ref GlossBlock "blocks" in the glossary for details.
+ * Again the vectors are assumed to have the correct size before calling
+ * this function. If this is not the case, an assertion is thrown.
*
- * This function is used in the step-22, step-31, and step-32
- * tutorial programs.
+ * This function is used in the step-22, step-31, and step-32 tutorial
+ * programs.
*
- * @pre The dofs_per_block variable has as many components as the
- * finite element used by the dof_handler argument has blocks, or
- * alternatively as many blocks as are enumerated in the
- * target_blocks argument if given.
+ * @pre The dofs_per_block variable has as many components as the finite
+ * element used by the dof_handler argument has blocks, or alternatively as
+ * many blocks as are enumerated in the target_blocks argument if given.
*/
template <class DH>
void
/**
* @deprecated See the previous function with the same name for a
- * description. This function exists for compatibility with older
- * versions only.
+ * description. This function exists for compatibility with older versions
+ * only.
*/
template <int dim, int spacedim>
void
/**
- * For each active cell of a DoFHandler or hp::DoFHandler, extract
- * the active finite element index and fill the vector given as
- * second argument. This vector is assumed to have as many entries
- * as there are active cells.
+ * For each active cell of a DoFHandler or hp::DoFHandler, extract the
+ * active finite element index and fill the vector given as second argument.
+ * This vector is assumed to have as many entries as there are active cells.
*
- * For non-hp DoFHandler objects given as first argument, the
- * returned vector will consist of only zeros, indicating that all
- * cells use the same finite element. For a hp::DoFHandler, the
- * values may be different, though.
+ * For non-hp DoFHandler objects given as first argument, the returned
+ * vector will consist of only zeros, indicating that all cells use the same
+ * finite element. For a hp::DoFHandler, the values may be different,
+ * though.
*/
template <class DH>
void
* solution of a local problem on the patch surrounding each of the cells of
* the mesh. You can get a list of cells that form the patch around a given
* cell using GridTools::get_patch_around_cell(). This function is then
- * useful in setting up the size of the linear system used to solve the local
- * problem on the patch around a cell. The function
- * DoFTools::get_dofs_on_patch() will then help to make the
- * connection between global degrees of freedom and the local ones.
- *
- * @tparam Container A type that is either DoFHandler or hp::DoFHandler.
- * In C++, the compiler can not determine the type of <code>DH</code>
- * from the function call. You need to specify it as an explicit template
- * argument following the function name.
+ * useful in setting up the size of the linear system used to solve the
+ * local problem on the patch around a cell. The function
+ * DoFTools::get_dofs_on_patch() will then help to make the connection
+ * between global degrees of freedom and the local ones.
+ *
+ * @tparam Container A type that is either DoFHandler or hp::DoFHandler. In
+ * C++, the compiler can not determine the type of <code>DH</code> from the
+ * function call. You need to specify it as an explicit template argument
+ * following the function name.
* @param patch[in] A collection of cells within an object of type DH
- * @return The number of degrees of freedom associated with the cells of this patch.
+ * @return The number of degrees of freedom associated with the cells of
+ * this patch.
*
* @note In the context of a parallel distributed computation, it only makes
- * sense to call this function on patches around locally owned cells. This is because the
- * neighbors of locally owned cells are either locally owned themselves, or
- * ghost cells. For both, we know that these are in fact the real cells of
- * the complete, parallel triangulation. We can also query the degrees of
- * freedom on these. In other words, this function can only work if all
- * cells in the patch are either locally owned or ghost cells.
+ * sense to call this function on patches around locally owned cells. This
+ * is because the neighbors of locally owned cells are either locally owned
+ * themselves, or ghost cells. For both, we know that these are in fact the
+ * real cells of the complete, parallel triangulation. We can also query the
+ * degrees of freedom on these. In other words, this function can only work
+ * if all cells in the patch are either locally owned or ghost cells.
*
* @author Arezou Ghesmati, Wolfgang Bangerth, 2014
*/
count_dofs_on_patch (const std::vector<typename DH::active_cell_iterator> &patch);
/**
- * Return the set of degrees of freedom that live on a set of
- * cells (i.e., a patch) described by the argument.
+ * Return the set of degrees of freedom that live on a set of cells (i.e., a
+ * patch) described by the argument.
*
* Patches are often used in defining error estimators that require the
* solution of a local problem on the patch surrounding each of the cells of
* the mesh. You can get a list of cells that form the patch around a given
- * cell using GridTools::get_patch_around_cell(). While DoFTools::count_dofs_on_patch()
- * can be used to determine the size of these local problems, so that one can assemble
- * the local system and then solve it, it is still necessary to provide a mapping
- * between the global indices of the degrees of freedom that live on the patch
- * and a local enumeration. This function provides such a local enumeration
- * by returning the set of degrees of freedom that live on the patch.
- *
- * Since this set is returned in the form of a std::vector, one can also think
- * of it as a mapping
+ * cell using GridTools::get_patch_around_cell(). While
+ * DoFTools::count_dofs_on_patch() can be used to determine the size of
+ * these local problems, so that one can assemble the local system and then
+ * solve it, it is still necessary to provide a mapping between the global
+ * indices of the degrees of freedom that live on the patch and a local
+ * enumeration. This function provides such a local enumeration by returning
+ * the set of degrees of freedom that live on the patch.
+ *
+ * Since this set is returned in the form of a std::vector, one can also
+ * think of it as a mapping
* @code
* i -> global_dof_index
* @endcode
- * where <code>i</code> is an index into the returned vector (i.e., a
- * the <i>local</i> index of a degree of freedom on the patch) and
+ * where <code>i</code> is an index into the returned vector (i.e., a the
+ * <i>local</i> index of a degree of freedom on the patch) and
* <code>global_dof_index</code> is the global index of a degree of freedom
* located on the patch. The array returned has size equal to
* DoFTools::count_dofs_on_patch().
* one considers the index into this array a local DoF index, then the local
* system that results retains the block structure of the global system.
*
- * @tparam Container A type that is either DoFHandler or hp::DoFHandler.
- * In C++, the compiler can not determine the type of <code>DH</code>
- * from the function call. You need to specify it as an explicit template
- * argument following the function name.
+ * @tparam Container A type that is either DoFHandler or hp::DoFHandler. In
+ * C++, the compiler can not determine the type of <code>DH</code> from the
+ * function call. You need to specify it as an explicit template argument
+ * following the function name.
* @param patch[in] A collection of cells within an object of type DH
- * @return A list of those global degrees of freedom located on the
- * patch, as defined above.
+ * @return A list of those global degrees of freedom located on the patch,
+ * as defined above.
*
* @note In the context of a parallel distributed computation, it only makes
- * sense to call this function on patches around locally owned cells. This is because the
- * neighbors of locally owned cells are either locally owned themselves, or
- * ghost cells. For both, we know that these are in fact the real cells of
- * the complete, parallel triangulation. We can also query the degrees of
- * freedom on these. In other words, this function can only work if all
- * cells in the patch are either locally owned or ghost cells.
+ * sense to call this function on patches around locally owned cells. This
+ * is because the neighbors of locally owned cells are either locally owned
+ * themselves, or ghost cells. For both, we know that these are in fact the
+ * real cells of the complete, parallel triangulation. We can also query the
+ * degrees of freedom on these. In other words, this function can only work
+ * if all cells in the patch are either locally owned or ghost cells.
*
* @author Arezou Ghesmati, Wolfgang Bangerth, 2014
*/
*/
/**
- * Create a mapping from degree of freedom indices to the index of
- * that degree of freedom on the boundary. After this operation,
- * <tt>mapping[dof]</tt> gives the index of the degree of freedom
- * with global number @p dof in the list of degrees of freedom on
- * the boundary. If the degree of freedom requested is not on the
- * boundary, the value of <tt>mapping[dof]</tt> is @p
- * invalid_dof_index. This function is mainly used when setting up
- * matrices and vectors on the boundary from the trial functions,
- * which have global numbers, while the matrices and vectors use
+ * Create a mapping from degree of freedom indices to the index of that
+ * degree of freedom on the boundary. After this operation,
+ * <tt>mapping[dof]</tt> gives the index of the degree of freedom with
+ * global number @p dof in the list of degrees of freedom on the boundary.
+ * If the degree of freedom requested is not on the boundary, the value of
+ * <tt>mapping[dof]</tt> is @p invalid_dof_index. This function is mainly
+ * used when setting up matrices and vectors on the boundary from the trial
+ * functions, which have global numbers, while the matrices and vectors use
* numbers of the trial functions local to the boundary.
*
* Prior content of @p mapping is deleted.
std::vector<types::global_dof_index> &mapping);
/**
- * Same as the previous function, except that only those parts of
- * the boundary are considered for which the boundary indicator is
- * listed in the second argument.
+ * Same as the previous function, except that only those parts of the
+ * boundary are considered for which the boundary indicator is listed in the
+ * second argument.
*
* See the general doc of this class for more information.
*
std::vector<types::global_dof_index> &mapping);
/**
- * Return a list of support points (see this @ref GlossSupport
- * "glossary entry") for all the degrees of freedom handled by this
- * DoF handler object. This function, of course, only works if the
- * finite element object used by the DoF handler object actually
- * provides support points, i.e. no edge elements or the
- * like. Otherwise, an exception is thrown.
+ * Return a list of support points (see this @ref GlossSupport "glossary
+ * entry") for all the degrees of freedom handled by this DoF handler
+ * object. This function, of course, only works if the finite element object
+ * used by the DoF handler object actually provides support points, i.e. no
+ * edge elements or the like. Otherwise, an exception is thrown.
*
- * @pre The given array must have a length of as many elements as
- * there are degrees of freedom.
+ * @pre The given array must have a length of as many elements as there are
+ * degrees of freedom.
*
- * @note The precondition to this function that the output argument
- * needs to have size equal to the total number of degrees of
- * freedom makes this function unsuitable for the case that the
- * given DoFHandler object derives from a
- * parallel::distributed::Triangulation object. Consequently, this
+ * @note The precondition to this function that the output argument needs to
+ * have size equal to the total number of degrees of freedom makes this
+ * function unsuitable for the case that the given DoFHandler object derives
+ * from a parallel::distributed::Triangulation object. Consequently, this
* function will produce an error if called with such a DoFHandler.
*/
template <int dim, int spacedim>
/**
* This function is a version of the above map_dofs_to_support_points
- * function that doesn't simply return a vector of support points (see
- * this @ref GlossSupport "glossary entry") with one
- * entry for each global degree of freedom, but instead a map that
- * maps from the DoFs index to its location. The point of this
- * function is that it is also usable in cases where the DoFHandler
- * is based on a parallel::distributed::Triangulation object. In such cases,
- * each processor will not be able to determine the support point location
- * of all DoFs, and worse no processor may be able to hold a vector that
- * would contain the locations of all DoFs even if they were known. As
- * a consequence, this function constructs a map from those DoFs for which
- * we can know the locations (namely, those DoFs that are
- * locally relevant (see @ref GlossLocallyRelevantDof "locally relevant DoFs")
- * to their locations.
+ * function that doesn't simply return a vector of support points (see this
+ * @ref GlossSupport "glossary entry") with one entry for each global degree
+ * of freedom, but instead a map that maps from the DoFs index to its
+ * location. The point of this function is that it is also usable in cases
+ * where the DoFHandler is based on a parallel::distributed::Triangulation
+ * object. In such cases, each processor will not be able to determine the
+ * support point location of all DoFs, and worse no processor may be able to
+ * hold a vector that would contain the locations of all DoFs even if they
+ * were known. As a consequence, this function constructs a map from those
+ * DoFs for which we can know the locations (namely, those DoFs that are
+ * locally relevant (see @ref GlossLocallyRelevantDof "locally relevant
+ * DoFs") to their locations.
*
* For non-distributed triangulations, the map returned as @p support_points
* is of course dense, i.e., every DoF is to be found in it.
*
* @param mapping The mapping from the reference cell to the real cell on
- * which DoFs are defined.
+ * which DoFs are defined.
* @param dof_handler The object that describes which DoF indices live on
- * which cell of the triangulation.
+ * which cell of the triangulation.
* @param support_points A map that for every locally relevant DoF index
- * contains the corresponding location in real space coordinates.
- * Previous content of this object is deleted in this function.
+ * contains the corresponding location in real space coordinates. Previous
+ * content of this object is deleted in this function.
*/
template <int dim, int spacedim>
void
/**
- * This is the opposite function to the one above. It generates a
- * map where the keys are the support points of the degrees of
- * freedom, while the values are the DoF indices. For a definition
- * of support points, see this @ref GlossSupport "glossary entry".
+ * This is the opposite function to the one above. It generates a map where
+ * the keys are the support points of the degrees of freedom, while the
+ * values are the DoF indices. For a definition of support points, see this
+ * @ref GlossSupport "glossary entry".
*
- * Since there is no natural order in the space of points (except
- * for the 1d case), you have to provide a map with an explicitly
- * specified comparator object. This function is therefore
- * templatized on the comparator object. Previous content of the map
- * object is deleted in this function.
+ * Since there is no natural order in the space of points (except for the 1d
+ * case), you have to provide a map with an explicitly specified comparator
+ * object. This function is therefore templatized on the comparator object.
+ * Previous content of the map object is deleted in this function.
*
- * Just as with the function above, it is assumed that the finite
- * element in use here actually supports the notion of support
- * points of all its components.
+ * Just as with the function above, it is assumed that the finite element in
+ * use here actually supports the notion of support points of all its
+ * components.
*/
template <class DH, class Comp>
void
std::map<Point<DH::space_dimension>, types::global_dof_index, Comp> &point_to_index_map);
/**
- * Map a coupling table from the user friendly organization by
- * components to the organization by blocks. Specializations of this
- * function for DoFHandler and hp::DoFHandler are required due to
- * the different results of their finite element access.
+ * Map a coupling table from the user friendly organization by components to
+ * the organization by blocks. Specializations of this function for
+ * DoFHandler and hp::DoFHandler are required due to the different results
+ * of their finite element access.
*
- * The return vector will be initialized to the correct length
- * inside this function.
+ * The return vector will be initialized to the correct length inside this
+ * function.
*/
template <int dim, int spacedim>
void
std::vector<Table<2,Coupling> > &tables_by_block);
/**
- * Make a constraint matrix for the constraints that result from
- * zero boundary values on the given boundary indicator.
+ * Make a constraint matrix for the constraints that result from zero
+ * boundary values on the given boundary indicator.
*
- * This function constrains all degrees of freedom on the given part
- * of the boundary.
+ * This function constrains all degrees of freedom on the given part of the
+ * boundary.
*
- * A variant of this function with different arguments is used in
- * step-36.
+ * A variant of this function with different arguments is used in step-36.
*
* @param dof The DoFHandler to work on.
- * @param boundary_indicator The indicator of that part of the boundary
- * for which constraints should be computed. If this number equals
- * numbers::invalid_boundary_id then all boundaries of the domain
- * will be treated.
+ * @param boundary_indicator The indicator of that part of the boundary for
+ * which constraints should be computed. If this number equals
+ * numbers::invalid_boundary_id then all boundaries of the domain will be
+ * treated.
* @param zero_boundary_constraints The constraint object into which the
- * constraints will be written. The new constraints due to zero boundary
- * values will simply be added, preserving any other constraints
- * previously present. However, this will only work if the previous
- * content of that object consists of constraints on degrees of freedom
- * that are not located on the boundary treated here. If there are
- * previously existing constraints for degrees of freedom located on the
- * boundary, then this would constitute a conflict. See the @ref constraints
- * module for handling the case where there are conflicting constraints
- * on individual degrees of freedom.
- * @param component_mask An optional component mask that
- * restricts the functionality of this function to a subset of an FESystem.
- * For non-@ref GlossPrimitive "primitive"
- * shape functions, any degree of freedom
- * is affected that belongs to a
- * shape function where at least
- * one of its nonzero components
- * is affected by the component mask (see @ref GlossComponentMask). If
- * this argument is omitted, all components of the finite element with
- * degrees of freedom at the boundary will be considered.
+ * constraints will be written. The new constraints due to zero boundary
+ * values will simply be added, preserving any other constraints previously
+ * present. However, this will only work if the previous content of that
+ * object consists of constraints on degrees of freedom that are not located
+ * on the boundary treated here. If there are previously existing
+ * constraints for degrees of freedom located on the boundary, then this
+ * would constitute a conflict. See the @ref constraints module for handling
+ * the case where there are conflicting constraints on individual degrees of
+ * freedom.
+ * @param component_mask An optional component mask that restricts the
+ * functionality of this function to a subset of an FESystem. For non-@ref
+ * GlossPrimitive "primitive" shape functions, any degree of freedom is
+ * affected that belongs to a shape function where at least one of its
+ * nonzero components is affected by the component mask (see @ref
+ * GlossComponentMask). If this argument is omitted, all components of the
+ * finite element with degrees of freedom at the boundary will be
+ * considered.
*
* @ingroup constraints
*
const ComponentMask &component_mask = ComponentMask());
/**
- * Do the same as the previous function, except do it for all
- * parts of the boundary, not just those with a particular boundary
- * indicator. This function is then equivalent to calling the previous
- * one with numbers::invalid_boundary_id as second argument.
+ * Do the same as the previous function, except do it for all parts of the
+ * boundary, not just those with a particular boundary indicator. This
+ * function is then equivalent to calling the previous one with
+ * numbers::invalid_boundary_id as second argument.
*
* This function is used in step-36, for example.
*
/**
- * Map a coupling table from the user friendly organization by
- * components to the organization by blocks. Specializations of this
- * function for DoFHandler and hp::DoFHandler are required due to
- * the different results of their finite element access.
+ * Map a coupling table from the user friendly organization by components to
+ * the organization by blocks. Specializations of this function for
+ * DoFHandler and hp::DoFHandler are required due to the different results
+ * of their finite element access.
*
- * The return vector will be initialized to the correct length
- * inside this function.
+ * The return vector will be initialized to the correct length inside this
+ * function.
*/
template <int dim, int spacedim>
void
std::vector<Table<2,Coupling> > &tables_by_block);
/**
- * Given a finite element and a table how the vector components of
- * it couple with each other, compute and return a table that
- * describes how the individual shape functions couple with each
- * other.
+ * Given a finite element and a table how the vector components of it couple
+ * with each other, compute and return a table that describes how the
+ * individual shape functions couple with each other.
*/
template <int dim, int spacedim>
Table<2,Coupling>
const Table<2,Coupling> &component_couplings);
/**
- * Same function as above for a collection of finite elements,
- * returning a collection of tables.
+ * Same function as above for a collection of finite elements, returning a
+ * collection of tables.
*
- * The function currently treats DoFTools::Couplings::nonzero the
- * same as DoFTools::Couplings::always .
+ * The function currently treats DoFTools::Couplings::nonzero the same as
+ * DoFTools::Couplings::always .
*/
template <int dim, int spacedim>
std::vector<Table<2,Coupling> >
*/
DeclException0 (ExcGridsDontMatch);
/**
- * The ::DoFHandler or hp::DoFHandler was not initialized with a
- * finite element. Please call DoFHandler::distribute_dofs() etc. first.
+ * The ::DoFHandler or hp::DoFHandler was not initialized with a finite
+ * element. Please call DoFHandler::distribute_dofs() etc. first.
*
* @ingroup Exceptions
*/
/**
- * This class declares a local typedef that denotes a mapping between a boundary indicator
- * (see @ref GlossBoundaryIndicator) that is used to describe what kind of boundary
- * condition holds on a particular piece of the boundary,
- * and the function describing the actual function that provides the boundary
- * values on this part of the boundary. This type is required in many functions
- * in the library where, for example, we need to know about the functions $h_i(\mathbf x)$
- * used in boundary conditions
- * @f{align*}
- * \mathbf n \cdot \nabla u = h_i \qquad \qquad \text{on}\ \Gamma_i\subset\partial\Omega.
- * @f}
- * An example is the function KellyErrorEstimator::estimate() that allows us
- * to provide a set of functions $h_i$ for all those boundary indicators $i$ for
- * which the boundary condition is supposed to be of Neumann type. Of course,
- * the same kind of principle can be applied to cases where we care about
- * Dirichlet values, where one needs to provide a map from boundary indicator $i$
- * to Dirichlet function $h_i$ if the boundary conditions are given as
- * @f{align*}
- * u = h_i \qquad \qquad \text{on}\ \Gamma_i\subset\partial\Omega.
- * @f}
- * This is, for example, the case for the VectorTools::interpolate() functions.
+ * This class declares a local typedef that denotes a mapping between a
+ * boundary indicator (see @ref GlossBoundaryIndicator) that is used to
+ * describe what kind of boundary condition holds on a particular piece of the
+ * boundary, and the function describing the actual function that provides the
+ * boundary values on this part of the boundary. This type is required in many
+ * functions in the library where, for example, we need to know about the
+ * functions $h_i(\mathbf x)$ used in boundary conditions @f{align*} \mathbf n
+ * \cdot \nabla u = h_i \qquad \qquad \text{on}\
+ * \Gamma_i\subset\partial\Omega. @f} An example is the function
+ * KellyErrorEstimator::estimate() that allows us to provide a set of
+ * functions $h_i$ for all those boundary indicators $i$ for which the
+ * boundary condition is supposed to be of Neumann type. Of course, the same
+ * kind of principle can be applied to cases where we care about Dirichlet
+ * values, where one needs to provide a map from boundary indicator $i$ to
+ * Dirichlet function $h_i$ if the boundary conditions are given as @f{align*}
+ * u = h_i \qquad \qquad \text{on}\ \Gamma_i\subset\partial\Omega. @f} This
+ * is, for example, the case for the VectorTools::interpolate() functions.
*
* Tutorial programs step-6, step-7 and step-8 show examples of how to use
- * function arguments of this type in situations where we actually have an empty
- * map (i.e., we want to describe that <i>no</i> part of the boundary is a
- * Neumann boundary). step-16 actually uses it in a case where one of the
- * parts of the boundary uses a boundary indicator for which we want to use
- * a function object.
+ * function arguments of this type in situations where we actually have an
+ * empty map (i.e., we want to describe that <i>no</i> part of the boundary is
+ * a Neumann boundary). step-16 actually uses it in a case where one of the
+ * parts of the boundary uses a boundary indicator for which we want to use a
+ * function object.
*
* It seems odd at first to declare this typedef inside a class, rather than
* declaring a typedef at global scope. The reason is that C++ does not allow
* to define templated typedefs, where here in fact we want a typdef that
- * depends on the space dimension. (Defining templated typedefs is something that
- * is possible starting with the C++11 standard, but that wasn't possible within
- * the C++98 standard in place when this programming pattern was conceived.)
+ * depends on the space dimension. (Defining templated typedefs is something
+ * that is possible starting with the C++11 standard, but that wasn't possible
+ * within the C++98 standard in place when this programming pattern was
+ * conceived.)
*
* @ingroup functions
* @author Wolfgang Bangerth, Ralf Hartmann, 2001
struct FunctionMap
{
/**
- * Declare the type as discussed
- * above. Since we can't name it
- * FunctionMap (as that would
- * ambiguate a possible
- * constructor of this class),
- * name it in the fashion of the
- * STL local typedefs.
+ * Declare the type as discussed above. Since we can't name it FunctionMap
+ * (as that would ambiguate a possible constructor of this class), name it
+ * in the fashion of the STL local typedefs.
*/
typedef std::map<types::boundary_id, const Function<dim,Number>*> type;
};
namespace DoFHandler
{
/**
- * A structure used by the
- * DoFHandler classes to store
- * information about the degrees
- * of freedom they deal with.
+ * A structure used by the DoFHandler classes to store information about
+ * the degrees of freedom they deal with.
*/
struct NumberCache
{
NumberCache ();
/**
- * Determine an estimate for the
- * memory consumption (in bytes) of
- * this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
void clear ();
/**
- * Total number of dofs,
- * accumulated over all
- * processors that may
+ * Total number of dofs, accumulated over all processors that may
* participate on this mesh.
*/
types::global_dof_index n_global_dofs;
/**
- * Number of dofs owned by
- * this MPI process. If this
- * is a sequential
- * computation, then this
- * equals n_global_dofs.
+ * Number of dofs owned by this MPI process. If this is a sequential
+ * computation, then this equals n_global_dofs.
*/
types::global_dof_index n_locally_owned_dofs;
/**
- * An index set denoting the
- * set of locally owned
- * dofs. If this is a
- * sequential computation,
- * then it contains the
- * entire range
+ * An index set denoting the set of locally owned dofs. If this is a
+ * sequential computation, then it contains the entire range
* [0,n_global_dofs).
*/
IndexSet locally_owned_dofs;
/**
- * The number of dofs owned
- * by each of the various MPI
- * processes. If this is a
- * sequential job, then the
- * vector contains a single
- * element equal to
- * n_global_dofs.
+ * The number of dofs owned by each of the various MPI processes. If
+ * this is a sequential job, then the vector contains a single element
+ * equal to n_global_dofs.
*/
std::vector<types::global_dof_index> n_locally_owned_dofs_per_processor;
/**
- * The dofs owned by each of
- * the various MPI
- * processes. If this is a
- * sequential job, then the
- * vector has a single
- * element equal to
+ * The dofs owned by each of the various MPI processes. If this is a
+ * sequential job, then the vector has a single element equal to
* locally_owned_dofs.
*/
std::vector<IndexSet> locally_owned_dofs_per_processor;
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
*/
template <class Archive>
void serialize (Archive &ar,
/**
- * This class represents a mask that can be used to select individual
- * vector blocks of a finite element (see also
- * @ref GlossBlockMask "this glossary entry"). It will typically have as many
- * elements as the finite element has blocks, and one can
- * use <code>operator[]</code> to query whether a particular block
- * has been selected.
+ * This class represents a mask that can be used to select individual vector
+ * blocks of a finite element (see also @ref GlossBlockMask "this glossary
+ * entry"). It will typically have as many elements as the finite element has
+ * blocks, and one can use <code>operator[]</code> to query whether a
+ * particular block has been selected.
*
* The semantics of this class are the same as the related ComponentMask
- * class, i.e., a default constructed mask represents all possible
- * blocks. See there for more information about these semantics.
+ * class, i.e., a default constructed mask represents all possible blocks. See
+ * there for more information about these semantics.
*
* Objects of this kind are used in many places where one wants to restrict
* operations to a certain subset of blocks, e.g. in DoFTools::extract_dofs.
- * These objects can
- * either be created by hand, or, simpler, by asking the finite element
- * to generate a block mask from certain selected blocks using
- * code such as this where we create a mask that only denotes the
- * velocity block of a Stokes element (see @ref vector_valued):
+ * These objects can either be created by hand, or, simpler, by asking the
+ * finite element to generate a block mask from certain selected blocks using
+ * code such as this where we create a mask that only denotes the velocity
+ * block of a Stokes element (see @ref vector_valued):
* @code
* FESystem<dim> stokes_fe (FESystem<dim>(FE_Q<dim>(2), dim), 1, // Q2 element for the velocities
* FE_Q<dim>(1), 1); // Q1 element for the pressure
* FEValuesExtractors::Scalar pressure(dim);
* BlockMask pressure_mask = stokes_fe.block_mask (pressure);
* @endcode
- * Note that by wrapping the velocity elements into a single FESystem
- * object we make sure that the overall element has only 2 blocks.
- * The result is a block mask that, in both 2d and 3d, would have values
- * <code>[false, true]</code>. (Compare this to the corresponding
- * component mask discussed in the ComponentMask documentation.)
- * Similarly, using
+ * Note that by wrapping the velocity elements into a single FESystem object
+ * we make sure that the overall element has only 2 blocks. The result is a
+ * block mask that, in both 2d and 3d, would have values <code>[false,
+ * true]</code>. (Compare this to the corresponding component mask discussed
+ * in the ComponentMask documentation.) Similarly, using
* @code
* FEValuesExtractors::Vector velocities(0);
* BlockMask velocity_mask = stokes_fe.block_mask (velocities);
{
public:
/**
- * Initialize a block mask. The default is that a block
- * mask represents a set of blocks that are <i>all</i>
- * selected, i.e., calling this constructor results in
- * a block mask that always returns <code>true</code>
+ * Initialize a block mask. The default is that a block mask represents a
+ * set of blocks that are <i>all</i> selected, i.e., calling this
+ * constructor results in a block mask that always returns <code>true</code>
* whenever asked whether a block is selected.
*/
BlockMask ();
/**
- * Initialize an object of this type with a set of selected
- * blocks specified by the argument.
+ * Initialize an object of this type with a set of selected blocks specified
+ * by the argument.
*
- * @param block_mask A vector of <code>true/false</code>
- * entries that determine which blocks of a finite element
- * are selected. If the length of the given vector is zero,
- * then this interpreted as the case where <i>every</i> block
- * is selected.
+ * @param block_mask A vector of <code>true/false</code> entries that
+ * determine which blocks of a finite element are selected. If the length of
+ * the given vector is zero, then this interpreted as the case where
+ * <i>every</i> block is selected.
*/
BlockMask (const std::vector<bool> &block_mask);
/**
- * Initialize the block mask with a number of elements that
- * are either all true or false.
+ * Initialize the block mask with a number of elements that are either all
+ * true or false.
*
* @param n_blocks The number of elements of this mask
* @param initializer The value each of these elements is supposed to have:
- * either true or false.
+ * either true or false.
*/
BlockMask (const unsigned int n_blocks,
const bool initializer);
/**
- * If this block mask has been initialized with a mask of
- * size greater than zero, then return the size of the mask
- * represented by this object. On the other hand, if this
- * mask has been initialized as an empty object that represents
- * a mask that is true for every element (i.e., if this object
- * would return true when calling represents_the_all_selected_mask())
- * then return zero since no definite size is known.
+ * If this block mask has been initialized with a mask of size greater than
+ * zero, then return the size of the mask represented by this object. On the
+ * other hand, if this mask has been initialized as an empty object that
+ * represents a mask that is true for every element (i.e., if this object
+ * would return true when calling represents_the_all_selected_mask()) then
+ * return zero since no definite size is known.
*/
unsigned int size () const;
/**
- * Return whether a particular block is selected by this
- * mask. If this mask represents the case of an object that
- * selects <i>all blocks</i> (e.g. if it is created
- * using the default constructor or is converted from an
- * empty vector of type bool) then this function returns
- * true regardless of the given argument.
+ * Return whether a particular block is selected by this mask. If this mask
+ * represents the case of an object that selects <i>all blocks</i> (e.g. if
+ * it is created using the default constructor or is converted from an empty
+ * vector of type bool) then this function returns true regardless of the
+ * given argument.
*
- * @param block_index The index for which the function
- * should return whether the block is selected. If this
- * object represents a mask in which all blocks are always
- * selected then any index is allowed here. Otherwise, the
- * given index needs to be between zero and the number of
- * blocks that this mask represents.
+ * @param block_index The index for which the function should return whether
+ * the block is selected. If this object represents a mask in which all
+ * blocks are always selected then any index is allowed here. Otherwise, the
+ * given index needs to be between zero and the number of blocks that this
+ * mask represents.
*/
bool operator[] (const unsigned int block_index) const;
/**
- * Return whether this block mask represents a mask with
- * exactly <code>n</code> blocks. This is true if either
- * it was initilized with a vector with exactly <code>n</code>
- * entries of type <code>bool</code> (in this case, @p n must
- * equal the result of size()) or if it was initialized
- * with an empty vector (or using the default constructor) in
- * which case it can represent a mask with an arbitrary number
- * of blocks and will always say that a block is
- * selected.
+ * Return whether this block mask represents a mask with exactly
+ * <code>n</code> blocks. This is true if either it was initilized with a
+ * vector with exactly <code>n</code> entries of type <code>bool</code> (in
+ * this case, @p n must equal the result of size()) or if it was initialized
+ * with an empty vector (or using the default constructor) in which case it
+ * can represent a mask with an arbitrary number of blocks and will always
+ * say that a block is selected.
*/
bool
represents_n_blocks (const unsigned int n) const;
/**
* Return the number of blocks that are selected by this mask.
*
- * Since empty block masks represent a block mask that
- * would return <code>true</code> for every block, this
- * function may not know the true size of the block
- * mask and it therefore requires an argument that denotes the
- * overall number of blocks.
+ * Since empty block masks represent a block mask that would return
+ * <code>true</code> for every block, this function may not know the true
+ * size of the block mask and it therefore requires an argument that denotes
+ * the overall number of blocks.
*
- * If the object has been initialized with a non-empty mask (i.e.,
- * if the size() function returns something greater than zero,
- * or equivalently if represents_the_all_selected_mask() returns
- * false) then the argument can be omitted and the result of size()
- * is taken.
+ * If the object has been initialized with a non-empty mask (i.e., if the
+ * size() function returns something greater than zero, or equivalently if
+ * represents_the_all_selected_mask() returns false) then the argument can
+ * be omitted and the result of size() is taken.
*/
unsigned int
n_selected_blocks (const unsigned int overall_number_of_blocks = numbers::invalid_unsigned_int) const;
/**
- * Return the index of the first selected block. The argument
- * is there for the same reason it exists with the
- * n_selected_blocks() function.
+ * Return the index of the first selected block. The argument is there for
+ * the same reason it exists with the n_selected_blocks() function.
*
* The function throws an exception if no block is selected at all.
*/
first_selected_block (const unsigned int overall_number_of_blocks = numbers::invalid_unsigned_int) const;
/**
- * Return true if this mask represents a default
- * constructed mask that corresponds to one in which
- * all blocks are selected. If true, then the size()
- * function will return zero.
+ * Return true if this mask represents a default constructed mask that
+ * corresponds to one in which all blocks are selected. If true, then the
+ * size() function will return zero.
*/
bool
represents_the_all_selected_mask () const;
/**
- * Return a block mask that contains the union of the
- * blocks selected by the current object and the one
- * passed as an argument.
+ * Return a block mask that contains the union of the blocks selected by the
+ * current object and the one passed as an argument.
*/
BlockMask operator | (const BlockMask &mask) const;
/**
- * Return a block mask that has only those elements set that
- * are set both in the current object as well as the one
- * passed as an argument.
+ * Return a block mask that has only those elements set that are set both in
+ * the current object as well as the one passed as an argument.
*/
BlockMask operator & (const BlockMask &mask) const;
bool operator!= (const BlockMask &mask) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t
memory_consumption () const;
/**
- * Write a block mask to an output stream. If the block
- * mask represents one where all blocks are selected without
- * specifying a particular size of the mask, then it
- * writes the string <code>[all blocks selected]</code> to the
+ * Write a block mask to an output stream. If the block mask represents one
+ * where all blocks are selected without specifying a particular size of the
+ * mask, then it writes the string <code>[all blocks selected]</code> to the
* stream. Otherwise, it prints the block mask in a form like
* <code>[true,true,true,false]</code>.
*
* @param out The stream to write to.
- * @param mask The mask to write.
- * @return A reference to the first argument.
+ * @param mask The mask to write. @return A reference to the first argument.
*/
std::ostream &operator << (std::ostream &out,
const BlockMask &mask);
/**
- * This class represents a mask that can be used to select individual
- * vector components of a finite element (see also
- * @ref GlossComponentMask "this glossary entry"). It will typically have as many
- * elements as the finite element has vector components, and one can
- * use <code>operator[]</code> to query whether a particular component
- * has been selected.
+ * This class represents a mask that can be used to select individual vector
+ * components of a finite element (see also @ref GlossComponentMask "this
+ * glossary entry"). It will typically have as many elements as the finite
+ * element has vector components, and one can use <code>operator[]</code> to
+ * query whether a particular component has been selected.
*
* Objects of this kind are used in many places where one wants to restrict
- * operations to a certain subset of components, e.g. in DoFTools::make_zero_boundary_values
- * or VectorTools::interpolate_boundary_values. These objects can
- * either be created by hand, or, simpler, by asking the finite element
- * to generate a component mask from certain selected components using
- * code such as this where we create a mask that only denotes the
- * velocity components of a Stokes element (see @ref vector_valued):
+ * operations to a certain subset of components, e.g. in
+ * DoFTools::make_zero_boundary_values or
+ * VectorTools::interpolate_boundary_values. These objects can either be
+ * created by hand, or, simpler, by asking the finite element to generate a
+ * component mask from certain selected components using code such as this
+ * where we create a mask that only denotes the velocity components of a
+ * Stokes element (see @ref vector_valued):
* @code
* FESystem<dim> stokes_fe (FE_Q<dim>(2), dim, // Q2 element for the velocities
* FE_Q<dim>(1), 1); // Q1 element for the pressure
* FEValuesExtractors::Scalar pressure(dim);
* ComponentMask pressure_mask = stokes_fe.component_mask (pressure);
* @endcode
- * The result is a component mask that, in 2d, would have values
- * <code>[false, false, true]</code>. Similarly, using
+ * The result is a component mask that, in 2d, would have values <code>[false,
+ * false, true]</code>. Similarly, using
* @code
* FEValuesExtractors::Vector velocities(0);
* ComponentMask velocity_mask = stokes_fe.component_mask (velocities);
* @endcode
- * would result in a mask <code>[true, true, false]</code> in 2d. Of
- * course, in 3d, the result would be <code>[true, true, true, false]</code>.
+ * would result in a mask <code>[true, true, false]</code> in 2d. Of course,
+ * in 3d, the result would be <code>[true, true, true, false]</code>.
*
* @ingroup fe
* @author Wolfgang Bangerth
{
public:
/**
- * Initialize a component mask. The default is that a component
- * mask represents a set of components that are <i>all</i>
- * selected, i.e., calling this constructor results in
- * a component mask that always returns <code>true</code>
- * whenever asked whether a component is selected.
+ * Initialize a component mask. The default is that a component mask
+ * represents a set of components that are <i>all</i> selected, i.e.,
+ * calling this constructor results in a component mask that always returns
+ * <code>true</code> whenever asked whether a component is selected.
*/
ComponentMask ();
/**
- * Initialize an object of this type with a set of selected
- * components specified by the argument.
+ * Initialize an object of this type with a set of selected components
+ * specified by the argument.
*
- * @param component_mask A vector of <code>true/false</code>
- * entries that determine which components of a finite element
- * are selected. If the length of the given vector is zero,
- * then this interpreted as the case where <i>every</i> component
- * is selected.
+ * @param component_mask A vector of <code>true/false</code> entries that
+ * determine which components of a finite element are selected. If the
+ * length of the given vector is zero, then this interpreted as the case
+ * where <i>every</i> component is selected.
*/
ComponentMask (const std::vector<bool> &component_mask);
/**
- * Initialize the component mask with a number of elements that
- * are either all true or false.
+ * Initialize the component mask with a number of elements that are either
+ * all true or false.
*
* @param n_components The number of elements of this mask
* @param initializer The value each of these elements is supposed to have:
- * either true or false.
+ * either true or false.
*/
ComponentMask (const unsigned int n_components,
const bool initializer);
void set (const unsigned int index, const bool value);
/**
- * If this component mask has been initialized with a mask of
- * size greater than zero, then return the size of the mask
- * represented by this object. On the other hand, if this
- * mask has been initialized as an empty object that represents
- * a mask that is true for every element (i.e., if this object
- * would return true when calling represents_the_all_selected_mask())
+ * If this component mask has been initialized with a mask of size greater
+ * than zero, then return the size of the mask represented by this object.
+ * On the other hand, if this mask has been initialized as an empty object
+ * that represents a mask that is true for every element (i.e., if this
+ * object would return true when calling represents_the_all_selected_mask())
* then return zero since no definite size is known.
*/
unsigned int size () const;
/**
- * Return whether a particular component is selected by this
- * mask. If this mask represents the case of an object that
- * selects <i>all components</i> (e.g. if it is created
- * using the default constructor or is converted from an
- * empty vector of type bool) then this function returns
- * true regardless of the given argument.
+ * Return whether a particular component is selected by this mask. If this
+ * mask represents the case of an object that selects <i>all components</i>
+ * (e.g. if it is created using the default constructor or is converted from
+ * an empty vector of type bool) then this function returns true regardless
+ * of the given argument.
*
- * @param component_index The index for which the function
- * should return whether the component is selected. If this
- * object represents a mask in which all components are always
- * selected then any index is allowed here. Otherwise, the
- * given index needs to be between zero and the number of
+ * @param component_index The index for which the function should return
+ * whether the component is selected. If this object represents a mask in
+ * which all components are always selected then any index is allowed here.
+ * Otherwise, the given index needs to be between zero and the number of
* components that this mask represents.
*/
bool operator[] (const unsigned int component_index) const;
/**
- * Return whether this component mask represents a mask with
- * exactly <code>n</code> components. This is true if either
- * it was initilized with a vector with exactly <code>n</code>
- * entries of type <code>bool</code> (in this case, @p n must
- * equal the result of size()) or if it was initialized
- * with an empty vector (or using the default constructor) in
- * which case it can represent a mask with an arbitrary number
- * of components and will always say that a component is
- * selected.
+ * Return whether this component mask represents a mask with exactly
+ * <code>n</code> components. This is true if either it was initilized with
+ * a vector with exactly <code>n</code> entries of type <code>bool</code>
+ * (in this case, @p n must equal the result of size()) or if it was
+ * initialized with an empty vector (or using the default constructor) in
+ * which case it can represent a mask with an arbitrary number of components
+ * and will always say that a component is selected.
*/
bool
represents_n_components (const unsigned int n) const;
/**
* Return the number of components that are selected by this mask.
*
- * Since empty component masks represent a component mask that
- * would return <code>true</code> for every component, this
- * function may not know the true size of the component
- * mask and it therefore requires an argument that denotes the
- * overall number of components.
+ * Since empty component masks represent a component mask that would return
+ * <code>true</code> for every component, this function may not know the
+ * true size of the component mask and it therefore requires an argument
+ * that denotes the overall number of components.
*
- * If the object has been initialized with a non-empty mask (i.e.,
- * if the size() function returns something greater than zero,
- * or equivalently if represents_the_all_selected_mask() returns
- * false) then the argument can be omitted and the result of size()
- * is taken.
+ * If the object has been initialized with a non-empty mask (i.e., if the
+ * size() function returns something greater than zero, or equivalently if
+ * represents_the_all_selected_mask() returns false) then the argument can
+ * be omitted and the result of size() is taken.
*/
unsigned int
n_selected_components (const unsigned int overall_number_of_components = numbers::invalid_unsigned_int) const;
/**
- * Return the index of the first selected component. The argument
- * is there for the same reason it exists with the
- * n_selected_components() function.
+ * Return the index of the first selected component. The argument is there
+ * for the same reason it exists with the n_selected_components() function.
*
* The function throws an exception if no component is selected at all.
*/
first_selected_component (const unsigned int overall_number_of_components = numbers::invalid_unsigned_int) const;
/**
- * Return true if this mask represents a default
- * constructed mask that corresponds to one in which
- * all components are selected. If true, then the size()
- * function will return zero.
+ * Return true if this mask represents a default constructed mask that
+ * corresponds to one in which all components are selected. If true, then
+ * the size() function will return zero.
*/
bool
represents_the_all_selected_mask () const;
/**
- * Return a component mask that contains the union of the
- * components selected by the current object and the one
- * passed as an argument.
+ * Return a component mask that contains the union of the components
+ * selected by the current object and the one passed as an argument.
*/
ComponentMask operator | (const ComponentMask &mask) const;
/**
- * Return a component mask that has only those elements set that
- * are set both in the current object as well as the one
- * passed as an argument.
+ * Return a component mask that has only those elements set that are set
+ * both in the current object as well as the one passed as an argument.
*/
ComponentMask operator & (const ComponentMask &mask) const;
bool operator!= (const ComponentMask &mask) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t
memory_consumption () const;
/**
- * Write a component mask to an output stream. If the component
- * mask represents one where all components are selected without
- * specifying a particular size of the mask, then it
- * writes the string <code>[all components selected]</code> to the
- * stream. Otherwise, it prints the component mask in a form like
- * <code>[true,true,true,false]</code>.
+ * Write a component mask to an output stream. If the component mask
+ * represents one where all components are selected without specifying a
+ * particular size of the mask, then it writes the string <code>[all
+ * components selected]</code> to the stream. Otherwise, it prints the
+ * component mask in a form like <code>[true,true,true,false]</code>.
*
* @param out The stream to write to.
- * @param mask The mask to write.
- * @return A reference to the first argument.
+ * @param mask The mask to write. @return A reference to the first argument.
*/
std::ostream &operator << (std::ostream &out,
const ComponentMask &mask);
/**
- * Base class for finite elements in arbitrary dimensions. This class
- * provides several fields which describe a specific finite element
- * and which are filled by derived classes. It more or less only
- * offers the fields and access functions which makes it possible to
- * copy finite elements without knowledge of the actual type (linear,
- * quadratic, etc). In particular, the functions to fill the data
- * fields of FEValues and its derived classes are declared.
+ * Base class for finite elements in arbitrary dimensions. This class provides
+ * several fields which describe a specific finite element and which are
+ * filled by derived classes. It more or less only offers the fields and
+ * access functions which makes it possible to copy finite elements without
+ * knowledge of the actual type (linear, quadratic, etc). In particular, the
+ * functions to fill the data fields of FEValues and its derived classes are
+ * declared.
*
- * The interface of this class is very restrictive. The reason is that
- * finite element values should be accessed only by use of FEValues
- * objects. These, together with FiniteElement are responsible to
- * provide an optimized implementation.
+ * The interface of this class is very restrictive. The reason is that finite
+ * element values should be accessed only by use of FEValues objects. These,
+ * together with FiniteElement are responsible to provide an optimized
+ * implementation.
*
- * This class declares the shape functions and their derivatives on
- * the unit cell $[0,1]^d$. The means to transform them onto a given
- * cell in physical space is provided by the FEValues class with a
- * Mapping object.
+ * This class declares the shape functions and their derivatives on the unit
+ * cell $[0,1]^d$. The means to transform them onto a given cell in physical
+ * space is provided by the FEValues class with a Mapping object.
*
- * The different matrices are initialized with the correct size, such
- * that in the derived (concrete) finite element classes, their
- * entries only have to be filled in; no resizing is needed. If the
- * matrices are not defined by a concrete finite element, they should
- * be resized to zero. This way functions using them can find out,
- * that they are missing. On the other hand, it is possible to use
- * finite element classes without implementation of the full
- * functionality, if only part of it is needed. The functionality
- * under consideration here is hanging nodes constraints and grid
- * transfer, respectively.
+ * The different matrices are initialized with the correct size, such that in
+ * the derived (concrete) finite element classes, their entries only have to
+ * be filled in; no resizing is needed. If the matrices are not defined by a
+ * concrete finite element, they should be resized to zero. This way functions
+ * using them can find out, that they are missing. On the other hand, it is
+ * possible to use finite element classes without implementation of the full
+ * functionality, if only part of it is needed. The functionality under
+ * consideration here is hanging nodes constraints and grid transfer,
+ * respectively.
*
- * The <tt>spacedim</tt> parameter has to be used if one wants to
- * solve problems in the boundary element method formulation or in an
- * equivalent one, as it is explained in the Triangulation class. If
- * not specified, this parameter takes the default value <tt>=dim</tt>
- * so that this class can be used to solve problems in the finite
- * element method formulation.
+ * The <tt>spacedim</tt> parameter has to be used if one wants to solve
+ * problems in the boundary element method formulation or in an equivalent
+ * one, as it is explained in the Triangulation class. If not specified, this
+ * parameter takes the default value <tt>=dim</tt> so that this class can be
+ * used to solve problems in the finite element method formulation.
*
* <h3>Components and blocks</h3>
*
- * For vector valued elements shape functions may have nonzero entries
- * in one or several @ref GlossComponent "components" of the vector
- * valued function. If the element is @ref GlossPrimitive "primitive",
- * there is indeed a single component with a nonzero entry for each
- * shape function. This component can be determined by
- * system_to_component_index(), the number of components is
+ * For vector valued elements shape functions may have nonzero entries in one
+ * or several @ref GlossComponent "components" of the vector valued function.
+ * If the element is @ref GlossPrimitive "primitive", there is indeed a single
+ * component with a nonzero entry for each shape function. This component can
+ * be determined by system_to_component_index(), the number of components is
* FiniteElementData::n_components().
*
- * Furthermore, you may want to split your linear system into @ref
- * GlossBlock "blocks" for the use in BlockVector, BlockSparseMatrix,
- * BlockMatrixArray and so on. If you use non-primitive elements, you
- * cannot determine the block number by
- * system_to_component_index(). Instead, you can use
+ * Furthermore, you may want to split your linear system into @ref GlossBlock
+ * "blocks" for the use in BlockVector, BlockSparseMatrix, BlockMatrixArray
+ * and so on. If you use non-primitive elements, you cannot determine the
+ * block number by system_to_component_index(). Instead, you can use
* system_to_block_index(), which will automatically take care of the
- * additional components occupied by vector valued elements. The
- * number of generated blocks can be determined by
- * FiniteElementData::n_blocks().
+ * additional components occupied by vector valued elements. The number of
+ * generated blocks can be determined by FiniteElementData::n_blocks().
*
- * If you decide to operate by base element and multiplicity, the
- * function first_block_of_base() will be helpful.
+ * If you decide to operate by base element and multiplicity, the function
+ * first_block_of_base() will be helpful.
*
* <h3>Support points</h3>
*
- * Since a FiniteElement does not have information on the actual grid
- * cell, it can only provide @ref GlossSupport "support points" on the
- * unit cell. Support points on the actual grid cell must be computed
- * by mapping these points. The class used for this kind of operation
- * is FEValues. In most cases, code of the following type will serve
- * to provide the mapped support points.
+ * Since a FiniteElement does not have information on the actual grid cell, it
+ * can only provide @ref GlossSupport "support points" on the unit cell.
+ * Support points on the actual grid cell must be computed by mapping these
+ * points. The class used for this kind of operation is FEValues. In most
+ * cases, code of the following type will serve to provide the mapped support
+ * points.
*
* @code
* Quadrature<dim> dummy_quadrature (fe.get_unit_support_points());
* Point<dim> mapped_point =
* mapping.transform_unit_to_real_cell (cell, unit_points[i]);
* @endcode
- * This is a shortcut, and as all shortcuts should be used cautiously.
- * If the mapping of all support points is needed, the first variant should
- * be preferred for efficiency.
+ * This is a shortcut, and as all shortcuts should be used cautiously. If the
+ * mapping of all support points is needed, the first variant should be
+ * preferred for efficiency.
*
* @note Finite elements' implementation of the get_unit_support_points()
- * returns these points in the same order as shape functions. As a consequence,
- * the quadrature points accessed above are also ordered in this way. The
- * order of shape functions is typically documented in the class documentation
- * of the various finite element classes.
+ * returns these points in the same order as shape functions. As a
+ * consequence, the quadrature points accessed above are also ordered in this
+ * way. The order of shape functions is typically documented in the class
+ * documentation of the various finite element classes.
*
*
* <h3>Notes on the implementation of derived classes</h3>
*
- * The following sections list the information to be provided by
- * derived classes, depending on the dimension. They are
- * followed by a list of functions helping to generate these values.
+ * The following sections list the information to be provided by derived
+ * classes, depending on the dimension. They are followed by a list of
+ * functions helping to generate these values.
*
* <h4>Finite elements in one dimension</h4>
*
- * Finite elements in one dimension need only set the #restriction
- * and #prolongation matrices. The constructor of this class in one
- * dimension presets the #interface_constraints matrix to have
- * dimension zero. Changing this behaviour in derived classes is
- * generally not a reasonable idea and you risk getting into trouble.
+ * Finite elements in one dimension need only set the #restriction and
+ * #prolongation matrices. The constructor of this class in one dimension
+ * presets the #interface_constraints matrix to have dimension zero. Changing
+ * this behaviour in derived classes is generally not a reasonable idea and
+ * you risk getting into trouble.
*
* <h4>Finite elements in two dimensions</h4>
*
- * In addition to the fields already present in 1D, a constraint
- * matrix is needed, if the finite element has node values located on
- * edges or vertices. These constraints are represented by an $m\times
- * n$-matrix #interface_constraints, where <i>m</i> is the number of
- * degrees of freedom on the refined side without the corner vertices
- * (those dofs on the middle vertex plus those on the two lines), and
- * <i>n</i> is that of the unrefined side (those dofs on the two
- * vertices plus those on the line). The matrix is thus a rectangular
- * one. The $m\times n$ size of the #interface_constraints matrix can
- * also be accessed through the interface_constraints_size() function.
+ * In addition to the fields already present in 1D, a constraint matrix is
+ * needed, if the finite element has node values located on edges or vertices.
+ * These constraints are represented by an $m\times n$-matrix
+ * #interface_constraints, where <i>m</i> is the number of degrees of freedom
+ * on the refined side without the corner vertices (those dofs on the middle
+ * vertex plus those on the two lines), and <i>n</i> is that of the unrefined
+ * side (those dofs on the two vertices plus those on the line). The matrix is
+ * thus a rectangular one. The $m\times n$ size of the #interface_constraints
+ * matrix can also be accessed through the interface_constraints_size()
+ * function.
*
- * The mapping of the dofs onto the indices of the matrix on the
- * unrefined side is as follows: let $d_v$ be the number of dofs on a
- * vertex, $d_l$ that on a line, then $n=0...d_v-1$ refers to the dofs
- * on vertex zero of the unrefined line, $n=d_v...2d_v-1$ to those on
- * vertex one, $n=2d_v...2d_v+d_l-1$ to those on the line.
+ * The mapping of the dofs onto the indices of the matrix on the unrefined
+ * side is as follows: let $d_v$ be the number of dofs on a vertex, $d_l$ that
+ * on a line, then $n=0...d_v-1$ refers to the dofs on vertex zero of the
+ * unrefined line, $n=d_v...2d_v-1$ to those on vertex one,
+ * $n=2d_v...2d_v+d_l-1$ to those on the line.
*
- * Similarly, $m=0...d_v-1$ refers to the dofs on the middle vertex of
- * the refined side (vertex one of child line zero, vertex zero of
- * child line one), $m=d_v...d_v+d_l-1$ refers to the dofs on child
- * line zero, $m=d_v+d_l...d_v+2d_l-1$ refers to the dofs on child
- * line one. Please note that we do not need to reserve space for the
- * dofs on the end vertices of the refined lines, since these must be
- * mapped one-to-one to the appropriate dofs of the vertices of the
- * unrefined line.
+ * Similarly, $m=0...d_v-1$ refers to the dofs on the middle vertex of the
+ * refined side (vertex one of child line zero, vertex zero of child line
+ * one), $m=d_v...d_v+d_l-1$ refers to the dofs on child line zero,
+ * $m=d_v+d_l...d_v+2d_l-1$ refers to the dofs on child line one. Please note
+ * that we do not need to reserve space for the dofs on the end vertices of
+ * the refined lines, since these must be mapped one-to-one to the appropriate
+ * dofs of the vertices of the unrefined line.
*
* It should be noted that it is not possible to distribute a constrained
* degree of freedom to other degrees of freedom which are themselves
- * constrained. Only one level of indirection is allowed. It is not known
- * at the time of this writing whether this is a constraint itself.
+ * constrained. Only one level of indirection is allowed. It is not known at
+ * the time of this writing whether this is a constraint itself.
*
*
* <h4>Finite elements in three dimensions</h4>
* to the usual numbering of degrees of freedom on quadrilaterals.
*
* The numbering of the degrees of freedom on the interior of the refined
- * faces for the index $m$ is as follows: let $d_v$ and $d_l$ be as above,
- * and $d_q$ be the number of degrees of freedom per quadrilateral (and
- * therefore per face), then $m=0...d_v-1$ denote the dofs on the vertex at
- * the center, $m=d_v...5d_v-1$ for the dofs on the vertices at the center
- * of the bounding lines of the quadrilateral,
- * $m=5d_v..5d_v+4*d_l-1$ are for the degrees of freedom on
- * the four lines connecting the center vertex to the outer boundary of the
- * mother face, $m=5d_v+4*d_l...5d_v+4*d_l+8*d_l-1$ for the degrees of freedom
- * on the small lines surrounding the quad,
- * and $m=5d_v+12*d_l...5d_v+12*d_l+4*d_q-1$ for the dofs on the
- * four child faces. Note the direction of the lines at the boundary of the
- * quads, as shown below.
+ * faces for the index $m$ is as follows: let $d_v$ and $d_l$ be as above, and
+ * $d_q$ be the number of degrees of freedom per quadrilateral (and therefore
+ * per face), then $m=0...d_v-1$ denote the dofs on the vertex at the center,
+ * $m=d_v...5d_v-1$ for the dofs on the vertices at the center of the bounding
+ * lines of the quadrilateral, $m=5d_v..5d_v+4*d_l-1$ are for the degrees of
+ * freedom on the four lines connecting the center vertex to the outer
+ * boundary of the mother face, $m=5d_v+4*d_l...5d_v+4*d_l+8*d_l-1$ for the
+ * degrees of freedom on the small lines surrounding the quad, and
+ * $m=5d_v+12*d_l...5d_v+12*d_l+4*d_q-1$ for the dofs on the four child faces.
+ * Note the direction of the lines at the boundary of the quads, as shown
+ * below.
*
* The order of the twelve lines and the four child faces can be extracted
- * from the following sketch, where the overall order of the different
- * dof groups is depicted:
+ * from the following sketch, where the overall order of the different dof
+ * groups is depicted:
* @verbatim
* *--15--4--16--*
* | | |
* | | |
* *--13--3--14--*
* @endverbatim
- * The numbering of vertices and lines, as well as the numbering of
- * children within a line is consistent with the one described in
- * Triangulation. Therefore, this numbering is seen from the
- * outside and inside, respectively, depending on the face.
+ * The numbering of vertices and lines, as well as the numbering of children
+ * within a line is consistent with the one described in Triangulation.
+ * Therefore, this numbering is seen from the outside and inside,
+ * respectively, depending on the face.
*
* The three-dimensional case has a few pitfalls available for derived classes
* that want to implement constraint matrices. Consider the following case:
* Now assume that we want to refine cell 2. We will end up with two faces
* with hanging nodes, namely the faces between cells 1 and 2, as well as
* between cells 2 and 3. Constraints have to be applied to the degrees of
- * freedom on both these faces. The problem is that there is now an edge
- * (the top right one of cell 2) which is part of both faces. The hanging
- * node(s) on this edge are therefore constrained twice, once from both
- * faces. To be meaningful, these constraints of course have to be
- * consistent: both faces have to constrain the hanging nodes on the edge to
- * the same nodes on the coarse edge (and only on the edge, as there can
- * then be no constraints to nodes on the rest of the face), and they have
- * to do so with the same weights. This is sometimes tricky since the nodes
- * on the edge may have different local numbers.
+ * freedom on both these faces. The problem is that there is now an edge (the
+ * top right one of cell 2) which is part of both faces. The hanging node(s)
+ * on this edge are therefore constrained twice, once from both faces. To be
+ * meaningful, these constraints of course have to be consistent: both faces
+ * have to constrain the hanging nodes on the edge to the same nodes on the
+ * coarse edge (and only on the edge, as there can then be no constraints to
+ * nodes on the rest of the face), and they have to do so with the same
+ * weights. This is sometimes tricky since the nodes on the edge may have
+ * different local numbers.
*
* For the constraint matrix this means the following: if a degree of freedom
* on one edge of a face is constrained by some other nodes on the same edge
*
* <h4>Helper functions</h4>
*
- * Construction of a finite element and computation of the matrices
- * described above may be a tedious task, in particular if it has to
- * be performed for several dimensions. Therefore, some
- * functions in FETools have been provided to help with these tasks.
+ * Construction of a finite element and computation of the matrices described
+ * above may be a tedious task, in particular if it has to be performed for
+ * several dimensions. Therefore, some functions in FETools have been provided
+ * to help with these tasks.
*
* <h5>Computing the correct basis from "raw" basis functions</h5>
*
- * First, already the basis of the shape function space may be
- * difficult to implement for arbitrary order and dimension. On the
- * other hand, if the @ref GlossNodes "node values" are given, then
- * the duality relation between node functionals and basis functions
- * defines the basis. As a result, the shape function space may be
- * defined with arbitrary "raw" basis functions, such that the actual
- * finite element basis is computed from linear combinations of
- * them. The coefficients of these combinations are determined by the
+ * First, already the basis of the shape function space may be difficult to
+ * implement for arbitrary order and dimension. On the other hand, if the @ref
+ * GlossNodes "node values" are given, then the duality relation between node
+ * functionals and basis functions defines the basis. As a result, the shape
+ * function space may be defined with arbitrary "raw" basis functions, such
+ * that the actual finite element basis is computed from linear combinations
+ * of them. The coefficients of these combinations are determined by the
* duality of node values.
*
- * Using this matrix allows the construction of the basis of shape
- * functions in two steps.
+ * Using this matrix allows the construction of the basis of shape functions
+ * in two steps.
* <ol>
*
* <li>Define the space of shape functions using an arbitrary basis
- * <i>w<sub>j</sub></i> and compute the matrix <i>M</i> of node
- * functionals <i>N<sub>i</sub></i> applied to these basis functions,
- * such that its entries are <i>m<sub>ij</sub> =
- * N<sub>i</sub>(w<sub>j</sub>)</i>.
+ * <i>w<sub>j</sub></i> and compute the matrix <i>M</i> of node functionals
+ * <i>N<sub>i</sub></i> applied to these basis functions, such that its
+ * entries are <i>m<sub>ij</sub> = N<sub>i</sub>(w<sub>j</sub>)</i>.
*
- * <li>Compute the basis <i>v<sub>j</sub></i> of the finite element
- * shape function space by applying <i>M<sup>-1</sup></i> to the basis
+ * <li>Compute the basis <i>v<sub>j</sub></i> of the finite element shape
+ * function space by applying <i>M<sup>-1</sup></i> to the basis
* <i>w<sub>j</sub></i>.
* </ol>
*
* The function computing the matrix <i>M</i> for you is
* FETools::compute_node_matrix(). It relies on the existence of
- * #generalized_support_points and implementation of interpolate()
- * with VectorSlice argument.
- * See the @ref GlossGeneralizedSupport "glossary entry on generalized support points"
- * for more information.
+ * #generalized_support_points and implementation of interpolate() with
+ * VectorSlice argument. See the @ref GlossGeneralizedSupport "glossary entry
+ * on generalized support points" for more information.
*
- * The piece of code in the constructor of a finite element
- * responsible for this looks like
+ * The piece of code in the constructor of a finite element responsible for
+ * this looks like
* @code
- FullMatrix<double> M(this->dofs_per_cell, this->dofs_per_cell);
- FETools::compute_node_matrix(M, *this);
- this->inverse_node_matrix.reinit(this->dofs_per_cell, this->dofs_per_cell);
- this->inverse_node_matrix.invert(M);
+ * FullMatrix<double> M(this->dofs_per_cell, this->dofs_per_cell);
+ * FETools::compute_node_matrix(M, *this);
+ * this->inverse_node_matrix.reinit(this->dofs_per_cell, this->dofs_per_cell);
+ * this->inverse_node_matrix.invert(M);
* @endcode
* Don't forget to make sure that #unit_support_points or
* #generalized_support_points are initialized before this!
*
* This can be achieved by
* @code
- for (unsigned int i=0; i<GeometryInfo<dim>::children_per_cell; ++i)
- this->prolongation[i].reinit (this->dofs_per_cell,
- this->dofs_per_cell);
- FETools::compute_embedding_matrices (*this, this->prolongation);
+ * for (unsigned int i=0; i<GeometryInfo<dim>::children_per_cell; ++i)
+ * this->prolongation[i].reinit (this->dofs_per_cell,
+ * this->dofs_per_cell);
+ * FETools::compute_embedding_matrices (*this, this->prolongation);
* @endcode
*
* <h5>Computing the #restriction matrices for error estimators</h5>
* <h5>Computing #interface_constraints</h5>
*
* Constraint matrices can be computed semi-automatically using
- * FETools::compute_face_embedding_matrices(). This function computes
- * the representation of the coarse mesh functions by fine mesh
- * functions for each child of a face separately. These matrices must
- * be convoluted into a single rectangular constraint matrix,
- * eliminating degrees of freedom on common vertices and edges as well
- * as on the coarse grid vertices. See the discussion above for details.
+ * FETools::compute_face_embedding_matrices(). This function computes the
+ * representation of the coarse mesh functions by fine mesh functions for each
+ * child of a face separately. These matrices must be convoluted into a single
+ * rectangular constraint matrix, eliminating degrees of freedom on common
+ * vertices and edges as well as on the coarse grid vertices. See the
+ * discussion above for details.
*
* @ingroup febase fe
*
- * @author Wolfgang Bangerth, Guido Kanschat, Ralf Hartmann, 1998, 2000, 2001, 2005
+ * @author Wolfgang Bangerth, Guido Kanschat, Ralf Hartmann, 1998, 2000, 2001,
+ * 2005
*/
template <int dim, int spacedim=dim>
class FiniteElement : public Subscriptor,
* Return the gradient of the @p ith shape function at the point @p p. @p p
* is a point on the reference element, and likewise the gradient is the
* gradient on the unit cell with respect to unit cell coordinates. If the
- * finite element is vector-valued, then return the value of the only
- * non-zero component of the vector value of this shape function. If the
- * shape function has more than one non-zero component (which we refer to
- * with the term non-primitive), then derived classes implementing this
- * function should throw an exception of type
- * ExcShapeFunctionNotPrimitive. In that case, use the
- * shape_grad_component() function.
+ * finite element is vector-valued, then return the value of the only non-
+ * zero component of the vector value of this shape function. If the shape
+ * function has more than one non-zero component (which we refer to with the
+ * term non-primitive), then derived classes implementing this function
+ * should throw an exception of type ExcShapeFunctionNotPrimitive. In that
+ * case, use the shape_grad_component() function.
*
* An ExcUnitShapeValuesDoNotExist is thrown if the shape values of the
* FiniteElement under consideration depends on the shape of the cell in
* cell with respect to unit cell coordinates. If the finite element is
* vector-valued, then return the value of the only non-zero component of
* the vector value of this shape function. If the shape function has more
- * than one non-zero component (which we refer to with the term
- * non-primitive), then derived classes implementing this function should
- * throw an exception of type ExcShapeFunctionNotPrimitive. In that case,
- * use the shape_grad_grad_component() function.
+ * than one non-zero component (which we refer to with the term non-
+ * primitive), then derived classes implementing this function should throw
+ * an exception of type ExcShapeFunctionNotPrimitive. In that case, use the
+ * shape_grad_grad_component() function.
*
* An ExcUnitShapeValuesDoNotExist is thrown if the shape values of the
* FiniteElement under consideration depends on the shape of the cell in
const Point<dim> &p) const;
/**
- * Just like for shape_grad_grad(),
- * but this function will be
- * called when the shape function
- * has more than one non-zero
- * vector component. In that
- * case, this function should
- * return the gradient of the
- * @p component-th vector
- * component of the @p ith shape
- * function at point @p p.
+ * Just like for shape_grad_grad(), but this function will be called when
+ * the shape function has more than one non-zero vector component. In that
+ * case, this function should return the gradient of the @p component-th
+ * vector component of the @p ith shape function at point @p p.
*/
virtual Tensor<2,dim> shape_grad_grad_component (const unsigned int i,
const Point<dim> &p,
*/
/**
- * If, on a vertex, several finite elements are active, the hp code
- * first assigns the degrees of freedom of each of these FEs
- * different global indices. It then calls this function to find out
- * which of them should get identical values, and consequently can
- * receive the same global DoF index. This function therefore
- * returns a list of identities between DoFs of the present finite
- * element object with the DoFs of @p fe_other, which is a reference
- * to a finite element object representing one of the other finite
- * elements active on this particular vertex. The function computes
- * which of the degrees of freedom of the two finite element objects
- * are equivalent, both numbered between zero and the corresponding
- * value of dofs_per_vertex of the two finite elements. The first
- * index of each pair denotes one of the vertex dofs of the present
- * element, whereas the second is the corresponding index of the
- * other finite element.
+ * If, on a vertex, several finite elements are active, the hp code first
+ * assigns the degrees of freedom of each of these FEs different global
+ * indices. It then calls this function to find out which of them should get
+ * identical values, and consequently can receive the same global DoF index.
+ * This function therefore returns a list of identities between DoFs of the
+ * present finite element object with the DoFs of @p fe_other, which is a
+ * reference to a finite element object representing one of the other finite
+ * elements active on this particular vertex. The function computes which of
+ * the degrees of freedom of the two finite element objects are equivalent,
+ * both numbered between zero and the corresponding value of dofs_per_vertex
+ * of the two finite elements. The first index of each pair denotes one of
+ * the vertex dofs of the present element, whereas the second is the
+ * corresponding index of the other finite element.
*/
virtual
std::vector<std::pair<unsigned int, unsigned int> >
hp_vertex_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
/**
- * Same as hp_vertex_dof_indices(), except that the function treats
- * degrees of freedom on lines.
+ * Same as hp_vertex_dof_indices(), except that the function treats degrees
+ * of freedom on lines.
*/
virtual
std::vector<std::pair<unsigned int, unsigned int> >
hp_line_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
/**
- * Same as hp_vertex_dof_indices(), except that the function treats
- * degrees of freedom on quads.
+ * Same as hp_vertex_dof_indices(), except that the function treats degrees
+ * of freedom on quads.
*/
virtual
std::vector<std::pair<unsigned int, unsigned int> >
*
* To explain the concept, consider the case where we would like to know
* whether a degree of freedom on a face, for example as part of an FESystem
- * element, is primitive. Unfortunately, the
- * is_primitive() function in the FiniteElement class takes a cell index, so
- * we would need to find the cell index of the shape function that
- * corresponds to the present face index. This function does that.
+ * element, is primitive. Unfortunately, the is_primitive() function in the
+ * FiniteElement class takes a cell index, so we would need to find the cell
+ * index of the shape function that corresponds to the present face index.
+ * This function does that.
*
* Code implementing this would then look like this:
* @code
* actual faces can be in their standard ordering with respect to the cell
* under consideration, or can be flipped, oriented, etc.
*
- * @param face_dof_index The index of the degree of freedom on a face.
- * This index must be between zero and dofs_per_face.
- * @param face The number of the face this degree of freedom lives on.
- * This number must be between zero and GeometryInfo::faces_per_cell.
- * @param face_orientation One part of the description of the orientation
- * of the face. See @ref GlossFaceOrientation .
- * @param face_flip One part of the description of the orientation
- * of the face. See @ref GlossFaceOrientation .
- * @param face_rotation One part of the description of the orientation
- * of the face. See @ref GlossFaceOrientation .
- * @return The index of this degree of freedom within the set
- * of degrees of freedom on the entire cell. The returned value
- * will be between zero and dofs_per_cell.
- *
- * @note This function exists in this class because that is where it
- * was first implemented. However, it can't really work in the most
- * general case without knowing what element we have. The reason is that
- * when a face is flipped or rotated, we also need to know whether we
- * need to swap the degrees of freedom on this face, or whether they
- * are immune from this. For this, consider the situation of a $Q_3$
- * element in 2d. If face_flip is true, then we need to consider
- * the two degrees of freedom on the edge in reverse order. On the other
- * hand, if the element were a $Q_1^2$, then because the two degrees of
- * freedom on this edge belong to different vector components, they
- * should not be considered in reverse order. What all of this shows is
- * that the function can't work if there are more than one degree of
- * freedom per line or quad, and that in these cases the function will
- * throw an exception pointing out that this functionality will need
- * to be provided by a derived class that knows what degrees of freedom
- * actually represent.
+ * @param face_dof_index The index of the degree of freedom on a face. This
+ * index must be between zero and dofs_per_face.
+ * @param face The number of the face this degree of freedom lives on. This
+ * number must be between zero and GeometryInfo::faces_per_cell.
+ * @param face_orientation One part of the description of the orientation of
+ * the face. See @ref GlossFaceOrientation .
+ * @param face_flip One part of the description of the orientation of the
+ * face. See @ref GlossFaceOrientation .
+ * @param face_rotation One part of the description of the orientation of
+ * the face. See @ref GlossFaceOrientation . @return The index of this
+ * degree of freedom within the set of degrees of freedom on the entire
+ * cell. The returned value will be between zero and dofs_per_cell.
+ *
+ * @note This function exists in this class because that is where it was
+ * first implemented. However, it can't really work in the most general case
+ * without knowing what element we have. The reason is that when a face is
+ * flipped or rotated, we also need to know whether we need to swap the
+ * degrees of freedom on this face, or whether they are immune from this.
+ * For this, consider the situation of a $Q_3$ element in 2d. If face_flip
+ * is true, then we need to consider the two degrees of freedom on the edge
+ * in reverse order. On the other hand, if the element were a $Q_1^2$, then
+ * because the two degrees of freedom on this edge belong to different
+ * vector components, they should not be considered in reverse order. What
+ * all of this shows is that the function can't work if there are more than
+ * one degree of freedom per line or quad, and that in these cases the
+ * function will throw an exception pointing out that this functionality
+ * will need to be provided by a derived class that knows what degrees of
+ * freedom actually represent.
*/
virtual
unsigned int face_to_cell_index (const unsigned int face_dof_index,
get_nonzero_components (const unsigned int i) const;
/**
- * Return in how many vector components the @p ith shape function is
- * non-zero. This value equals the number of entries equal to @p true in the
+ * Return in how many vector components the @p ith shape function is non-
+ * zero. This value equals the number of entries equal to @p true in the
* result of the get_nonzero_components() function.
*
* For most finite element spaces, the result will be equal to one. It is
/**
* Return whether the @p ith shape function is primitive in the sense that
- * the shape function is non-zero in only one vector
- * component. Non-primitive shape functions would then, for example, be
- * those of divergence free ansatz spaces, in which the individual vector
- * components are coupled.
+ * the shape function is non-zero in only one vector component. Non-
+ * primitive shape functions would then, for example, be those of divergence
+ * free ansatz spaces, in which the individual vector components are
+ * coupled.
*
* The result of the function is @p true if and only if the result of
* <tt>n_nonzero_components(i)</tt> is equal to one.
* within this base element.
*
* If the element is not composed of others, then base and instance are
- * always zero, and the index is equal to the number of the shape
- * function. If the element is composed of single instances of other
- * elements (i.e. all with multiplicity one) all of which are scalar, then
- * base values and dof indices within this element are equal to the
+ * always zero, and the index is equal to the number of the shape function.
+ * If the element is composed of single instances of other elements (i.e.
+ * all with multiplicity one) all of which are scalar, then base values and
+ * dof indices within this element are equal to the
* #system_to_component_table. It differs only in case the element is
* composed of other elements and at least one of them is vector-valued
* itself.
* glossary" for more information.
*
* @param scalar An object that represents a single scalar vector component
- * of this finite element.
- * @return A component mask that is false in all components except for the
- * one that corresponds to the argument.
+ * of this finite element. @return A component mask that is false in all
+ * components except for the one that corresponds to the argument.
*/
ComponentMask
component_mask (const FEValuesExtractors::Scalar &scalar) const;
* glossary" for more information.
*
* @param vector An object that represents dim vector components of this
- * finite element.
- * @return A component mask that is false in all components except for the
- * ones that corresponds to the argument.
+ * finite element. @return A component mask that is false in all components
+ * except for the ones that corresponds to the argument.
*/
ComponentMask
component_mask (const FEValuesExtractors::Vector &vector) const;
* from BlockMask to ComponentMask.
*
* @param block_mask The mask that selects individual blocks of the finite
- * element
- * @return A mask that selects those components corresponding to the selected
- * blocks of the input argument.
+ * element @return A mask that selects those components corresponding to the
+ * selected blocks of the input argument.
*/
ComponentMask
component_mask (const BlockMask &block_mask) const;
* exception.
*
* @param scalar An object that represents a single scalar vector component
- * of this finite element.
- * @return A component mask that is false in all components except for the
- * one that corresponds to the argument.
+ * of this finite element. @return A component mask that is false in all
+ * components except for the one that corresponds to the argument.
*/
BlockMask
block_mask (const FEValuesExtractors::Scalar &scalar) const;
* full blocks and does not split blocks of this element.
*
* @param vector An object that represents dim vector components of this
- * finite element.
- * @return A component mask that is false in all components except for the
- * ones that corresponds to the argument.
+ * finite element. @return A component mask that is false in all components
+ * except for the ones that corresponds to the argument.
*/
BlockMask
block_mask (const FEValuesExtractors::Vector &vector) const;
*
* @param sym_tensor An object that represents dim*(dim+1)/2 components of
* this finite element that are jointly to be interpreted as forming a
- * symmetric tensor.
- * @return A component mask that is false in all components except for the
- * ones that corresponds to the argument.
+ * symmetric tensor. @return A component mask that is false in all
+ * components except for the ones that corresponds to the argument.
*/
BlockMask
block_mask (const FEValuesExtractors::SymmetricTensor<2> &sym_tensor) const;
* exception.
*
* @param component_mask The mask that selects individual components of the
- * finite element
- * @return A mask that selects those blocks corresponding to the selected
- * blocks of the input argument.
+ * finite element @return A mask that selects those blocks corresponding to
+ * the selected blocks of the input argument.
*/
BlockMask
block_mask (const ComponentMask &component_mask) const;
*
* See the class documentation for details on support points.
*
- * @note Finite elements' implementation of this function
- * returns these points in the same order as shape functions. The
- * order of shape functions is typically documented in the class documentation
- * of the various finite element classes. In particular, shape functions (and
- * consequently the mapped quadrature points discussed in the class documentation
- * of this class) will then traverse first those shape functions
- * located on vertices, then on lines, then on quads, etc.
+ * @note Finite elements' implementation of this function returns these
+ * points in the same order as shape functions. The order of shape functions
+ * is typically documented in the class documentation of the various finite
+ * element classes. In particular, shape functions (and consequently the
+ * mapped quadrature points discussed in the class documentation of this
+ * class) will then traverse first those shape functions located on
+ * vertices, then on lines, then on quads, etc.
*
* @note If this element implements support points, then it will return one
- * such point per shape function. Since multiple shape functions may be defined
- * at the same location, the support points returned here may be duplicated. An
- * example would be an element of the kind <code>FESystem(FE_Q(1),3)</code>
- * for which each support point would appear three times in the returned array.
+ * such point per shape function. Since multiple shape functions may be
+ * defined at the same location, the support points returned here may be
+ * duplicated. An example would be an element of the kind
+ * <code>FESystem(FE_Q(1),3)</code> for which each support point would
+ * appear three times in the returned array.
*/
const std::vector<Point<dim> > &
get_unit_support_points () const;
* degrees of freedom from both sides of a face (or from all adjacent
* elements to a vertex) would be identified with each other, which is not
* what we would like to have). Logically, these degrees of freedom are
- * therefore defined to belong to the cell, rather than the face or
- * vertex. In that case, the returned element would therefore have length
- * zero.
+ * therefore defined to belong to the cell, rather than the face or vertex.
+ * In that case, the returned element would therefore have length zero.
*
* If the finite element defines support points, then their number equals
* the number of degrees of freedom on the face (#dofs_per_face). The order
has_generalized_face_support_points () const;
/**
- * For a given degree of freedom, return whether it is logically
- * associated with a vertex, line, quad or hex.
- *
- * For instance, for continuous finite elements this coincides with
- * the lowest dimensional object the support point of the degree of
- * freedom lies on. To give an example, for $Q_1$ elements in 3d,
- * every degree of freedom is defined by a shape function that we
- * get by interpolating using support points that lie on the
- * vertices of the cell. The support of these points of course
- * extends to all edges connected to this vertex, as well
- * as the adjacent faces and the cell interior, but we say that
- * logically the degree of freedom is associated with the vertex as
- * this is the lowest-dimensional object it is associated with.
- * Likewise, for $Q_2$ elements in 3d, the degrees of freedom
- * with support points at edge midpoints would yield a value of
- * GeometryPrimitive::line from this function, whereas those on
- * the centers of faces in 3d would return GeometryPrimitive::quad.
- *
- * To make this more formal, the kind of object returned by
- * this function represents the object so that the support of the
- * shape function corresponding to the degree of freedom, (i.e., that
- * part of the domain where the function "lives") is the union
- * of all of the cells sharing this object. To return to the example
- * above, for $Q_2$ in 3d, the shape function with support point at
- * an edge midpoint has support on all cells that share the edge and
- * not only the cells that share the adjacent faces, and consequently
- * the function will return GeometryPrimitive::line.
- *
- * On the other hand, for discontinuous elements of type $DGQ_2$,
- * a degree of freedom associated with an interpolation polynomial
- * that has its support point physically located at a line bounding
- * a cell, but is nonzero only on one cell. Consequently, it is
- * logically associated with the interior of that cell (i.e., with a
- * GeometryPrimitive::quad in 2d and a GeometryPrimitive::hex in 3d).
- *
- * @param[in] cell_dof_index The index of a shape function or
- * degree of freedom. This index must be in the range
- * <code>[0,dofs_per_cell)</code>.
- *
- * @note The integer value of the object returned by this function
- * equals the dimensionality of the object it describes, and can
- * consequently be used in generic programming paradigms. For
- * example, if a degree of freedom is associated with a vertex,
- * then this function returns GeometryPrimitive::vertex, which has
- * a numeric value of zero (the dimensionality of a vertex).
+ * For a given degree of freedom, return whether it is logically associated
+ * with a vertex, line, quad or hex.
+ *
+ * For instance, for continuous finite elements this coincides with the
+ * lowest dimensional object the support point of the degree of freedom lies
+ * on. To give an example, for $Q_1$ elements in 3d, every degree of freedom
+ * is defined by a shape function that we get by interpolating using support
+ * points that lie on the vertices of the cell. The support of these points
+ * of course extends to all edges connected to this vertex, as well as the
+ * adjacent faces and the cell interior, but we say that logically the
+ * degree of freedom is associated with the vertex as this is the lowest-
+ * dimensional object it is associated with. Likewise, for $Q_2$ elements in
+ * 3d, the degrees of freedom with support points at edge midpoints would
+ * yield a value of GeometryPrimitive::line from this function, whereas
+ * those on the centers of faces in 3d would return GeometryPrimitive::quad.
+ *
+ * To make this more formal, the kind of object returned by this function
+ * represents the object so that the support of the shape function
+ * corresponding to the degree of freedom, (i.e., that part of the domain
+ * where the function "lives") is the union of all of the cells sharing this
+ * object. To return to the example above, for $Q_2$ in 3d, the shape
+ * function with support point at an edge midpoint has support on all cells
+ * that share the edge and not only the cells that share the adjacent faces,
+ * and consequently the function will return GeometryPrimitive::line.
+ *
+ * On the other hand, for discontinuous elements of type $DGQ_2$, a degree
+ * of freedom associated with an interpolation polynomial that has its
+ * support point physically located at a line bounding a cell, but is
+ * nonzero only on one cell. Consequently, it is logically associated with
+ * the interior of that cell (i.e., with a GeometryPrimitive::quad in 2d and
+ * a GeometryPrimitive::hex in 3d).
+ *
+ * @param[in] cell_dof_index The index of a shape function or degree of
+ * freedom. This index must be in the range <code>[0,dofs_per_cell)</code>.
+ *
+ * @note The integer value of the object returned by this function equals
+ * the dimensionality of the object it describes, and can consequently be
+ * used in generic programming paradigms. For example, if a degree of
+ * freedom is associated with a vertex, then this function returns
+ * GeometryPrimitive::vertex, which has a numeric value of zero (the
+ * dimensionality of a vertex).
*/
GeometryPrimitive
get_associated_geometry_primitive (const unsigned int cell_dof_index) const;
* For faces with non-standard face_orientation in 3D, the dofs on faces
* (quads) have to be permuted in order to be combined with the correct
* shape functions. Given a local dof @p index on a quad, return the shift
- * in the local index, if the face has non-standard face_orientation,
- * i.e. <code>old_index + shift = new_index</code>. In 2D and 1D there is no
- * need for permutation so the vector is empty. In 3D it has the size of
- * <code> #dofs_per_quad * 8 </code>, where 8 is the number of orientations,
- * a face can be in (all combinations of the three bool flags
- * face_orientation, face_flip and face_rotation).
+ * in the local index, if the face has non-standard face_orientation, i.e.
+ * <code>old_index + shift = new_index</code>. In 2D and 1D there is no need
+ * for permutation so the vector is empty. In 3D it has the size of <code>
+ * #dofs_per_quad * 8 </code>, where 8 is the number of orientations, a face
+ * can be in (all combinations of the three bool flags face_orientation,
+ * face_flip and face_rotation).
*
* The standard implementation fills this with zeros, i.e. no permuatation
* at all. Derived finite element classes have to fill this Table with the
* For lines with non-standard line_orientation in 3D, the dofs on lines
* have to be permuted in order to be combined with the correct shape
* functions. Given a local dof @p index on a line, return the shift in the
- * local index, if the line has non-standard line_orientation,
- * i.e. <code>old_index + shift = new_index</code>. In 2D and 1D there is no
- * need for permutation so the vector is empty. In 3D it has the size of
+ * local index, if the line has non-standard line_orientation, i.e.
+ * <code>old_index + shift = new_index</code>. In 2D and 1D there is no need
+ * for permutation so the vector is empty. In 3D it has the size of
* #dofs_per_line.
*
* The standard implementation fills this with zeros, i.e. no permutation at
* case the element is composed of other elements and at least one of them
* is vector-valued itself.
*
- * This array has valid values also in the case of vector-valued
- * (i.e. non-primitive) shape functions, in contrast to the
+ * This array has valid values also in the case of vector-valued (i.e. non-
+ * primitive) shape functions, in contrast to the
* #system_to_component_table.
*/
std::vector<std::pair<std::pair<unsigned int,unsigned int>,unsigned int> >
* The base element establishing a component.
*
* For each component number <tt>c</tt>, the entries have the following
- * meaning:
- * <dl>
- * <dt><tt>table[c].first.first</tt></dt>
- * <dd>Number of the base element for <tt>c</tt>.</dd>
- * <dt><tt>table[c].first.second</tt></dt>
+ * meaning: <dl> <dt><tt>table[c].first.first</tt></dt> <dd>Number of the
+ * base element for <tt>c</tt>.</dd> <dt><tt>table[c].first.second</tt></dt>
* <dd>Component in the base element for <tt>c</tt>.</dd>
- * <dt><tt>table[c].second</tt></dt>
- * <dd>Multiple of the base element for <tt>c</tt>.</dd>
- * </dl>
+ * <dt><tt>table[c].second</tt></dt> <dd>Multiple of the base element for
+ * <tt>c</tt>.</dd> </dl>
*
* This variable is set to the correct size by the constructor of this
* class, but needs to be initialized by derived classes, unless its size is
- * one and the only entry is a zero, which is the case for scalar
- * elements. In that case, the initialization by the base class is
- * sufficient.
+ * one and the only entry is a zero, which is the case for scalar elements.
+ * In that case, the initialization by the base class is sufficient.
*/
std::vector<std::pair<std::pair<unsigned int, unsigned int>, unsigned int> >
component_to_base_table;
* vector component of the element. This is based on the fact that all the
* shape functions that belong to the same vector component must necessarily
* behave in the same way, to make things reasonable. However, the problem
- * is that it is sometimes impossible to query this flag in the
- * vector-valued case: this used to be done with the
- * #system_to_component_index function that returns which vector component a
- * shape function is associated with. The point is that since we now support
- * shape functions that are associated with more than one vector component
- * (for example the shape functions of Raviart-Thomas, or Nedelec elements),
- * that function can no more be used, so it can be difficult to find out
- * which for vector component we would like to query the
- * restriction-is-additive flags.
+ * is that it is sometimes impossible to query this flag in the vector-
+ * valued case: this used to be done with the #system_to_component_index
+ * function that returns which vector component a shape function is
+ * associated with. The point is that since we now support shape functions
+ * that are associated with more than one vector component (for example the
+ * shape functions of Raviart-Thomas, or Nedelec elements), that function
+ * can no more be used, so it can be difficult to find out which for vector
+ * component we would like to query the restriction-is-additive flags.
*/
const std::vector<bool> restriction_is_additive_flags;
/**
* Return the size of interface constraint matrices. Since this is needed in
* every derived finite element class when initializing their size, it is
- * placed into this function, to avoid having to recompute the
- * dimension-dependent size of these matrices each time.
+ * placed into this function, to avoid having to recompute the dimension-
+ * dependent size of these matrices each time.
*
* Note that some elements do not implement the interface constraints for
* certain polynomial degrees. In this case, this function still returns the
/**
* Given the pattern of nonzero components for each shape function, compute
- * for each entry how many components are non-zero for each shape
- * function. This function is used in the constructor of this class.
+ * for each entry how many components are non-zero for each shape function.
+ * This function is used in the constructor of this class.
*/
static
std::vector<unsigned int>
/**
* Implementation of Arnold-Boffi-Falk (ABF) elements, conforming with the
- * space H<sup>div</sup>. These elements generate vector fields with
- * normal components continuous between mesh cells.
+ * space H<sup>div</sup>. These elements generate vector fields with normal
+ * components continuous between mesh cells.
*
* These elements are based on an article from Arnold, Boffi and Falk:
- * Quadrilateral H(div) finite elements, SIAM J. Numer. Anal.
- * Vol.42, No.6, pp.2429-2451
+ * Quadrilateral H(div) finite elements, SIAM J. Numer. Anal. Vol.42, No.6,
+ * pp.2429-2451
*
- * In this article, the authors demonstrate that the usual RT elements
- * and also BDM and other proposed finite dimensional subspaces of
- * H(div) do not work properly on arbitrary FE grids. I.e. the
- * convergence rates deteriorate on these meshes. As a solution the
- * authors propose the ABF elements, which are implemented in this
- * module.
+ * In this article, the authors demonstrate that the usual RT elements and
+ * also BDM and other proposed finite dimensional subspaces of H(div) do not
+ * work properly on arbitrary FE grids. I.e. the convergence rates deteriorate
+ * on these meshes. As a solution the authors propose the ABF elements, which
+ * are implemented in this module.
*
- * This class is not implemented for the codimension one case
- * (<tt>spacedim != dim</tt>).
+ * This class is not implemented for the codimension one case (<tt>spacedim !=
+ * dim</tt>).
*
* @todo Even if this element is implemented for two and three space
- * dimensions, the definition of the node values relies on
- * consistently oriented faces in 3D. Therefore, care should be taken
- * on complicated meshes.
+ * dimensions, the definition of the node values relies on consistently
+ * oriented faces in 3D. Therefore, care should be taken on complicated
+ * meshes.
*
* <h3>Interpolation</h3>
*
- * The @ref GlossInterpolation "interpolation" operators associated
- * with the RT element are constructed such that interpolation and
- * computing the divergence are commuting operations. We require this
- * from interpolating arbitrary functions as well as the #restriction
- * matrices. It can be achieved by two interpolation schemes, the
- * simplified one in FE_RaviartThomasNodal and the original one here:
+ * The @ref GlossInterpolation "interpolation" operators associated with the
+ * RT element are constructed such that interpolation and computing the
+ * divergence are commuting operations. We require this from interpolating
+ * arbitrary functions as well as the #restriction matrices. It can be
+ * achieved by two interpolation schemes, the simplified one in
+ * FE_RaviartThomasNodal and the original one here:
*
* <h4>Node values on edges/faces</h4>
*
- * On edges or faces, the @ref GlossNodes "node values" are the moments of
- * the normal component of the interpolated function with respect to
- * the traces of the RT polynomials. Since the normal trace of the RT
- * space of degree <i>k</i> on an edge/face is the space
- * <i>Q<sub>k</sub></i>, the moments are taken with respect to this
- * space.
+ * On edges or faces, the @ref GlossNodes "node values" are the moments of the
+ * normal component of the interpolated function with respect to the traces of
+ * the RT polynomials. Since the normal trace of the RT space of degree
+ * <i>k</i> on an edge/face is the space <i>Q<sub>k</sub></i>, the moments are
+ * taken with respect to this space.
*
* <h4>Interior node values</h4>
*
- * Higher order RT spaces have interior nodes. These are moments taken
- * with respect to the gradient of functions in <i>Q<sub>k</sub></i>
- * on the cell (this space is the matching space for RT<sub>k</sub> in
- * a mixed formulation).
+ * Higher order RT spaces have interior nodes. These are moments taken with
+ * respect to the gradient of functions in <i>Q<sub>k</sub></i> on the cell
+ * (this space is the matching space for RT<sub>k</sub> in a mixed
+ * formulation).
*
* <h4>Generalized support points</h4>
*
* The node values above rely on integrals, which will be computed by
- * quadrature rules themselves. The generalized support points are a
- * set of points such that this quadrature can be performed with
- * sufficient accuracy. The points needed are those of
- * QGauss<sub>k+1</sub> on each face as well as QGauss<sub>k</sub> in
- * the interior of the cell (or none for RT<sub>0</sub>).
- * See the @ref GlossGeneralizedSupport "glossary entry on generalized support points"
- * for more information.
+ * quadrature rules themselves. The generalized support points are a set of
+ * points such that this quadrature can be performed with sufficient accuracy.
+ * The points needed are those of QGauss<sub>k+1</sub> on each face as well as
+ * QGauss<sub>k</sub> in the interior of the cell (or none for
+ * RT<sub>0</sub>). See the @ref GlossGeneralizedSupport "glossary entry on
+ * generalized support points" for more information.
*
*
- * @author Oliver Kayser-Herold, 2006, based on previous work
- * by Guido Kanschat and Wolfgang Bangerth
+ * @author Oliver Kayser-Herold, 2006, based on previous work by Guido
+ * Kanschat and Wolfgang Bangerth
*/
template <int dim>
class FE_ABF : public FE_PolyTensor<PolynomialsABF<dim>, dim>
{
public:
/**
- * Constructor for the ABF
- * element of degree @p p.
+ * Constructor for the ABF element of degree @p p.
*/
FE_ABF (const unsigned int p);
/**
- * Return a string that uniquely
- * identifies a finite
- * element. This class returns
- * <tt>FE_ABF<dim>(degree)</tt>, with
- * @p dim and @p degree
- * replaced by appropriate
- * values.
+ * Return a string that uniquely identifies a finite element. This class
+ * returns <tt>FE_ABF<dim>(degree)</tt>, with @p dim and @p degree replaced
+ * by appropriate values.
*/
virtual std::string get_name () const;
private:
/**
- * The order of the
- * ABF element. The
- * lowest order elements are
- * usually referred to as RT0,
- * even though their shape
- * functions are piecewise
+ * The order of the ABF element. The lowest order elements are usually
+ * referred to as RT0, even though their shape functions are piecewise
* quadratics.
*/
const unsigned int rt_order;
/**
- * Only for internal use. Its
- * full name is
- * @p get_dofs_per_object_vector
- * function and it creates the
- * @p dofs_per_object vector that is
- * needed within the constructor to
- * be passed to the constructor of
- * @p FiniteElementData.
+ * Only for internal use. Its full name is @p get_dofs_per_object_vector
+ * function and it creates the @p dofs_per_object vector that is needed
+ * within the constructor to be passed to the constructor of @p
+ * FiniteElementData.
*/
static std::vector<unsigned int>
get_dpo_vector (const unsigned int degree);
/**
- * Initialize the @p
- * generalized_support_points
- * field of the FiniteElement
- * class and fill the tables with
- * interpolation weights
- * (#boundary_weights and
- * #interior_weights). Called
- * from the constructor.
- *
- * See the @ref GlossGeneralizedSupport "glossary entry on generalized support points"
- * for more information.
+ * Initialize the @p generalized_support_points field of the FiniteElement
+ * class and fill the tables with interpolation weights (#boundary_weights
+ * and #interior_weights). Called from the constructor.
+ *
+ * See the @ref GlossGeneralizedSupport "glossary entry on generalized
+ * support points" for more information.
*/
void initialize_support_points (const unsigned int rt_degree);
/**
- * Initialize the interpolation
- * from functions on refined mesh
- * cells onto the father
- * cell. According to the
- * philosophy of the
- * Raviart-Thomas element, this
- * restriction operator preserves
- * the divergence of a function
+ * Initialize the interpolation from functions on refined mesh cells onto
+ * the father cell. According to the philosophy of the Raviart-Thomas
+ * element, this restriction operator preserves the divergence of a function
* weakly.
*/
void initialize_restriction ();
/**
- * Given a set of flags indicating
- * what quantities are requested
- * from a @p FEValues object,
- * return which of these can be
- * precomputed once and for
- * all. Often, the values of
- * shape function at quadrature
- * points can be precomputed, for
- * example, in which case the
- * return value of this function
- * would be the logical and of
- * the input @p flags and
- * @p update_values.
+ * Given a set of flags indicating what quantities are requested from a @p
+ * FEValues object, return which of these can be precomputed once and for
+ * all. Often, the values of shape function at quadrature points can be
+ * precomputed, for example, in which case the return value of this function
+ * would be the logical and of the input @p flags and @p update_values.
*
- * For the present kind of finite
- * element, this is exactly the
- * case.
+ * For the present kind of finite element, this is exactly the case.
*/
virtual UpdateFlags update_once (const UpdateFlags flags) const;
/**
- * This is the opposite to the
- * above function: given a set of
- * flags indicating what we want
- * to know, return which of these
- * need to be computed each time
- * we visit a new cell.
+ * This is the opposite to the above function: given a set of flags
+ * indicating what we want to know, return which of these need to be
+ * computed each time we visit a new cell.
*
- * If for the computation of one
- * quantity something else is
- * also required (for example, we
- * often need the covariant
- * transformation when gradients
- * need to be computed), include
- * this in the result as well.
+ * If for the computation of one quantity something else is also required
+ * (for example, we often need the covariant transformation when gradients
+ * need to be computed), include this in the result as well.
*/
virtual UpdateFlags update_each (const UpdateFlags flags) const;
/**
* Fields of cell-independent data.
*
- * For information about the
- * general purpose of this class,
- * see the documentation of the
- * base class.
+ * For information about the general purpose of this class, see the
+ * documentation of the base class.
*/
class InternalData : public FiniteElement<dim>::InternalDataBase
{
public:
/**
- * Array with shape function
- * values in quadrature
- * points. There is one row
- * for each shape function,
- * containing values for each
- * quadrature point. Since
- * the shape functions are
- * vector-valued (with as
- * many components as there
- * are space dimensions), the
- * value is a tensor.
+ * Array with shape function values in quadrature points. There is one row
+ * for each shape function, containing values for each quadrature point.
+ * Since the shape functions are vector-valued (with as many components as
+ * there are space dimensions), the value is a tensor.
*
- * In this array, we store
- * the values of the shape
- * function in the quadrature
- * points on the unit
- * cell. The transformation
- * to the real space cell is
- * then simply done by
- * multiplication with the
- * Jacobian of the mapping.
+ * In this array, we store the values of the shape function in the
+ * quadrature points on the unit cell. The transformation to the real
+ * space cell is then simply done by multiplication with the Jacobian of
+ * the mapping.
*/
std::vector<std::vector<Tensor<1,dim> > > shape_values;
/**
- * Array with shape function
- * gradients in quadrature
- * points. There is one
- * row for each shape
- * function, containing
- * values for each quadrature
+ * Array with shape function gradients in quadrature points. There is one
+ * row for each shape function, containing values for each quadrature
* point.
*
- * We store the gradients in
- * the quadrature points on
- * the unit cell. We then
- * only have to apply the
- * transformation (which is a
- * matrix-vector
- * multiplication) when
- * visiting an actual cell.
+ * We store the gradients in the quadrature points on the unit cell. We
+ * then only have to apply the transformation (which is a matrix-vector
+ * multiplication) when visiting an actual cell.
*/
std::vector<std::vector<Tensor<2,dim> > > shape_gradients;
};
/**
- * These are the factors
- * multiplied to a function in
- * the
- * #generalized_face_support_points
- * when computing the
- * integration. They are
- * organized such that there is
- * one row for each generalized
- * face support point and one
- * column for each degree of
- * freedom on the face.
+ * These are the factors multiplied to a function in the
+ * #generalized_face_support_points when computing the integration. They are
+ * organized such that there is one row for each generalized face support
+ * point and one column for each degree of freedom on the face.
*/
Table<2, double> boundary_weights;
/**
- * Precomputed factors for
- * interpolation of interior
- * degrees of freedom. The
- * rationale for this Table is
- * the same as for
- * #boundary_weights. Only, this
- * table has a third coordinate
- * for the space direction of the
- * component evaluated.
+ * Precomputed factors for interpolation of interior degrees of freedom. The
+ * rationale for this Table is the same as for #boundary_weights. Only, this
+ * table has a third coordinate for the space direction of the component
+ * evaluated.
*/
Table<3, double> interior_weights;
/**
- * These are the factors
- * multiplied to a function in
- * the
- * #generalized_face_support_points
- * when computing the
- * integration. They are
- * organized such that there is
- * one row for each generalized
- * face support point and one
- * column for each degree of
- * freedom on the face.
+ * These are the factors multiplied to a function in the
+ * #generalized_face_support_points when computing the integration. They are
+ * organized such that there is one row for each generalized face support
+ * point and one column for each degree of freedom on the face.
*/
Table<2, double> boundary_weights_abf;
/**
- * Precomputed factors for
- * interpolation of interior
- * degrees of freedom. The
- * rationale for this Table is
- * the same as for
- * #boundary_weights. Only, this
- * table has a third coordinate
- * for the space direction of the
- * component evaluated.
+ * Precomputed factors for interpolation of interior degrees of freedom. The
+ * rationale for this Table is the same as for #boundary_weights. Only, this
+ * table has a third coordinate for the space direction of the component
+ * evaluated.
*/
Table<3, double> interior_weights_abf;
/**
- * Allow access from other
- * dimensions.
+ * Allow access from other dimensions.
*/
template <int dim1> friend class FE_ABF;
};
* to the implementation in a concrete finite element class.
*
* @ingroup febase
- * @author Wolfgang Bangerth, Guido Kanschat, 1998, 1999, 2000, 2001, 2003, 2005
+ * @author Wolfgang Bangerth, Guido Kanschat, 1998, 1999, 2000, 2001, 2003,
+ * 2005
*/
template <int dim>
class FiniteElementData
* <li> <i>H<sup>2</sup></i> implies that the function is continuously
* differentiable over cell boundaries.
*
- * <li> <i>L<sup>2</sup></i> indicates that the element is
- * discontinuous. Since discontinuous elements have no topological couplings
- * between grid cells and code may actually depend on this property,
- * <i>L<sup>2</sup></i> conformity is handled in a special way in the sense
+ * <li> <i>L<sup>2</sup></i> indicates that the element is discontinuous.
+ * Since discontinuous elements have no topological couplings between grid
+ * cells and code may actually depend on this property, <i>L<sup>2</sup></i>
+ * conformity is handled in a special way in the sense
* that it is <b>not</b> implied by any higher conformity. </ol>
*
* In order to test if a finite element conforms to a certain space, use
*
* @todo Restriction matrices are missing.
*
- * The matching pressure space for FE_BDM of order <i>k</i> is the
- * element FE_DGP of order <i>k</i>.
+ * The matching pressure space for FE_BDM of order <i>k</i> is the element
+ * FE_DGP of order <i>k</i>.
*
- * The BDM element of order @p p has <i>p+1</i> degrees of freedom on
- * each face. These are implemented as the function values in the
- * <i>p+1</i> Gauss points on each face.
+ * The BDM element of order @p p has <i>p+1</i> degrees of freedom on each
+ * face. These are implemented as the function values in the <i>p+1</i> Gauss
+ * points on each face.
*
* Additionally, for order greater or equal 2, we have additional
* <i>p(p-1)</i>, the number of vector valued polynomials in
- * <i>P<sub>p</sub></i>, interior degrees of freedom. These are the
- * vector function values in the first <i>p(p-1)/2</i> of the
- * <i>p<sup>2</sup></i> Gauss points in the cell.
+ * <i>P<sub>p</sub></i>, interior degrees of freedom. These are the vector
+ * function values in the first <i>p(p-1)/2</i> of the <i>p<sup>2</sup></i>
+ * Gauss points in the cell.
*/
template <int dim>
class FE_BDM
{
public:
/**
- * Constructor for the BDM
- * element of degree @p p.
+ * Constructor for the BDM element of degree @p p.
*/
FE_BDM (const unsigned int p);
/**
- * Return a string that uniquely
- * identifies a finite
- * element. This class returns
- * <tt>FE_BDM<dim>(degree)</tt>, with
- * @p dim and @p degree
- * replaced by appropriate
- * values.
+ * Return a string that uniquely identifies a finite element. This class
+ * returns <tt>FE_BDM<dim>(degree)</tt>, with @p dim and @p degree replaced
+ * by appropriate values.
*/
virtual std::string get_name () const;
const VectorSlice<const std::vector<std::vector<double> > > &values) const;
private:
/**
- * Only for internal use. Its
- * full name is
- * @p get_dofs_per_object_vector
- * function and it creates the
- * @p dofs_per_object vector that is
- * needed within the constructor to
- * be passed to the constructor of
- * @p FiniteElementData.
+ * Only for internal use. Its full name is @p get_dofs_per_object_vector
+ * function and it creates the @p dofs_per_object vector that is needed
+ * within the constructor to be passed to the constructor of @p
+ * FiniteElementData.
*/
static std::vector<unsigned int>
get_dpo_vector (const unsigned int degree);
/**
- * Compute the vector used for
- * the
- * @p restriction_is_additive
- * field passed to the base
- * class's constructor.
+ * Compute the vector used for the @p restriction_is_additive field passed
+ * to the base class's constructor.
*/
static std::vector<bool>
get_ria_vector (const unsigned int degree);
/**
- * Initialize the
- * FiniteElement<dim>::generalized_support_points
- * and FiniteElement<dim>::generalized_face_support_points
- * fields. Called from the
- * constructor.
- * See the @ref GlossGeneralizedSupport "glossary entry on generalized support points"
- * for more information.
+ * Initialize the FiniteElement<dim>::generalized_support_points and
+ * FiniteElement<dim>::generalized_face_support_points fields. Called from
+ * the constructor. See the @ref GlossGeneralizedSupport "glossary entry on
+ * generalized support points" for more information.
*/
void initialize_support_points (const unsigned int rt_degree);
/**
- * The values in the interior
- * support points of the
- * polynomials needed as test
- * functions. The outer vector is
- * indexed by quadrature points,
- * the inner by the test
- * function.
+ * The values in the interior support points of the polynomials needed as
+ * test functions. The outer vector is indexed by quadrature points, the
+ * inner by the test function.
*/
std::vector<std::vector<double> > test_values;
};
/**
* DG elements based on vector valued polynomials.
*
- * These elements use vector valued polynomial spaces as they have
- * been introduced for H<sup>div</sup> and H<sup>curl</sup> conforming
- * finite elements, but do not use the usual continuity of these
- * elements. Thus, they are suitable for DG and hybrid formulations
- * involving these function spaces.
+ * These elements use vector valued polynomial spaces as they have been
+ * introduced for H<sup>div</sup> and H<sup>curl</sup> conforming finite
+ * elements, but do not use the usual continuity of these elements. Thus, they
+ * are suitable for DG and hybrid formulations involving these function
+ * spaces.
*
- * The template argument <tt>POLY</tt> refers to a vector valued
- * polynomial space like PolynomialsRaviartThomas or
- * PolynomialsNedelec. Note that the dimension of the polynomial space
- * and the argument <tt>dim</tt> must coincide.
+ * The template argument <tt>POLY</tt> refers to a vector valued polynomial
+ * space like PolynomialsRaviartThomas or PolynomialsNedelec. Note that the
+ * dimension of the polynomial space and the argument <tt>dim</tt> must
+ * coincide.
*
* @ingroup febase
* @author Guido Kanschat
{
public:
/**
- * Constructor for the vector
- * element of degree @p p.
+ * Constructor for the vector element of degree @p p.
*/
FE_DGVector (const unsigned int p, MappingType m);
public:
FiniteElement<dim, spacedim> *clone() const;
/**
- * Return a string that uniquely
- * identifies a finite
- * element. This class returns
- * <tt>FE_RaviartThomas<dim>(degree)</tt>, with
- * @p dim and @p degree
- * replaced by appropriate
- * values.
+ * Return a string that uniquely identifies a finite element. This class
+ * returns <tt>FE_RaviartThomas<dim>(degree)</tt>, with @p dim and @p degree
+ * replaced by appropriate values.
*/
virtual std::string get_name () const;
private:
/**
- * Only for internal use. Its
- * full name is
- * @p get_dofs_per_object_vector
- * function and it creates the
- * @p dofs_per_object vector that is
- * needed within the constructor to
- * be passed to the constructor of
- * @p FiniteElementData.
+ * Only for internal use. Its full name is @p get_dofs_per_object_vector
+ * function and it creates the @p dofs_per_object vector that is needed
+ * within the constructor to be passed to the constructor of @p
+ * FiniteElementData.
*/
static std::vector<unsigned int>
get_dpo_vector (const unsigned int degree);
/**
- * Initialize the @p
- * generalized_support_points
- * field of the FiniteElement
- * class and fill the tables with
- * @p interior_weights. Called
- * from the constructor.
- *
- * See the @ref GlossGeneralizedSupport "glossary entry on generalized support points"
- * for more information.
+ * Initialize the @p generalized_support_points field of the FiniteElement
+ * class and fill the tables with @p interior_weights. Called from the
+ * constructor.
+ *
+ * See the @ref GlossGeneralizedSupport "glossary entry on generalized
+ * support points" for more information.
*/
void initialize_support_points (const unsigned int degree);
/**
- * Initialize the interpolation
- * from functions on refined mesh
- * cells onto the father
- * cell. According to the
- * philosophy of the
- * Raviart-Thomas element, this
- * restriction operator preserves
- * the divergence of a function
+ * Initialize the interpolation from functions on refined mesh cells onto
+ * the father cell. According to the philosophy of the Raviart-Thomas
+ * element, this restriction operator preserves the divergence of a function
* weakly.
*/
void initialize_restriction ();
/**
* Fields of cell-independent data.
*
- * For information about the
- * general purpose of this class,
- * see the documentation of the
- * base class.
+ * For information about the general purpose of this class, see the
+ * documentation of the base class.
*/
class InternalData : public FiniteElement<dim>::InternalDataBase
{
public:
/**
- * Array with shape function
- * values in quadrature
- * points. There is one row
- * for each shape function,
- * containing values for each
- * quadrature point. Since
- * the shape functions are
- * vector-valued (with as
- * many components as there
- * are space dimensions), the
- * value is a tensor.
+ * Array with shape function values in quadrature points. There is one row
+ * for each shape function, containing values for each quadrature point.
+ * Since the shape functions are vector-valued (with as many components as
+ * there are space dimensions), the value is a tensor.
*
- * In this array, we store
- * the values of the shape
- * function in the quadrature
- * points on the unit
- * cell. The transformation
- * to the real space cell is
- * then simply done by
- * multiplication with the
- * Jacobian of the mapping.
+ * In this array, we store the values of the shape function in the
+ * quadrature points on the unit cell. The transformation to the real
+ * space cell is then simply done by multiplication with the Jacobian of
+ * the mapping.
*/
std::vector<std::vector<Tensor<1,dim> > > shape_values;
/**
- * Array with shape function
- * gradients in quadrature
- * points. There is one
- * row for each shape
- * function, containing
- * values for each quadrature
+ * Array with shape function gradients in quadrature points. There is one
+ * row for each shape function, containing values for each quadrature
* point.
*
- * We store the gradients in
- * the quadrature points on
- * the unit cell. We then
- * only have to apply the
- * transformation (which is a
- * matrix-vector
- * multiplication) when
- * visiting an actual cell.
+ * We store the gradients in the quadrature points on the unit cell. We
+ * then only have to apply the transformation (which is a matrix-vector
+ * multiplication) when visiting an actual cell.
*/
std::vector<std::vector<Tensor<2,dim> > > shape_gradients;
};
{
public:
/**
- * Constructor for the discontinuous Nédélec
- * element of degree @p p.
+ * Constructor for the discontinuous Nédélec element of degree
+ * @p p.
*/
FE_DGNedelec (const unsigned int p);
/**
- * Return a string that uniquely
- * identifies a finite
- * element. This class returns
- * <tt>FE_DGNedelec<dim>(degree)</tt>, with
- * @p dim and @p degree
- * replaced by appropriate
- * values.
+ * Return a string that uniquely identifies a finite element. This class
+ * returns <tt>FE_DGNedelec<dim>(degree)</tt>, with @p dim and @p degree
+ * replaced by appropriate values.
*/
virtual std::string get_name () const;
};
/**
- * A vector-valued DG element based on the polynomials space of FE_RaviartThomas.
+ * A vector-valued DG element based on the polynomials space of
+ * FE_RaviartThomas.
*
* @ingroup fe
* @author Guido Kanschat
{
public:
/**
- * Constructor for the Raviart-Thomas
- * element of degree @p p.
+ * Constructor for the Raviart-Thomas element of degree @p p.
*/
FE_DGRaviartThomas (const unsigned int p);
/**
- * Return a string that uniquely
- * identifies a finite
- * element. This class returns
- * <tt>FE_DGRaviartThomas<dim>(degree)</tt>, with
- * @p dim and @p degree
- * replaced by appropriate
- * values.
+ * Return a string that uniquely identifies a finite element. This class
+ * returns <tt>FE_DGRaviartThomas<dim>(degree)</tt>, with @p dim and @p
+ * degree replaced by appropriate values.
*/
virtual std::string get_name () const;
};
{
public:
/**
- * Constructor for the discontinuous BDM
- * element of degree @p p.
+ * Constructor for the discontinuous BDM element of degree @p p.
*/
FE_DGBDM (const unsigned int p);
/**
- * Return a string that uniquely
- * identifies a finite
- * element. This class returns
- * <tt>FE_DGBDM<dim>(degree)</tt>, with
- * @p dim and @p degree
- * replaced by appropriate
- * values.
+ * Return a string that uniquely identifies a finite element. This class
+ * returns <tt>FE_DGBDM<dim>(degree)</tt>, with @p dim and @p degree
+ * replaced by appropriate values.
*/
virtual std::string get_name () const;
};
/**
* Discontinuous finite elements based on Legendre polynomials.
*
- * This finite element implements complete polynomial spaces, that is,
- * dim-dimensional polynomials of degree p. For example, in 2d the
- * element FE_DGP(1) would represent the span of the functions
- * $\{1,\hat x,\hat y\}$, which is in contrast to the element FE_DGQ(1)
- * that is formed by the span of $\{1,\hat x,\hat y,\hat x\hat y\}$. Since the
- * DGP space has only three unknowns for each quadrilateral, it is
- * immediately clear that this element can not be continuous.
+ * This finite element implements complete polynomial spaces, that is, dim-
+ * dimensional polynomials of degree p. For example, in 2d the element
+ * FE_DGP(1) would represent the span of the functions $\{1,\hat x,\hat y\}$,
+ * which is in contrast to the element FE_DGQ(1) that is formed by the span of
+ * $\{1,\hat x,\hat y,\hat x\hat y\}$. Since the DGP space has only three
+ * unknowns for each quadrilateral, it is immediately clear that this element
+ * can not be continuous.
*
- * The basis functions used in this element for the space described above
- * are chosen to form a Legendre basis on the unit square. As a consequence,
- * the first basis function of this element is always the function that
- * is constant and equal to one. As a result of the orthogonality of
- * the basis functions, the mass matrix is diagonal if the
- * grid cells are parallelograms. Note that this is in contrast to the
- * FE_DGPMonomial class that actually uses the monomial basis listed
- * above as basis functions.
+ * The basis functions used in this element for the space described above are
+ * chosen to form a Legendre basis on the unit square. As a consequence, the
+ * first basis function of this element is always the function that is
+ * constant and equal to one. As a result of the orthogonality of the basis
+ * functions, the mass matrix is diagonal if the grid cells are
+ * parallelograms. Note that this is in contrast to the FE_DGPMonomial class
+ * that actually uses the monomial basis listed above as basis functions.
*
* The shape functions are defined in the class PolynomialSpace. The
- * polynomials used inside PolynomialSpace are Polynomials::Legendre
- * up to degree <tt>p</tt> given in FE_DGP. For the ordering of the
- * basis functions, refer to PolynomialSpace, remembering that the
- * Legendre polynomials are ordered by ascending degree.
+ * polynomials used inside PolynomialSpace are Polynomials::Legendre up to
+ * degree <tt>p</tt> given in FE_DGP. For the ordering of the basis functions,
+ * refer to PolynomialSpace, remembering that the Legendre polynomials are
+ * ordered by ascending degree.
*
- * @note This element is not defined by finding shape functions within
- * the given function space that interpolate a particular set of points.
- * Consequently, there are no support points to which a given function
- * could be interpolated; finding a finite element function that approximates
- * a given function is therefore only possible through projection, rather
- * than interpolation. Secondly, the shape functions of this element do not
- * jointly add up to one. As a consequence of this, adding or subtracting
- * a constant value -- such as one would do to make a function have mean
- * value zero -- can not be done by simply subtracting the constant value
- * from each degree of freedom. Rather, one needs to use the fact that the
- * first basis function is constant equal to one and simply subtract the
- * constant from the value of the degree of freedom corresponding to this
- * first shape function on each cell.
+ * @note This element is not defined by finding shape functions within the
+ * given function space that interpolate a particular set of points.
+ * Consequently, there are no support points to which a given function could
+ * be interpolated; finding a finite element function that approximates a
+ * given function is therefore only possible through projection, rather than
+ * interpolation. Secondly, the shape functions of this element do not jointly
+ * add up to one. As a consequence of this, adding or subtracting a constant
+ * value -- such as one would do to make a function have mean value zero --
+ * can not be done by simply subtracting the constant value from each degree
+ * of freedom. Rather, one needs to use the fact that the first basis function
+ * is constant equal to one and simply subtract the constant from the value of
+ * the degree of freedom corresponding to this first shape function on each
+ * cell.
*
*
* @note This class is only partially implemented for the codimension one case
- * (<tt>spacedim != dim </tt>), since no passage of information
- * between meshes of different refinement level is possible because
- * the embedding and projection matrices are not computed in the class
- * constructor.
+ * (<tt>spacedim != dim </tt>), since no passage of information between meshes
+ * of different refinement level is possible because the embedding and
+ * projection matrices are not computed in the class constructor.
*
* <h3>Transformation properties</h3>
*
- * It is worth noting that under a (bi-, tri-)linear mapping, the
- * space described by this element does not contain $P(k)$, even if we
- * use a basis of polynomials of degree $k$. Consequently, for
- * example, on meshes with non-affine cells, a linear function can not
- * be exactly represented by elements of type FE_DGP(1) or
- * FE_DGPMonomial(1).
+ * It is worth noting that under a (bi-, tri-)linear mapping, the space
+ * described by this element does not contain $P(k)$, even if we use a basis
+ * of polynomials of degree $k$. Consequently, for example, on meshes with
+ * non-affine cells, a linear function can not be exactly represented by
+ * elements of type FE_DGP(1) or FE_DGPMonomial(1).
*
- * This can be understood by the following 2-d example: consider the
- * cell with vertices at $(0,0),(1,0),(0,1),(s,s)$:
- * @image html dgp_doesnt_contain_p.png
+ * This can be understood by the following 2-d example: consider the cell with
+ * vertices at $(0,0),(1,0),(0,1),(s,s)$: @image html dgp_doesnt_contain_p.png
*
- * For this cell, a bilinear transformation $F$ produces the relations
- * $x=\hat x+\hat x\hat y$ and $y=\hat y+\hat x\hat y$ that correlate
- * reference coordinates $\hat x,\hat y$ and coordinates in real space
- * $x,y$. Under this mapping, the constant function is clearly mapped
- * onto itself, but the two other shape functions of the $P_1$ space,
- * namely $\phi_1(\hat x,\hat y)=\hat x$ and $\phi_2(\hat x,\hat
- * y)=\hat y$ are mapped onto
+ * For this cell, a bilinear transformation $F$ produces the relations $x=\hat
+ * x+\hat x\hat y$ and $y=\hat y+\hat x\hat y$ that correlate reference
+ * coordinates $\hat x,\hat y$ and coordinates in real space $x,y$. Under this
+ * mapping, the constant function is clearly mapped onto itself, but the two
+ * other shape functions of the $P_1$ space, namely $\phi_1(\hat x,\hat
+ * y)=\hat x$ and $\phi_2(\hat x,\hat y)=\hat y$ are mapped onto
* $\phi_1(x,y)=\frac{x-t}{t(s-1)},\phi_2(x,y)=t$ where
* $t=\frac{y}{s-x+sx+y-sy}$.
*
- * For the simple case that $s=1$, i.e. if the real cell is the unit
- * square, the expressions can be simplified to $t=y$ and
- * $\phi_1(x,y)=x,\phi_2(x,y)=y$. However, for all other cases, the
- * functions $\phi_1(x,y),\phi_2(x,y)$ are not linear any more, and
- * neither is any linear combincation of them. Consequently, the
- * linear functions are not within the range of the mapped $P_1$
- * polynomials.
+ * For the simple case that $s=1$, i.e. if the real cell is the unit square,
+ * the expressions can be simplified to $t=y$ and
+ * $\phi_1(x,y)=x,\phi_2(x,y)=y$. However, for all other cases, the functions
+ * $\phi_1(x,y),\phi_2(x,y)$ are not linear any more, and neither is any
+ * linear combincation of them. Consequently, the linear functions are not
+ * within the range of the mapped $P_1$ polynomials.
*
*
* @author Guido Kanschat, 2001, 2002, Ralf Hartmann 2004
{
public:
/**
- * Constructor for tensor product
- * polynomials of degree @p p.
+ * Constructor for tensor product polynomials of degree @p p.
*/
FE_DGP (const unsigned int p);
/**
- * Return a string that uniquely
- * identifies a finite
- * element. This class returns
- * <tt>FE_DGP<dim>(degree)</tt>, with
- * @p dim and @p degree
- * replaced by appropriate
- * values.
+ * Return a string that uniquely identifies a finite element. This class
+ * returns <tt>FE_DGP<dim>(degree)</tt>, with @p dim and @p degree replaced
+ * by appropriate values.
*/
virtual std::string get_name () const;
*/
/**
- * If, on a vertex, several finite elements are active, the hp code
- * first assigns the degrees of freedom of each of these FEs
- * different global indices. It then calls this function to find out
- * which of them should get identical values, and consequently can
- * receive the same global DoF index. This function therefore
- * returns a list of identities between DoFs of the present finite
- * element object with the DoFs of @p fe_other, which is a reference
- * to a finite element object representing one of the other finite
- * elements active on this particular vertex. The function computes
- * which of the degrees of freedom of the two finite element objects
- * are equivalent, both numbered between zero and the corresponding
- * value of dofs_per_vertex of the two finite elements. The first
- * index of each pair denotes one of the vertex dofs of the present
- * element, whereas the second is the corresponding index of the
- * other finite element.
+ * If, on a vertex, several finite elements are active, the hp code first
+ * assigns the degrees of freedom of each of these FEs different global
+ * indices. It then calls this function to find out which of them should get
+ * identical values, and consequently can receive the same global DoF index.
+ * This function therefore returns a list of identities between DoFs of the
+ * present finite element object with the DoFs of @p fe_other, which is a
+ * reference to a finite element object representing one of the other finite
+ * elements active on this particular vertex. The function computes which of
+ * the degrees of freedom of the two finite element objects are equivalent,
+ * both numbered between zero and the corresponding value of dofs_per_vertex
+ * of the two finite elements. The first index of each pair denotes one of
+ * the vertex dofs of the present element, whereas the second is the
+ * corresponding index of the other finite element.
*
- * This being a discontinuous element, the set of such constraints
- * is of course empty.
+ * This being a discontinuous element, the set of such constraints is of
+ * course empty.
*/
virtual
std::vector<std::pair<unsigned int, unsigned int> >
hp_vertex_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
/**
- * Same as hp_vertex_dof_indices(), except that the function treats
- * degrees of freedom on lines.
+ * Same as hp_vertex_dof_indices(), except that the function treats degrees
+ * of freedom on lines.
*
- * This being a discontinuous element, the set of such constraints
- * is of course empty.
+ * This being a discontinuous element, the set of such constraints is of
+ * course empty.
*/
virtual
std::vector<std::pair<unsigned int, unsigned int> >
hp_line_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
/**
- * Same as
- * hp_vertex_dof_indices(),
- * except that the function
- * treats degrees of freedom on
- * quads.
+ * Same as hp_vertex_dof_indices(), except that the function treats degrees
+ * of freedom on quads.
*
- * This being a discontinuous element,
- * the set of such constraints is of
+ * This being a discontinuous element, the set of such constraints is of
* course empty.
*/
virtual
hp_quad_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
/**
- * Return whether this element
- * implements its hanging node
- * constraints in the new way,
- * which has to be used to make
- * elements "hp compatible".
+ * Return whether this element implements its hanging node constraints in
+ * the new way, which has to be used to make elements "hp compatible".
*
- * For the FE_DGP class the result is
- * always true (independent of the degree
- * of the element), as it has no hanging
- * nodes (being a discontinuous element).
+ * For the FE_DGP class the result is always true (independent of the degree
+ * of the element), as it has no hanging nodes (being a discontinuous
+ * element).
*/
virtual bool hp_constraints_are_implemented () const;
/**
- * Return whether this element dominates
- * the one given as argument when they
- * meet at a common face,
- * whether it is the other way around,
- * whether neither dominates, or if
- * either could dominate.
+ * Return whether this element dominates the one given as argument when they
+ * meet at a common face, whether it is the other way around, whether
+ * neither dominates, or if either could dominate.
*
- * For a definition of domination, see
- * FiniteElementBase::Domination and in
+ * For a definition of domination, see FiniteElementBase::Domination and in
* particular the @ref hp_paper "hp paper".
*/
virtual
*/
/**
- * Return the matrix
- * interpolating from a face of
- * of one element to the face of
- * the neighboring element.
- * The size of the matrix is
- * then <tt>source.dofs_per_face</tt> times
- * <tt>this->dofs_per_face</tt>.
+ * Return the matrix interpolating from a face of of one element to the face
+ * of the neighboring element. The size of the matrix is then
+ * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
*
- * Derived elements will have to
- * implement this function. They
- * may only provide interpolation
- * matrices for certain source
- * finite elements, for example
- * those from the same family. If
- * they don't implement
- * interpolation from a given
- * element, then they must throw
- * an exception of type
+ * Derived elements will have to implement this function. They may only
+ * provide interpolation matrices for certain source finite elements, for
+ * example those from the same family. If they don't implement interpolation
+ * from a given element, then they must throw an exception of type
* FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented.
*/
virtual void
FullMatrix<double> &matrix) const;
/**
- * Return the matrix
- * interpolating from a face of
- * of one element to the face of
- * the neighboring element.
- * The size of the matrix is
- * then <tt>source.dofs_per_face</tt> times
- * <tt>this->dofs_per_face</tt>.
+ * Return the matrix interpolating from a face of of one element to the face
+ * of the neighboring element. The size of the matrix is then
+ * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
*
- * Derived elements will have to
- * implement this function. They
- * may only provide interpolation
- * matrices for certain source
- * finite elements, for example
- * those from the same family. If
- * they don't implement
- * interpolation from a given
- * element, then they must throw
- * an exception of type
+ * Derived elements will have to implement this function. They may only
+ * provide interpolation matrices for certain source finite elements, for
+ * example those from the same family. If they don't implement interpolation
+ * from a given element, then they must throw an exception of type
* FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented.
*/
virtual void
const unsigned int face_index) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*
- * This function is made virtual,
- * since finite element objects
- * are usually accessed through
- * pointers to their base class,
- * rather than the class itself.
+ * This function is made virtual, since finite element objects are usually
+ * accessed through pointers to their base class, rather than the class
+ * itself.
*/
virtual std::size_t memory_consumption () const;
/**
- * Declare a nested class which
- * will hold static definitions of
- * various matrices such as
- * constraint and embedding
- * matrices. The definition of
- * the various static fields are
- * in the files <tt>fe_dgp_[123]d.cc</tt>
- * in the source directory.
+ * Declare a nested class which will hold static definitions of various
+ * matrices such as constraint and embedding matrices. The definition of the
+ * various static fields are in the files <tt>fe_dgp_[123]d.cc</tt> in the
+ * source directory.
*/
struct Matrices
{
/**
- * As @p embedding but for
- * projection matrices.
+ * As @p embedding but for projection matrices.
*/
static const double *const projection_matrices[][GeometryInfo<dim>::max_children_per_cell];
/**
- * As
- * @p n_embedding_matrices
- * but for projection
- * matrices.
+ * As @p n_embedding_matrices but for projection matrices.
*/
static const unsigned int n_projection_matrices;
};
protected:
/**
- * @p clone function instead of
- * a copy constructor.
+ * @p clone function instead of a copy constructor.
*
- * This function is needed by the
- * constructors of @p FESystem.
+ * This function is needed by the constructors of @p FESystem.
*/
virtual FiniteElement<dim,spacedim> *clone() const;
private:
/**
- * Only for internal use. Its
- * full name is
- * @p get_dofs_per_object_vector
- * function and it creates the
- * @p dofs_per_object vector that is
- * needed within the constructor to
- * be passed to the constructor of
- * @p FiniteElementData.
+ * Only for internal use. Its full name is @p get_dofs_per_object_vector
+ * function and it creates the @p dofs_per_object vector that is needed
+ * within the constructor to be passed to the constructor of @p
+ * FiniteElementData.
*/
static std::vector<unsigned int> get_dpo_vector (const unsigned int degree);
};
/**
* Discontinuous finite elements based on monomials.
*
- * This finite element implements complete polynomial spaces, that is,
- * dim-dimensional polynomials of degree p. For example, in 2d the
- * element FE_DGP(1) would represent the span of the functions
- * $\{1,\hat x,\hat y\}$, which is in contrast to the element FE_DGQ(1)
- * that is formed by the span of $\{1,\hat x,\hat y,\hat x\hat y\}$. Since the
- * DGP space has only three unknowns for each quadrilateral, it is
- * immediately clear that this element can not be continuous.
+ * This finite element implements complete polynomial spaces, that is, dim-
+ * dimensional polynomials of degree p. For example, in 2d the element
+ * FE_DGP(1) would represent the span of the functions $\{1,\hat x,\hat y\}$,
+ * which is in contrast to the element FE_DGQ(1) that is formed by the span of
+ * $\{1,\hat x,\hat y,\hat x\hat y\}$. Since the DGP space has only three
+ * unknowns for each quadrilateral, it is immediately clear that this element
+ * can not be continuous.
*
- * The basis functions for this element are chosen to be the monomials
- * listed above. Note that this is the main difference to the FE_DGP
- * class that uses a set of polynomials of complete degree
- * <code>p</code> that form a Legendre basis on the unit square. Thus,
- * there, the mass matrix is diagonal, if the grid cells are
- * parallelograms. The basis here does not have this property;
- * however, it is simpler to compute. On the other hand, this element
- * has the additional disadvantage that the local cell matrices
- * usually have a worse condition number than the ones originating
- * from the FE_DGP element.
+ * The basis functions for this element are chosen to be the monomials listed
+ * above. Note that this is the main difference to the FE_DGP class that uses
+ * a set of polynomials of complete degree <code>p</code> that form a Legendre
+ * basis on the unit square. Thus, there, the mass matrix is diagonal, if the
+ * grid cells are parallelograms. The basis here does not have this property;
+ * however, it is simpler to compute. On the other hand, this element has the
+ * additional disadvantage that the local cell matrices usually have a worse
+ * condition number than the ones originating from the FE_DGP element.
*
- * This class is not implemented for the codimension one case
- * (<tt>spacedim != dim</tt>).
+ * This class is not implemented for the codimension one case (<tt>spacedim !=
+ * dim</tt>).
*
* <h3>Transformation properties</h3>
*
- * It is worth noting that under a (bi-, tri-)linear mapping, the
- * space described by this element does not contain $P(k)$, even if we
- * use a basis of polynomials of degree $k$. Consequently, for
- * example, on meshes with non-affine cells, a linear function can not
- * be exactly represented by elements of type FE_DGP(1) or
- * FE_DGPMonomial(1).
+ * It is worth noting that under a (bi-, tri-)linear mapping, the space
+ * described by this element does not contain $P(k)$, even if we use a basis
+ * of polynomials of degree $k$. Consequently, for example, on meshes with
+ * non-affine cells, a linear function can not be exactly represented by
+ * elements of type FE_DGP(1) or FE_DGPMonomial(1).
*
- * This can be understood by the following 2-d example: consider the
- * cell with vertices at $(0,0),(1,0),(0,1),(s,s)$:
- * @image html dgp_doesnt_contain_p.png
+ * This can be understood by the following 2-d example: consider the cell with
+ * vertices at $(0,0),(1,0),(0,1),(s,s)$: @image html dgp_doesnt_contain_p.png
*
- * For this cell, a bilinear transformation $F$ produces the relations
- * $x=\hat x+\hat x\hat y$ and $y=\hat y+\hat x\hat y$ that correlate
- * reference coordinates $\hat x,\hat y$ and coordinates in real space
- * $x,y$. Under this mapping, the constant function is clearly mapped
- * onto itself, but the two other shape functions of the $P_1$ space,
- * namely $\phi_1(\hat x,\hat y)=\hat x$ and $\phi_2(\hat x,\hat
- * y)=\hat y$ are mapped onto
+ * For this cell, a bilinear transformation $F$ produces the relations $x=\hat
+ * x+\hat x\hat y$ and $y=\hat y+\hat x\hat y$ that correlate reference
+ * coordinates $\hat x,\hat y$ and coordinates in real space $x,y$. Under this
+ * mapping, the constant function is clearly mapped onto itself, but the two
+ * other shape functions of the $P_1$ space, namely $\phi_1(\hat x,\hat
+ * y)=\hat x$ and $\phi_2(\hat x,\hat y)=\hat y$ are mapped onto
* $\phi_1(x,y)=\frac{x-t}{t(s-1)},\phi_2(x,y)=t$ where
* $t=\frac{y}{s-x+sx+y-sy}$.
*
- * For the simple case that $s=1$, i.e. if the real cell is the unit
- * square, the expressions can be simplified to $t=y$ and
- * $\phi_1(x,y)=x,\phi_2(x,y)=y$. However, for all other cases, the
- * functions $\phi_1(x,y),\phi_2(x,y)$ are not linear any more, and
- * neither is any linear combincation of them. Consequently, the
- * linear functions are not within the range of the mapped $P_1$
- * polynomials.
+ * For the simple case that $s=1$, i.e. if the real cell is the unit square,
+ * the expressions can be simplified to $t=y$ and
+ * $\phi_1(x,y)=x,\phi_2(x,y)=y$. However, for all other cases, the functions
+ * $\phi_1(x,y),\phi_2(x,y)$ are not linear any more, and neither is any
+ * linear combincation of them. Consequently, the linear functions are not
+ * within the range of the mapped $P_1$ polynomials.
*
*
* @author Ralf Hartmann, 2004
{
public:
/**
- * Constructor for the polynomial
- * space of degree <tt>p</tt>.
+ * Constructor for the polynomial space of degree <tt>p</tt>.
*/
FE_DGPMonomial (const unsigned int p);
/**
- * Return a string that uniquely
- * identifies a finite
- * element. This class returns
- * <tt>FE_DGPMonomial<dim>(degree)</tt>,
- * with <tt>dim</tt> and
- * <tt>p</tt> replaced by
- * appropriate values.
+ * Return a string that uniquely identifies a finite element. This class
+ * returns <tt>FE_DGPMonomial<dim>(degree)</tt>, with <tt>dim</tt> and
+ * <tt>p</tt> replaced by appropriate values.
*/
virtual std::string get_name () const;
*/
/**
- * If, on a vertex, several finite elements are active, the hp code
- * first assigns the degrees of freedom of each of these FEs
- * different global indices. It then calls this function to find out
- * which of them should get identical values, and consequently can
- * receive the same global DoF index. This function therefore
- * returns a list of identities between DoFs of the present finite
- * element object with the DoFs of @p fe_other, which is a reference
- * to a finite element object representing one of the other finite
- * elements active on this particular vertex. The function computes
- * which of the degrees of freedom of the two finite element objects
- * are equivalent, both numbered between zero and the corresponding
- * value of dofs_per_vertex of the two finite elements. The first
- * index of each pair denotes one of the vertex dofs of the present
- * element, whereas the second is the corresponding index of the
- * other finite element.
+ * If, on a vertex, several finite elements are active, the hp code first
+ * assigns the degrees of freedom of each of these FEs different global
+ * indices. It then calls this function to find out which of them should get
+ * identical values, and consequently can receive the same global DoF index.
+ * This function therefore returns a list of identities between DoFs of the
+ * present finite element object with the DoFs of @p fe_other, which is a
+ * reference to a finite element object representing one of the other finite
+ * elements active on this particular vertex. The function computes which of
+ * the degrees of freedom of the two finite element objects are equivalent,
+ * both numbered between zero and the corresponding value of dofs_per_vertex
+ * of the two finite elements. The first index of each pair denotes one of
+ * the vertex dofs of the present element, whereas the second is the
+ * corresponding index of the other finite element.
*
- * This being a discontinuous element, the set of such constraints
- * is of course empty.
+ * This being a discontinuous element, the set of such constraints is of
+ * course empty.
*/
virtual
std::vector<std::pair<unsigned int, unsigned int> >
hp_vertex_dof_identities (const FiniteElement<dim> &fe_other) const;
/**
- * Same as hp_vertex_dof_indices(), except that the function treats
- * degrees of freedom on lines.
+ * Same as hp_vertex_dof_indices(), except that the function treats degrees
+ * of freedom on lines.
*
- * This being a discontinuous element, the set of such constraints
- * is of course empty.
+ * This being a discontinuous element, the set of such constraints is of
+ * course empty.
*/
virtual
std::vector<std::pair<unsigned int, unsigned int> >
hp_line_dof_identities (const FiniteElement<dim> &fe_other) const;
/**
- * Same as
- * hp_vertex_dof_indices(),
- * except that the function
- * treats degrees of freedom on
- * quads.
+ * Same as hp_vertex_dof_indices(), except that the function treats degrees
+ * of freedom on quads.
*
- * This being a discontinuous element,
- * the set of such constraints is of
+ * This being a discontinuous element, the set of such constraints is of
* course empty.
*/
virtual
hp_quad_dof_identities (const FiniteElement<dim> &fe_other) const;
/**
- * Return whether this element
- * implements its hanging node
- * constraints in the new way,
- * which has to be used to make
- * elements "hp compatible".
+ * Return whether this element implements its hanging node constraints in
+ * the new way, which has to be used to make elements "hp compatible".
*
- * For the FE_DGPMonomial class the
- * result is always true (independent of
- * the degree of the element), as it has
- * no hanging nodes (being a
+ * For the FE_DGPMonomial class the result is always true (independent of
+ * the degree of the element), as it has no hanging nodes (being a
* discontinuous element).
*/
virtual bool hp_constraints_are_implemented () const;
/**
- * Return whether this element dominates
- * the one given as argument when they
- * meet at a common face,
- * whether it is the other way around,
- * whether neither dominates, or if
- * either could dominate.
+ * Return whether this element dominates the one given as argument when they
+ * meet at a common face, whether it is the other way around, whether
+ * neither dominates, or if either could dominate.
*
- * For a definition of domination, see
- * FiniteElementBase::Domination and in
+ * For a definition of domination, see FiniteElementBase::Domination and in
* particular the @ref hp_paper "hp paper".
*/
virtual
*/
/**
- * Return the matrix
- * interpolating from the given
- * finite element to the present
- * one. The size of the matrix is
- * then @p dofs_per_cell times
+ * Return the matrix interpolating from the given finite element to the
+ * present one. The size of the matrix is then @p dofs_per_cell times
* <tt>source.dofs_per_cell</tt>.
*
- * These matrices are only
- * available if the source
- * element is also a @p FE_Q
- * element. Otherwise, an
- * exception of type
- * FiniteElement<dim>::ExcInterpolationNotImplemented
- * is thrown.
+ * These matrices are only available if the source element is also a @p FE_Q
+ * element. Otherwise, an exception of type
+ * FiniteElement<dim>::ExcInterpolationNotImplemented is thrown.
*/
virtual void
get_interpolation_matrix (const FiniteElement<dim> &source,
FullMatrix<double> &matrix) const;
/**
- * Return the matrix
- * interpolating from a face of
- * of one element to the face of
- * the neighboring element.
- * The size of the matrix is
- * then @p dofs_per_face times
- * <tt>source.dofs_per_face</tt>.
+ * Return the matrix interpolating from a face of of one element to the face
+ * of the neighboring element. The size of the matrix is then @p
+ * dofs_per_face times <tt>source.dofs_per_face</tt>.
*
- * Derived elements will have to
- * implement this function. They
- * may only provide interpolation
- * matrices for certain source
- * finite elements, for example
- * those from the same family. If
- * they don't implement
- * interpolation from a given
- * element, then they must throw
- * an exception of type
+ * Derived elements will have to implement this function. They may only
+ * provide interpolation matrices for certain source finite elements, for
+ * example those from the same family. If they don't implement interpolation
+ * from a given element, then they must throw an exception of type
* FiniteElement<dim>::ExcInterpolationNotImplemented.
*/
virtual void
FullMatrix<double> &matrix) const;
/**
- * Return the matrix
- * interpolating from a face of
- * of one element to the face of
- * the neighboring element.
- * The size of the matrix is
- * then @p dofs_per_face times
- * <tt>source.dofs_per_face</tt>.
+ * Return the matrix interpolating from a face of of one element to the face
+ * of the neighboring element. The size of the matrix is then @p
+ * dofs_per_face times <tt>source.dofs_per_face</tt>.
*
- * Derived elements will have to
- * implement this function. They
- * may only provide interpolation
- * matrices for certain source
- * finite elements, for example
- * those from the same family. If
- * they don't implement
- * interpolation from a given
- * element, then they must throw
- * an exception of type
+ * Derived elements will have to implement this function. They may only
+ * provide interpolation matrices for certain source finite elements, for
+ * example those from the same family. If they don't implement interpolation
+ * from a given element, then they must throw an exception of type
* FiniteElement<dim>::ExcInterpolationNotImplemented.
*/
virtual void
const unsigned int face_index) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*
- * This function is made virtual,
- * since finite element objects
- * are usually accessed through
- * pointers to their base class,
- * rather than the class itself.
+ * This function is made virtual, since finite element objects are usually
+ * accessed through pointers to their base class, rather than the class
+ * itself.
*/
virtual std::size_t memory_consumption () const;
protected:
/**
- * @p clone function instead of
- * a copy constructor.
+ * @p clone function instead of a copy constructor.
*
- * This function is needed by the
- * constructors of @p FESystem.
+ * This function is needed by the constructors of @p FESystem.
*/
virtual FiniteElement<dim> *clone() const;
private:
/**
- * Only for internal use. Its
- * full name is
- * @p get_dofs_per_object_vector
- * function and it creates the
- * @p dofs_per_object vector that is
- * needed within the constructor to
- * be passed to the constructor of
- * @p FiniteElementData.
+ * Only for internal use. Its full name is @p get_dofs_per_object_vector
+ * function and it creates the @p dofs_per_object vector that is needed
+ * within the constructor to be passed to the constructor of @p
+ * FiniteElementData.
*/
static std::vector<unsigned int> get_dpo_vector (const unsigned int degree);
/**
- * Initialize the embedding
- * matrices. Called from the
- * constructor.
+ * Initialize the embedding matrices. Called from the constructor.
*/
void initialize_embedding ();
/**
- * Initialize the restriction
- * matrices. Called from the
- * constructor.
+ * Initialize the restriction matrices. Called from the constructor.
*/
void initialize_restriction ();
};
* This finite element implements complete polynomial spaces, that is,
* $d$-dimensional polynomials of order $k$.
*
- * The polynomials are not mapped. Therefore, they are constant,
- * linear, quadratic, etc. on any grid cell.
+ * The polynomials are not mapped. Therefore, they are constant, linear,
+ * quadratic, etc. on any grid cell.
*
- * Since the polynomials are evaluated at the quadrature points of the
- * actual grid cell, no grid transfer and interpolation matrices are
- * available.
+ * Since the polynomials are evaluated at the quadrature points of the actual
+ * grid cell, no grid transfer and interpolation matrices are available.
*
- * The purpose of this class is experimental, therefore the
- * implementation will remain incomplete.
+ * The purpose of this class is experimental, therefore the implementation
+ * will remain incomplete.
*
* Besides, this class is not implemented for the codimension one case
* (<tt>spacedim != dim</tt>).
{
public:
/**
- * Constructor for tensor product
- * polynomials of degree @p k.
+ * Constructor for tensor product polynomials of degree @p k.
*/
FE_DGPNonparametric (const unsigned int k);
/**
- * Return a string that uniquely
- * identifies a finite
- * element. This class returns
- * <tt>FE_DGPNonparametric<dim>(degree)</tt>,
- * with @p dim and @p degree
- * replaced by appropriate
- * values.
+ * Return a string that uniquely identifies a finite element. This class
+ * returns <tt>FE_DGPNonparametric<dim>(degree)</tt>, with @p dim and @p
+ * degree replaced by appropriate values.
*/
virtual std::string get_name () const;
/**
- * Return the value of the
- * @p ith shape function at the
- * point @p p. See the
- * FiniteElement base
- * class for more information
- * about the semantics of this
+ * Return the value of the @p ith shape function at the point @p p. See the
+ * FiniteElement base class for more information about the semantics of this
* function.
*/
virtual double shape_value (const unsigned int i,
const Point<dim> &p) const;
/**
- * Return the value of the
- * @p componentth vector
- * component of the @p ith shape
- * function at the point
- * @p p. See the
- * FiniteElement base
- * class for more information
- * about the semantics of this
- * function.
+ * Return the value of the @p componentth vector component of the @p ith
+ * shape function at the point @p p. See the FiniteElement base class for
+ * more information about the semantics of this function.
*
- * Since this element is scalar,
- * the returned value is the same
- * as if the function without the
- * @p _component suffix were
- * called, provided that the
+ * Since this element is scalar, the returned value is the same as if the
+ * function without the @p _component suffix were called, provided that the
* specified component is zero.
*/
virtual double shape_value_component (const unsigned int i,
const unsigned int component) const;
/**
- * Return the gradient of the
- * @p ith shape function at the
- * point @p p. See the
- * FiniteElement base
- * class for more information
- * about the semantics of this
- * function.
+ * Return the gradient of the @p ith shape function at the point @p p. See
+ * the FiniteElement base class for more information about the semantics of
+ * this function.
*/
virtual Tensor<1,dim> shape_grad (const unsigned int i,
const Point<dim> &p) const;
/**
- * Return the gradient of the
- * @p componentth vector
- * component of the @p ith shape
- * function at the point
- * @p p. See the
- * FiniteElement base
- * class for more information
- * about the semantics of this
- * function.
+ * Return the gradient of the @p componentth vector component of the @p ith
+ * shape function at the point @p p. See the FiniteElement base class for
+ * more information about the semantics of this function.
*
- * Since this element is scalar,
- * the returned value is the same
- * as if the function without the
- * @p _component suffix were
- * called, provided that the
+ * Since this element is scalar, the returned value is the same as if the
+ * function without the @p _component suffix were called, provided that the
* specified component is zero.
*/
virtual Tensor<1,dim> shape_grad_component (const unsigned int i,
const unsigned int component) const;
/**
- * Return the tensor of second
- * derivatives of the @p ith
- * shape function at point @p p
- * on the unit cell. See the
- * FiniteElement base
- * class for more information
- * about the semantics of this
- * function.
+ * Return the tensor of second derivatives of the @p ith shape function at
+ * point @p p on the unit cell. See the FiniteElement base class for more
+ * information about the semantics of this function.
*/
virtual Tensor<2,dim> shape_grad_grad (const unsigned int i,
const Point<dim> &p) const;
/**
- * Return the second derivative
- * of the @p componentth vector
- * component of the @p ith shape
- * function at the point
- * @p p. See the
- * FiniteElement base
- * class for more information
- * about the semantics of this
- * function.
+ * Return the second derivative of the @p componentth vector component of
+ * the @p ith shape function at the point @p p. See the FiniteElement base
+ * class for more information about the semantics of this function.
*
- * Since this element is scalar,
- * the returned value is the same
- * as if the function without the
- * @p _component suffix were
- * called, provided that the
+ * Since this element is scalar, the returned value is the same as if the
+ * function without the @p _component suffix were called, provided that the
* specified component is zero.
*/
virtual Tensor<2,dim> shape_grad_grad_component (const unsigned int i,
const unsigned int component) const;
/**
- * Return the polynomial degree
- * of this finite element,
- * i.e. the value passed to the
- * constructor.
+ * Return the polynomial degree of this finite element, i.e. the value
+ * passed to the constructor.
*/
unsigned int get_degree () const;
/**
- * Return the matrix
- * interpolating from a face of
- * of one element to the face of
- * the neighboring element.
- * The size of the matrix is
- * then <tt>source.dofs_per_face</tt> times
- * <tt>this->dofs_per_face</tt>.
+ * Return the matrix interpolating from a face of of one element to the face
+ * of the neighboring element. The size of the matrix is then
+ * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
*
- * Derived elements will have to
- * implement this function. They
- * may only provide interpolation
- * matrices for certain source
- * finite elements, for example
- * those from the same family. If
- * they don't implement
- * interpolation from a given
- * element, then they must throw
- * an exception of type
+ * Derived elements will have to implement this function. They may only
+ * provide interpolation matrices for certain source finite elements, for
+ * example those from the same family. If they don't implement interpolation
+ * from a given element, then they must throw an exception of type
* FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented.
*/
virtual void
FullMatrix<double> &matrix) const;
/**
- * Return the matrix
- * interpolating from a face of
- * of one element to the face of
- * the neighboring element.
- * The size of the matrix is
- * then <tt>source.dofs_per_face</tt> times
- * <tt>this->dofs_per_face</tt>.
+ * Return the matrix interpolating from a face of of one element to the face
+ * of the neighboring element. The size of the matrix is then
+ * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
*
- * Derived elements will have to
- * implement this function. They
- * may only provide interpolation
- * matrices for certain source
- * finite elements, for example
- * those from the same family. If
- * they don't implement
- * interpolation from a given
- * element, then they must throw
- * an exception of type
+ * Derived elements will have to implement this function. They may only
+ * provide interpolation matrices for certain source finite elements, for
+ * example those from the same family. If they don't implement interpolation
+ * from a given element, then they must throw an exception of type
* FiniteElement<dim,spacedim>::ExcInterpolationNotImplemented.
*/
virtual void
*/
/**
- * If, on a vertex, several finite elements are active, the hp code
- * first assigns the degrees of freedom of each of these FEs
- * different global indices. It then calls this function to find out
- * which of them should get identical values, and consequently can
- * receive the same global DoF index. This function therefore
- * returns a list of identities between DoFs of the present finite
- * element object with the DoFs of @p fe_other, which is a reference
- * to a finite element object representing one of the other finite
- * elements active on this particular vertex. The function computes
- * which of the degrees of freedom of the two finite element objects
- * are equivalent, both numbered between zero and the corresponding
- * value of dofs_per_vertex of the two finite elements. The first
- * index of each pair denotes one of the vertex dofs of the present
- * element, whereas the second is the corresponding index of the
- * other finite element.
+ * If, on a vertex, several finite elements are active, the hp code first
+ * assigns the degrees of freedom of each of these FEs different global
+ * indices. It then calls this function to find out which of them should get
+ * identical values, and consequently can receive the same global DoF index.
+ * This function therefore returns a list of identities between DoFs of the
+ * present finite element object with the DoFs of @p fe_other, which is a
+ * reference to a finite element object representing one of the other finite
+ * elements active on this particular vertex. The function computes which of
+ * the degrees of freedom of the two finite element objects are equivalent,
+ * both numbered between zero and the corresponding value of dofs_per_vertex
+ * of the two finite elements. The first index of each pair denotes one of
+ * the vertex dofs of the present element, whereas the second is the
+ * corresponding index of the other finite element.
*
- * This being a discontinuous element, the set of such constraints
- * is of course empty.
+ * This being a discontinuous element, the set of such constraints is of
+ * course empty.
*/
virtual
std::vector<std::pair<unsigned int, unsigned int> >
hp_vertex_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
/**
- * Same as hp_vertex_dof_indices(), except that the function treats
- * degrees of freedom on lines.
+ * Same as hp_vertex_dof_indices(), except that the function treats degrees
+ * of freedom on lines.
*
- * This being a discontinuous element, the set of such constraints
- * is of course empty.
+ * This being a discontinuous element, the set of such constraints is of
+ * course empty.
*/
virtual
std::vector<std::pair<unsigned int, unsigned int> >
hp_line_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
/**
- * Same as hp_vertex_dof_indices(), except that the function treats
- * degrees of freedom on quads.
+ * Same as hp_vertex_dof_indices(), except that the function treats degrees
+ * of freedom on quads.
*
- * This being a discontinuous element, the set of such constraints
- * is of course empty.
+ * This being a discontinuous element, the set of such constraints is of
+ * course empty.
*/
virtual
std::vector<std::pair<unsigned int, unsigned int> >
hp_quad_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
/**
- * Return whether this element
- * implements its hanging node
- * constraints in the new way,
- * which has to be used to make
- * elements "hp compatible".
+ * Return whether this element implements its hanging node constraints in
+ * the new way, which has to be used to make elements "hp compatible".
*
- * For the FE_DGPNonparametric class the
- * result is always true (independent of
- * the degree of the element), as it has
- * no hanging nodes (being a
+ * For the FE_DGPNonparametric class the result is always true (independent
+ * of the degree of the element), as it has no hanging nodes (being a
* discontinuous element).
*/
virtual bool hp_constraints_are_implemented () const;
/**
- * Return whether this element dominates
- * the one given as argument when they
- * meet at a common face,
- * whether it is the other way around,
- * whether neither dominates, or if
- * either could dominate.
+ * Return whether this element dominates the one given as argument when they
+ * meet at a common face, whether it is the other way around, whether
+ * neither dominates, or if either could dominate.
*
- * For a definition of domination, see
- * FiniteElementBase::Domination and in
+ * For a definition of domination, see FiniteElementBase::Domination and in
* particular the @ref hp_paper "hp paper".
*/
virtual
const unsigned int face_index) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*
- * This function is made virtual,
- * since finite element objects
- * are usually accessed through
- * pointers to their base class,
- * rather than the class itself.
+ * This function is made virtual, since finite element objects are usually
+ * accessed through pointers to their base class, rather than the class
+ * itself.
*/
virtual std::size_t memory_consumption () const;
private:
/**
- * Declare a nested class which
- * will hold static definitions of
- * various matrices such as
- * constraint and embedding
- * matrices. The definition of
- * the various static fields are
- * in the files <tt>fe_dgp_[123]d.cc</tt>
- * in the source directory.
+ * Declare a nested class which will hold static definitions of various
+ * matrices such as constraint and embedding matrices. The definition of the
+ * various static fields are in the files <tt>fe_dgp_[123]d.cc</tt> in the
+ * source directory.
*/
struct Matrices
{
/**
- * Pointers to the embedding
- * matrices, one for each
- * polynomial degree starting
- * from constant elements
+ * Pointers to the embedding matrices, one for each polynomial degree
+ * starting from constant elements
*/
static const double *const embedding[][GeometryInfo<dim>::max_children_per_cell];
/**
- * Number of elements (first
- * index) the above field
- * has. Equals the highest
- * polynomial degree plus one
- * for which the embedding
- * matrices have been
- * computed.
+ * Number of elements (first index) the above field has. Equals the
+ * highest polynomial degree plus one for which the embedding matrices
+ * have been computed.
*/
static const unsigned int n_embedding_matrices;
/**
- * As @p embedding but for
- * projection matrices.
+ * As @p embedding but for projection matrices.
*/
static const double *const projection_matrices[][GeometryInfo<dim>::max_children_per_cell];
/**
- * As
- * @p n_embedding_matrices
- * but for projection
- * matrices.
+ * As @p n_embedding_matrices but for projection matrices.
*/
static const unsigned int n_projection_matrices;
};
protected:
/**
- * @p clone function instead of
- * a copy constructor.
+ * @p clone function instead of a copy constructor.
*
- * This function is needed by the
- * constructors of @p FESystem.
+ * This function is needed by the constructors of @p FESystem.
*/
virtual FiniteElement<dim,spacedim> *clone() const;
/**
- * Prepare internal data
- * structures and fill in values
- * independent of the cell.
+ * Prepare internal data structures and fill in values independent of the
+ * cell.
*/
virtual
typename Mapping<dim,spacedim>::InternalDataBase *
const Quadrature<dim> &quadrature) const ;
/**
- * Implementation of the same
- * function in
- * FiniteElement.
+ * Implementation of the same function in FiniteElement.
*/
virtual void
fill_fe_values (const Mapping<dim,spacedim> &mapping,
CellSimilarity::Similarity &cell_similarity) const;
/**
- * Implementation of the same
- * function in
- * FiniteElement.
+ * Implementation of the same function in FiniteElement.
*/
virtual void
fill_fe_face_values (const Mapping<dim,spacedim> &mapping,
FEValuesData<dim,spacedim> &data) const ;
/**
- * Implementation of the same
- * function in
- * FiniteElement.
+ * Implementation of the same function in FiniteElement.
*/
virtual void
fill_fe_subface_values (const Mapping<dim,spacedim> &mapping,
private:
/**
- * Only for internal use. Its
- * full name is
- * @p get_dofs_per_object_vector
- * function and it creates the
- * @p dofs_per_object vector that is
- * needed within the constructor to
- * be passed to the constructor of
- * @p FiniteElementData.
+ * Only for internal use. Its full name is @p get_dofs_per_object_vector
+ * function and it creates the @p dofs_per_object vector that is needed
+ * within the constructor to be passed to the constructor of @p
+ * FiniteElementData.
*/
static std::vector<unsigned int> get_dpo_vector (const unsigned int degree);
/**
- * Given a set of flags indicating
- * what quantities are requested
- * from a @p FEValues object,
- * return which of these can be
- * precomputed once and for
- * all. Often, the values of
- * shape function at quadrature
- * points can be precomputed, for
- * example, in which case the
- * return value of this function
- * would be the logical and of
- * the input @p flags and
- * @p update_values.
+ * Given a set of flags indicating what quantities are requested from a @p
+ * FEValues object, return which of these can be precomputed once and for
+ * all. Often, the values of shape function at quadrature points can be
+ * precomputed, for example, in which case the return value of this function
+ * would be the logical and of the input @p flags and @p update_values.
*
- * For the present kind of finite
- * element, this is exactly the
- * case.
+ * For the present kind of finite element, this is exactly the case.
*/
virtual UpdateFlags update_once (const UpdateFlags flags) const;
/**
- * This is the opposite to the
- * above function: given a set of
- * flags indicating what we want
- * to know, return which of these
- * need to be computed each time
- * we visit a new cell.
+ * This is the opposite to the above function: given a set of flags
+ * indicating what we want to know, return which of these need to be
+ * computed each time we visit a new cell.
*
- * If for the computation of one
- * quantity something else is
- * also required (for example, we
- * often need the covariant
- * transformation when gradients
- * need to be computed), include
- * this in the result as well.
+ * If for the computation of one quantity something else is also required
+ * (for example, we often need the covariant transformation when gradients
+ * need to be computed), include this in the result as well.
*/
virtual UpdateFlags update_each (const UpdateFlags flags) const;
const unsigned int degree;
/**
- * Pointer to an object
- * representing the polynomial
- * space used here.
+ * Pointer to an object representing the polynomial space used here.
*/
const PolynomialSpace<dim> polynomial_space;
/**
* Fields of cell-independent data.
*
- * For information about the
- * general purpose of this class,
- * see the documentation of the
- * base class.
+ * For information about the general purpose of this class, see the
+ * documentation of the base class.
*/
class InternalData : public FiniteElement<dim,spacedim>::InternalDataBase
{
template <int, int> friend class FE_DGPNonparametric;
/**
- * Allows @p MappingQ class to
- * access to build_renumbering
- * function.
+ * Allows @p MappingQ class to access to build_renumbering function.
*/
template <int, int> friend class MappingQ;
// friend class MappingQ<dim>;
/*@{*/
/**
- * Implementation of scalar, discontinuous tensor product elements
- * based on equidistant support points.
+ * Implementation of scalar, discontinuous tensor product elements based on
+ * equidistant support points.
*
* This is a discontinuous finite element based on tensor products of
- * Lagrangian polynomials. The shape functions are Lagrangian
- * interpolants of an equidistant grid of points on the unit cell. The
- * points are numbered in lexicographical order, with <i>x</i> running
- * fastest, then <i>y</i>, then <i>z</i> (if these coordinates are present for a
- * given space dimension at all). For example, these are the node
- * orderings for <tt>FE_DGQ(1)</tt> in 3d:
+ * Lagrangian polynomials. The shape functions are Lagrangian interpolants of
+ * an equidistant grid of points on the unit cell. The points are numbered in
+ * lexicographical order, with <i>x</i> running fastest, then <i>y</i>, then
+ * <i>z</i> (if these coordinates are present for a given space dimension at
+ * all). For example, these are the node orderings for <tt>FE_DGQ(1)</tt> in
+ * 3d:
* @verbatim
* 6-------7 6-------7
* /| | / /|
* @endverbatim
* with node 13 being placed in the interior of the hex.
*
- * Note, however, that these are just the Lagrange interpolation
- * points of the shape functions. Even though they may physically be
- * on the surface of the cell, they are logically in the interior
- * since there are no continuity requirements for these shape
- * functions across cell boundaries.
- * This class if partially implemented for the codimension one case
- * (<tt>spacedim != dim </tt>), since no passage of information
- * between meshes of different refinement level is possible because
- * the embedding and projection matrices are not computed in the class
- * constructor.
+ * Note, however, that these are just the Lagrange interpolation points of the
+ * shape functions. Even though they may physically be on the surface of the
+ * cell, they are logically in the interior since there are no continuity
+ * requirements for these shape functions across cell boundaries. This class
+ * if partially implemented for the codimension one case (<tt>spacedim != dim
+ * </tt>), since no passage of information between meshes of different
+ * refinement level is possible because the embedding and projection matrices
+ * are not computed in the class constructor.
*
* @author Ralf Hartmann, Guido Kanschat 2001, 2004
*/
{
public:
/**
- * Constructor for tensor product
- * polynomials of degree
- * <tt>p</tt>. The shape
- * functions created using this
- * constructor correspond to
- * Lagrange interpolation
- * polynomials for equidistantly
- * spaced support points in each
+ * Constructor for tensor product polynomials of degree <tt>p</tt>. The
+ * shape functions created using this constructor correspond to Lagrange
+ * interpolation polynomials for equidistantly spaced support points in each
* coordinate direction.
*/
FE_DGQ (const unsigned int p);
/**
- * Return a string that uniquely
- * identifies a finite
- * element. This class returns
- * <tt>FE_DGQ<dim>(degree)</tt>, with
- * <tt>dim</tt> and <tt>degree</tt>
- * replaced by appropriate
- * values.
+ * Return a string that uniquely identifies a finite element. This class
+ * returns <tt>FE_DGQ<dim>(degree)</tt>, with <tt>dim</tt> and
+ * <tt>degree</tt> replaced by appropriate values.
*/
virtual std::string get_name () const;
/**
- * Return the matrix
- * interpolating from the given
- * finite element to the present
- * one. The size of the matrix is
- * then @p dofs_per_cell times
+ * Return the matrix interpolating from the given finite element to the
+ * present one. The size of the matrix is then @p dofs_per_cell times
* <tt>source.dofs_per_cell</tt>.
*
- * These matrices are only
- * available if the source
- * element is also a @p FE_DGQ
- * element. Otherwise, an
- * exception of type
- * FiniteElement<dim>::ExcInterpolationNotImplemented
- * is thrown.
+ * These matrices are only available if the source element is also a @p
+ * FE_DGQ element. Otherwise, an exception of type
+ * FiniteElement<dim>::ExcInterpolationNotImplemented is thrown.
*/
virtual void
get_interpolation_matrix (const FiniteElement<dim, spacedim> &source,
FullMatrix<double> &matrix) const;
/**
- * Return the matrix
- * interpolating from a face of
- * of one element to the face of
- * the neighboring element.
- * The size of the matrix is
- * then <tt>source.dofs_per_face</tt> times
- * <tt>this->dofs_per_face</tt>.
+ * Return the matrix interpolating from a face of of one element to the face
+ * of the neighboring element. The size of the matrix is then
+ * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
*
- * Derived elements will have to
- * implement this function. They
- * may only provide interpolation
- * matrices for certain source
- * finite elements, for example
- * those from the same family. If
- * they don't implement
- * interpolation from a given
- * element, then they must throw
- * an exception of type
+ * Derived elements will have to implement this function. They may only
+ * provide interpolation matrices for certain source finite elements, for
+ * example those from the same family. If they don't implement interpolation
+ * from a given element, then they must throw an exception of type
* FiniteElement<dim>::ExcInterpolationNotImplemented.
*/
virtual void
FullMatrix<double> &matrix) const;
/**
- * Return the matrix
- * interpolating from a face of
- * of one element to the face of
- * the neighboring element.
- * The size of the matrix is
- * then <tt>source.dofs_per_face</tt> times
- * <tt>this->dofs_per_face</tt>.
+ * Return the matrix interpolating from a face of of one element to the face
+ * of the neighboring element. The size of the matrix is then
+ * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
*
- * Derived elements will have to
- * implement this function. They
- * may only provide interpolation
- * matrices for certain source
- * finite elements, for example
- * those from the same family. If
- * they don't implement
- * interpolation from a given
- * element, then they must throw
- * an exception of type
+ * Derived elements will have to implement this function. They may only
+ * provide interpolation matrices for certain source finite elements, for
+ * example those from the same family. If they don't implement interpolation
+ * from a given element, then they must throw an exception of type
* FiniteElement<dim>::ExcInterpolationNotImplemented.
*/
virtual void
*/
/**
- * If, on a vertex, several finite elements are active, the hp code
- * first assigns the degrees of freedom of each of these FEs
- * different global indices. It then calls this function to find out
- * which of them should get identical values, and consequently can
- * receive the same global DoF index. This function therefore
- * returns a list of identities between DoFs of the present finite
- * element object with the DoFs of @p fe_other, which is a reference
- * to a finite element object representing one of the other finite
- * elements active on this particular vertex. The function computes
- * which of the degrees of freedom of the two finite element objects
- * are equivalent, both numbered between zero and the corresponding
- * value of dofs_per_vertex of the two finite elements. The first
- * index of each pair denotes one of the vertex dofs of the present
- * element, whereas the second is the corresponding index of the
- * other finite element.
+ * If, on a vertex, several finite elements are active, the hp code first
+ * assigns the degrees of freedom of each of these FEs different global
+ * indices. It then calls this function to find out which of them should get
+ * identical values, and consequently can receive the same global DoF index.
+ * This function therefore returns a list of identities between DoFs of the
+ * present finite element object with the DoFs of @p fe_other, which is a
+ * reference to a finite element object representing one of the other finite
+ * elements active on this particular vertex. The function computes which of
+ * the degrees of freedom of the two finite element objects are equivalent,
+ * both numbered between zero and the corresponding value of dofs_per_vertex
+ * of the two finite elements. The first index of each pair denotes one of
+ * the vertex dofs of the present element, whereas the second is the
+ * corresponding index of the other finite element.
*
- * This being a discontinuous element, the set of such constraints
- * is of course empty.
+ * This being a discontinuous element, the set of such constraints is of
+ * course empty.
*/
virtual
std::vector<std::pair<unsigned int, unsigned int> >
hp_vertex_dof_identities (const FiniteElement<dim, spacedim> &fe_other) const;
/**
- * Same as hp_vertex_dof_indices(), except that the function treats
- * degrees of freedom on lines.
+ * Same as hp_vertex_dof_indices(), except that the function treats degrees
+ * of freedom on lines.
*
- * This being a discontinuous element, the set of such constraints
- * is of course empty.
+ * This being a discontinuous element, the set of such constraints is of
+ * course empty.
*/
virtual
std::vector<std::pair<unsigned int, unsigned int> >
hp_line_dof_identities (const FiniteElement<dim, spacedim> &fe_other) const;
/**
- * Same as hp_vertex_dof_indices(), except that the function treats
- * degrees of freedom on quads.
+ * Same as hp_vertex_dof_indices(), except that the function treats degrees
+ * of freedom on quads.
*
- * This being a discontinuous element, the set of such constraints
- * is of course empty.
+ * This being a discontinuous element, the set of such constraints is of
+ * course empty.
*/
virtual
std::vector<std::pair<unsigned int, unsigned int> >
hp_quad_dof_identities (const FiniteElement<dim, spacedim> &fe_other) const;
/**
- * Return whether this element
- * implements its hanging node
- * constraints in the new way,
- * which has to be used to make
- * elements "hp compatible".
+ * Return whether this element implements its hanging node constraints in
+ * the new way, which has to be used to make elements "hp compatible".
*
- * For the FE_DGQ class the result is
- * always true (independent of the degree
- * of the element), as it has no hanging
- * nodes (being a discontinuous element).
+ * For the FE_DGQ class the result is always true (independent of the degree
+ * of the element), as it has no hanging nodes (being a discontinuous
+ * element).
*/
virtual bool hp_constraints_are_implemented () const;
/**
- * Return whether this element dominates
- * the one given as argument when they
- * meet at a common face,
- * whether it is the other way around,
- * whether neither dominates, or if
- * either could dominate.
+ * Return whether this element dominates the one given as argument when they
+ * meet at a common face, whether it is the other way around, whether
+ * neither dominates, or if either could dominate.
*
- * For a definition of domination, see
- * FiniteElementBase::Domination and in
+ * For a definition of domination, see FiniteElementBase::Domination and in
* particular the @ref hp_paper "hp paper".
*/
virtual
get_constant_modes () const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*
- * This function is made virtual,
- * since finite element objects
- * are usually accessed through
- * pointers to their base class,
- * rather than the class itself.
+ * This function is made virtual, since finite element objects are usually
+ * accessed through pointers to their base class, rather than the class
+ * itself.
*/
virtual std::size_t memory_consumption () const;
protected:
/**
- * Constructor for tensor product
- * polynomials based on
- * Polynomials::Lagrange
- * interpolation of the support
- * points in the quadrature rule
- * <tt>points</tt>. The degree of
- * these polynomials is
+ * Constructor for tensor product polynomials based on Polynomials::Lagrange
+ * interpolation of the support points in the quadrature rule
+ * <tt>points</tt>. The degree of these polynomials is
* <tt>points.size()-1</tt>.
*
- * Note: The FE_DGQ::clone function
- * does not work properly for FE with
+ * Note: The FE_DGQ::clone function does not work properly for FE with
* arbitrary nodes!
*/
FE_DGQ (const Quadrature<1> &points);
/**
- * @p clone function instead of
- * a copy constructor.
+ * @p clone function instead of a copy constructor.
*
- * This function is needed by the
- * constructors of @p FESystem.
+ * This function is needed by the constructors of @p FESystem.
*/
virtual FiniteElement<dim, spacedim> *clone() const;
private:
/**
- * Only for internal use. Its
- * full name is
- * @p get_dofs_per_object_vector
- * function and it creates the
- * @p dofs_per_object vector that is
- * needed within the constructor to
- * be passed to the constructor of
- * @p FiniteElementData.
+ * Only for internal use. Its full name is @p get_dofs_per_object_vector
+ * function and it creates the @p dofs_per_object vector that is needed
+ * within the constructor to be passed to the constructor of @p
+ * FiniteElementData.
*/
static std::vector<unsigned int> get_dpo_vector (const unsigned int degree);
/**
- * Compute renumbering for rotation
- * of degrees of freedom.
+ * Compute renumbering for rotation of degrees of freedom.
*
- * Rotates a tensor product
- * numbering of degrees of
- * freedom by 90 degrees. It is
- * used to compute the transfer
- * matrices of the children by
- * using only the matrix for the
- * first child.
+ * Rotates a tensor product numbering of degrees of freedom by 90 degrees.
+ * It is used to compute the transfer matrices of the children by using only
+ * the matrix for the first child.
*
- * The direction parameter
- * determines the type of
- * rotation. It is one character
- * of @p xXyYzZ. The character
- * determines the axis of
- * rotation, case determines the
- * direction. Lower case is
- * counter-clockwise seen in
+ * The direction parameter determines the type of rotation. It is one
+ * character of @p xXyYzZ. The character determines the axis of rotation,
+ * case determines the direction. Lower case is counter-clockwise seen in
* direction of the axis.
*
- * Since rotation around the
- * y-axis is not used, it is not
- * implemented either.
+ * Since rotation around the y-axis is not used, it is not implemented
+ * either.
*/
void rotate_indices (std::vector<unsigned int> &indices,
const char direction) const;
template <int dim1, int spacedim1> friend class FE_DGQ;
/**
- * Allows @p MappingQ class to
- * access to build_renumbering
- * function.
+ * Allows @p MappingQ class to access to build_renumbering function.
*/
template <int dim1, int spacedim1> friend class MappingQ;
};
{
public:
/**
- * Constructor for tensor product
- * polynomials based on
- * Polynomials::Lagrange
- * interpolation of the support
- * points in the quadrature rule
- * <tt>points</tt>. The degree of
- * these polynomials is
+ * Constructor for tensor product polynomials based on Polynomials::Lagrange
+ * interpolation of the support points in the quadrature rule
+ * <tt>points</tt>. The degree of these polynomials is
* <tt>points.size()-1</tt>.
*/
FE_DGQArbitraryNodes (const Quadrature<1> &points);
/**
- * Return a string that uniquely
- * identifies a finite
- * element. This class returns
- * <tt>FE_DGQArbitraryNodes<dim>(degree)</tt>,
- * with <tt>dim</tt> and <tt>degree</tt>
- * replaced by appropriate
- * values.
+ * Return a string that uniquely identifies a finite element. This class
+ * returns <tt>FE_DGQArbitraryNodes<dim>(degree)</tt>, with <tt>dim</tt> and
+ * <tt>degree</tt> replaced by appropriate values.
*/
virtual std::string get_name () const;
protected:
/**
- * @p clone function instead of
- * a copy constructor.
+ * @p clone function instead of a copy constructor.
*
- * This function is needed by the
- * constructors of @p FESystem.
+ * This function is needed by the constructors of @p FESystem.
*/
virtual FiniteElement<dim,spacedim> *clone() const;
};
* and two, the polynomials hence correspond to the usual Lagrange polynomials
* on equidistant points.
*
- * Although the name does not give it away, the element is discontinuous
- * at locations where faces of cells meet. In particular,
- * this finite element is the trace space of FE_RaviartThomas on the faces and
- * serves in hybridized methods, e.g. in combination with the FE_DGQ
- * element. Its use is demonstrated in the step-51 tutorial program.
+ * Although the name does not give it away, the element is discontinuous at
+ * locations where faces of cells meet. In particular, this finite element is
+ * the trace space of FE_RaviartThomas on the faces and serves in hybridized
+ * methods, e.g. in combination with the FE_DGQ element. Its use is
+ * demonstrated in the step-51 tutorial program.
*
- * @note Since this element is defined only on faces, only
- * FEFaceValues and FESubfaceValues will be able to extract reasonable
- * values from any face polynomial. In order to make the use of
- * FESystem simpler, using a (cell) FEValues object will not fail using this finite
- * element space, but all shape function values extracted will be equal
- * to zero.
+ * @note Since this element is defined only on faces, only FEFaceValues and
+ * FESubfaceValues will be able to extract reasonable values from any face
+ * polynomial. In order to make the use of FESystem simpler, using a (cell)
+ * FEValues object will not fail using this finite element space, but all
+ * shape function values extracted will be equal to zero.
*
* @ingroup fe
* @author Guido Kanschat, Martin Kronbichler
* FiniteElement.
*
* This class assumes that shape functions of this FiniteElement do
- * <em>not</em> depend on the actual shape of the cells in real
- * space. Therefore, the effect in this element is as follows: if
- * <tt>update_values</tt> is set in <tt>flags</tt>, copy it to the
- * result. All other flags of the result are cleared, since everything else
- * must be computed for each cell.
+ * <em>not</em> depend on the actual shape of the cells in real space.
+ * Therefore, the effect in this element is as follows: if
+ * <tt>update_values</tt> is set in <tt>flags</tt>, copy it to the result.
+ * All other flags of the result are cleared, since everything else must be
+ * computed for each cell.
*/
virtual UpdateFlags update_once (const UpdateFlags flags) const;
/**
* A finite element, which is a Legendre element of complete polynomials on
- * each face (i.e., it is the face equivalent of what FE_DGP is on cells)
- * and undefined in the interior of the cells. The basis functions on
- * the faces are from Polynomials::Legendre.
+ * each face (i.e., it is the face equivalent of what FE_DGP is on cells) and
+ * undefined in the interior of the cells. The basis functions on the faces
+ * are from Polynomials::Legendre.
*
- * Although the name does not give it away, the element is discontinuous
- * at locations where faces of cells meet. The element
- * serves in hybridized methods, e.g. in combination with the FE_DGP
- * element. An example of hybridizes methods can be found in the
- * step-51 tutorial program.
+ * Although the name does not give it away, the element is discontinuous at
+ * locations where faces of cells meet. The element serves in hybridized
+ * methods, e.g. in combination with the FE_DGP element. An example of
+ * hybridizes methods can be found in the step-51 tutorial program.
*
- * @note Since this element is defined only on faces, only
- * FEFaceValues and FESubfaceValues will be able to extract reasonable
- * values from any face polynomial. In order to make the use of
- * FESystem simpler, using a (cell) FEValues object will not fail using this finite
- * element space, but all shape function values extracted will be equal
- * to zero.
+ * @note Since this element is defined only on faces, only FEFaceValues and
+ * FESubfaceValues will be able to extract reasonable values from any face
+ * polynomial. In order to make the use of FESystem simpler, using a (cell)
+ * FEValues object will not fail using this finite element space, but all
+ * shape function values extracted will be equal to zero.
*
* @ingroup fe
* @author Martin Kronbichler
/*@{*/
/**
- * @warning Several aspects of the implementation are
- * experimental. For the moment, it is safe to use the element on
- * globally refined meshes with consistent orientation of faces. See
- * the todo entries below for more detailed caveats.
+ * @warning Several aspects of the implementation are experimental. For the
+ * moment, it is safe to use the element on globally refined meshes with
+ * consistent orientation of faces. See the todo entries below for more
+ * detailed caveats.
*
- * Implementation of Nédélec elements, conforming with the
- * space H<sup>curl</sup>. These elements generate vector fields with
- * tangential components continuous between mesh cells.
+ * Implementation of Nédélec elements, conforming with the space
+ * H<sup>curl</sup>. These elements generate vector fields with tangential
+ * components continuous between mesh cells.
*
* We follow the convention that the degree of Nédélec elements
* denotes the polynomial degree of the largest complete polynomial subspace
* \stackrel{\text{div}}{\rightarrow}
* DGQ_{k}
* @f]
- * Consequently, approximation order of
- * the Nédélec space equals the value <i>degree</i> given to the constructor.
- * In this scheme, the lowest order element would be created by the call
- * FE_Nedelec<dim>(0). Note that this follows the convention of Brezzi and
- * Raviart, though not the one used in the original paper by Nédélec.
+ * Consequently, approximation order of the Nédélec space equals the value
+ * <i>degree</i> given to the constructor. In this scheme, the lowest order
+ * element would be created by the call FE_Nedelec<dim>(0). Note that this
+ * follows the convention of Brezzi and Raviart, though not the one used in
+ * the original paper by Nédélec.
*
- * This class is not implemented for the codimension one case
- * (<tt>spacedim != dim</tt>).
+ * This class is not implemented for the codimension one case (<tt>spacedim !=
+ * dim</tt>).
*
* @todo Even if this element is implemented for two and three space
- * dimensions, the definition of the node values relies on
- * consistently oriented faces in 3D. Therefore, care should be taken
- * on complicated meshes.
+ * dimensions, the definition of the node values relies on consistently
+ * oriented faces in 3D. Therefore, care should be taken on complicated
+ * meshes.
*
* <h3>Restriction on transformations</h3>
*
- * In some sense, the implementation of this element is not complete,
- * but you will rarely notice. Here is the fact: since the element is
- * vector-valued already on the unit cell, the Jacobian matrix (or its
- * inverse) is needed already to generate the values of the shape
- * functions on the cells in real space. This is in contrast to most
- * other elements, where you only need the Jacobian for the
- * gradients. Thus, to generate the gradients of Nédélec shape
- * functions, one would need to have the derivatives of the inverse of
+ * In some sense, the implementation of this element is not complete, but you
+ * will rarely notice. Here is the fact: since the element is vector-valued
+ * already on the unit cell, the Jacobian matrix (or its inverse) is needed
+ * already to generate the values of the shape functions on the cells in real
+ * space. This is in contrast to most other elements, where you only need the
+ * Jacobian for the gradients. Thus, to generate the gradients of Nédélec
+ * shape functions, one would need to have the derivatives of the inverse of
* the Jacobian matrix.
*
- * Basically, the Nédélec shape functions can be understood as the
- * gradients of scalar shape functions on the real cell. They are thus
- * the inverse Jacobian matrix times the gradients of scalar shape
- * functions on the unit cell. The gradient of Nédélec shape functions
- * is then, by the product rule, the sum of first the derivative (with
- * respect to true coordinates) of the inverse Jacobian times the
- * gradient (in unit coordinates) of the scalar shape function, plus
- * second the inverse Jacobian times the derivative (in true
- * coordinates) of the gradient (in unit coordinates) of the scalar
- * shape functions. Note that each of the derivatives in true
- * coordinates can be expressed as inverse Jacobian times gradient in
- * unit coordinates.
+ * Basically, the Nédélec shape functions can be understood as the gradients
+ * of scalar shape functions on the real cell. They are thus the inverse
+ * Jacobian matrix times the gradients of scalar shape functions on the unit
+ * cell. The gradient of Nédélec shape functions is then, by the product
+ * rule, the sum of first the derivative (with respect to true coordinates) of
+ * the inverse Jacobian times the gradient (in unit coordinates) of the scalar
+ * shape function, plus second the inverse Jacobian times the derivative (in
+ * true coordinates) of the gradient (in unit coordinates) of the scalar shape
+ * functions. Note that each of the derivatives in true coordinates can be
+ * expressed as inverse Jacobian times gradient in unit coordinates.
*
- * The problem is the derivative of the inverse Jacobian. This rank-3
- * tensor can actually be computed (and we did so in very early
- * versions of the library), but is a large task and very time
- * consuming, so we dropped it. Since it is not available, we simply
- * drop this first term.
+ * The problem is the derivative of the inverse Jacobian. This rank-3 tensor
+ * can actually be computed (and we did so in very early versions of the
+ * library), but is a large task and very time consuming, so we dropped it.
+ * Since it is not available, we simply drop this first term.
*
- * What this means for the present case: first the computation of
- * gradients of Nédélec shape functions is wrong in general. Second,
- * in the following two cases you will not notice this:
+ * What this means for the present case: first the computation of gradients of
+ * Nédélec shape functions is wrong in general. Second, in the following two
+ * cases you will not notice this:
*
- * - If the cell is a parallelogram, then the usual bi-/trilinear mapping
- * is in fact affine. In that case, the gradient of the Jacobian vanishes
- * and the gradient of the shape functions is computed exactly, since the
- * first term is zero.
+ * - If the cell is a parallelogram, then the usual bi-/trilinear mapping is
+ * in fact affine. In that case, the gradient of the Jacobian vanishes and the
+ * gradient of the shape functions is computed exactly, since the first term
+ * is zero.
*
- * - With the Nédélec elements, you will usually want to compute
- * the curl, not the general derivative tensor. However, the curl of the
- * Jacobian vanishes, so for the curl of shape functions the first term
- * is irrelevant, and the curl will always be computed correctly even on
- * cells that are not parallelograms.
+ * - With the Nédélec elements, you will usually want to compute the curl,
+ * not the general derivative tensor. However, the curl of the Jacobian
+ * vanishes, so for the curl of shape functions the first term is irrelevant,
+ * and the curl will always be computed correctly even on cells that are not
+ * parallelograms.
*
*
* <h3>Interpolation</h3>
*
- * The @ref GlossInterpolation "interpolation" operators associated
- * with the Nédélec element are constructed such that
- * interpolation and computing the curl are commuting operations on
- * rectangular mesh cells. We require this from interpolating
- * arbitrary functions as well as the #restriction matrices.
+ * The @ref GlossInterpolation "interpolation" operators associated with the
+ * Nédélec element are constructed such that interpolation and
+ * computing the curl are commuting operations on rectangular mesh cells. We
+ * require this from interpolating arbitrary functions as well as the
+ * #restriction matrices.
*
* <h4>Node values</h4>
*
- * The @ref GlossNodes "node values" for an element of degree <i>k</i>
- * on the reference cell are:
+ * The @ref GlossNodes "node values" for an element of degree <i>k</i> on the
+ * reference cell are:
* <ol>
- * <li> On edges: the moments of the tangential component with respect
- * to polynomials of degree <i>k</i>.
- * <li> On faces: the moments of the tangential components with
- * respect to <tt>dim</tt>-1 dimensional FE_Nedelec
- * polynomials of degree <i>k</i>-1.
- * <li> In cells: the moments with respect to gradients of polynomials
- * in FE_Q of degree <i>k</i>.
+ * <li> On edges: the moments of the tangential component with respect to
+ * polynomials of degree <i>k</i>.
+ * <li> On faces: the moments of the tangential components with respect to
+ * <tt>dim</tt>-1 dimensional FE_Nedelec polynomials of degree <i>k</i>-1.
+ * <li> In cells: the moments with respect to gradients of polynomials in FE_Q
+ * of degree <i>k</i>.
* </ol>
*
* <h4>Generalized support points</h4>
*
* The node values above rely on integrals, which will be computed by
- * quadrature rules themselves. The generalized support points are a
- * set of points such that this quadrature can be performed with
- * sufficient accuracy. The points needed are those of
- * QGauss<sub>k+1</sub> on each edge and QGauss<sub>k+2</sub> on each face and in
- * the interior of the cell (or none for N<sub>1</sub>).
+ * quadrature rules themselves. The generalized support points are a set of
+ * points such that this quadrature can be performed with sufficient accuracy.
+ * The points needed are those of QGauss<sub>k+1</sub> on each edge and
+ * QGauss<sub>k+2</sub> on each face and in the interior of the cell (or none
+ * for N<sub>1</sub>).
*
* @author Markus Bürg
* @date 2009, 2010, 2011
{
public:
/**
- * Constructor for the Nédélec
- * element of degree @p p.
+ * Constructor for the Nédélec element of degree @p p.
*/
FE_Nedelec (const unsigned int p);
/**
- * Return a string that uniquely
- * identifies a finite
- * element. This class returns
- * <tt>FE_Nedelec<dim>(degree)</tt>, with
- * @p dim and @p degree
- * replaced by appropriate
- * values.
+ * Return a string that uniquely identifies a finite element. This class
+ * returns <tt>FE_Nedelec<dim>(degree)</tt>, with @p dim and @p degree
+ * replaced by appropriate values.
*/
virtual std::string get_name () const;
const unsigned int face_index) const;
/**
- * Return whether this element implements its
- * hanging node constraints in the new way, which
- * has to be used to make elements "hp compatible".
+ * Return whether this element implements its hanging node constraints in
+ * the new way, which has to be used to make elements "hp compatible".
*
- * For the <tt>FE_Nedelec</tt> class the result is
- * always true (independent of the degree of the
- * element), as it implements the complete set of
+ * For the <tt>FE_Nedelec</tt> class the result is always true (independent
+ * of the degree of the element), as it implements the complete set of
* functions necessary for hp capability.
*/
virtual bool hp_constraints_are_implemented () const;
/**
- * Return whether this element dominates the one,
- * which is given as argument.
+ * Return whether this element dominates the one, which is given as
+ * argument.
*/
virtual FiniteElementDomination::Domination
compare_for_face_domination (const FiniteElement<dim> &fe_other) const;
/**
- * If, on a vertex, several finite elements are active, the hp code
- * first assigns the degrees of freedom of each of these FEs
- * different global indices. It then calls this function to find out
- * which of them should get identical values, and consequently can
- * receive the same global DoF index. This function therefore
- * returns a list of identities between DoFs of the present finite
- * element object with the DoFs of @p fe_other, which is a reference
- * to a finite element object representing one of the other finite
- * elements active on this particular vertex. The function computes
- * which of the degrees of freedom of the two finite element objects
- * are equivalent, both numbered between zero and the corresponding
- * value of dofs_per_vertex of the two finite elements. The first
- * index of each pair denotes one of the vertex dofs of the present
- * element, whereas the second is the corresponding index of the
- * other finite element.
+ * If, on a vertex, several finite elements are active, the hp code first
+ * assigns the degrees of freedom of each of these FEs different global
+ * indices. It then calls this function to find out which of them should get
+ * identical values, and consequently can receive the same global DoF index.
+ * This function therefore returns a list of identities between DoFs of the
+ * present finite element object with the DoFs of @p fe_other, which is a
+ * reference to a finite element object representing one of the other finite
+ * elements active on this particular vertex. The function computes which of
+ * the degrees of freedom of the two finite element objects are equivalent,
+ * both numbered between zero and the corresponding value of dofs_per_vertex
+ * of the two finite elements. The first index of each pair denotes one of
+ * the vertex dofs of the present element, whereas the second is the
+ * corresponding index of the other finite element.
*/
virtual std::vector<std::pair<unsigned int, unsigned int> >
hp_vertex_dof_identities (const FiniteElement<dim> &fe_other) const;
/**
- * Same as hp_vertex_dof_indices(), except that
- * the function treats degrees of freedom on lines.
+ * Same as hp_vertex_dof_indices(), except that the function treats degrees
+ * of freedom on lines.
*/
virtual std::vector<std::pair<unsigned int, unsigned int> >
hp_line_dof_identities (const FiniteElement<dim> &fe_other) const;
/**
- * Same as hp_vertex_dof_indices(), except that
- * the function treats degrees of freedom on lines.
+ * Same as hp_vertex_dof_indices(), except that the function treats degrees
+ * of freedom on lines.
*/
virtual std::vector<std::pair<unsigned int, unsigned int> >
hp_quad_dof_identities (const FiniteElement<dim> &fe_other) const;
/**
- * Return the matrix interpolating from a face of one
- * element to the face of the neighboring element. The
- * size of the matrix is then <tt>source.dofs_per_face</tt>
- * times <tt>this->dofs_per_face</tt>.
+ * Return the matrix interpolating from a face of one element to the face of
+ * the neighboring element. The size of the matrix is then
+ * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
*
- * Derived elements will have to implement this function.
- * They may only provide interpolation matrices for certain
- * source finite elements, for example those from the same
- * family. If they don't implement interpolation from a given
- * element, then they must throw an exception of type
+ * Derived elements will have to implement this function. They may only
+ * provide interpolation matrices for certain source finite elements, for
+ * example those from the same family. If they don't implement interpolation
+ * from a given element, then they must throw an exception of type
* <tt>FiniteElement<dim>::ExcInterpolationNotImplemented</tt>.
*/
virtual void
FullMatrix<double> &matrix) const;
/**
- * Return the matrix interpolating from a face of one element
- * to the subface of the neighboring element. The size of
- * the matrix is then <tt>source.dofs_per_face</tt> times
- * <tt>this->dofs_per_face</tt>.
+ * Return the matrix interpolating from a face of one element to the subface
+ * of the neighboring element. The size of the matrix is then
+ * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
*
- * Derived elements will have to implement this function.
- * They may only provide interpolation matrices for certain
- * source finite elements, for example those from the same
- * family. If they don't implement interpolation from a given
- * element, then they must throw an exception of type
+ * Derived elements will have to implement this function. They may only
+ * provide interpolation matrices for certain source finite elements, for
+ * example those from the same family. If they don't implement interpolation
+ * from a given element, then they must throw an exception of type
* <tt>ExcInterpolationNotImplemented</tt>.
*/
virtual void
private:
/**
- * Only for internal use. Its
- * full name is
- * @p get_dofs_per_object_vector
- * function and it creates the
- * @p dofs_per_object vector that is
- * needed within the constructor to
- * be passed to the constructor of
- * @p FiniteElementData.
- *
- * If the optional argument
- * <tt>dg</tt> is true, the
- * vector returned will have all
- * degrees of freedom assigned to
- * the cell, none on the faces
- * and edges.
- */
+ * Only for internal use. Its full name is @p get_dofs_per_object_vector
+ * function and it creates the @p dofs_per_object vector that is needed
+ * within the constructor to be passed to the constructor of @p
+ * FiniteElementData.
+ *
+ * If the optional argument <tt>dg</tt> is true, the vector returned will
+ * have all degrees of freedom assigned to the cell, none on the faces and
+ * edges.
+ */
static std::vector<unsigned int>
get_dpo_vector (const unsigned int degree, bool dg=false);
/**
- * Initialize the @p
- * generalized_support_points
- * field of the FiniteElement
- * class and fill the tables with
- * interpolation weights
- * (#boundary_weights and
- * interior_weights). Called
- * from the constructor.
+ * Initialize the @p generalized_support_points field of the FiniteElement
+ * class and fill the tables with interpolation weights (#boundary_weights
+ * and interior_weights). Called from the constructor.
*/
void initialize_support_points (const unsigned int degree);
/**
- * Initialize the interpolation
- * from functions on refined mesh
- * cells onto the father
- * cell. According to the
- * philosophy of the
- * Nédélec element, this
- * restriction operator preserves
- * the curl of a function
- * weakly.
+ * Initialize the interpolation from functions on refined mesh cells onto
+ * the father cell. According to the philosophy of the Nédélec element,
+ * this restriction operator preserves the curl of a function weakly.
*/
void initialize_restriction ();
/**
* Fields of cell-independent data.
*
- * For information about the
- * general purpose of this class,
- * see the documentation of the
- * base class.
+ * For information about the general purpose of this class, see the
+ * documentation of the base class.
*/
class InternalData : public FiniteElement<dim>::InternalDataBase
{
public:
/**
- * Array with shape function
- * values in quadrature
- * points. There is one row
- * for each shape function,
- * containing values for each
- * quadrature point. Since
- * the shape functions are
- * vector-valued (with as
- * many components as there
- * are space dimensions), the
- * value is a tensor.
+ * Array with shape function values in quadrature points. There is one row
+ * for each shape function, containing values for each quadrature point.
+ * Since the shape functions are vector-valued (with as many components as
+ * there are space dimensions), the value is a tensor.
*
- * In this array, we store
- * the values of the shape
- * function in the quadrature
- * points on the unit
- * cell. The transformation
- * to the real space cell is
- * then simply done by
- * multiplication with the
- * Jacobian of the mapping.
+ * In this array, we store the values of the shape function in the
+ * quadrature points on the unit cell. The transformation to the real
+ * space cell is then simply done by multiplication with the Jacobian of
+ * the mapping.
*/
std::vector<std::vector<Tensor<1, dim> > > shape_values;
/**
- * Array with shape function
- * gradients in quadrature
- * points. There is one
- * row for each shape
- * function, containing
- * values for each quadrature
+ * Array with shape function gradients in quadrature points. There is one
+ * row for each shape function, containing values for each quadrature
* point.
*
- * We store the gradients in
- * the quadrature points on
- * the unit cell. We then
- * only have to apply the
- * transformation (which is a
- * matrix-vector
- * multiplication) when
- * visiting an actual cell.
+ * We store the gradients in the quadrature points on the unit cell. We
+ * then only have to apply the transformation (which is a matrix-vector
+ * multiplication) when visiting an actual cell.
*/
std::vector<std::vector<Tensor<2, dim> > > shape_gradients;
};
/**
- * These are the factors
- * multiplied to a function in
- * the
- * #generalized_face_support_points
- * when computing the
- * integration.
- *
- * See the @ref GlossGeneralizedSupport "glossary entry on generalized support points"
- * for more information.
+ * These are the factors multiplied to a function in the
+ * #generalized_face_support_points when computing the integration.
+ *
+ * See the @ref GlossGeneralizedSupport "glossary entry on generalized
+ * support points" for more information.
*/
Table<2, double> boundary_weights;
mutable Threads::Mutex mutex;
/**
- * Allow access from other
- * dimensions.
+ * Allow access from other dimensions.
*/
template <int dim1> friend class FE_Nedelec;
};
* FE_Nothing elements are used. The hp::DoFHandler will therefore assign no
* degrees of freedom to the FE_Nothing cells, and this subregion is therefore
* implicitly deleted from the computation. step-46 shows a use case for this
- * element. An interesting application for this element is also presented in the
- * paper A. Cangiani, J. Chapman, E. Georgoulis, M. Jensen:
- * <b>Implementation of the Continuous-Discontinuous Galerkin Finite Element Method</b>,
- * arXiv:1201.2878v1 [math.NA], 2012 (see http://arxiv.org/abs/1201.2878).
+ * element. An interesting application for this element is also presented in
+ * the paper A. Cangiani, J. Chapman, E. Georgoulis, M. Jensen:
+ * <b>Implementation of the Continuous-Discontinuous Galerkin Finite Element
+ * Method</b>, arXiv:1201.2878v1 [math.NA], 2012 (see
+ * http://arxiv.org/abs/1201.2878).
*
* Note that some care must be taken that the resulting mesh topology
- * continues to make sense when FE_Nothing elements are introduced.
- * This is particularly true when dealing with hanging node constraints,
- * because the library makes some basic assumptions about the nature
- * of those constraints. The following geometries are acceptable:
+ * continues to make sense when FE_Nothing elements are introduced. This is
+ * particularly true when dealing with hanging node constraints, because the
+ * library makes some basic assumptions about the nature of those constraints.
+ * The following geometries are acceptable:
* @code
* +---------+----+----+
* | | 0 | |
* | | 1 | |
* +---------+----+----+
* @endcode
- * Here, 0 denotes an FE_Nothing cell, and 1 denotes some other
- * element type. The library has no difficulty computing the necessary
- * hanging node constraints in these cases (i.e. no constraint).
- * However, the following geometry is NOT acceptable (at least
- * in the current implementation):
+ * Here, 0 denotes an FE_Nothing cell, and 1 denotes some other element type.
+ * The library has no difficulty computing the necessary hanging node
+ * constraints in these cases (i.e. no constraint). However, the following
+ * geometry is NOT acceptable (at least in the current implementation):
* @code
* +---------+----+----+
* | | 0 | |
* | | 1 | |
* +---------+----+----+
* @endcode
- * The distinction lies in the mixed nature of the child faces,
- * a case we have not implemented as of yet.
+ * The distinction lies in the mixed nature of the child faces, a case we have
+ * not implemented as of yet.
*
* @author Joshua White, Wolfgang Bangerth
*/
public:
/**
- * Constructor. Argument denotes the
- * number of components to give this
- * finite element (default = 1).
- */
+ * Constructor. Argument denotes the number of components to give this
+ * finite element (default = 1).
+ */
FE_Nothing (const unsigned int n_components = 1);
/**
- * A sort of virtual copy
- * constructor. Some places in
- * the library, for example the
- * constructors of FESystem as
- * well as the hp::FECollection
- * class, need to make copied of
- * finite elements without
- * knowing their exact type. They
- * do so through this function.
+ * A sort of virtual copy constructor. Some places in the library, for
+ * example the constructors of FESystem as well as the hp::FECollection
+ * class, need to make copied of finite elements without knowing their exact
+ * type. They do so through this function.
*/
virtual
FiniteElement<dim,spacedim> *
clone() const;
/**
- * Return a string that uniquely
- * identifies a finite
- * element. In this case it is
- * <code>FE_Nothing@<dim@></code>.
+ * Return a string that uniquely identifies a finite element. In this case
+ * it is <code>FE_Nothing@<dim@></code>.
*/
virtual
std::string
get_name() const;
/**
- * Determine the values a finite
- * element should compute on
- * initialization of data for
- * FEValues.
+ * Determine the values a finite element should compute on initialization of
+ * data for FEValues.
*
- * Given a set of flags
- * indicating what quantities are
- * requested from a FEValues
- * object, update_once() and
- * update_each() compute which
- * values must really be
- * computed. Then, the
- * <tt>fill_*_values</tt> functions
- * are called with the result of
- * these.
+ * Given a set of flags indicating what quantities are requested from a
+ * FEValues object, update_once() and update_each() compute which values
+ * must really be computed. Then, the <tt>fill_*_values</tt> functions are
+ * called with the result of these.
*
- * In this case, since the element
- * has zero degrees of freedom and
- * no information can be computed on
- * it, this function simply returns
- * the default (empty) set of update
- * flags.
+ * In this case, since the element has zero degrees of freedom and no
+ * information can be computed on it, this function simply returns the
+ * default (empty) set of update flags.
*/
virtual
update_once (const UpdateFlags flags) const;
/**
- * Complementary function for
- * update_once().
+ * Complementary function for update_once().
*
- * While update_once() returns
- * the values to be computed on
- * the unit cell for yielding the
- * required data, this function
- * determines the values that
- * must be recomputed on each
- * cell.
+ * While update_once() returns the values to be computed on the unit cell
+ * for yielding the required data, this function determines the values that
+ * must be recomputed on each cell.
*
- * Refer to update_once() for
- * more details.
+ * Refer to update_once() for more details.
*/
virtual
UpdateFlags
update_each (const UpdateFlags flags) const;
/**
- * Return the value of the
- * @p ith shape function at the
- * point @p p. @p p is a point
- * on the reference element. Because the
- * current element has no degrees of freedom,
- * this function should obviously not be
- * called in practice. All this function
- * really does, therefore, is trigger an
+ * Return the value of the @p ith shape function at the point @p p. @p p is
+ * a point on the reference element. Because the current element has no
+ * degrees of freedom, this function should obviously not be called in
+ * practice. All this function really does, therefore, is trigger an
* exception.
*/
virtual
shape_value (const unsigned int i, const Point<dim> &p) const;
/**
- * Fill the fields of
- * FEValues. This function
- * performs all the operations
- * needed to compute the data of an
- * FEValues object.
+ * Fill the fields of FEValues. This function performs all the operations
+ * needed to compute the data of an FEValues object.
*
- * In the current case, this function
- * returns no meaningful information,
- * since the element has no degrees of
- * freedom.
+ * In the current case, this function returns no meaningful information,
+ * since the element has no degrees of freedom.
*/
virtual
void
CellSimilarity::Similarity &cell_similarity) const;
/**
- * Fill the fields of
- * FEFaceValues. This function
- * performs all the operations
- * needed to compute the data of an
- * FEFaceValues object.
+ * Fill the fields of FEFaceValues. This function performs all the
+ * operations needed to compute the data of an FEFaceValues object.
*
- * In the current case, this function
- * returns no meaningful information,
- * since the element has no degrees of
- * freedom.
+ * In the current case, this function returns no meaningful information,
+ * since the element has no degrees of freedom.
*/
virtual
void
FEValuesData<dim,spacedim> &data) const;
/**
- * Fill the fields of
- * FESubFaceValues. This function
- * performs all the operations
- * needed to compute the data of an
- * FESubFaceValues object.
+ * Fill the fields of FESubFaceValues. This function performs all the
+ * operations needed to compute the data of an FESubFaceValues object.
*
- * In the current case, this function
- * returns no meaningful information,
- * since the element has no degrees of
- * freedom.
+ * In the current case, this function returns no meaningful information,
+ * since the element has no degrees of freedom.
*/
virtual
void
FEValuesData<dim,spacedim> &data) const;
/**
- * Prepare internal data
- * structures and fill in values
- * independent of the
- * cell. Returns a pointer to an
- * object of which the caller of
- * this function then has to
- * assume ownership (which
- * includes destruction when it
- * is no more needed).
+ * Prepare internal data structures and fill in values independent of the
+ * cell. Returns a pointer to an object of which the caller of this function
+ * then has to assume ownership (which includes destruction when it is no
+ * more needed).
*
- * In the current case, this function
- * just returns a default pointer, since
- * no meaningful data exists for this
- * element.
+ * In the current case, this function just returns a default pointer, since
+ * no meaningful data exists for this element.
*/
virtual
typename Mapping<dim,spacedim>::InternalDataBase *
const Quadrature<dim> &quadrature) const;
/**
- * Return whether this element dominates
- * the one given as argument when they
- * meet at a common face,
- * whether it is the other way around,
- * whether neither dominates, or if
- * either could dominate.
+ * Return whether this element dominates the one given as argument when they
+ * meet at a common face, whether it is the other way around, whether
+ * neither dominates, or if either could dominate.
*
- * For a definition of domination, see
- * FiniteElementBase::Domination and in
+ * For a definition of domination, see FiniteElementBase::Domination and in
* particular the @ref hp_paper "hp paper".
*
- * In the current case, this element
- * is always assumed to dominate, unless
- * it is also of type FE_Nothing(). In
- * that situation, either element can
+ * In the current case, this element is always assumed to dominate, unless
+ * it is also of type FE_Nothing(). In that situation, either element can
* dominate.
*/
virtual
hp_constraints_are_implemented () const;
/**
- * Return the matrix
- * interpolating from a face of
- * of one element to the face of
- * the neighboring element.
- * The size of the matrix is
- * then <tt>source.#dofs_per_face</tt> times
- * <tt>this->#dofs_per_face</tt>.
- *
- * Since the current finite element has no
- * degrees of freedom, the interpolation
- * matrix is necessarily empty.
- */
+ * Return the matrix interpolating from a face of of one element to the face
+ * of the neighboring element. The size of the matrix is then
+ * <tt>source.#dofs_per_face</tt> times <tt>this->#dofs_per_face</tt>.
+ *
+ * Since the current finite element has no degrees of freedom, the
+ * interpolation matrix is necessarily empty.
+ */
virtual
void
/**
- * Return the matrix
- * interpolating from a face of
- * of one element to the subface of
- * the neighboring element.
- * The size of the matrix is
- * then <tt>source.#dofs_per_face</tt> times
- * <tt>this->#dofs_per_face</tt>.
+ * Return the matrix interpolating from a face of of one element to the
+ * subface of the neighboring element. The size of the matrix is then
+ * <tt>source.#dofs_per_face</tt> times <tt>this->#dofs_per_face</tt>.
*
- * Since the current finite element has no
- * degrees of freedom, the interpolation
- * matrix is necessarily empty.
+ * Since the current finite element has no degrees of freedom, the
+ * interpolation matrix is necessarily empty.
*/
virtual
* FiniteElement classes based on polynomial spaces like the
* TensorProductPolynomials or PolynomialSpace classes.
*
- * Every class conforming to the following interface can be used as
- * template parameter POLY.
+ * Every class conforming to the following interface can be used as template
+ * parameter POLY.
*
* @code
* static const unsigned int dimension;
* Example classes are TensorProductPolynomials, PolynomialSpace or
* PolynomialsP.
*
- * This class is not a fully implemented FiniteElement class. Instead
- * there are several pure virtual functions declared in the
- * FiniteElement and FiniteElement classes which cannot
- * implemented by this class but are left for implementation in
- * derived classes.
+ * This class is not a fully implemented FiniteElement class. Instead there
+ * are several pure virtual functions declared in the FiniteElement and
+ * FiniteElement classes which cannot implemented by this class but are left
+ * for implementation in derived classes.
*
- * Furthermore, this class assumes that shape functions of the
- * FiniteElement under consideration do <em>not</em> depend on the
- * actual shape of the cells in real space, i.e. update_once()
- * includes <tt>update_values</tt>. For FiniteElements whose shape
- * functions depend on the cells in real space, the update_once() and
- * update_each() functions must be overloaded.
+ * Furthermore, this class assumes that shape functions of the FiniteElement
+ * under consideration do <em>not</em> depend on the actual shape of the cells
+ * in real space, i.e. update_once() includes <tt>update_values</tt>. For
+ * FiniteElements whose shape functions depend on the cells in real space, the
+ * update_once() and update_each() functions must be overloaded.
*
- * @todo Since nearly all functions for spacedim != dim are
- * specialized, this class needs cleaning up.
+ * @todo Since nearly all functions for spacedim != dim are specialized, this
+ * class needs cleaning up.
*
* @author Ralf Hartmann 2004, Guido Kanschat, 2009
- **/
+ */
template <class POLY, int dim=POLY::dimension, int spacedim=dim>
class FE_Poly : public FiniteElement<dim,spacedim>
{
* FiniteElement.
*
* This class assumes that shape functions of this FiniteElement do
- * <em>not</em> depend on the actual shape of the cells in real
- * space. Therefore, the effect in this element is as follows: if
- * <tt>update_values</tt> is set in <tt>flags</tt>, copy it to the
- * result. All other flags of the result are cleared, since everything else
- * must be computed for each cell.
+ * <em>not</em> depend on the actual shape of the cells in real space.
+ * Therefore, the effect in this element is as follows: if
+ * <tt>update_values</tt> is set in <tt>flags</tt>, copy it to the result.
+ * All other flags of the result are cleared, since everything else must be
+ * computed for each cell.
*/
virtual UpdateFlags update_once (const UpdateFlags flags) const;
* @warning This class is not sufficiently tested yet!
*
* This class gives a unified framework for the implementation of
- * FiniteElement classes only located on faces of the mesh. They are
- * based on polynomial spaces like the TensorProductPolynomials or a
- * PolynomialSpace classes.
+ * FiniteElement classes only located on faces of the mesh. They are based on
+ * polynomial spaces like the TensorProductPolynomials or a PolynomialSpace
+ * classes.
*
- * Every class that implements the following functions can be used as
- * template parameter POLY.
+ * Every class that implements the following functions can be used as template
+ * parameter POLY.
*
* @code
* double compute_value (const unsigned int i,
* which cannot be implemented by this class but are left for implementation
* in derived classes.
*
- * Furthermore, this class assumes that shape functions of the
- * FiniteElement under consideration do <em>not</em> depend on the
- * actual shape of the cells in real space, i.e. update_once()
- * includes <tt>update_values</tt>. For FiniteElements whose shape
- * functions depend on the cells in real space, the update_once() and
- * update_each() functions must be overloaded.
+ * Furthermore, this class assumes that shape functions of the FiniteElement
+ * under consideration do <em>not</em> depend on the actual shape of the cells
+ * in real space, i.e. update_once() includes <tt>update_values</tt>. For
+ * FiniteElements whose shape functions depend on the cells in real space, the
+ * update_once() and update_each() functions must be overloaded.
*
* @author Guido Kanschat, 2009
- **/
+ */
template <class POLY, int dim=POLY::dimension+1, int spacedim=dim>
class FE_PolyFace : public FiniteElement<dim,spacedim>
{
const std::vector<bool> &restriction_is_additive_flags);
/**
- * Return the polynomial degree
- * of this finite element,
- * i.e. the value passed to the
- * constructor.
+ * Return the polynomial degree of this finite element, i.e. the value
+ * passed to the constructor.
*/
unsigned int get_degree () const;
/**
- * Return the value of the
- * <tt>i</tt>th shape function at
- * the point <tt>p</tt>. See the
- * FiniteElement base class
- * for more information about the
- * semantics of this function.
+ * Return the value of the <tt>i</tt>th shape function at the point
+ * <tt>p</tt>. See the FiniteElement base class for more information about
+ * the semantics of this function.
*/
// virtual double shape_value (const unsigned int i,
// const Point<dim> &p) const;
/**
- * Return the value of the
- * <tt>component</tt>th vector
- * component of the <tt>i</tt>th
- * shape function at the point
- * <tt>p</tt>. See the
- * FiniteElement base class
- * for more information about the
- * semantics of this function.
+ * Return the value of the <tt>component</tt>th vector component of the
+ * <tt>i</tt>th shape function at the point <tt>p</tt>. See the
+ * FiniteElement base class for more information about the semantics of this
+ * function.
*
- * Since this element is scalar,
- * the returned value is the same
- * as if the function without the
- * <tt>_component</tt> suffix
- * were called, provided that the
- * specified component is zero.
+ * Since this element is scalar, the returned value is the same as if the
+ * function without the <tt>_component</tt> suffix were called, provided
+ * that the specified component is zero.
*/
// virtual double shape_value_component (const unsigned int i,
// const Point<dim> &p,
// const unsigned int component) const;
/**
- * Return the gradient of the
- * <tt>i</tt>th shape function at
- * the point <tt>p</tt>. See the
- * FiniteElement base class
- * for more information about the
- * semantics of this function.
+ * Return the gradient of the <tt>i</tt>th shape function at the point
+ * <tt>p</tt>. See the FiniteElement base class for more information about
+ * the semantics of this function.
*/
// virtual Tensor<1,dim> shape_grad (const unsigned int i,
// const Point<dim> &p) const;
/**
- * Return the gradient of the
- * <tt>component</tt>th vector
- * component of the <tt>i</tt>th
- * shape function at the point
- * <tt>p</tt>. See the
- * FiniteElement base class
- * for more information about the
- * semantics of this function.
+ * Return the gradient of the <tt>component</tt>th vector component of the
+ * <tt>i</tt>th shape function at the point <tt>p</tt>. See the
+ * FiniteElement base class for more information about the semantics of this
+ * function.
*
- * Since this element is scalar,
- * the returned value is the same
- * as if the function without the
- * <tt>_component</tt> suffix
- * were called, provided that the
- * specified component is zero.
+ * Since this element is scalar, the returned value is the same as if the
+ * function without the <tt>_component</tt> suffix were called, provided
+ * that the specified component is zero.
*/
// virtual Tensor<1,dim> shape_grad_component (const unsigned int i,
// const Point<dim> &p,
// const unsigned int component) const;
/**
- * Return the tensor of second
- * derivatives of the
- * <tt>i</tt>th shape function at
- * point <tt>p</tt> on the unit
- * cell. See the
- * FiniteElement base class
- * for more information about the
- * semantics of this function.
+ * Return the tensor of second derivatives of the <tt>i</tt>th shape
+ * function at point <tt>p</tt> on the unit cell. See the FiniteElement base
+ * class for more information about the semantics of this function.
*/
// virtual Tensor<2,dim> shape_grad_grad (const unsigned int i,
// const Point<dim> &p) const;
/**
- * Return the second derivative
- * of the <tt>component</tt>th
- * vector component of the
- * <tt>i</tt>th shape function at
- * the point <tt>p</tt>. See the
- * FiniteElement base class
- * for more information about the
- * semantics of this function.
+ * Return the second derivative of the <tt>component</tt>th vector component
+ * of the <tt>i</tt>th shape function at the point <tt>p</tt>. See the
+ * FiniteElement base class for more information about the semantics of this
+ * function.
*
- * Since this element is scalar,
- * the returned value is the same
- * as if the function without the
- * <tt>_component</tt> suffix
- * were called, provided that the
- * specified component is zero.
+ * Since this element is scalar, the returned value is the same as if the
+ * function without the <tt>_component</tt> suffix were called, provided
+ * that the specified component is zero.
*/
// virtual Tensor<2,dim> shape_grad_grad_component (const unsigned int i,
// const Point<dim> &p,
/**
- * Determine the values that need
- * to be computed on the unit
- * cell to be able to compute all
- * values required by
- * <tt>flags</tt>.
+ * Determine the values that need to be computed on the unit cell to be able
+ * to compute all values required by <tt>flags</tt>.
*
- * For the purpuse of this
- * function, refer to the
- * documentation in
+ * For the purpuse of this function, refer to the documentation in
* FiniteElement.
*
- * This class assumes that shape
- * functions of this
- * FiniteElement do <em>not</em>
- * depend on the actual shape of
- * the cells in real
- * space. Therefore, the effect
- * in this element is as follows:
- * if <tt>update_values</tt> is
- * set in <tt>flags</tt>, copy it
- * to the result. All other flags
- * of the result are cleared,
- * since everything else must be
+ * This class assumes that shape functions of this FiniteElement do
+ * <em>not</em> depend on the actual shape of the cells in real space.
+ * Therefore, the effect in this element is as follows: if
+ * <tt>update_values</tt> is set in <tt>flags</tt>, copy it to the result.
+ * All other flags of the result are cleared, since everything else must be
* computed for each cell.
*/
virtual UpdateFlags update_once (const UpdateFlags flags) const;
/**
- * Determine the values that need
- * to be computed on every cell
- * to be able to compute all
- * values required by
- * <tt>flags</tt>.
+ * Determine the values that need to be computed on every cell to be able to
+ * compute all values required by <tt>flags</tt>.
*
- * For the purpuse of this
- * function, refer to the
- * documentation in
+ * For the purpuse of this function, refer to the documentation in
* FiniteElement.
*
- * This class assumes that shape
- * functions of this
- * FiniteElement do <em>not</em>
- * depend on the actual shape of
- * the cells in real
- * space.
+ * This class assumes that shape functions of this FiniteElement do
+ * <em>not</em> depend on the actual shape of the cells in real space.
*
- * The effect in this element is
- * as follows:
+ * The effect in this element is as follows:
* <ul>
*
* <li> if <tt>update_gradients</tt> is set, the result will contain
/**
* Fields of cell-independent data.
*
- * For information about the
- * general purpose of this class,
- * see the documentation of the
- * base class.
+ * For information about the general purpose of this class, see the
+ * documentation of the base class.
*/
class InternalData : public FiniteElement<dim,spacedim>::InternalDataBase
{
public:
/**
- * Array with shape function
- * values in quadrature
- * points on one face. There is one
- * row for each shape
- * function, containing
- * values for each quadrature
- * point.
+ * Array with shape function values in quadrature points on one face.
+ * There is one row for each shape function, containing values for each
+ * quadrature point.
*
- * In this array, we store
- * the values of the shape
- * function in the quadrature
- * points on one face of the unit
- * cell. Since these values
- * do not change under
- * transformation to the real
- * cell, we only need to copy
- * them over when visiting a
- * concrete cell.
+ * In this array, we store the values of the shape function in the
+ * quadrature points on one face of the unit cell. Since these values do
+ * not change under transformation to the real cell, we only need to copy
+ * them over when visiting a concrete cell.
*
- * In particular, we can
- * simply copy the same set
- * of values to each of the
+ * In particular, we can simply copy the same set of values to each of the
* faces.
*/
std::vector<std::vector<double> > shape_values;
};
/**
- * The polynomial space. Its type
- * is given by the template
- * parameter POLY.
+ * The polynomial space. Its type is given by the template parameter POLY.
*/
POLY poly_space;
};
* FiniteElement classes based on Tensor valued polynomial spaces like
* PolynomialsBDM and PolynomialsRaviartThomas.
*
- * Every class that implements following function can be used as
- * template parameter POLY.
+ * Every class that implements following function can be used as template
+ * parameter POLY.
*
* @code
* void compute (const Point<dim> &unit_point,
* std::vector<Tensor<3,dim> > &grad_grads) const;
* @endcode
*
- * In many cases, the node functionals depend on the shape of the mesh
- * cell, since they evaluate normal or tangential components on the
- * faces. In order to allow for a set of transformations, the variable
- * #mapping_type has been introduced. It should also be set in the
- * constructor of a derived class.
+ * In many cases, the node functionals depend on the shape of the mesh cell,
+ * since they evaluate normal or tangential components on the faces. In order
+ * to allow for a set of transformations, the variable #mapping_type has been
+ * introduced. It should also be set in the constructor of a derived class.
*
- * This class is not a fully implemented FiniteElement class, but
- * implements some common features of vector valued elements based on
- * vector valued polynomial classes. What's missing here in particular
- * is information on the topological location of the node values.
+ * This class is not a fully implemented FiniteElement class, but implements
+ * some common features of vector valued elements based on vector valued
+ * polynomial classes. What's missing here in particular is information on the
+ * topological location of the node values.
*
- * For more information on the template parameter <tt>spacedim</tt>,
- * see the documentation for the class Triangulation.
+ * For more information on the template parameter <tt>spacedim</tt>, see the
+ * documentation for the class Triangulation.
*
* <h3>Deriving classes</h3>
*
* Any derived class must decide on the polynomial space to use. This
- * polynomial space should be implemented simply as a set of vector
- * valued polynomials like PolynomialsBDM and
- * PolynomialsRaviartThomas. In order to facilitate this
- * implementation, the basis of this space may be arbitrary.
+ * polynomial space should be implemented simply as a set of vector valued
+ * polynomials like PolynomialsBDM and PolynomialsRaviartThomas. In order to
+ * facilitate this implementation, the basis of this space may be arbitrary.
*
* <h4>Determining the correct basis</h4>
*
- * In most cases, the set of desired node values $N_i$ and the basis
- * functions $v_j$ will not fulfill the interpolation condition
- * $N_i(v_j) = \delta_{ij}$.
+ * In most cases, the set of desired node values $N_i$ and the basis functions
+ * $v_j$ will not fulfill the interpolation condition $N_i(v_j) =
+ * \delta_{ij}$.
*
- * The use of the member data #inverse_node_matrix allows to compute
- * the basis $v_j$ automatically, after the node values
- * for each original basis function of the polynomial space have been
- * computed.
+ * The use of the member data #inverse_node_matrix allows to compute the basis
+ * $v_j$ automatically, after the node values for each original basis function
+ * of the polynomial space have been computed.
*
- * Therefore, the constructor of a derived class should have a
- * structure like this (example for interpolation in support points):
+ * Therefore, the constructor of a derived class should have a structure like
+ * this (example for interpolation in support points):
*
* @code
* fill_support_points();
* this->inverse_node_matrix.invert(N);
* @endcode
*
- * @note The matrix #inverse_node_matrix should have dimensions zero
- * before this piece of code is executed. Only then,
- * shape_value_component() will return the raw polynomial <i>j</i> as
- * defined in the polynomial space POLY.
+ * @note The matrix #inverse_node_matrix should have dimensions zero before
+ * this piece of code is executed. Only then, shape_value_component() will
+ * return the raw polynomial <i>j</i> as defined in the polynomial space POLY.
*
* <h4>Setting the transformation</h4>
*
- * In most cases, vector valued basis functions must be transformed
- * when mapped from the reference cell to the actual grid cell. These
- * transformations can be selected from the set MappingType and stored
- * in #mapping_type. Therefore, each constructor should contain a line
- * like:
+ * In most cases, vector valued basis functions must be transformed when
+ * mapped from the reference cell to the actual grid cell. These
+ * transformations can be selected from the set MappingType and stored in
+ * #mapping_type. Therefore, each constructor should contain a line like:
* @code
* this->mapping_type = this->mapping_none;
* @endcode
* @ingroup febase
* @author Guido Kanschat
* @date 2005
- **/
+ */
template <class POLY, int dim, int spacedim=dim>
class FE_PolyTensor : public FiniteElement<dim,spacedim>
{
/**
* Constructor.
*
- * @arg @c degree: constructor
- * argument for poly. May be
- * different from @p
+ * @arg @c degree: constructor argument for poly. May be different from @p
* fe_data.degree.
*/
FE_PolyTensor (const unsigned int degree,
const std::vector<ComponentMask> &nonzero_components);
/**
- * Since these elements are
- * vector valued, an exception is
- * thrown.
+ * Since these elements are vector valued, an exception is thrown.
*/
virtual double shape_value (const unsigned int i,
const Point<dim> &p) const;
const unsigned int component) const;
/**
- * Since these elements are
- * vector valued, an exception is
- * thrown.
+ * Since these elements are vector valued, an exception is thrown.
*/
virtual Tensor<1,dim> shape_grad (const unsigned int i,
const Point<dim> &p) const;
const unsigned int component) const;
/**
- * Since these elements are
- * vector valued, an exception is
- * thrown.
+ * Since these elements are vector valued, an exception is thrown.
*/
virtual Tensor<2,dim> shape_grad_grad (const unsigned int i,
const Point<dim> &p) const;
const unsigned int component) const;
/**
- * Given <tt>flags</tt>,
- * determines the values which
- * must be computed only for the
- * reference cell. Make sure,
- * that #mapping_type is set by
- * the derived class, such that
- * this function can operate
- * correctly.
+ * Given <tt>flags</tt>, determines the values which must be computed only
+ * for the reference cell. Make sure, that #mapping_type is set by the
+ * derived class, such that this function can operate correctly.
*/
virtual UpdateFlags update_once (const UpdateFlags flags) const;
/**
- * Given <tt>flags</tt>,
- * determines the values which
- * must be computed in each cell
- * cell. Make sure, that
- * #mapping_type is set by the
- * derived class, such that this
- * function can operate
- * correctly.
+ * Given <tt>flags</tt>, determines the values which must be computed in
+ * each cell cell. Make sure, that #mapping_type is set by the derived
+ * class, such that this function can operate correctly.
*/
virtual UpdateFlags update_each (const UpdateFlags flags) const;
protected:
/**
- * The mapping type to be used to
- * map shape functions from the
- * reference cell to the mesh
- * cell.
+ * The mapping type to be used to map shape functions from the reference
+ * cell to the mesh cell.
*/
MappingType mapping_type;
FEValuesData<dim,spacedim> &data) const ;
/**
- * Fields of cell-independent
- * data for FE_PolyTensor. Stores
- * the values of the shape
- * functions and their
- * derivatives on the reference
- * cell for later use.
+ * Fields of cell-independent data for FE_PolyTensor. Stores the values of
+ * the shape functions and their derivatives on the reference cell for later
+ * use.
*
- * All tables are organized in a
- * way, that the value for shape
- * function <i>i</i> at
- * quadrature point <i>k</i> is
- * accessed by indices
+ * All tables are organized in a way, that the value for shape function
+ * <i>i</i> at quadrature point <i>k</i> is accessed by indices
* <i>(i,k)</i>.
*/
class InternalData : public FiniteElement<dim,spacedim>::InternalDataBase
{
public:
/**
- * Array with shape function
- * values in quadrature
- * points. There is one
- * row for each shape
- * function, containing
- * values for each quadrature
- * point.
+ * Array with shape function values in quadrature points. There is one row
+ * for each shape function, containing values for each quadrature point.
*/
std::vector<std::vector<Tensor<1,dim> > > shape_values;
/**
- * Array with shape function
- * gradients in quadrature
- * points. There is one
- * row for each shape
- * function, containing
- * values for each quadrature
+ * Array with shape function gradients in quadrature points. There is one
+ * row for each shape function, containing values for each quadrature
* point.
*/
std::vector< std::vector< DerivativeForm<1, dim, spacedim> > > shape_grads;
};
/**
- * The polynomial space. Its type
- * is given by the template
- * parameter POLY.
+ * The polynomial space. Its type is given by the template parameter POLY.
*/
POLY poly_space;
/**
- * The inverse of the matrix
- * <i>a<sub>ij</sub></i> of node
- * values <i>N<sub>i</sub></i>
- * applied to polynomial
- * <i>p<sub>j</sub></i>. This
- * matrix is used to convert
- * polynomials in the "raw" basis
- * provided in #poly_space to the
- * basis dual to the node
- * functionals on the reference cell.
+ * The inverse of the matrix <i>a<sub>ij</sub></i> of node values
+ * <i>N<sub>i</sub></i> applied to polynomial <i>p<sub>j</sub></i>. This
+ * matrix is used to convert polynomials in the "raw" basis provided in
+ * #poly_space to the basis dual to the node functionals on the reference
+ * cell.
*
- * This object is not filled by
- * FE_PolyTensor, but is a chance
- * for a derived class to allow
- * for reorganization of the
- * basis functions. If it is left
- * empty, the basis in
- * #poly_space is used.
+ * This object is not filled by FE_PolyTensor, but is a chance for a derived
+ * class to allow for reorganization of the basis functions. If it is left
+ * empty, the basis in #poly_space is used.
*/
FullMatrix<double> inverse_node_matrix;
/**
- * If a shape function is
- * computed at a single point, we
- * must compute all of them to
- * apply #inverse_node_matrix. In
- * order to avoid too much
- * overhead, we cache the point
- * and the function values for
- * the next evaluation.
+ * If a shape function is computed at a single point, we must compute all of
+ * them to apply #inverse_node_matrix. In order to avoid too much overhead,
+ * we cache the point and the function values for the next evaluation.
*/
mutable Point<dim> cached_point;
/**
- * Cached shape function values after
- * call to
- * shape_value_component().
+ * Cached shape function values after call to shape_value_component().
*/
mutable std::vector<Tensor<1,dim> > cached_values;
/**
- * Cached shape function gradients after
- * call to
- * shape_grad_component().
+ * Cached shape function gradients after call to shape_grad_component().
*/
mutable std::vector<Tensor<2,dim> > cached_grads;
/**
- * Cached second derivatives of
- * shape functions after call to
+ * Cached second derivatives of shape functions after call to
* shape_grad_grad_component().
*/
mutable std::vector<Tensor<3,dim> > cached_grad_grads;
*
* The standard constructor of this class takes the degree @p p of this finite
* element. Alternatively, it can take a quadrature formula @p points defining
- * the support points of the Lagrange interpolation in one coordinate direction.
+ * the support points of the Lagrange interpolation in one coordinate
+ * direction.
*
- * For more information about the <tt>spacedim</tt> template parameter
- * check the documentation of FiniteElement or the one of
- * Triangulation.
+ * For more information about the <tt>spacedim</tt> template parameter check
+ * the documentation of FiniteElement or the one of Triangulation.
*
* <h3>Implementation</h3>
*
* creates a TensorProductPolynomials object that includes the tensor product
* of @p Lagrange polynomials with the support points from @p points.
*
- * Furthermore the constructor fills the @p interface_constraints, the
- * @p prolongation (embedding) and the @p restriction matrices. These
- * are implemented only up to a certain degree and may not be
- * available for very high polynomial degree.
+ * Furthermore the constructor fills the @p interface_constraints, the @p
+ * prolongation (embedding) and the @p restriction matrices. These are
+ * implemented only up to a certain degree and may not be available for very
+ * high polynomial degree.
*
*
* <h3>Numbering of the degrees of freedom (DoFs)</h3>
*
* The original ordering of the shape functions represented by the
- * TensorProductPolynomials is a tensor product
- * numbering. However, the shape functions on a cell are renumbered
- * beginning with the shape functions whose support points are at the
- * vertices, then on the line, on the quads, and finally (for 3d) on
- * the hexes. To be explicit, these numberings are listed in the
- * following:
+ * TensorProductPolynomials is a tensor product numbering. However, the shape
+ * functions on a cell are renumbered beginning with the shape functions whose
+ * support points are at the vertices, then on the line, on the quads, and
+ * finally (for 3d) on the hexes. To be explicit, these numberings are listed
+ * in the following:
*
* <h4>Q1 elements</h4>
* <ul>
* 0-------1 0-------1
* @endverbatim
*
- * The respective coordinate values of the support points of the shape
- * functions are as follows:
- * <ul>
- * <li> Shape function 0: <tt>[0, 0, 0]</tt>;
- * <li> Shape function 1: <tt>[1, 0, 0]</tt>;
- * <li> Shape function 2: <tt>[0, 1, 0]</tt>;
- * <li> Shape function 3: <tt>[1, 1, 0]</tt>;
- * <li> Shape function 4: <tt>[0, 0, 1]</tt>;
- * <li> Shape function 5: <tt>[1, 0, 1]</tt>;
- * <li> Shape function 6: <tt>[0, 1, 1]</tt>;
- * <li> Shape function 7: <tt>[1, 1, 1]</tt>;
- * </ul>
+ * The respective coordinate values of the support points of the shape
+ * functions are as follows:
+ * <ul>
+ * <li> Shape function 0: <tt>[0, 0, 0]</tt>;
+ * <li> Shape function 1: <tt>[1, 0, 0]</tt>;
+ * <li> Shape function 2: <tt>[0, 1, 0]</tt>;
+ * <li> Shape function 3: <tt>[1, 1, 0]</tt>;
+ * <li> Shape function 4: <tt>[0, 0, 1]</tt>;
+ * <li> Shape function 5: <tt>[1, 0, 1]</tt>;
+ * <li> Shape function 6: <tt>[0, 1, 1]</tt>;
+ * <li> Shape function 7: <tt>[1, 1, 1]</tt>;
+ * </ul>
* </ul>
*
- * In 2d, these shape functions look as follows:
- * <table>
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q1/Q1_shape0000.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q1/Q1_shape0001.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_1$ element, shape function 0
- * </td>
- *
- * <td align="center">
- * $Q_1$ element, shape function 1
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q1/Q1_shape0002.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q1/Q1_shape0003.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_1$ element, shape function 2
- * </td>
- *
- * <td align="center">
- * $Q_1$ element, shape function 3
- * </td>
- * </tr>
- * </table>
+ * In 2d, these shape functions look as follows: <table> <tr> <td
+ * align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q1/Q1_shape0000.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q1/Q1_shape0001.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_1$ element, shape function 0 </td>
+ *
+ * <td align="center"> $Q_1$ element, shape function 1 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q1/Q1_shape0002.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q1/Q1_shape0003.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_1$ element, shape function 2 </td>
+ *
+ * <td align="center"> $Q_1$ element, shape function 3 </td> </tr> </table>
*
*
* <h4>Q2 elements</h4>
* |/ / | |/
* *-------* *-------*
* @endverbatim
- * The center vertex has number 26.
- *
- * The respective coordinate values of the support points of the shape
- * functions are as follows:
- * <ul>
- * <li> Shape function 0: <tt>[0, 0, 0]</tt>;
- * <li> Shape function 1: <tt>[1, 0, 0]</tt>;
- * <li> Shape function 2: <tt>[0, 1, 0]</tt>;
- * <li> Shape function 3: <tt>[1, 1, 0]</tt>;
- * <li> Shape function 4: <tt>[0, 0, 1]</tt>;
- * <li> Shape function 5: <tt>[1, 0, 1]</tt>;
- * <li> Shape function 6: <tt>[0, 1, 1]</tt>;
- * <li> Shape function 7: <tt>[1, 1, 1]</tt>;
- * <li> Shape function 8: <tt>[0, 1/2, 0]</tt>;
- * <li> Shape function 9: <tt>[1, 1/2, 0]</tt>;
- * <li> Shape function 10: <tt>[1/2, 0, 0]</tt>;
- * <li> Shape function 11: <tt>[1/2, 1, 0]</tt>;
- * <li> Shape function 12: <tt>[0, 1/2, 1]</tt>;
- * <li> Shape function 13: <tt>[1, 1/2, 1]</tt>;
- * <li> Shape function 14: <tt>[1/2, 0, 1]</tt>;
- * <li> Shape function 15: <tt>[1/2, 1, 1]</tt>;
- * <li> Shape function 16: <tt>[0, 0, 1/2]</tt>;
- * <li> Shape function 17: <tt>[1, 0, 1/2]</tt>;
- * <li> Shape function 18: <tt>[0, 1, 1/2]</tt>;
- * <li> Shape function 19: <tt>[1, 1, 1/2]</tt>;
- * <li> Shape function 20: <tt>[0, 1/2, 1/2]</tt>;
- * <li> Shape function 21: <tt>[1, 1/2, 1/2]</tt>;
- * <li> Shape function 22: <tt>[1/2, 0, 1/2]</tt>;
- * <li> Shape function 23: <tt>[1/2, 1, 1/2]</tt>;
- * <li> Shape function 24: <tt>[1/2, 1/2, 0]</tt>;
- * <li> Shape function 25: <tt>[1/2, 1/2, 1]</tt>;
- * <li> Shape function 26: <tt>[1/2, 1/2, 1/2]</tt>;
- * </ul>
+ * The center vertex has number 26.
+ *
+ * The respective coordinate values of the support points of the shape
+ * functions are as follows:
+ * <ul>
+ * <li> Shape function 0: <tt>[0, 0, 0]</tt>;
+ * <li> Shape function 1: <tt>[1, 0, 0]</tt>;
+ * <li> Shape function 2: <tt>[0, 1, 0]</tt>;
+ * <li> Shape function 3: <tt>[1, 1, 0]</tt>;
+ * <li> Shape function 4: <tt>[0, 0, 1]</tt>;
+ * <li> Shape function 5: <tt>[1, 0, 1]</tt>;
+ * <li> Shape function 6: <tt>[0, 1, 1]</tt>;
+ * <li> Shape function 7: <tt>[1, 1, 1]</tt>;
+ * <li> Shape function 8: <tt>[0, 1/2, 0]</tt>;
+ * <li> Shape function 9: <tt>[1, 1/2, 0]</tt>;
+ * <li> Shape function 10: <tt>[1/2, 0, 0]</tt>;
+ * <li> Shape function 11: <tt>[1/2, 1, 0]</tt>;
+ * <li> Shape function 12: <tt>[0, 1/2, 1]</tt>;
+ * <li> Shape function 13: <tt>[1, 1/2, 1]</tt>;
+ * <li> Shape function 14: <tt>[1/2, 0, 1]</tt>;
+ * <li> Shape function 15: <tt>[1/2, 1, 1]</tt>;
+ * <li> Shape function 16: <tt>[0, 0, 1/2]</tt>;
+ * <li> Shape function 17: <tt>[1, 0, 1/2]</tt>;
+ * <li> Shape function 18: <tt>[0, 1, 1/2]</tt>;
+ * <li> Shape function 19: <tt>[1, 1, 1/2]</tt>;
+ * <li> Shape function 20: <tt>[0, 1/2, 1/2]</tt>;
+ * <li> Shape function 21: <tt>[1, 1/2, 1/2]</tt>;
+ * <li> Shape function 22: <tt>[1/2, 0, 1/2]</tt>;
+ * <li> Shape function 23: <tt>[1/2, 1, 1/2]</tt>;
+ * <li> Shape function 24: <tt>[1/2, 1/2, 0]</tt>;
+ * <li> Shape function 25: <tt>[1/2, 1/2, 1]</tt>;
+ * <li> Shape function 26: <tt>[1/2, 1/2, 1/2]</tt>;
+ * </ul>
* </ul>
*
*
* In 2d, these shape functions look as follows (the black plane corresponds
- * to zero; negative shape function values may not be visible):
- * <table>
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0000.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0001.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_2$ element, shape function 0
- * </td>
- *
- * <td align="center">
- * $Q_2$ element, shape function 1
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0002.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0003.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_2$ element, shape function 2
- * </td>
- *
- * <td align="center">
- * $Q_2$ element, shape function 3
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0004.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0005.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_2$ element, shape function 4
- * </td>
- *
- * <td align="center">
- * $Q_2$ element, shape function 5
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0006.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0007.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_2$ element, shape function 6
- * </td>
- *
- * <td align="center">
- * $Q_2$ element, shape function 7
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q2/Q2_shape0008.png" alt="">
- * </td>
- *
- * <td align="center">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_2$ element, shape function 8
- * </td>
- *
- * <td align="center">
- * </td>
- * </tr>
- * </table>
+ * to zero; negative shape function values may not be visible): <table> <tr>
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q2/Q2_shape0000.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q2/Q2_shape0001.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_2$ element, shape function 0 </td>
+ *
+ * <td align="center"> $Q_2$ element, shape function 1 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q2/Q2_shape0002.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q2/Q2_shape0003.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_2$ element, shape function 2 </td>
+ *
+ * <td align="center"> $Q_2$ element, shape function 3 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q2/Q2_shape0004.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q2/Q2_shape0005.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_2$ element, shape function 4 </td>
+ *
+ * <td align="center"> $Q_2$ element, shape function 5 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q2/Q2_shape0006.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q2/Q2_shape0007.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_2$ element, shape function 6 </td>
+ *
+ * <td align="center"> $Q_2$ element, shape function 7 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q2/Q2_shape0008.png" alt=""> </td>
+ *
+ * <td align="center"> </td> </tr> <tr> <td align="center"> $Q_2$ element,
+ * shape function 8 </td>
+ *
+ * <td align="center"> </td> </tr> </table>
*
*
* <h4>Q3 elements</h4>
* </ul>
*
* In 2d, these shape functions look as follows (the black plane corresponds
- * to zero; negative shape function values may not be visible):
- * <table>
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0000.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0001.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_3$ element, shape function 0
- * </td>
- *
- * <td align="center">
- * $Q_3$ element, shape function 1
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0002.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0003.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_3$ element, shape function 2
- * </td>
- *
- * <td align="center">
- * $Q_3$ element, shape function 3
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0004.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0005.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_3$ element, shape function 4
- * </td>
- *
- * <td align="center">
- * $Q_3$ element, shape function 5
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0006.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0007.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_3$ element, shape function 6
- * </td>
- *
- * <td align="center">
- * $Q_3$ element, shape function 7
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0008.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0009.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_3$ element, shape function 8
- * </td>
- *
- * <td align="center">
- * $Q_3$ element, shape function 9
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0010.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0011.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_3$ element, shape function 10
- * </td>
- *
- * <td align="center">
- * $Q_3$ element, shape function 11
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0012.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0013.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_3$ element, shape function 12
- * </td>
- *
- * <td align="center">
- * $Q_3$ element, shape function 13
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0014.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q3/Q3_shape0015.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_3$ element, shape function 14
- * </td>
- *
- * <td align="center">
- * $Q_3$ element, shape function 15
- * </td>
- * </tr>
- * </table>
+ * to zero; negative shape function values may not be visible): <table> <tr>
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0000.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0001.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3$ element, shape function 0 </td>
+ *
+ * <td align="center"> $Q_3$ element, shape function 1 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0002.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0003.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3$ element, shape function 2 </td>
+ *
+ * <td align="center"> $Q_3$ element, shape function 3 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0004.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0005.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3$ element, shape function 4 </td>
+ *
+ * <td align="center"> $Q_3$ element, shape function 5 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0006.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0007.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3$ element, shape function 6 </td>
+ *
+ * <td align="center"> $Q_3$ element, shape function 7 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0008.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0009.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3$ element, shape function 8 </td>
+ *
+ * <td align="center"> $Q_3$ element, shape function 9 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0010.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0011.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3$ element, shape function 10 </td>
+ *
+ * <td align="center"> $Q_3$ element, shape function 11 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0012.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0013.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3$ element, shape function 12 </td>
+ *
+ * <td align="center"> $Q_3$ element, shape function 13 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0014.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q3/Q3_shape0015.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3$ element, shape function 14 </td>
+ *
+ * <td align="center"> $Q_3$ element, shape function 15 </td> </tr> </table>
*
*
* <h4>Q4 elements</h4>
* </ul>
*
* In 2d, these shape functions look as follows (the black plane corresponds
- * to zero; negative shape function values may not be visible):
- * <table>
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0000.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0001.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4$ element, shape function 0
- * </td>
- *
- * <td align="center">
- * $Q_4$ element, shape function 1
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0002.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0003.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4$ element, shape function 2
- * </td>
- *
- * <td align="center">
- * $Q_4$ element, shape function 3
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0004.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0005.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4$ element, shape function 4
- * </td>
- *
- * <td align="center">
- * $Q_4$ element, shape function 5
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0006.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0007.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4$ element, shape function 6
- * </td>
- *
- * <td align="center">
- * $Q_4$ element, shape function 7
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0008.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0009.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4$ element, shape function 8
- * </td>
- *
- * <td align="center">
- * $Q_4$ element, shape function 9
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0010.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0011.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4$ element, shape function 10
- * </td>
- *
- * <td align="center">
- * $Q_4$ element, shape function 11
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0012.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0013.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4$ element, shape function 12
- * </td>
- *
- * <td align="center">
- * $Q_4$ element, shape function 13
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0014.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0015.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4$ element, shape function 14
- * </td>
- *
- * <td align="center">
- * $Q_4$ element, shape function 15
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0016.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0017.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4$ element, shape function 16
- * </td>
- *
- * <td align="center">
- * $Q_4$ element, shape function 17
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0018.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0019.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4$ element, shape function 18
- * </td>
- *
- * <td align="center">
- * $Q_4$ element, shape function 19
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0020.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0021.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4$ element, shape function 20
- * </td>
- *
- * <td align="center">
- * $Q_4$ element, shape function 21
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0022.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0023.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4$ element, shape function 22
- * </td>
- *
- * <td align="center">
- * $Q_4$ element, shape function 23
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/lagrange/Q4/Q4_shape0024.png" alt="">
- * </td>
- *
- * <td align="center">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4$ element, shape function 24
- * </td>
- *
- * <td align="center">
- * </td>
- * </tr>
- * </table>
- *
- *
- *
- * @author Wolfgang Bangerth, 1998, 2003; Guido Kanschat, 2001; Ralf Hartmann, 2001, 2004, 2005; Oliver Kayser-Herold, 2004; Katharina Kormann, 2008; Martin Kronbichler, 2008
+ * to zero; negative shape function values may not be visible): <table> <tr>
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0000.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0001.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 0 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 1 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0002.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0003.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 2 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 3 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0004.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0005.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 4 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 5 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0006.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0007.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 6 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 7 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0008.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0009.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 8 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 9 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0010.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0011.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 10 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 11 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0012.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0013.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 12 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 13 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0014.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0015.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 14 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 15 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0016.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0017.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 16 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 17 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0018.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0019.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 18 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 19 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0020.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0021.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 20 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 21 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0022.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0023.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4$ element, shape function 22 </td>
+ *
+ * <td align="center"> $Q_4$ element, shape function 23 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/lagrange/Q4/Q4_shape0024.png" alt=""> </td>
+ *
+ * <td align="center"> </td> </tr> <tr> <td align="center"> $Q_4$ element,
+ * shape function 24 </td>
+ *
+ * <td align="center"> </td> </tr> </table>
+ *
+ *
+ *
+ * @author Wolfgang Bangerth, 1998, 2003; Guido Kanschat, 2001; Ralf Hartmann,
+ * 2001, 2004, 2005; Oliver Kayser-Herold, 2004; Katharina Kormann, 2008;
+ * Martin Kronbichler, 2008
*/
template <int dim, int spacedim=dim>
class FE_Q : public FE_Q_Base<TensorProductPolynomials<dim>,dim,spacedim>
/**
* This class collects the basic methods used in FE_Q and FE_Q_DG0. There is
- * no public constructor for this class as it is not functional as a
- * stand-alone. The completion of definitions is left to the derived classes.
+ * no public constructor for this class as it is not functional as a stand-
+ * alone. The completion of definitions is left to the derived classes.
*
- * @author Wolfgang Bangerth, 1998, 2003; Guido Kanschat, 2001; Ralf Hartmann, 2001, 2004, 2005; Oliver Kayser-Herold, 2004; Katharina Kormann, 2008; Martin Kronbichler, 2008, 2013
+ * @author Wolfgang Bangerth, 1998, 2003; Guido Kanschat, 2001; Ralf Hartmann,
+ * 2001, 2004, 2005; Oliver Kayser-Herold, 2004; Katharina Kormann, 2008;
+ * Martin Kronbichler, 2008, 2013
*/
template <class POLY, int dim=POLY::dimension, int spacedim=dim>
class FE_Q_Base : public FE_Poly<POLY,dim,spacedim>
*
* To explain the concept, consider the case where we would like to know
* whether a degree of freedom on a face, for example as part of an FESystem
- * element, is primitive. Unfortunately, the
- * is_primitive() function in the FiniteElement class takes a cell index, so
- * we would need to find the cell index of the shape function that
- * corresponds to the present face index. This function does that.
+ * element, is primitive. Unfortunately, the is_primitive() function in the
+ * FiniteElement class takes a cell index, so we would need to find the cell
+ * index of the shape function that corresponds to the present face index.
+ * This function does that.
*
* Code implementing this would then look like this:
* @code
* actual faces can be in their standard ordering with respect to the cell
* under consideration, or can be flipped, oriented, etc.
*
- * @param face_dof_index The index of the degree of freedom on a face.
- * This index must be between zero and dofs_per_face.
- * @param face The number of the face this degree of freedom lives on.
- * This number must be between zero and GeometryInfo::faces_per_cell.
- * @param face_orientation One part of the description of the orientation
- * of the face. See @ref GlossFaceOrientation .
- * @param face_flip One part of the description of the orientation
- * of the face. See @ref GlossFaceOrientation .
- * @param face_rotation One part of the description of the orientation
- * of the face. See @ref GlossFaceOrientation .
- * @return The index of this degree of freedom within the set
- * of degrees of freedom on the entire cell. The returned value
- * will be between zero and dofs_per_cell.
+ * @param face_dof_index The index of the degree of freedom on a face. This
+ * index must be between zero and dofs_per_face.
+ * @param face The number of the face this degree of freedom lives on. This
+ * number must be between zero and GeometryInfo::faces_per_cell.
+ * @param face_orientation One part of the description of the orientation of
+ * the face. See @ref GlossFaceOrientation .
+ * @param face_flip One part of the description of the orientation of the
+ * face. See @ref GlossFaceOrientation .
+ * @param face_rotation One part of the description of the orientation of
+ * the face. See @ref GlossFaceOrientation . @return The index of this
+ * degree of freedom within the set of degrees of freedom on the entire
+ * cell. The returned value will be between zero and dofs_per_cell.
*/
virtual
unsigned int face_to_cell_index (const unsigned int face_dof_index,
virtual bool hp_constraints_are_implemented () const;
/**
- * If, on a vertex, several finite elements are active, the hp code
- * first assigns the degrees of freedom of each of these FEs
- * different global indices. It then calls this function to find out
- * which of them should get identical values, and consequently can
- * receive the same global DoF index. This function therefore
- * returns a list of identities between DoFs of the present finite
- * element object with the DoFs of @p fe_other, which is a reference
- * to a finite element object representing one of the other finite
- * elements active on this particular vertex. The function computes
- * which of the degrees of freedom of the two finite element objects
- * are equivalent, both numbered between zero and the corresponding
- * value of dofs_per_vertex of the two finite elements. The first
- * index of each pair denotes one of the vertex dofs of the present
- * element, whereas the second is the corresponding index of the
- * other finite element.
+ * If, on a vertex, several finite elements are active, the hp code first
+ * assigns the degrees of freedom of each of these FEs different global
+ * indices. It then calls this function to find out which of them should get
+ * identical values, and consequently can receive the same global DoF index.
+ * This function therefore returns a list of identities between DoFs of the
+ * present finite element object with the DoFs of @p fe_other, which is a
+ * reference to a finite element object representing one of the other finite
+ * elements active on this particular vertex. The function computes which of
+ * the degrees of freedom of the two finite element objects are equivalent,
+ * both numbered between zero and the corresponding value of dofs_per_vertex
+ * of the two finite elements. The first index of each pair denotes one of
+ * the vertex dofs of the present element, whereas the second is the
+ * corresponding index of the other finite element.
*/
virtual
std::vector<std::pair<unsigned int, unsigned int> >
hp_vertex_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
/**
- * Same as hp_vertex_dof_indices(), except that the function treats
- * degrees of freedom on lines.
+ * Same as hp_vertex_dof_indices(), except that the function treats degrees
+ * of freedom on lines.
*/
virtual
std::vector<std::pair<unsigned int, unsigned int> >
hp_line_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
/**
- * Same as hp_vertex_dof_indices(), except that the function treats
- * degrees of freedom on quads.
+ * Same as hp_vertex_dof_indices(), except that the function treats degrees
+ * of freedom on quads.
*/
virtual
std::vector<std::pair<unsigned int, unsigned int> >
void initialize_constraints (const std::vector<Point<1> > &points);
/**
- * Initialize the @p unit_support_points field of the FiniteElement
- * class. Called from initialize().
- */
+ * Initialize the @p unit_support_points field of the FiniteElement class.
+ * Called from initialize().
+ */
void initialize_unit_support_points (const std::vector<Point<1> > &points);
/**
- * Initialize the @p unit_face_support_points field of the FiniteElement
- * class. Called from initialize().
- */
+ * Initialize the @p unit_face_support_points field of the FiniteElement
+ * class. Called from initialize().
+ */
void initialize_unit_face_support_points (const std::vector<Point<1> > &points);
/**
/*@{*/
/**
- * Implementation of a scalar Lagrange finite element @p Qp+DG0 that yields the
- * finite element space of continuous, piecewise polynomials of degree @p p in
- * each coordinate direction plus the space of locally constant functions.
- * This class is realized using tensor product polynomials based on equidistant
- * or given support points.
+ * Implementation of a scalar Lagrange finite element @p Qp+DG0 that yields
+ * the finite element space of continuous, piecewise polynomials of degree @p
+ * p in each coordinate direction plus the space of locally constant
+ * functions. This class is realized using tensor product polynomials based on
+ * equidistant or given support points.
*
* The standard constructor of this class takes the degree @p p of this finite
* element. Alternatively, it can take a quadrature formula @p points defining
- * the support points of the Lagrange interpolation in one coordinate direction.
+ * the support points of the Lagrange interpolation in one coordinate
+ * direction.
*
* For more information about the <tt>spacedim</tt> template parameter check
* the documentation of FiniteElement or the one of Triangulation.
*
- * For more information regarding this element see:
- * Boffi, D., et al. "Local Mass Conservation of Stokes Finite Elements."
- * Journal of Scientific Computing (2012): 1-18.
+ * For more information regarding this element see: Boffi, D., et al. "Local
+ * Mass Conservation of Stokes Finite Elements." Journal of Scientific
+ * Computing (2012): 1-18.
*
* <h3>Implementation</h3>
*
* The constructor creates a TensorProductPolynomials object that includes the
- * tensor product of @p LagrangeEquidistant polynomials of degree @p p plus the
- * locally constant function. This @p TensorProductPolynomialsConst object
+ * tensor product of @p LagrangeEquidistant polynomials of degree @p p plus
+ * the locally constant function. This @p TensorProductPolynomialsConst object
* provides all values and derivatives of the shape functions. In case a
* quadrature rule is given, the constructor creates a
* TensorProductPolynomialsConst object that includes the tensor product of @p
* <h3>Numbering of the degrees of freedom (DoFs)</h3>
*
* The original ordering of the shape functions represented by the
- * TensorProductPolynomialsConst is a tensor product
- * numbering. However, the shape functions on a cell are renumbered
- * beginning with the shape functions whose support points are at the
- * vertices, then on the line, on the quads, and finally (for 3d) on
- * the hexes. Finally there is a support point for the discontinuous shape
- * function in the middle of the cell. To be explicit, these numberings are
- * listed in the following:
+ * TensorProductPolynomialsConst is a tensor product numbering. However, the
+ * shape functions on a cell are renumbered beginning with the shape functions
+ * whose support points are at the vertices, then on the line, on the quads,
+ * and finally (for 3d) on the hexes. Finally there is a support point for the
+ * discontinuous shape function in the middle of the cell. To be explicit,
+ * these numberings are listed in the following:
*
* <h4>Q1 elements</h4>
* <ul>
* 0-------1 0-------1
* @endverbatim
*
- * The respective coordinate values of the support points of the degrees
- * of freedom are as follows:
- * <ul>
- * <li> Index 0: <tt>[ 0, 0, 0]</tt>;
- * <li> Index 1: <tt>[ 1, 0, 0]</tt>;
- * <li> Index 2: <tt>[ 0, 1, 0]</tt>;
- * <li> Index 3: <tt>[ 1, 1, 0]</tt>;
- * <li> Index 4: <tt>[ 0, 0, 1]</tt>;
- * <li> Index 5: <tt>[ 1, 0, 1]</tt>;
- * <li> Index 6: <tt>[ 0, 1, 1]</tt>;
- * <li> Index 7: <tt>[ 1, 1, 1]</tt>;
- * <li> Index 8: <tt>[1/2, 1/2, 1/2]</tt>;
- * </ul>
+ * The respective coordinate values of the support points of the degrees of
+ * freedom are as follows:
+ * <ul>
+ * <li> Index 0: <tt>[ 0, 0, 0]</tt>;
+ * <li> Index 1: <tt>[ 1, 0, 0]</tt>;
+ * <li> Index 2: <tt>[ 0, 1, 0]</tt>;
+ * <li> Index 3: <tt>[ 1, 1, 0]</tt>;
+ * <li> Index 4: <tt>[ 0, 0, 1]</tt>;
+ * <li> Index 5: <tt>[ 1, 0, 1]</tt>;
+ * <li> Index 6: <tt>[ 0, 1, 1]</tt>;
+ * <li> Index 7: <tt>[ 1, 1, 1]</tt>;
+ * <li> Index 8: <tt>[1/2, 1/2, 1/2]</tt>;
+ * </ul>
* </ul>
* <h4>Q2 elements</h4>
* <ul>
* @verbatim
* 0---2---1
* @endverbatim
- * Index 3 has the same coordinates as index 2
+ * Index 3 has the same coordinates as index 2
*
* <li> 2D case:
* @verbatim
* | |
* 0---6---1
* @endverbatim
- * Index 9 has the same coordinates as index 2
+ * Index 9 has the same coordinates as index 2
*
* <li> 3D case:
* @verbatim
* |/ / | |/
* *-------* *-------*
* @endverbatim
- * The center vertices have number 26 and 27.
+ * The center vertices have number 26 and 27.
*
- * The respective coordinate values of the support points of the degrees
- * of freedom are as follows:
- * <ul>
- * <li> Index 0: <tt>[0, 0, 0]</tt>;
- * <li> Index 1: <tt>[1, 0, 0]</tt>;
- * <li> Index 2: <tt>[0, 1, 0]</tt>;
- * <li> Index 3: <tt>[1, 1, 0]</tt>;
- * <li> Index 4: <tt>[0, 0, 1]</tt>;
- * <li> Index 5: <tt>[1, 0, 1]</tt>;
- * <li> Index 6: <tt>[0, 1, 1]</tt>;
- * <li> Index 7: <tt>[1, 1, 1]</tt>;
- * <li> Index 8: <tt>[0, 1/2, 0]</tt>;
- * <li> Index 9: <tt>[1, 1/2, 0]</tt>;
- * <li> Index 10: <tt>[1/2, 0, 0]</tt>;
- * <li> Index 11: <tt>[1/2, 1, 0]</tt>;
- * <li> Index 12: <tt>[0, 1/2, 1]</tt>;
- * <li> Index 13: <tt>[1, 1/2, 1]</tt>;
- * <li> Index 14: <tt>[1/2, 0, 1]</tt>;
- * <li> Index 15: <tt>[1/2, 1, 1]</tt>;
- * <li> Index 16: <tt>[0, 0, 1/2]</tt>;
- * <li> Index 17: <tt>[1, 0, 1/2]</tt>;
- * <li> Index 18: <tt>[0, 1, 1/2]</tt>;
- * <li> Index 19: <tt>[1, 1, 1/2]</tt>;
- * <li> Index 20: <tt>[0, 1/2, 1/2]</tt>;
- * <li> Index 21: <tt>[1, 1/2, 1/2]</tt>;
- * <li> Index 22: <tt>[1/2, 0, 1/2]</tt>;
- * <li> Index 23: <tt>[1/2, 1, 1/2]</tt>;
- * <li> Index 24: <tt>[1/2, 1/2, 0]</tt>;
- * <li> Index 25: <tt>[1/2, 1/2, 1]</tt>;
- * <li> Index 26: <tt>[1/2, 1/2, 1/2]</tt>;
- * <li> Index 27: <tt>[1/2, 1/2, 1/2]</tt>;
- * </ul>
+ * The respective coordinate values of the support points of the degrees of
+ * freedom are as follows:
+ * <ul>
+ * <li> Index 0: <tt>[0, 0, 0]</tt>;
+ * <li> Index 1: <tt>[1, 0, 0]</tt>;
+ * <li> Index 2: <tt>[0, 1, 0]</tt>;
+ * <li> Index 3: <tt>[1, 1, 0]</tt>;
+ * <li> Index 4: <tt>[0, 0, 1]</tt>;
+ * <li> Index 5: <tt>[1, 0, 1]</tt>;
+ * <li> Index 6: <tt>[0, 1, 1]</tt>;
+ * <li> Index 7: <tt>[1, 1, 1]</tt>;
+ * <li> Index 8: <tt>[0, 1/2, 0]</tt>;
+ * <li> Index 9: <tt>[1, 1/2, 0]</tt>;
+ * <li> Index 10: <tt>[1/2, 0, 0]</tt>;
+ * <li> Index 11: <tt>[1/2, 1, 0]</tt>;
+ * <li> Index 12: <tt>[0, 1/2, 1]</tt>;
+ * <li> Index 13: <tt>[1, 1/2, 1]</tt>;
+ * <li> Index 14: <tt>[1/2, 0, 1]</tt>;
+ * <li> Index 15: <tt>[1/2, 1, 1]</tt>;
+ * <li> Index 16: <tt>[0, 0, 1/2]</tt>;
+ * <li> Index 17: <tt>[1, 0, 1/2]</tt>;
+ * <li> Index 18: <tt>[0, 1, 1/2]</tt>;
+ * <li> Index 19: <tt>[1, 1, 1/2]</tt>;
+ * <li> Index 20: <tt>[0, 1/2, 1/2]</tt>;
+ * <li> Index 21: <tt>[1, 1/2, 1/2]</tt>;
+ * <li> Index 22: <tt>[1/2, 0, 1/2]</tt>;
+ * <li> Index 23: <tt>[1/2, 1, 1/2]</tt>;
+ * <li> Index 24: <tt>[1/2, 1/2, 0]</tt>;
+ * <li> Index 25: <tt>[1/2, 1/2, 1]</tt>;
+ * <li> Index 26: <tt>[1/2, 1/2, 1/2]</tt>;
+ * <li> Index 27: <tt>[1/2, 1/2, 1/2]</tt>;
+ * </ul>
* </ul>
* <h4>Q3 elements</h4>
* <ul>
* @verbatim
* 0--2--3--4--1
* @endverbatim
- * Index 5 has the same coordinates as index 3
+ * Index 5 has the same coordinates as index 3
*
* <li> 2D case:
* @verbatim
* | |
* 0--10-11-12-1
* @endverbatim
- * Index 21 has the same coordinates as index 20
+ * Index 21 has the same coordinates as index 20
* </ul>
*
*/
private:
/**
- * Returns the restriction_is_additive flags.
- * Only the last component is true.
+ * Returns the restriction_is_additive flags. Only the last component is
+ * true.
*/
static std::vector<bool> get_riaf_vector(const unsigned int degree);
/*@{*/
/**
- * Implementation of Hierarchical finite elements @p Qp that yield the
- * finite element space of continuous, piecewise polynomials of degree
- * @p p. This class is realized using tensor product polynomials
- * based on a hierarchical basis @p Hierarchical on the interval
- * <tt>[0,1]</tt> which is suitable for building an @p hp tensor product
- * finite element, if we assume that each element has a single degree.
- *
- * There are not many differences between @p FE_Q_Hierarchical and
- * @p FE_Q, except that we add a function @p embedding_dofs that takes
- * a given integer @p q, between @p 1 and @p p, and
- * returns the numbering of basis functions of the element of order
- * @p q in basis of order @p p. This function is
- * useful if one wants to make calculations using the hierarchical
- * nature of these shape functions.
+ * Implementation of Hierarchical finite elements @p Qp that yield the finite
+ * element space of continuous, piecewise polynomials of degree @p p. This
+ * class is realized using tensor product polynomials based on a hierarchical
+ * basis @p Hierarchical on the interval <tt>[0,1]</tt> which is suitable for
+ * building an @p hp tensor product finite element, if we assume that each
+ * element has a single degree.
+ *
+ * There are not many differences between @p FE_Q_Hierarchical and @p FE_Q,
+ * except that we add a function @p embedding_dofs that takes a given integer
+ * @p q, between @p 1 and @p p, and returns the numbering of basis functions
+ * of the element of order @p q in basis of order @p p. This function is
+ * useful if one wants to make calculations using the hierarchical nature of
+ * these shape functions.
*
* The unit support points now are reduced to @p 0, @p 1, and <tt>0.5</tt> in
* one dimension, and tensor products in higher dimensions. Thus, various
* interpolation functions will only work correctly for the linear case.
*
- * The constructor of this class takes the degree @p p of this finite
- * element.
+ * The constructor of this class takes the degree @p p of this finite element.
*
- * This class is not implemented for the codimension one case
- * (<tt>spacedim != dim</tt>).
+ * This class is not implemented for the codimension one case (<tt>spacedim !=
+ * dim</tt>).
*
* <h3>Implementation</h3>
*
- * The constructor creates a TensorProductPolynomials object
- * that includes the tensor product of @p Hierarchical
- * polynomials of degree @p p. This @p TensorProductPolynomials
- * object provides all values and derivatives of the shape functions.
+ * The constructor creates a TensorProductPolynomials object that includes the
+ * tensor product of @p Hierarchical polynomials of degree @p p. This @p
+ * TensorProductPolynomials object provides all values and derivatives of the
+ * shape functions.
*
* <h3>Numbering of the degrees of freedom (DoFs)</h3>
*
* The original ordering of the shape functions represented by the
- * TensorProductPolynomials is a tensor product
- * numbering. However, the shape functions on a cell are renumbered
- * beginning with the shape functions whose support points are at the
- * vertices, then on the line, on the quads, and finally (for 3d) on
- * the hexes. To be explicit, these numberings are listed in the
- * following:
+ * TensorProductPolynomials is a tensor product numbering. However, the shape
+ * functions on a cell are renumbered beginning with the shape functions whose
+ * support points are at the vertices, then on the line, on the quads, and
+ * finally (for 3d) on the hexes. To be explicit, these numberings are listed
+ * in the following:
*
* <h4>Q1 elements</h4>
*
- * The $Q_1^H$ element is of polynomial degree one and, consequently,
- * is exactly the same as the $Q_1$ element in class FE_Q. In particular,
- * the shape function are defined in the exact same way:
+ * The $Q_1^H$ element is of polynomial degree one and, consequently, is
+ * exactly the same as the $Q_1$ element in class FE_Q. In particular, the
+ * shape function are defined in the exact same way:
*
* <ul>
* <li> 1D case:
* 0-------1 0-------1
* @endverbatim
*
- * The respective coordinate values of the support points of the degrees
- * of freedom are as follows:
- * <ul>
- * <li> Shape function 0: <tt>[0, 0, 0]</tt>;
- * <li> Shape function 1: <tt>[1, 0, 0]</tt>;
- * <li> Shape function 2: <tt>[0, 1, 0]</tt>;
- * <li> Shape function 3: <tt>[1, 1, 0]</tt>;
- * <li> Shape function 4: <tt>[0, 0, 1]</tt>;
- * <li> Shape function 5: <tt>[1, 0, 1]</tt>;
- * <li> Shape function 6: <tt>[0, 1, 1]</tt>;
- * <li> Shape function 7: <tt>[1, 1, 1]</tt>;
- * </ul>
+ * The respective coordinate values of the support points of the degrees of
+ * freedom are as follows:
+ * <ul>
+ * <li> Shape function 0: <tt>[0, 0, 0]</tt>;
+ * <li> Shape function 1: <tt>[1, 0, 0]</tt>;
+ * <li> Shape function 2: <tt>[0, 1, 0]</tt>;
+ * <li> Shape function 3: <tt>[1, 1, 0]</tt>;
+ * <li> Shape function 4: <tt>[0, 0, 1]</tt>;
+ * <li> Shape function 5: <tt>[1, 0, 1]</tt>;
+ * <li> Shape function 6: <tt>[0, 1, 1]</tt>;
+ * <li> Shape function 7: <tt>[1, 1, 1]</tt>;
+ * </ul>
* </ul>
*
- * In 2d, these shape functions look as follows:
- * <table>
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q1/Q1H_shape0000.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q1/Q1H_shape0001.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_1^H$ element, shape function 0
- * </td>
- *
- * <td align="center">
- * $Q_1^H$ element, shape function 1
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q1/Q1H_shape0002.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q1/Q1H_shape0003.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_1^H$ element, shape function 2
- * </td>
- *
- * <td align="center">
- * $Q_1^H$ element, shape function 3
- * </td>
- * </tr>
- * </table>
+ * In 2d, these shape functions look as follows: <table> <tr> <td
+ * align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q1/Q1H_shape0000.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q1/Q1H_shape0001.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_1^H$ element, shape function 0 </td>
+ *
+ * <td align="center"> $Q_1^H$ element, shape function 1 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q1/Q1H_shape0002.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q1/Q1H_shape0003.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_1^H$ element, shape function 2 </td>
+ *
+ * <td align="center"> $Q_1^H$ element, shape function 3 </td> </tr> </table>
*
*
* <h4>Q2 elements</h4>
* |/ / | |/
* *-------* *-------*
* @endverbatim
- * The center vertex has number 26.
- *
- * The respective coordinate values of the support points of the degrees
- * of freedom are as follows:
- * <ul>
- * <li> Shape function 0: <tt>[0, 0, 0]</tt>;
- * <li> Shape function 1: <tt>[1, 0, 0]</tt>;
- * <li> Shape function 2: <tt>[0, 1, 0]</tt>;
- * <li> Shape function 3: <tt>[1, 1, 0]</tt>;
- * <li> Shape function 4: <tt>[0, 0, 1]</tt>;
- * <li> Shape function 5: <tt>[1, 0, 1]</tt>;
- * <li> Shape function 6: <tt>[0, 1, 1]</tt>;
- * <li> Shape function 7: <tt>[1, 1, 1]</tt>;
- * <li> Shape function 8: <tt>[0, 1/2, 0]</tt>;
- * <li> Shape function 9: <tt>[1, 1/2, 0]</tt>;
- * <li> Shape function 10: <tt>[1/2, 0, 0]</tt>;
- * <li> Shape function 11: <tt>[1/2, 1, 0]</tt>;
- * <li> Shape function 12: <tt>[0, 1/2, 1]</tt>;
- * <li> Shape function 13: <tt>[1, 1/2, 1]</tt>;
- * <li> Shape function 14: <tt>[1/2, 0, 1]</tt>;
- * <li> Shape function 15: <tt>[1/2, 1, 1]</tt>;
- * <li> Shape function 16: <tt>[0, 0, 1/2]</tt>;
- * <li> Shape function 17: <tt>[1, 0, 1/2]</tt>;
- * <li> Shape function 18: <tt>[0, 1, 1/2]</tt>;
- * <li> Shape function 19: <tt>[1, 1, 1/2]</tt>;
- * <li> Shape function 20: <tt>[0, 1/2, 1/2]</tt>;
- * <li> Shape function 21: <tt>[1, 1/2, 1/2]</tt>;
- * <li> Shape function 22: <tt>[1/2, 0, 1/2]</tt>;
- * <li> Shape function 23: <tt>[1/2, 1, 1/2]</tt>;
- * <li> Shape function 24: <tt>[1/2, 1/2, 0]</tt>;
- * <li> Shape function 25: <tt>[1/2, 1/2, 1]</tt>;
- * <li> Shape function 26: <tt>[1/2, 1/2, 1/2]</tt>;
- * </ul>
+ * The center vertex has number 26.
+ *
+ * The respective coordinate values of the support points of the degrees of
+ * freedom are as follows:
+ * <ul>
+ * <li> Shape function 0: <tt>[0, 0, 0]</tt>;
+ * <li> Shape function 1: <tt>[1, 0, 0]</tt>;
+ * <li> Shape function 2: <tt>[0, 1, 0]</tt>;
+ * <li> Shape function 3: <tt>[1, 1, 0]</tt>;
+ * <li> Shape function 4: <tt>[0, 0, 1]</tt>;
+ * <li> Shape function 5: <tt>[1, 0, 1]</tt>;
+ * <li> Shape function 6: <tt>[0, 1, 1]</tt>;
+ * <li> Shape function 7: <tt>[1, 1, 1]</tt>;
+ * <li> Shape function 8: <tt>[0, 1/2, 0]</tt>;
+ * <li> Shape function 9: <tt>[1, 1/2, 0]</tt>;
+ * <li> Shape function 10: <tt>[1/2, 0, 0]</tt>;
+ * <li> Shape function 11: <tt>[1/2, 1, 0]</tt>;
+ * <li> Shape function 12: <tt>[0, 1/2, 1]</tt>;
+ * <li> Shape function 13: <tt>[1, 1/2, 1]</tt>;
+ * <li> Shape function 14: <tt>[1/2, 0, 1]</tt>;
+ * <li> Shape function 15: <tt>[1/2, 1, 1]</tt>;
+ * <li> Shape function 16: <tt>[0, 0, 1/2]</tt>;
+ * <li> Shape function 17: <tt>[1, 0, 1/2]</tt>;
+ * <li> Shape function 18: <tt>[0, 1, 1/2]</tt>;
+ * <li> Shape function 19: <tt>[1, 1, 1/2]</tt>;
+ * <li> Shape function 20: <tt>[0, 1/2, 1/2]</tt>;
+ * <li> Shape function 21: <tt>[1, 1/2, 1/2]</tt>;
+ * <li> Shape function 22: <tt>[1/2, 0, 1/2]</tt>;
+ * <li> Shape function 23: <tt>[1/2, 1, 1/2]</tt>;
+ * <li> Shape function 24: <tt>[1/2, 1/2, 0]</tt>;
+ * <li> Shape function 25: <tt>[1/2, 1/2, 1]</tt>;
+ * <li> Shape function 26: <tt>[1/2, 1/2, 1/2]</tt>;
+ * </ul>
* </ul>
*
*
* In 2d, these shape functions look as follows (the black plane corresponds
- * to zero; negative shape function values may not be visible):
- * <table>
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0000.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0001.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_2^H$ element, shape function 0
- * </td>
- *
- * <td align="center">
- * $Q_2^H$ element, shape function 1
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0002.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0003.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_2^H$ element, shape function 2
- * </td>
- *
- * <td align="center">
- * $Q_2^H$ element, shape function 3
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0004.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0005.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_2^H$ element, shape function 4
- * </td>
- *
- * <td align="center">
- * $Q_2^H$ element, shape function 5
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0006.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0007.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_2^H$ element, shape function 6
- * </td>
- *
- * <td align="center">
- * $Q_2^H$ element, shape function 7
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q2/Q2H_shape0008.png" alt="">
- * </td>
- *
- * <td align="center">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_2^H$ element, shape function 8
- * </td>
- *
- * <td align="center">
- * </td>
- * </tr>
- * </table>
+ * to zero; negative shape function values may not be visible): <table> <tr>
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q2/Q2H_shape0000.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q2/Q2H_shape0001.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_2^H$ element, shape function 0 </td>
+ *
+ * <td align="center"> $Q_2^H$ element, shape function 1 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q2/Q2H_shape0002.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q2/Q2H_shape0003.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_2^H$ element, shape function 2 </td>
+ *
+ * <td align="center"> $Q_2^H$ element, shape function 3 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q2/Q2H_shape0004.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q2/Q2H_shape0005.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_2^H$ element, shape function 4 </td>
+ *
+ * <td align="center"> $Q_2^H$ element, shape function 5 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q2/Q2H_shape0006.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q2/Q2H_shape0007.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_2^H$ element, shape function 6 </td>
+ *
+ * <td align="center"> $Q_2^H$ element, shape function 7 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q2/Q2H_shape0008.png" alt=""> </td>
+ *
+ * <td align="center"> </td> </tr> <tr> <td align="center"> $Q_2^H$ element,
+ * shape function 8 </td>
+ *
+ * <td align="center"> </td> </tr> </table>
*
*
* <h4>Q3 elements</h4>
* </ul>
*
* In 2d, these shape functions look as follows (the black plane corresponds
- * to zero; negative shape function values may not be visible):
- * <table>
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0000.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0001.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_3^H$ element, shape function 0
- * </td>
- *
- * <td align="center">
- * $Q_3^H$ element, shape function 1
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0002.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0003.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_3^H$ element, shape function 2
- * </td>
- *
- * <td align="center">
- * $Q_3^H$ element, shape function 3
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0004.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0005.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_3^H$ element, shape function 4
- * </td>
- *
- * <td align="center">
- * $Q_3^H$ element, shape function 5
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0006.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0007.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_3^H$ element, shape function 6
- * </td>
- *
- * <td align="center">
- * $Q_3^H$ element, shape function 7
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0008.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0009.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_3^H$ element, shape function 8
- * </td>
- *
- * <td align="center">
- * $Q_3^H$ element, shape function 9
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0010.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0011.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_3^H$ element, shape function 10
- * </td>
- *
- * <td align="center">
- * $Q_3^H$ element, shape function 11
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0012.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0013.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_3^H$ element, shape function 12
- * </td>
- *
- * <td align="center">
- * $Q_3^H$ element, shape function 13
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0014.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q3/Q3H_shape0015.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_3^H$ element, shape function 14
- * </td>
- *
- * <td align="center">
- * $Q_3^H$ element, shape function 15
- * </td>
- * </tr>
- * </table>
+ * to zero; negative shape function values may not be visible): <table> <tr>
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0000.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0001.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3^H$ element, shape function 0 </td>
+ *
+ * <td align="center"> $Q_3^H$ element, shape function 1 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0002.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0003.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3^H$ element, shape function 2 </td>
+ *
+ * <td align="center"> $Q_3^H$ element, shape function 3 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0004.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0005.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3^H$ element, shape function 4 </td>
+ *
+ * <td align="center"> $Q_3^H$ element, shape function 5 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0006.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0007.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3^H$ element, shape function 6 </td>
+ *
+ * <td align="center"> $Q_3^H$ element, shape function 7 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0008.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0009.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3^H$ element, shape function 8 </td>
+ *
+ * <td align="center"> $Q_3^H$ element, shape function 9 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0010.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0011.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3^H$ element, shape function 10 </td>
+ *
+ * <td align="center"> $Q_3^H$ element, shape function 11 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0012.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0013.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3^H$ element, shape function 12 </td>
+ *
+ * <td align="center"> $Q_3^H$ element, shape function 13 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0014.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q3/Q3H_shape0015.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_3^H$ element, shape function 14 </td>
+ *
+ * <td align="center"> $Q_3^H$ element, shape function 15 </td> </tr> </table>
*
*
* <h4>Q4 elements</h4>
* </ul>
*
* In 2d, these shape functions look as follows (the black plane corresponds
- * to zero; negative shape function values may not be visible):
- * <table>
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0000.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0001.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4^H$ element, shape function 0
- * </td>
- *
- * <td align="center">
- * $Q_4^H$ element, shape function 1
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0002.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0003.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4^H$ element, shape function 2
- * </td>
- *
- * <td align="center">
- * $Q_4^H$ element, shape function 3
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0004.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0005.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4^H$ element, shape function 4
- * </td>
- *
- * <td align="center">
- * $Q_4^H$ element, shape function 5
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0006.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0007.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4^H$ element, shape function 6
- * </td>
- *
- * <td align="center">
- * $Q_4^H$ element, shape function 7
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0008.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0009.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4^H$ element, shape function 8
- * </td>
- *
- * <td align="center">
- * $Q_4^H$ element, shape function 9
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0010.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0011.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4^H$ element, shape function 10
- * </td>
- *
- * <td align="center">
- * $Q_4^H$ element, shape function 11
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0012.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0013.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4^H$ element, shape function 12
- * </td>
- *
- * <td align="center">
- * $Q_4^H$ element, shape function 13
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0014.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0015.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4^H$ element, shape function 14
- * </td>
- *
- * <td align="center">
- * $Q_4^H$ element, shape function 15
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0016.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0017.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4^H$ element, shape function 16
- * </td>
- *
- * <td align="center">
- * $Q_4^H$ element, shape function 17
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0018.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0019.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4^H$ element, shape function 18
- * </td>
- *
- * <td align="center">
- * $Q_4^H$ element, shape function 19
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0020.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0021.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4^H$ element, shape function 20
- * </td>
- *
- * <td align="center">
- * $Q_4^H$ element, shape function 21
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0022.png" alt="">
- * </td>
- *
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0023.png" alt="">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4^H$ element, shape function 22
- * </td>
- *
- * <td align="center">
- * $Q_4^H$ element, shape function 23
- * </td>
- * </tr>
- *
- * <tr>
- * <td align="center">
- * <img src="http://www.dealii.org/images/shape-functions/hierarchical/Q4/Q4H_shape0024.png" alt="">
- * </td>
- *
- * <td align="center">
- * </td>
- * </tr>
- * <tr>
- * <td align="center">
- * $Q_4^H$ element, shape function 24
- * </td>
- *
- * <td align="center">
- * </td>
- * </tr>
- * </table>
+ * to zero; negative shape function values may not be visible): <table> <tr>
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0000.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0001.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 0 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 1 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0002.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0003.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 2 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 3 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0004.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0005.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 4 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 5 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0006.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0007.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 6 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 7 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0008.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0009.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 8 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 9 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0010.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0011.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 10 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 11 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0012.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0013.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 12 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 13 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0014.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0015.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 14 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 15 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0016.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0017.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 16 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 17 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0018.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0019.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 18 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 19 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0020.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0021.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 20 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 21 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0022.png" alt=""> </td>
+ *
+ * <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0023.png" alt=""> </td> </tr> <tr> <td
+ * align="center"> $Q_4^H$ element, shape function 22 </td>
+ *
+ * <td align="center"> $Q_4^H$ element, shape function 23 </td> </tr>
+ *
+ * <tr> <td align="center"> <img src="http://www.dealii.org/images/shape-
+ * functions/hierarchical/Q4/Q4H_shape0024.png" alt=""> </td>
+ *
+ * <td align="center"> </td> </tr> <tr> <td align="center"> $Q_4^H$ element,
+ * shape function 24 </td>
+ *
+ * <td align="center"> </td> </tr> </table>
*
*
*
{
public:
/**
- * Constructor for tensor product
- * polynomials of degree @p p.
+ * Constructor for tensor product polynomials of degree @p p.
*/
FE_Q_Hierarchical (const unsigned int p);
/**
- * Return a string that uniquely
- * identifies a finite
- * element. This class returns
- * <tt>FE_Q_Hierarchical<dim>(degree)</tt>,
- * with @p dim and @p degree
- * replaced by appropriate
- * values.
+ * Return a string that uniquely identifies a finite element. This class
+ * returns <tt>FE_Q_Hierarchical<dim>(degree)</tt>, with @p dim and @p
+ * degree replaced by appropriate values.
*/
virtual std::string get_name () const;
*/
/**
- * Return whether this element
- * implements its hanging node
- * constraints in the new way,
- * which has to be used to make
- * elements "hp compatible".
- *
- * For the FE_Q_Hierarchical class the
- * result is always true (independent of
- * the degree of the element), as it
- * implements the complete set of
- * functions necessary for hp capability.
+ * Return whether this element implements its hanging node constraints in
+ * the new way, which has to be used to make elements "hp compatible".
+ *
+ * For the FE_Q_Hierarchical class the result is always true (independent of
+ * the degree of the element), as it implements the complete set of
+ * functions necessary for hp capability.
*/
virtual bool hp_constraints_are_implemented () const;
/**
- * If, on a vertex, several finite elements are active, the hp code
- * first assigns the degrees of freedom of each of these FEs
- * different global indices. It then calls this function to find out
- * which of them should get identical values, and consequently can
- * receive the same global DoF index. This function therefore
- * returns a list of identities between DoFs of the present finite
- * element object with the DoFs of @p fe_other, which is a reference
- * to a finite element object representing one of the other finite
- * elements active on this particular vertex. The function computes
- * which of the degrees of freedom of the two finite element objects
- * are equivalent, both numbered between zero and the corresponding
- * value of dofs_per_vertex of the two finite elements. The first
- * index of each pair denotes one of the vertex dofs of the present
- * element, whereas the second is the corresponding index of the
- * other finite element.
+ * If, on a vertex, several finite elements are active, the hp code first
+ * assigns the degrees of freedom of each of these FEs different global
+ * indices. It then calls this function to find out which of them should get
+ * identical values, and consequently can receive the same global DoF index.
+ * This function therefore returns a list of identities between DoFs of the
+ * present finite element object with the DoFs of @p fe_other, which is a
+ * reference to a finite element object representing one of the other finite
+ * elements active on this particular vertex. The function computes which of
+ * the degrees of freedom of the two finite element objects are equivalent,
+ * both numbered between zero and the corresponding value of dofs_per_vertex
+ * of the two finite elements. The first index of each pair denotes one of
+ * the vertex dofs of the present element, whereas the second is the
+ * corresponding index of the other finite element.
*/
virtual
std::vector<std::pair<unsigned int, unsigned int> >
/*@}*/
/**
- * Return the matrix interpolating from a face of one
- * element to the face of the neighboring element. The
- * size of the matrix is then <tt>source.dofs_per_face</tt>
- * times <tt>this->dofs_per_face</tt>.
+ * Return the matrix interpolating from a face of one element to the face of
+ * the neighboring element. The size of the matrix is then
+ * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
*
- * Derived elements will have to implement this function.
- * They may only provide interpolation matrices for certain
- * source finite elements, for example those from the same
- * family. If they don't implement interpolation from a given
- * element, then they must throw an exception of type
+ * Derived elements will have to implement this function. They may only
+ * provide interpolation matrices for certain source finite elements, for
+ * example those from the same family. If they don't implement interpolation
+ * from a given element, then they must throw an exception of type
* <tt>FiniteElement<dim>::ExcInterpolationNotImplemented</tt>.
*/
virtual void get_face_interpolation_matrix (const FiniteElement<dim> &source, FullMatrix<double> &matrix) const;
/**
- * Return the matrix interpolating from a face of one element
- * to the subface of the neighboring element. The size of
- * the matrix is then <tt>source.dofs_per_face</tt> times
- * <tt>this->dofs_per_face</tt>.
+ * Return the matrix interpolating from a face of one element to the subface
+ * of the neighboring element. The size of the matrix is then
+ * <tt>source.dofs_per_face</tt> times <tt>this->dofs_per_face</tt>.
*
- * Derived elements will have to implement this function.
- * They may only provide interpolation matrices for certain
- * source finite elements, for example those from the same
- * family. If they don't implement interpolation from a given
- * element, then they must throw an exception of type
+ * Derived elements will have to implement this function. They may only
+ * provide interpolation matrices for certain source finite elements, for
+ * example those from the same family. If they don't implement interpolation
+ * from a given element, then they must throw an exception of type
* <tt>ExcInterpolationNotImplemented</tt>.
*/
virtual void get_subface_interpolation_matrix (const FiniteElement<dim> &source, const unsigned int subface, FullMatrix<double> &matrix) const;
/**
- * Return whether this element dominates
- * the one given as argument when they
- * meet at a common face,
- * whether it is the other way around,
- * whether neither dominates, or if
- * either could dominate.
+ * Return whether this element dominates the one given as argument when they
+ * meet at a common face, whether it is the other way around, whether
+ * neither dominates, or if either could dominate.
*
- * For a definition of domination, see
- * FiniteElementBase::Domination and in
+ * For a definition of domination, see FiniteElementBase::Domination and in
* particular the @ref hp_paper "hp paper".
*/
virtual
compare_for_face_domination (const FiniteElement<dim> &fe_other) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*
- * This function is made virtual,
- * since finite element objects
- * are usually accessed through
- * pointers to their base class,
- * rather than the class itself.
+ * This function is made virtual, since finite element objects are usually
+ * accessed through pointers to their base class, rather than the class
+ * itself.
*/
virtual std::size_t memory_consumption () const;
/**
- * For a finite element of degree
- * @p sub_degree < @p degree, we
- * return a vector which maps the
- * numbering on an FE
- * of degree @p sub_degree into the
+ * For a finite element of degree @p sub_degree < @p degree, we return a
+ * vector which maps the numbering on an FE of degree @p sub_degree into the
* numbering on this element.
*/
std::vector<unsigned int> get_embedding_dofs (const unsigned int sub_degree) const;
protected:
/**
- * @p clone function instead of
- * a copy constructor.
+ * @p clone function instead of a copy constructor.
*
- * This function is needed by the
- * constructors of @p FESystem.
+ * This function is needed by the constructors of @p FESystem.
*/
virtual FiniteElement<dim> *clone() const;
private:
/**
- * Only for internal use. Its
- * full name is
- * @p get_dofs_per_object_vector
- * function and it creates the
- * @p dofs_per_object vector that is
- * needed within the constructor to
- * be passed to the constructor of
- * @p FiniteElementData.
+ * Only for internal use. Its full name is @p get_dofs_per_object_vector
+ * function and it creates the @p dofs_per_object vector that is needed
+ * within the constructor to be passed to the constructor of @p
+ * FiniteElementData.
*/
static std::vector<unsigned int> get_dpo_vector(const unsigned int degree);
/**
- * The numbering of the degrees
- * of freedom in continuous finite
- * elements is hierarchic,
- * i.e. in such a way that we
- * first number the vertex dofs,
- * in the order of the vertices
- * as defined by the
- * triangulation, then the line
- * dofs in the order and
- * respecting the direction of
- * the lines, then the dofs on
- * quads, etc.
+ * The numbering of the degrees of freedom in continuous finite elements is
+ * hierarchic, i.e. in such a way that we first number the vertex dofs, in
+ * the order of the vertices as defined by the triangulation, then the line
+ * dofs in the order and respecting the direction of the lines, then the
+ * dofs on quads, etc.
*
- * The dofs associated with 1d
- * hierarchical polynomials are
- * ordered with the vertices
- * first ($phi_0(x)=1-x$ and
- * $phi_1(x)=x$) and then the
- * line dofs (the higher degree
- * polynomials). The 2d and 3d
- * hierarchical polynomials
- * originate from the 1d
- * hierarchical polynomials by
- * tensor product. In the
- * following, the resulting
- * numbering of dofs will be
- * denoted by `fe_q_hierarchical
- * numbering`.
+ * The dofs associated with 1d hierarchical polynomials are ordered with the
+ * vertices first ($phi_0(x)=1-x$ and $phi_1(x)=x$) and then the line dofs
+ * (the higher degree polynomials). The 2d and 3d hierarchical polynomials
+ * originate from the 1d hierarchical polynomials by tensor product. In the
+ * following, the resulting numbering of dofs will be denoted by
+ * `fe_q_hierarchical numbering`.
*
- * This function constructs a
- * table which fe_q_hierarchical
- * index each degree of freedom
- * in the hierarchic numbering
- * would have.
+ * This function constructs a table which fe_q_hierarchical index each
+ * degree of freedom in the hierarchic numbering would have.
*
- * This function is anologous to
- * the
- * FETools::hierarchical_to_lexicographic_numbering()
- * function. However, in contrast
- * to the fe_q_hierarchical
- * numbering defined above, the
- * lexicographic numbering
- * originates from the tensor
- * products of consecutive
- * numbered dofs (like for
- * LagrangeEquidistant).
+ * This function is anologous to the
+ * FETools::hierarchical_to_lexicographic_numbering() function. However, in
+ * contrast to the fe_q_hierarchical numbering defined above, the
+ * lexicographic numbering originates from the tensor products of
+ * consecutive numbered dofs (like for LagrangeEquidistant).
*
- * It is assumed that the size of
- * the output argument already
- * matches the correct size,
- * which is equal to the number
- * of degrees of freedom in the
+ * It is assumed that the size of the output argument already matches the
+ * correct size, which is equal to the number of degrees of freedom in the
* finite element.
*/
static
const FiniteElementData<dim> &fe);
/**
- * This is an analogon to the
- * previous function, but working
- * on faces.
+ * This is an analogon to the previous function, but working on faces.
*/
static
std::vector<unsigned int>
face_fe_q_hierarchical_to_hierarchic_numbering (const unsigned int degree);
/**
- * Initialize two auxiliary
- * fields that will be used in
- * setting up the various
- * matrices in the constructor.
+ * Initialize two auxiliary fields that will be used in setting up the
+ * various matrices in the constructor.
*/
void build_dofs_cell (std::vector<FullMatrix<double> > &dofs_cell,
std::vector<FullMatrix<double> > &dofs_subcell) const;
/**
- * Initialize the hanging node
- * constraints matrices. Called
- * from the constructor.
+ * Initialize the hanging node constraints matrices. Called from the
+ * constructor.
*/
void initialize_constraints (const std::vector<FullMatrix<double> > &dofs_subcell);
/**
- * Initialize the embedding
- * matrices. Called from the
- * constructor.
+ * Initialize the embedding matrices. Called from the constructor.
*/
void initialize_embedding_and_restriction (const std::vector<FullMatrix<double> > &dofs_cell,
const std::vector<FullMatrix<double> > &dofs_subcell);
/**
- * Initialize the
- * @p unit_support_points field
- * of the FiniteElement
- * class. Called from the
- * constructor.
+ * Initialize the @p unit_support_points field of the FiniteElement class.
+ * Called from the constructor.
*/
void initialize_unit_support_points ();
/**
- * Initialize the
- * @p unit_face_support_points field
- * of the FiniteElement
- * class. Called from the
- * constructor.
+ * Initialize the @p unit_face_support_points field of the FiniteElement
+ * class. Called from the constructor.
*/
void initialize_unit_face_support_points ();
/**
- * Mapping from lexicographic to
- * shape function numbering on first face.
+ * Mapping from lexicographic to shape function numbering on first face.
*/
const std::vector<unsigned int> face_renumber;
/**
- * Allow access from other
- * dimensions. We need this since
- * we want to call the functions
- * @p get_dpo_vector and
- * @p lexicographic_to_hierarchic_numbering
- * for the faces of the finite
- * element of dimension dim+1.
+ * Allow access from other dimensions. We need this since we want to call
+ * the functions @p get_dpo_vector and @p
+ * lexicographic_to_hierarchic_numbering for the faces of the finite element
+ * of dimension dim+1.
*/
template <int dim1> friend class FE_Q_Hierarchical;
};
* with @p p subdivisions in each coordinate direction. It yields an element
* with the same number of degrees of freedom as the @p Qp elements but using
* linear interpolation instead of higher order one. This type of element is
- * also called macro element in the literature as it really consists of several
- * smaller elements, namely <i>p</i><tt><sup>dim</sup></tt>.
+ * also called macro element in the literature as it really consists of
+ * several smaller elements, namely <i>p</i><tt><sup>dim</sup></tt>.
*
* The numbering of degrees of freedom is done in exactly the same way as in
* FE_Q of degree @p p. See there for a detailed description on how degrees of
* not higher order elements. </li>
*
* <li> Stokes/Navier Stokes systems as the one discussed in step-22 could be
- * solved with Q2-iso-Q1 elements for velocities instead of Q2
- * elements. Combined with Q1 pressures they give a stable mixed element
- * pair. However, they perform worse than the standard approach in most
- * situations. </li>
+ * solved with Q2-iso-Q1 elements for velocities instead of Q2 elements.
+ * Combined with Q1 pressures they give a stable mixed element pair. However,
+ * they perform worse than the standard approach in most situations. </li>
*
* <li> Preconditioning systems of FE_Q systems of higher order @p p with a
* preconditioner based on @p Qp-iso-Q1 elements: Some preconditioners like
- * algebraic multigrid perform much better with linear elements than with higher
- * order elements because they often implicitly assume a sparse connectivity
- * between entries. Then, creating a preconditioner matrix based on these
- * elements yields the same number of degrees of freedom (and a spectrally
- * equivalent linear system), which can be combined with a (high order) system
- * matrix in an iterative solver like CG. </li>
+ * algebraic multigrid perform much better with linear elements than with
+ * higher order elements because they often implicitly assume a sparse
+ * connectivity between entries. Then, creating a preconditioner matrix based
+ * on these elements yields the same number of degrees of freedom (and a
+ * spectrally equivalent linear system), which can be combined with a (high
+ * order) system matrix in an iterative solver like CG. </li>
* </ol>
*
* <h3>Appropriate integration</h3>
/*@{*/
/**
- * Implementation of Raviart-Thomas (RT) elements, conforming with the
- * space H<sup>div</sup>. These elements generate vector fields with
- * normal components continuous between mesh cells.
+ * Implementation of Raviart-Thomas (RT) elements, conforming with the space
+ * H<sup>div</sup>. These elements generate vector fields with normal
+ * components continuous between mesh cells.
*
- * We follow the usual definition of the degree of RT elements, which
- * denotes the polynomial degree of the largest complete polynomial
- * subspace contained in the RT space. Then, approximation order of
- * the function itself is <i>degree+1</i>, as with usual polynomial
- * spaces. The numbering so chosen implies the sequence
+ * We follow the usual definition of the degree of RT elements, which denotes
+ * the polynomial degree of the largest complete polynomial subspace contained
+ * in the RT space. Then, approximation order of the function itself is
+ * <i>degree+1</i>, as with usual polynomial spaces. The numbering so chosen
+ * implies the sequence
* @f[
* Q_{k+1}
* \stackrel{\text{grad}}{\rightarrow}
* @f]
* The lowest order element is consequently FE_RaviartThomas(0).
*
- * This class is not implemented for the codimension one case
- * (<tt>spacedim != dim</tt>).
+ * This class is not implemented for the codimension one case (<tt>spacedim !=
+ * dim</tt>).
*
* @todo Even if this element is implemented for two and three space
- * dimensions, the definition of the node values relies on
- * consistently oriented faces in 3D. Therefore, care should be taken
- * on complicated meshes.
+ * dimensions, the definition of the node values relies on consistently
+ * oriented faces in 3D. Therefore, care should be taken on complicated
+ * meshes.
*
* <h3>Interpolation</h3>
*
- * The @ref GlossInterpolation "interpolation" operators associated
- * with the RT element are constructed such that interpolation and
- * computing the divergence are commuting operations. We require this
- * from interpolating arbitrary functions as well as the #restriction
- * matrices. It can be achieved by two interpolation schemes, the
- * simplified one in FE_RaviartThomasNodal and the original one here:
+ * The @ref GlossInterpolation "interpolation" operators associated with the
+ * RT element are constructed such that interpolation and computing the
+ * divergence are commuting operations. We require this from interpolating
+ * arbitrary functions as well as the #restriction matrices. It can be
+ * achieved by two interpolation schemes, the simplified one in
+ * FE_RaviartThomasNodal and the original one here:
*
* <h4>Node values on edges/faces</h4>
*
- * On edges or faces, the @ref GlossNodes "node values" are the moments of
- * the normal component of the interpolated function with respect to
- * the traces of the RT polynomials. Since the normal trace of the RT
- * space of degree <i>k</i> on an edge/face is the space
- * <i>Q<sub>k</sub></i>, the moments are taken with respect to this
- * space.
+ * On edges or faces, the @ref GlossNodes "node values" are the moments of the
+ * normal component of the interpolated function with respect to the traces of
+ * the RT polynomials. Since the normal trace of the RT space of degree
+ * <i>k</i> on an edge/face is the space <i>Q<sub>k</sub></i>, the moments are
+ * taken with respect to this space.
*
* <h4>Interior node values</h4>
*
- * Higher order RT spaces have interior nodes. These are moments taken
- * with respect to the gradient of functions in <i>Q<sub>k</sub></i>
- * on the cell (this space is the matching space for RT<sub>k</sub> in
- * a mixed formulation).
+ * Higher order RT spaces have interior nodes. These are moments taken with
+ * respect to the gradient of functions in <i>Q<sub>k</sub></i> on the cell
+ * (this space is the matching space for RT<sub>k</sub> in a mixed
+ * formulation).
*
* <h4>Generalized support points</h4>
*
* The node values above rely on integrals, which will be computed by
- * quadrature rules themselves. The generalized support points are a
- * set of points such that this quadrature can be performed with
- * sufficient accuracy. The points needed are thode of
- * QGauss<sub>k+1</sub> on each face as well as QGauss<sub>k</sub> in
- * the interior of the cell (or none for RT<sub>0</sub>).
+ * quadrature rules themselves. The generalized support points are a set of
+ * points such that this quadrature can be performed with sufficient accuracy.
+ * The points needed are thode of QGauss<sub>k+1</sub> on each face as well as
+ * QGauss<sub>k</sub> in the interior of the cell (or none for
+ * RT<sub>0</sub>).
*
*
* @author Guido Kanschat, 2005, based on previous Work by Wolfgang Bangerth
{
public:
/**
- * Constructor for the Raviart-Thomas
- * element of degree @p p.
+ * Constructor for the Raviart-Thomas element of degree @p p.
*/
FE_RaviartThomas (const unsigned int p);
/**
- * Return a string that uniquely
- * identifies a finite
- * element. This class returns
- * <tt>FE_RaviartThomas<dim>(degree)</tt>, with
- * @p dim and @p degree
- * replaced by appropriate
- * values.
+ * Return a string that uniquely identifies a finite element. This class
+ * returns <tt>FE_RaviartThomas<dim>(degree)</tt>, with @p dim and @p degree
+ * replaced by appropriate values.
*/
virtual std::string get_name () const;
private:
/**
- * Only for internal use. Its
- * full name is
- * @p get_dofs_per_object_vector
- * function and it creates the
- * @p dofs_per_object vector that is
- * needed within the constructor to
- * be passed to the constructor of
- * @p FiniteElementData.
+ * Only for internal use. Its full name is @p get_dofs_per_object_vector
+ * function and it creates the @p dofs_per_object vector that is needed
+ * within the constructor to be passed to the constructor of @p
+ * FiniteElementData.
*/
static std::vector<unsigned int>
get_dpo_vector (const unsigned int degree);
/**
- * Initialize the @p
- * generalized_support_points
- * field of the FiniteElement
- * class and fill the tables with
- * interpolation weights
- * (#boundary_weights and
- * #interior_weights). Called
- * from the constructor.
+ * Initialize the @p generalized_support_points field of the FiniteElement
+ * class and fill the tables with interpolation weights (#boundary_weights
+ * and #interior_weights). Called from the constructor.
*/
void initialize_support_points (const unsigned int rt_degree);
/**
- * Initialize the interpolation
- * from functions on refined mesh
- * cells onto the father
- * cell. According to the
- * philosophy of the
- * Raviart-Thomas element, this
- * restriction operator preserves
- * the divergence of a function
+ * Initialize the interpolation from functions on refined mesh cells onto
+ * the father cell. According to the philosophy of the Raviart-Thomas
+ * element, this restriction operator preserves the divergence of a function
* weakly.
*/
void initialize_restriction ();
/**
* Fields of cell-independent data.
*
- * For information about the
- * general purpose of this class,
- * see the documentation of the
- * base class.
+ * For information about the general purpose of this class, see the
+ * documentation of the base class.
*/
class InternalData : public FiniteElement<dim>::InternalDataBase
{
public:
/**
- * Array with shape function
- * values in quadrature
- * points. There is one row
- * for each shape function,
- * containing values for each
- * quadrature point. Since
- * the shape functions are
- * vector-valued (with as
- * many components as there
- * are space dimensions), the
- * value is a tensor.
+ * Array with shape function values in quadrature points. There is one row
+ * for each shape function, containing values for each quadrature point.
+ * Since the shape functions are vector-valued (with as many components as
+ * there are space dimensions), the value is a tensor.
*
- * In this array, we store
- * the values of the shape
- * function in the quadrature
- * points on the unit
- * cell. The transformation
- * to the real space cell is
- * then simply done by
- * multiplication with the
- * Jacobian of the mapping.
+ * In this array, we store the values of the shape function in the
+ * quadrature points on the unit cell. The transformation to the real
+ * space cell is then simply done by multiplication with the Jacobian of
+ * the mapping.
*/
std::vector<std::vector<Tensor<1,dim> > > shape_values;
/**
- * Array with shape function
- * gradients in quadrature
- * points. There is one
- * row for each shape
- * function, containing
- * values for each quadrature
+ * Array with shape function gradients in quadrature points. There is one
+ * row for each shape function, containing values for each quadrature
* point.
*
- * We store the gradients in
- * the quadrature points on
- * the unit cell. We then
- * only have to apply the
- * transformation (which is a
- * matrix-vector
- * multiplication) when
- * visiting an actual cell.
+ * We store the gradients in the quadrature points on the unit cell. We
+ * then only have to apply the transformation (which is a matrix-vector
+ * multiplication) when visiting an actual cell.
*/
std::vector<std::vector<Tensor<2,dim> > > shape_gradients;
};
/**
- * These are the factors
- * multiplied to a function in
- * the
- * #generalized_face_support_points
- * when computing the
- * integration. They are
- * organized such that there is
- * one row for each generalized
- * face support point and one
- * column for each degree of
- * freedom on the face.
- *
- * See the @ref GlossGeneralizedSupport "glossary entry on generalized support points"
- * for more information.
+ * These are the factors multiplied to a function in the
+ * #generalized_face_support_points when computing the integration. They are
+ * organized such that there is one row for each generalized face support
+ * point and one column for each degree of freedom on the face.
+ *
+ * See the @ref GlossGeneralizedSupport "glossary entry on generalized
+ * support points" for more information.
*/
Table<2, double> boundary_weights;
/**
- * Precomputed factors for
- * interpolation of interior
- * degrees of freedom. The
- * rationale for this Table is
- * the same as for
- * #boundary_weights. Only, this
- * table has a third coordinate
- * for the space direction of the
- * component evaluated.
+ * Precomputed factors for interpolation of interior degrees of freedom. The
+ * rationale for this Table is the same as for #boundary_weights. Only, this
+ * table has a third coordinate for the space direction of the component
+ * evaluated.
*/
Table<3, double> interior_weights;
/**
- * Allow access from other
- * dimensions.
+ * Allow access from other dimensions.
*/
template <int dim1> friend class FE_RaviartThomas;
};
/**
- * The Raviart-Thomas elements with node functionals defined as point
- * values in Gauss points.
+ * The Raviart-Thomas elements with node functionals defined as point values
+ * in Gauss points.
*
* <h3>Description of node values</h3>
*
- * For this Raviart-Thomas element, the node values are not cell and
- * face moments with respect to certain polynomials, but the values in
- * quadrature points. Following the general scheme for numbering
- * degrees of freedom, the node values on edges are first, edge by
- * edge, according to the natural ordering of the edges of a cell. The
- * interior degrees of freedom are last.
+ * For this Raviart-Thomas element, the node values are not cell and face
+ * moments with respect to certain polynomials, but the values in quadrature
+ * points. Following the general scheme for numbering degrees of freedom, the
+ * node values on edges are first, edge by edge, according to the natural
+ * ordering of the edges of a cell. The interior degrees of freedom are last.
*
- * For an RT-element of degree <i>k</i>, we choose
- * <i>(k+1)<sup>d-1</sup></i> Gauss points on each face. These points
- * are ordered lexicographically with respect to the orientation of
- * the face. This way, the normal component which is in
- * <i>Q<sub>k</sub></i> is uniquely determined. Furthermore, since
- * this Gauss-formula is exact on <i>Q<sub>2k+1</sub></i>, these node
- * values correspond to the exact integration of the moments of the
- * RT-space.
+ * For an RT-element of degree <i>k</i>, we choose <i>(k+1)<sup>d-1</sup></i>
+ * Gauss points on each face. These points are ordered lexicographically with
+ * respect to the orientation of the face. This way, the normal component
+ * which is in <i>Q<sub>k</sub></i> is uniquely determined. Furthermore, since
+ * this Gauss-formula is exact on <i>Q<sub>2k+1</sub></i>, these node values
+ * correspond to the exact integration of the moments of the RT-space.
*
* In the interior of the cells, the moments are with respect to an
- * anisotropic <i>Q<sub>k</sub></i> space, where the test functions
- * are one degree lower in the direction corresponding to the vector
- * component under consideration. This is emulated by using an
- * anisotropic Gauss formula for integration.
+ * anisotropic <i>Q<sub>k</sub></i> space, where the test functions are one
+ * degree lower in the direction corresponding to the vector component under
+ * consideration. This is emulated by using an anisotropic Gauss formula for
+ * integration.
*
- * @todo The current implementation is for Cartesian meshes
- * only. You must use MappingCartesian.
+ * @todo The current implementation is for Cartesian meshes only. You must use
+ * MappingCartesian.
*
* @todo Even if this element is implemented for two and three space
- * dimensions, the definition of the node values relies on
- * consistently oriented faces in 3D. Therefore, care should be taken
- * on complicated meshes.
+ * dimensions, the definition of the node values relies on consistently
+ * oriented faces in 3D. Therefore, care should be taken on complicated
+ * meshes.
*
* @note The degree stored in the member variable
- * FiniteElementData<dim>::degree is higher by one than the
- * constructor argument!
+ * FiniteElementData<dim>::degree is higher by one than the constructor
+ * argument!
*
* @author Guido Kanschat, 2005, Zhu Liang, 2008
*/
{
public:
/**
- * Constructor for the Raviart-Thomas
- * element of degree @p p.
+ * Constructor for the Raviart-Thomas element of degree @p p.
*/
FE_RaviartThomasNodal (const unsigned int p);
/**
- * Return a string that uniquely
- * identifies a finite
- * element. This class returns
- * <tt>FE_RaviartThomasNodal<dim>(degree)</tt>, with
- * @p dim and @p degree
- * replaced by appropriate
- * values.
+ * Return a string that uniquely identifies a finite element. This class
+ * returns <tt>FE_RaviartThomasNodal<dim>(degree)</tt>, with @p dim and @p
+ * degree replaced by appropriate values.
*/
virtual std::string get_name () const;
private:
/**
- * Only for internal use. Its
- * full name is
- * @p get_dofs_per_object_vector
- * function and it creates the
- * @p dofs_per_object vector that is
- * needed within the constructor to
- * be passed to the constructor of
- * @p FiniteElementData.
+ * Only for internal use. Its full name is @p get_dofs_per_object_vector
+ * function and it creates the @p dofs_per_object vector that is needed
+ * within the constructor to be passed to the constructor of @p
+ * FiniteElementData.
*/
static std::vector<unsigned int>
get_dpo_vector (const unsigned int degree);
/**
- * Compute the vector used for
- * the
- * @p restriction_is_additive
- * field passed to the base
- * class's constructor.
+ * Compute the vector used for the @p restriction_is_additive field passed
+ * to the base class's constructor.
*/
static std::vector<bool>
get_ria_vector (const unsigned int degree);
* This function returns @p true, if the shape function @p shape_index has
* non-zero function values somewhere on the face @p face_index.
*
- * Right now, this is only
- * implemented for RT0 in
- * 1D. Otherwise, returns always
- * @p true.
+ * Right now, this is only implemented for RT0 in 1D. Otherwise, returns
+ * always @p true.
*/
virtual bool has_support_on_face (const unsigned int shape_index,
const unsigned int face_index) const;
/**
- * Initialize the
- * FiniteElement<dim>::generalized_support_points
- * and FiniteElement<dim>::generalized_face_support_points
- * fields. Called from the
- * constructor.
- *
- * See the @ref GlossGeneralizedSupport "glossary entry on generalized support points"
- * for more information.
+ * Initialize the FiniteElement<dim>::generalized_support_points and
+ * FiniteElement<dim>::generalized_face_support_points fields. Called from
+ * the constructor.
+ *
+ * See the @ref GlossGeneralizedSupport "glossary entry on generalized
+ * support points" for more information.
*/
void initialize_support_points (const unsigned int rt_degree);
};
* <h3>FESystem, components and blocks</h3>
*
* An FESystem, except in the most trivial case, produces a vector-valued
- * finite element with several components. The number of components n_components()
- * corresponds to the dimension of the solution function in the PDE system,
- * and correspondingly also to the number of equations your PDE system
- * has. For example, the mixed Laplace system covered in step-20 has $d+1$
- * components in $d$ space dimensions: the scalar pressure and the $d$
+ * finite element with several components. The number of components
+ * n_components() corresponds to the dimension of the solution function in the
+ * PDE system, and correspondingly also to the number of equations your PDE
+ * system has. For example, the mixed Laplace system covered in step-20 has
+ * $d+1$ components in $d$ space dimensions: the scalar pressure and the $d$
* components of the velocity vector. Similarly, the elasticity equation
* covered in step-8 has $d$ components in $d$ space dimensions. In general,
- * the number of components of a FESystem element is the
- * accumulated number of components of all base elements times their
- * multiplicities. A bit more on
- * components is also given in the
- * @ref GlossComponent "glossary entry on components".
+ * the number of components of a FESystem element is the accumulated number of
+ * components of all base elements times their multiplicities. A bit more on
+ * components is also given in the @ref GlossComponent "glossary entry on
+ * components".
*
* While the concept of components is important from the viewpoint of a
* partial differential equation, the finite element side looks a bit
* freedom associated with a single base element of an FESystem, where base
* elements with multiplicities count multiple times. These blocks are usually
* addressed using the information in DoFHandler::block_info(). The number of
- * blocks of a FESystem object is simply the sum of all multiplicities of
- * base elements and is given by n_blocks().
+ * blocks of a FESystem object is simply the sum of all multiplicities of base
+ * elements and is given by n_blocks().
*
- * For example, the FESystem for the Taylor-Hood element for the
- * three-dimensional Stokes problem can be built using the code
+ * For example, the FESystem for the Taylor-Hood element for the three-
+ * dimensional Stokes problem can be built using the code
*
* @code
* FE_Q<3> u(2);
* FESystem<3> sys3(u,1, p,1);
* @endcode
*
- * This example also produces a system with four components, but only
- * two blocks.
+ * This example also produces a system with four components, but only two
+ * blocks.
*
- * In most cases, the composed element behaves as if it were a usual
- * element. It just has more degrees of freedom than most of the "common"
- * elements. However the underlying structure is visible in the restriction,
+ * In most cases, the composed element behaves as if it were a usual element.
+ * It just has more degrees of freedom than most of the "common" elements.
+ * However the underlying structure is visible in the restriction,
* prolongation and interface constraint matrices, which do not couple the
* degrees of freedom of the base elements. E.g. the continuity requirement is
* imposed for the shape functions of the subobjects separately; no
* <h3>Internal information on numbering of degrees of freedom</h3>
*
* The overall numbering of degrees of freedom is as follows: for each
- * subobject (vertex, line, quad, or hex), the degrees of freedom are
- * numbered such that we run over all subelements first, before
- * turning for the next dof on this subobject or for the next
- * subobject. For example, for an element of three components in one
- * space dimension, the first two components being cubic lagrange
- * elements and the third being a quadratic lagrange element, the
- * ordering for the system <tt>s=(u,v,p)</tt> is:
+ * subobject (vertex, line, quad, or hex), the degrees of freedom are numbered
+ * such that we run over all subelements first, before turning for the next
+ * dof on this subobject or for the next subobject. For example, for an
+ * element of three components in one space dimension, the first two
+ * components being cubic lagrange elements and the third being a quadratic
+ * lagrange element, the ordering for the system <tt>s=(u,v,p)</tt> is:
*
* <ul>
* <li> First vertex: <tt>u0, v0, p0 = s0, s1, s2</tt>
* <li> Second vertex: <tt>u1, v1, p1 = s3, s4, s5</tt>
- * <li> First component on the line:
- * <tt>u2, u3 = s4, s5</tt>
- * <li> Second component on the line:
- * <tt>v2, v3 = s6, s7</tt>.
- * <li> Third component on the line:
- * <tt>p2 = s8</tt>.
+ * <li> First component on the line: <tt>u2, u3 = s4, s5</tt>
+ * <li> Second component on the line: <tt>v2, v3 = s6, s7</tt>.
+ * <li> Third component on the line: <tt>p2 = s8</tt>.
* </ul>
* That said, you should not rely on this numbering in your application as
* these %internals might change in future. Rather use the functions
* system_to_component_index() and component_to_system_index().
*
- * For more information on the template parameter <tt>spacedim</tt>
- * see the documentation of Triangulation.
+ * For more information on the template parameter <tt>spacedim</tt> see the
+ * documentation of Triangulation.
*
* @ingroup febase fe vector_valued
*
- * @author Wolfgang Bangerth, Guido Kanschat, 1999, 2002, 2003, 2006, Ralf Hartmann 2001.
+ * @author Wolfgang Bangerth, Guido Kanschat, 1999, 2002, 2003, 2006, Ralf
+ * Hartmann 2001.
*/
template <int dim, int spacedim=dim>
class FESystem : public FiniteElement<dim,spacedim>
* cell with respect to unit cell coordinates. Since this finite element is
* always vector-valued, we return the value of the only non-zero component
* of the vector value of this shape function. If the shape function has
- * more than one non-zero component (which we refer to with the term
- * non-primitive), then throw an exception of type @p
+ * more than one non-zero component (which we refer to with the term non-
+ * primitive), then throw an exception of type @p
* ExcShapeFunctionNotPrimitive.
*
* An @p ExcUnitShapeValuesDoNotExist is thrown if the shape values of the
*
* To explain the concept, consider the case where we would like to know
* whether a degree of freedom on a face, for example as part of an FESystem
- * element, is primitive. Unfortunately, the
- * is_primitive() function in the FiniteElement class takes a cell index, so
- * we would need to find the cell index of the shape function that
- * corresponds to the present face index. This function does that.
+ * element, is primitive. Unfortunately, the is_primitive() function in the
+ * FiniteElement class takes a cell index, so we would need to find the cell
+ * index of the shape function that corresponds to the present face index.
+ * This function does that.
*
* Code implementing this would then look like this:
* @code
* actual faces can be in their standard ordering with respect to the cell
* under consideration, or can be flipped, oriented, etc.
*
- * @param face_dof_index The index of the degree of freedom on a face.
- * This index must be between zero and dofs_per_face.
- * @param face The number of the face this degree of freedom lives on.
- * This number must be between zero and GeometryInfo::faces_per_cell.
- * @param face_orientation One part of the description of the orientation
- * of the face. See @ref GlossFaceOrientation .
- * @param face_flip One part of the description of the orientation
- * of the face. See @ref GlossFaceOrientation .
- * @param face_rotation One part of the description of the orientation
- * of the face. See @ref GlossFaceOrientation .
- * @return The index of this degree of freedom within the set
- * of degrees of freedom on the entire cell. The returned value
- * will be between zero and dofs_per_cell.
+ * @param face_dof_index The index of the degree of freedom on a face. This
+ * index must be between zero and dofs_per_face.
+ * @param face The number of the face this degree of freedom lives on. This
+ * number must be between zero and GeometryInfo::faces_per_cell.
+ * @param face_orientation One part of the description of the orientation of
+ * the face. See @ref GlossFaceOrientation .
+ * @param face_flip One part of the description of the orientation of the
+ * face. See @ref GlossFaceOrientation .
+ * @param face_rotation One part of the description of the orientation of
+ * the face. See @ref GlossFaceOrientation . @return The index of this
+ * degree of freedom within the set of degrees of freedom on the entire
+ * cell. The returned value will be between zero and dofs_per_cell.
*/
virtual
unsigned int face_to_cell_index (const unsigned int face_dof_index,
FullMatrix<double> &matrix) const;
/**
- * If, on a vertex, several finite elements are active, the hp code
- * first assigns the degrees of freedom of each of these FEs
- * different global indices. It then calls this function to find out
- * which of them should get identical values, and consequently can
- * receive the same global DoF index. This function therefore
- * returns a list of identities between DoFs of the present finite
- * element object with the DoFs of @p fe_other, which is a reference
- * to a finite element object representing one of the other finite
- * elements active on this particular vertex. The function computes
- * which of the degrees of freedom of the two finite element objects
- * are equivalent, both numbered between zero and the corresponding
- * value of dofs_per_vertex of the two finite elements. The first
- * index of each pair denotes one of the vertex dofs of the present
- * element, whereas the second is the corresponding index of the
- * other finite element.
+ * If, on a vertex, several finite elements are active, the hp code first
+ * assigns the degrees of freedom of each of these FEs different global
+ * indices. It then calls this function to find out which of them should get
+ * identical values, and consequently can receive the same global DoF index.
+ * This function therefore returns a list of identities between DoFs of the
+ * present finite element object with the DoFs of @p fe_other, which is a
+ * reference to a finite element object representing one of the other finite
+ * elements active on this particular vertex. The function computes which of
+ * the degrees of freedom of the two finite element objects are equivalent,
+ * both numbered between zero and the corresponding value of dofs_per_vertex
+ * of the two finite elements. The first index of each pair denotes one of
+ * the vertex dofs of the present element, whereas the second is the
+ * corresponding index of the other finite element.
*/
virtual
std::vector<std::pair<unsigned int, unsigned int> >
hp_vertex_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
/**
- * Same as hp_vertex_dof_indices(), except that the function treats
- * degrees of freedom on lines.
+ * Same as hp_vertex_dof_indices(), except that the function treats degrees
+ * of freedom on lines.
*/
virtual
std::vector<std::pair<unsigned int, unsigned int> >
hp_line_dof_identities (const FiniteElement<dim,spacedim> &fe_other) const;
/**
- * Same as hp_vertex_dof_indices(), except that the function treats
- * degrees of freedom on quads.
+ * Same as hp_vertex_dof_indices(), except that the function treats degrees
+ * of freedom on quads.
*/
virtual
std::vector<std::pair<unsigned int, unsigned int> >
/**
- * Initialize the @p unit_support_points field of the FiniteElement
- * class. Called from the constructor.
+ * Initialize the @p unit_support_points field of the FiniteElement class.
+ * Called from the constructor.
*/
void initialize_unit_support_points ();
* Compute the nonzero components of a list of finite elements with
* multiplicities given in the second argument. This function is called from
* all the above functions.
- */
+ */
static std::vector<ComponentMask>
compute_nonzero_components (const std::vector<const FiniteElement<dim,spacedim>*> &fes,
const std::vector<unsigned int> &multiplicities);
public:
/**
* Constructor. Is called by the @p get_data function. Sets the size of
- * the @p base_fe_datas vector to @p n_base_elements and initializes
- * the compute_hessians field.
+ * the @p base_fe_datas vector to @p n_base_elements and initializes the
+ * compute_hessians field.
*/
InternalData (const unsigned int n_base_elements,
const bool compute_hessians);
* pointing to. Sets <tt>fe_datas[base_no]</tt> to zero.
*
* This function is used to delete @p FEValuesData that are needed only on
- * the first cell but not any more afterwards. This is the case for
- * e.g. Lagrangian elements (see e.g. @p FE_Q classes).
+ * the first cell but not any more afterwards. This is the case for e.g.
+ * Lagrangian elements (see e.g. @p FE_Q classes).
*/
void delete_fe_values_data (const unsigned int base_no);
* are accessed to by the @p set_ and @p get_fe_data functions.
*
* The size of this vector is set to @p n_base_elements by the
- * InternalData constructor. It is filled by the @p get_data
- * function. Note that since the data for each instance of a base class is
+ * InternalData constructor. It is filled by the @p get_data function.
+ * Note that since the data for each instance of a base class is
* necessarily the same, we only need as many of these objects as there
* are base elements, irrespective of their multiplicity.
*/
/**
* This namespace offers interpolations and extrapolations of discrete
- * functions of one @p FiniteElement @p fe1 to another @p FiniteElement
- * @p fe2.
+ * functions of one @p FiniteElement @p fe1 to another @p FiniteElement @p
+ * fe2.
*
- * It also provides the local interpolation matrices that interpolate
- * on each cell. Furthermore it provides the difference matrix
- * $id-I_h$ that is needed for evaluating $(id-I_h)z$ for e.g. the
- * dual solution $z$.
+ * It also provides the local interpolation matrices that interpolate on each
+ * cell. Furthermore it provides the difference matrix $id-I_h$ that is needed
+ * for evaluating $(id-I_h)z$ for e.g. the dual solution $z$.
*
- * For more information about the <tt>spacedim</tt> template parameter
- * check the documentation of FiniteElement or the one of
- * Triangulation.
+ * For more information about the <tt>spacedim</tt> template parameter check
+ * the documentation of FiniteElement or the one of Triangulation.
*
- * @author Wolfgang Bangerth, Ralf Hartmann, Guido Kanschat;
- * 2000, 2003, 2004, 2005, 2006
+ * @author Wolfgang Bangerth, Ralf Hartmann, Guido Kanschat; 2000, 2003, 2004,
+ * 2005, 2006
*/
namespace FETools
{
* @warning In most cases, you will probably want to use
* compute_base_renumbering().
*
- * Compute the vector required to renumber the dofs of a cell by
- * component. Furthermore, compute the vector storing the start indices of
- * each component in the local block vector.
+ * Compute the vector required to renumber the dofs of a cell by component.
+ * Furthermore, compute the vector storing the start indices of each
+ * component in the local block vector.
*
* The second vector is organized such that there is a vector for each base
* element containing the start index for each component served by this base
std::vector<std::vector<unsigned int> > &start_indices);
/**
- * Compute the vector required to renumber the dofs of a cell by
- * block. Furthermore, compute the vector storing either the start indices
- * or the size of each local block vector.
+ * Compute the vector required to renumber the dofs of a cell by block.
+ * Furthermore, compute the vector storing either the start indices or the
+ * size of each local block vector.
*
* If the @p bool parameter is true, @p block_data is filled with the start
* indices of each local block. If it is false, then the block sizes are
* returned.
*
- * The vector <tt>renumbering</tt> will be indexed by the standard
- * numbering of local degrees of freedom, namely first first vertex,
- * then second vertex, after vertices lines, quads, and hexes. For
- * each index, the entry indicates the index which this degree of
- * freedom receives in a numbering scheme, where the first block is
- * numbered completely before the second.
+ * The vector <tt>renumbering</tt> will be indexed by the standard numbering
+ * of local degrees of freedom, namely first first vertex, then second
+ * vertex, after vertices lines, quads, and hexes. For each index, the entry
+ * indicates the index which this degree of freedom receives in a numbering
+ * scheme, where the first block is numbered completely before the second.
*/
template<int dim, int spacedim>
void compute_block_renumbering (
*
* This function gives the matrix that transforms a @p fe1 function $z$ to
* $z-I_hz$ where $I_h$ denotes the interpolation operator from the @p fe1
- * space to the @p fe2 space. This matrix hence is useful to evaluate
- * error-representations where $z$ denotes the dual solution.
+ * space to the @p fe2 space. This matrix hence is useful to evaluate error-
+ * representations where $z$ denotes the dual solution.
*/
template <int dim, typename number, int spacedim>
void
* For all possible (isotropic and anisotropic) refinement cases compute the
* embedding matrices from a coarse cell to the child cells. Each column of
* the resulting matrices contains the representation of a coarse grid basis
- * function by the fine grid basis; the matrices are split such that there is
- * one matrix for every child.
+ * function by the fine grid basis; the matrices are split such that there
+ * is one matrix for every child.
*
* This function computes the coarse grid function in a sufficiently large
* number of quadrature points and fits the fine grid functions using least
* data <tt>u<sub>q</sub>, 0 <= q < Q:=quadrature.size()</tt> defined at the
* quadrature points of a cell, with the points defined by the given
* <tt>rhs_quadrature</tt> object. We may then want to ask for that finite
- * element function (on a single cell) <tt>v<sub>h</sub></tt> in the
- * finite-dimensional space defined by the given FE object that is the
- * projection of <tt>u</tt> in the following sense:
+ * element function (on a single cell) <tt>v<sub>h</sub></tt> in the finite-
+ * dimensional space defined by the given FE object that is the projection
+ * of <tt>u</tt> in the following sense:
*
* Usually, the projection <tt>v<sub>h</sub></tt> is that function that
* satisfies <tt>(v<sub>h</sub>,w)=(u,w)</tt> for all discrete test
* triangulation. In effect, it therefore doesn't matter if you use a
* continuous or discontinuous version of the finite element.
*
- * It is worth noting that there are a few confusing cases of this
- * function. The first one is that it really only makes sense to project
- * onto a finite element that has at most as many degrees of freedom per
- * cell as there are quadrature points; the projection of N quadrature point
- * data into a space with M>N unknowns is well-defined, but often yields
- * funny and non-intuitive results. Secondly, one would think that if the
- * quadrature point data is defined in the support points of the finite
- * element, i.e. the quadrature points of <tt>ths_quadrature</tt> equal
+ * It is worth noting that there are a few confusing cases of this function.
+ * The first one is that it really only makes sense to project onto a finite
+ * element that has at most as many degrees of freedom per cell as there are
+ * quadrature points; the projection of N quadrature point data into a space
+ * with M>N unknowns is well-defined, but often yields funny and non-
+ * intuitive results. Secondly, one would think that if the quadrature point
+ * data is defined in the support points of the finite element, i.e. the
+ * quadrature points of <tt>ths_quadrature</tt> equal
* <tt>fe.get_unit_support_points()</tt>, then the projection should be the
* identity, i.e. each degree of freedom of the finite element equals the
* value of the given data in the support point of the corresponding shape
* the same triangulation.
*
* If the elements @p fe1 and @p fe2 are either both continuous or both
- * discontinuous then this interpolation is the usual point
- * interpolation. The same is true if @p fe1 is a continuous and @p fe2 is a
- * discontinuous finite element. For the case that @p fe1 is a discontinuous
- * and @p fe2 is a continuous finite element there is no point interpolation
- * defined at the discontinuities. Therefore the meanvalue is taken at the
- * DoF values on the discontinuities.
- *
- * Note that for continuous elements on grids with hanging nodes
- * (i.e. locally refined grids) this function does not give the expected
- * output. Indeed, the resulting output vector does not necessarily respect
+ * discontinuous then this interpolation is the usual point interpolation.
+ * The same is true if @p fe1 is a continuous and @p fe2 is a discontinuous
+ * finite element. For the case that @p fe1 is a discontinuous and @p fe2 is
+ * a continuous finite element there is no point interpolation defined at
+ * the discontinuities. Therefore the meanvalue is taken at the DoF values
+ * on the discontinuities.
+ *
+ * Note that for continuous elements on grids with hanging nodes (i.e.
+ * locally refined grids) this function does not give the expected output.
+ * Indeed, the resulting output vector does not necessarily respect
* continuity requirements at hanging nodes: if, for example, you are
* interpolating a Q2 field to a Q1 field, then at hanging nodes the output
* field will have the function value of the input field, which however is
* with hanging nodes (locally refined grids).
*
* If the elements @p fe1 and @p fe2 are either both continuous or both
- * discontinuous then this interpolation is the usual point
- * interpolation. The same is true if @p fe1 is a continuous and @p fe2 is a
- * discontinuous finite element. For the case that @p fe1 is a discontinuous
- * and @p fe2 is a continuous finite element there is no point interpolation
- * defined at the discontinuities. Therefore the mean value is taken at the
- * DoF values at the discontinuities.
+ * discontinuous then this interpolation is the usual point interpolation.
+ * The same is true if @p fe1 is a continuous and @p fe2 is a discontinuous
+ * finite element. For the case that @p fe1 is a discontinuous and @p fe2 is
+ * a continuous finite element there is no point interpolation defined at
+ * the discontinuities. Therefore the mean value is taken at the DoF values
+ * at the discontinuities.
*/
template <int dim, int spacedim,
template <int, int> class DH1,
* Gives the interpolation of the @p dof1-function @p u1 to a @p
* dof2-function, and interpolates this to a second @p dof1-function named
* @p u1_interpolated. @p constraints1 and @p constraints2 are the hanging
- * node constraints corresponding to @p dof1 and @p dof2,
- * respectively. These objects are particular important when continuous
- * elements on grids with hanging nodes (locally refined grids) are
- * involved.
+ * node constraints corresponding to @p dof1 and @p dof2, respectively.
+ * These objects are particular important when continuous elements on grids
+ * with hanging nodes (locally refined grids) are involved.
*
* Furthermore note, that for the specific case when the finite element
* space corresponding to @p dof1 is a subset of the finite element space
* other:
*
* - It interpolates directly from every cell of @p dof1 to the
- * corresponding cell of `dof2` using the interpolation matrix of the
- * finite element spaces used on these cells and provided by
- * the finite element objects involved. This step is done using the
- * FETools::interpolate() function.
- * - It then performs a loop over all non-active cells of `dof2`. If
- * such a non-active cell has at least one active child, then we
- * call the children of this cell a "patch". We then interpolate
- * from the children of this patch to the patch, using the finite
- * element space associated with `dof2` and immediately interpolate
- * back to the children. In essence, this information throws away
- * all information in the solution vector that lives on a scale
- * smaller than the patch cell.
- * - Since we traverse non-active cells from the coarsest to the
- * finest levels, we may find patches that correspond to child
- * cells of previously treated patches if the mesh had been
- * refined adaptively (this cannot happen if the mesh has been
- * refined globally because there the children of a patch are
- * all active). We also perform the operation described above
- * on these patches, but it is easy to see that on patches that
- * are children of previously treated patches, the operation is
- * now the identity operation (since it interpolates from the
- * children of the current patch a function that had previously
- * been interpolated to these children from an even coarser patch).
- * Consequently, this does not alter the solution vector any more.
- *
- * The name of the function originates from the fact that it can be
- * used to construct a representation of a function of higher polynomial
- * degree on a once coarser mesh. For example, if you imagine that you
- * start with a $Q_1$ function on globally refined mesh, and that @p dof2
- * is associated with a $Q_2$ element, then this function computes the
- * equivalent of the operator $I_{2h}^{(2)}$ interpolating the original
- * piecewise linear function onto a quadratic function on a once coarser
- * mesh with mesh size $2h$ (but representing this function on the original
- * mesh with size $h$). If the exact solution is sufficiently smooth,
- * then $u^\ast=I_{2h}^{(2)}u_h$ is typically a better approximation to
- * the exact solution $u$ of the PDE than $u_h$ is. In other words, this
- * function provides a postprocessing step that improves the solution in
- * a similar way one often obtains by extrapolating a sequence of solutions,
+ * corresponding cell of `dof2` using the interpolation matrix of the finite
+ * element spaces used on these cells and provided by the finite element
+ * objects involved. This step is done using the FETools::interpolate()
+ * function. - It then performs a loop over all non-active cells of `dof2`.
+ * If such a non-active cell has at least one active child, then we call the
+ * children of this cell a "patch". We then interpolate from the children of
+ * this patch to the patch, using the finite element space associated with
+ * `dof2` and immediately interpolate back to the children. In essence, this
+ * information throws away all information in the solution vector that lives
+ * on a scale smaller than the patch cell. - Since we traverse non-active
+ * cells from the coarsest to the finest levels, we may find patches that
+ * correspond to child cells of previously treated patches if the mesh had
+ * been refined adaptively (this cannot happen if the mesh has been refined
+ * globally because there the children of a patch are all active). We also
+ * perform the operation described above on these patches, but it is easy to
+ * see that on patches that are children of previously treated patches, the
+ * operation is now the identity operation (since it interpolates from the
+ * children of the current patch a function that had previously been
+ * interpolated to these children from an even coarser patch). Consequently,
+ * this does not alter the solution vector any more.
+ *
+ * The name of the function originates from the fact that it can be used to
+ * construct a representation of a function of higher polynomial degree on a
+ * once coarser mesh. For example, if you imagine that you start with a
+ * $Q_1$ function on globally refined mesh, and that @p dof2 is associated
+ * with a $Q_2$ element, then this function computes the equivalent of the
+ * operator $I_{2h}^{(2)}$ interpolating the original piecewise linear
+ * function onto a quadratic function on a once coarser mesh with mesh size
+ * $2h$ (but representing this function on the original mesh with size $h$).
+ * If the exact solution is sufficiently smooth, then
+ * $u^\ast=I_{2h}^{(2)}u_h$ is typically a better approximation to the exact
+ * solution $u$ of the PDE than $u_h$ is. In other words, this function
+ * provides a postprocessing step that improves the solution in a similar
+ * way one often obtains by extrapolating a sequence of solutions,
* explaining the origin of the function's name.
*
- * @note The resulting field does not satisfy continuity requirements of
- * the given finite elements if the algorithm outlined above is used.
- * When you use continuous elements on grids with hanging nodes, please use
- * the @p extrapolate function with an additional ConstraintMatrix argument,
- * see below.
+ * @note The resulting field does not satisfy continuity requirements of the
+ * given finite elements if the algorithm outlined above is used. When you
+ * use continuous elements on grids with hanging nodes, please use the @p
+ * extrapolate function with an additional ConstraintMatrix argument, see
+ * below.
*
* @note Since this function operates on patches of cells, it requires that
- * the underlying grid is refined at least once for every coarse grid cell. If
- * this is not the case, an exception will be raised.
+ * the underlying grid is refined at least once for every coarse grid cell.
+ * If this is not the case, an exception will be raised.
*/
template <int dim, class InVector, class OutVector, int spacedim>
void extrapolate (const DoFHandler<dim,spacedim> &dof1,
/**
* Gives the patchwise extrapolation of a @p dof1 function @p z1 to a @p
- * dof2 function @p z2. @p dof1 and @p dof2 need to be DoFHandler objects based on
- * the same triangulation. @p constraints is a hanging node constraints
- * object corresponding to @p dof2. This object is necessary when
- * interpolating onto continuous elements on grids with hanging nodes
+ * dof2 function @p z2. @p dof1 and @p dof2 need to be DoFHandler objects
+ * based on the same triangulation. @p constraints is a hanging node
+ * constraints object corresponding to @p dof2. This object is necessary
+ * when interpolating onto continuous elements on grids with hanging nodes
* (locally refined grids).
*
* Otherwise, the function does the same as the other @p extrapolate
* accordingly.
*
* The name must be in the form which is returned by the
- * FiniteElement::get_name function, where dimension template parameters <2> etc. can be
- * omitted. Alternatively, the explicit number can be replaced by
- * <tt>dim</tt> or <tt>d</tt>. If a number is given, it <b>must</b> match
- * the template parameter of this function.
+ * FiniteElement::get_name function, where dimension template parameters
+ * <2> etc. can be omitted. Alternatively, the explicit number can be
+ * replaced by <tt>dim</tt> or <tt>d</tt>. If a number is given, it
+ * <b>must</b> match the template parameter of this function.
*
- * The names of FESystem elements follow the pattern <code>FESystem[FE_Base1^p1-FE_Base2^p2]</code>
- * The powers <code>p1</code> etc. may either be numbers or can be
- * replaced by <tt>dim</tt> or <tt>d</tt>.
+ * The names of FESystem elements follow the pattern
+ * <code>FESystem[FE_Base1^p1-FE_Base2^p2]</code> The powers <code>p1</code>
+ * etc. may either be numbers or can be replaced by <tt>dim</tt> or
+ * <tt>d</tt>.
*
*
* If no finite element can be reconstructed from this string, an exception
* The format of the @p name parameter should include the name of a finite
* element. However, it is safe to use either the class name alone or to use
* the result of FiniteElement::get_name (which includes the space dimension
- * as well as the polynomial degree), since everything after the first
- * non-name character will be ignored.
+ * as well as the polynomial degree), since everything after the first non-
+ * name character will be ignored.
*
- * The FEFactory object should be an object newly created with
- * <tt>new</tt>. FETools will take ownership of this object and delete it
- * once it is not used anymore.
+ * The FEFactory object should be an object newly created with <tt>new</tt>.
+ * FETools will take ownership of this object and delete it once it is not
+ * used anymore.
*
* In most cases, if you want objects of type <code>MyFE</code> be created
* whenever the name <code>my_fe</code> is given to get_fe_from_name, you
* argument, i.e. you should never attempt to destroy it later on. The
* object will be deleted at the end of the program's lifetime.
*
- * If the name of the element is already in use, an exception is
- * thrown. Thus, functionality of get_fe_from_name() can only be added, not
- * changed.
+ * If the name of the element is already in use, an exception is thrown.
+ * Thus, functionality of get_fe_from_name() can only be added, not changed.
*
* @note This function manipulates a global table (one table for each space
* dimension). It is thread safe in the sense that every access to this
DEAL_II_NAMESPACE_OPEN
/**
- * A finite element, which is the trace of FE_Q elements, that is
- * a tensor product of polynomials on the faces,
- * undefined in the interior of the cells and continuous. The basis functions on
- * the faces are from Polynomials::LagrangeEquidistant
+ * A finite element, which is the trace of FE_Q elements, that is a tensor
+ * product of polynomials on the faces, undefined in the interior of the cells
+ * and continuous. The basis functions on the faces are from
+ * Polynomials::LagrangeEquidistant
*
- * This finite element is the trace space of FE_Q on the
- * faces.
+ * This finite element is the trace space of FE_Q on the faces.
*
- * @note Since these are only finite elements on faces, only
- * FEFaceValues and FESubfaceValues will be able to extract reasonable
- * values from any face polynomial. In order to make the use of
- * FESystem simpler, FEValues objects will not fail using this finite
- * element space, but all shape function values extracted will equal
- * to zero.
+ * @note Since these are only finite elements on faces, only FEFaceValues and
+ * FESubfaceValues will be able to extract reasonable values from any face
+ * polynomial. In order to make the use of FESystem simpler, FEValues objects
+ * will not fail using this finite element space, but all shape function
+ * values extracted will equal to zero.
*
- * @todo Polynomials::LagrangeEquidistant should be and will be
- * replaced by Polynomials::LagrangeGaussLobatto as soon as such a
- * polynomial set exists.
+ * @todo Polynomials::LagrangeEquidistant should be and will be replaced by
+ * Polynomials::LagrangeGaussLobatto as soon as such a polynomial set exists.
* @todo so far, hanging nodes are not implemented
*
*/
{
public:
/**
- * Constructor for tensor product
- * polynomials of degree
- * <tt>p</tt>. The shape
- * functions created using this
- * constructor correspond to
- * Legendre polynomials in each
- * coordinate direction.
+ * Constructor for tensor product polynomials of degree <tt>p</tt>. The
+ * shape functions created using this constructor correspond to Legendre
+ * polynomials in each coordinate direction.
*/
FE_TraceQ(unsigned int p);
virtual FiniteElement<dim,spacedim> *clone() const;
/**
- * Return a string that uniquely
- * identifies a finite
- * element. This class returns
- * <tt>FE_DGQ<dim>(degree)</tt>, with
- * <tt>dim</tt> and <tt>degree</tt>
- * replaced by appropriate
- * values.
+ * Return a string that uniquely identifies a finite element. This class
+ * returns <tt>FE_DGQ<dim>(degree)</tt>, with <tt>dim</tt> and
+ * <tt>degree</tt> replaced by appropriate values.
*/
virtual std::string get_name () const;
private:
/**
- * Return vector with dofs per
- * vertex, line, quad, hex.
+ * Return vector with dofs per vertex, line, quad, hex.
*/
static std::vector<unsigned int> get_dpo_vector (const unsigned int deg);
};
/*@{*/
/**
- * The enum type given to the constructors of FEValues, FEFaceValues
- * and FESubfaceValues, telling those objects which data will be
- * needed on each mesh cell.
+ * The enum type given to the constructors of FEValues, FEFaceValues and
+ * FESubfaceValues, telling those objects which data will be needed on each
+ * mesh cell.
*
- * Selecting these flags in a restrictive way is crucial for the
- * efficiency of FEValues::reinit(), FEFaceValues::reinit() and
- * FESubfaceValues::reinit(). Therefore, only the flags actually
- * needed should be selected. It is the responsibility of the involved
- * Mapping and FiniteElement to add additional flags according to
- * their own requirements. For instance, most finite elements will
- * add #update_covariant_transformation if #update_gradients is
- * selected.
-
- * By default, all flags are off, i.e. no reinitialization will be
+ * Selecting these flags in a restrictive way is crucial for the efficiency of
+ * FEValues::reinit(), FEFaceValues::reinit() and FESubfaceValues::reinit().
+ * Therefore, only the flags actually needed should be selected. It is the
+ * responsibility of the involved Mapping and FiniteElement to add additional
+ * flags according to their own requirements. For instance, most finite
+ * elements will add #update_covariant_transformation if #update_gradients is
+ * selected. By default, all flags are off, i.e. no reinitialization will be
* done.
*
- * You can select more than one flag by concatenation
- * using the bitwise or operator|(UpdateFlags,UpdateFlags).
+ * You can select more than one flag by concatenation using the bitwise or
+ * operator|(UpdateFlags,UpdateFlags).
*
* <h3>Generating the actual flags</h3>
*
* When given a set of UpdateFlags @p flags, the FEValues object must
* determine, which values will have to be computed once only for the
- * reference cell and which values will have to be updated for each
- * cell. Here, it is important to note that in many cases, the
- * FiniteElement will require additional updates from the Mapping. To
- * this end, several auxiliary functions have been implemented:
+ * reference cell and which values will have to be updated for each cell.
+ * Here, it is important to note that in many cases, the FiniteElement will
+ * require additional updates from the Mapping. To this end, several auxiliary
+ * functions have been implemented:
*
- * FiniteElement::update_once(flags) and
- * FiniteElement::update_each(flags) determine the values required by
- * the FiniteElement once or on each cell. The same functions exist in Mapping.
+ * FiniteElement::update_once(flags) and FiniteElement::update_each(flags)
+ * determine the values required by the FiniteElement once or on each cell.
+ * The same functions exist in Mapping.
*
- * Since the FiniteElement does not know if a value required from
- * Mapping should be computed once or for each cell,
- * FEValuesBase::compute_update_flags() is used to compute the union
- * of all values to be computed ever. It does this by first adding to
- * the flags set by the user all flags (once and each) added by the
- * FiniteElement. This new set of flags is then given to the Mapping
- * and all flags required there are added, again once and each.
+ * Since the FiniteElement does not know if a value required from Mapping
+ * should be computed once or for each cell,
+ * FEValuesBase::compute_update_flags() is used to compute the union of all
+ * values to be computed ever. It does this by first adding to the flags set
+ * by the user all flags (once and each) added by the FiniteElement. This new
+ * set of flags is then given to the Mapping and all flags required there are
+ * added, again once and each.
*
* This union of all flags is given to Mapping::fill_fe_values() and
- * FiniteElement::fill_fe_values, where it is split again into the
- * information generated only once and the information that must be
- * updated on each cell.
+ * FiniteElement::fill_fe_values, where it is split again into the information
+ * generated only once and the information that must be updated on each cell.
*
- * The flags finally stored in FEValues then are the union of all the
- * flags required by the user, by FiniteElement and by Mapping, for
- * computation once or on each cell. Subsequent calls to the functions
- * @p update_once and @p update_each should just select among these
- * flags, but should not add new flags.
+ * The flags finally stored in FEValues then are the union of all the flags
+ * required by the user, by FiniteElement and by Mapping, for computation once
+ * or on each cell. Subsequent calls to the functions @p update_once and @p
+ * update_each should just select among these flags, but should not add new
+ * flags.
*
- * The mechanism by which all this is accomplished is also discussed
- * on the page on @ref UpdateFlagsEssay.
+ * The mechanism by which all this is accomplished is also discussed on the
+ * page on @ref UpdateFlagsEssay.
*/
enum UpdateFlags
{
update_default = 0,
//! Shape function values
/**
- * Compute the values of the shape functions at the quadrature points on
- * the real space cell. For the usual Lagrange elements, these values are
- * equal to the values of the shape functions at the quadrature points on
- * the unit cell, but they are different for more complicated elements,
- * such as FE_RaviartThomas elements.
+ * Compute the values of the shape functions at the quadrature points on the
+ * real space cell. For the usual Lagrange elements, these values are equal
+ * to the values of the shape functions at the quadrature points on the unit
+ * cell, but they are different for more complicated elements, such as
+ * FE_RaviartThomas elements.
*/
update_values = 0x0001,
//! Shape function gradients
/**
- * Compute the gradients of the shape functions in coordinates of the
- * real cell.
+ * Compute the gradients of the shape functions in coordinates of the real
+ * cell.
*/
update_gradients = 0x0002,
//! Second derivatives of shape functions
/**
- * Compute the second derivatives of the shape functions in coordinates
- * of the real cell.
+ * Compute the second derivatives of the shape functions in coordinates of
+ * the real cell.
*/
update_hessians = 0x0004,
//! Outer normal vector, not normalized
/**
- * Vector product of tangential vectors, yielding a normal vector with
- * a length corresponding to the surface element; may be more efficient
- * than computing both.
+ * Vector product of tangential vectors, yielding a normal vector with a
+ * length corresponding to the surface element; may be more efficient than
+ * computing both.
*/
update_boundary_forms = 0x0008,
//! Transformed quadrature points
update_quadrature_points = 0x0010,
//! Transformed quadrature weights
/**
- * Compute the quadrature weights on the real cell, i.e. the weights
- * of the quadrature rule multiplied with the determinant of the Jacoian
- * of the transformation from reference to realcell.
+ * Compute the quadrature weights on the real cell, i.e. the weights of the
+ * quadrature rule multiplied with the determinant of the Jacoian of the
+ * transformation from reference to realcell.
*/
update_JxW_values = 0x0020,
//! Normal vectors
/**
* Compute the normal vectors, either for a face or for a cell of
- * codimension one. Setting this flag for any other object will raise
- * an error.
+ * codimension one. Setting this flag for any other object will raise an
+ * error.
*/
update_normal_vectors = 0x0040,
/**
update_cell_normal_vectors = update_normal_vectors,
//! Volume element
/**
- * Compute the Jacobian of the transformation from the reference cell
- * to the real cell.
+ * Compute the Jacobian of the transformation from the reference cell to the
+ * real cell.
*/
update_jacobians = 0x0080,
//! Gradient of volume element
update_contravariant_transformation = 0x0800,
//! Shape function values of transformation
/**
- * Compute the shape function values of the transformation defined by
- * the Mapping.
+ * Compute the shape function values of the transformation defined by the
+ * Mapping.
*/
update_transformation_values = 0x1000,
//! Shape function gradients of transformation
/**
- * Compute the shape function gradients of the transformation defined
- * by the Mapping.
+ * Compute the shape function gradients of the transformation defined by the
+ * Mapping.
*/
update_transformation_gradients = 0x2000,
//! Determinant of the Jacobian
*/
update_support_jacobians = 0x20000,
/**
- * Update the inverse Jacobian of the mapping in generalized support
- * points.
+ * Update the inverse Jacobian of the mapping in generalized support points.
*/
update_support_inverse_jacobians = 0x40000,
/**
/**
- * Global operator which returns an object in which all bits are set
- * which are either set in the first or the second argument. This
- * operator exists since if it did not then the result of the bit-or
- * <tt>operator |</tt> would be an integer which would in turn trigger
- * a compiler warning when we tried to assign it to an object of type
- * UpdateFlags.
+ * Global operator which returns an object in which all bits are set which are
+ * either set in the first or the second argument. This operator exists since
+ * if it did not then the result of the bit-or <tt>operator |</tt> would be an
+ * integer which would in turn trigger a compiler warning when we tried to
+ * assign it to an object of type UpdateFlags.
*
* @ref UpdateFlags
*/
/**
- * Global operator which sets the bits from the second argument also
- * in the first one.
+ * Global operator which sets the bits from the second argument also in the
+ * first one.
*
* @ref UpdateFlags
*/
/**
- * Global operator which returns an object in which all bits are set
- * which are set in the first as well as the second argument. This
- * operator exists since if it did not then the result of the bit-and
- * <tt>operator &</tt> would be an integer which would in turn trigger
- * a compiler warning when we tried to assign it to an object of type
- * UpdateFlags.
+ * Global operator which returns an object in which all bits are set which are
+ * set in the first as well as the second argument. This operator exists since
+ * if it did not then the result of the bit-and <tt>operator &</tt> would be
+ * an integer which would in turn trigger a compiler warning when we tried to
+ * assign it to an object of type UpdateFlags.
*
* @ref UpdateFlags
*/
/**
- * Global operator which clears all the bits in the first argument if
- * they are not also set in the second argument.
+ * Global operator which clears all the bits in the first argument if they are
+ * not also set in the second argument.
*
* @ref UpdateFlags
*/
/**
* This enum definition is used for storing similarities of the current cell
* to the previously visited cell. This information is used for reusing data
- * when calling the method FEValues::reinit() (like derivatives, which do
- * not change if one cell is just a translation of the previous). Currently,
- * this variable does only recognize a translation and an inverted translation
- * (if dim<spacedim). However, this concept
- * makes it easy to add additional staties to be detected in
- * FEValues/FEFaceValues for making use of these similarities as well.
+ * when calling the method FEValues::reinit() (like derivatives, which do not
+ * change if one cell is just a translation of the previous). Currently, this
+ * variable does only recognize a translation and an inverted translation (if
+ * dim<spacedim). However, this concept makes it easy to add additional
+ * staties to be detected in FEValues/FEFaceValues for making use of these
+ * similarities as well.
*/
namespace CellSimilarity
{
typedef double value_type;
/**
- * A typedef for the type of gradients of the view this class
- * represents. Here, for a scalar component of the finite element, the
- * gradient is a <code>Tensor@<1,dim@></code>.
+ * A typedef for the type of gradients of the view this class represents.
+ * Here, for a scalar component of the finite element, the gradient is a
+ * <code>Tensor@<1,dim@></code>.
*/
typedef dealii::Tensor<1,spacedim> gradient_type;
* Return the value of the vector component selected by this view, for the
* shape function and quadrature point selected by the arguments.
*
- * @param shape_function Number of the shape function to be
- * evaluated. Note that this number runs from zero to dofs_per_cell, even
- * in the case of an FEFaceValues or FESubfaceValues object.
+ * @param shape_function Number of the shape function to be evaluated.
+ * Note that this number runs from zero to dofs_per_cell, even in the case
+ * of an FEFaceValues or FESubfaceValues object.
*
* @param q_point Number of the quadrature point at which function is to
* be evaluated.
typedef dealii::Tensor<1,spacedim> value_type;
/**
- * A typedef for the type of gradients of the view this class
- * represents. Here, for a set of <code>dim</code> components of the
- * finite element, the gradient is a <code>Tensor@<2,spacedim@></code>.
+ * A typedef for the type of gradients of the view this class represents.
+ * Here, for a set of <code>dim</code> components of the finite element,
+ * the gradient is a <code>Tensor@<2,spacedim@></code>.
*
* See the general documentation of this class for how exactly the
* gradient of a vector is defined.
typedef double divergence_type;
/**
- * A typedef for the type of the curl of the view this class
- * represents. Here, for a set of <code>spacedim=2</code> components of
- * the finite element, the curl is a <code>Tensor@<1, 1@></code>. For
+ * A typedef for the type of the curl of the view this class represents.
+ * Here, for a set of <code>spacedim=2</code> components of the finite
+ * element, the curl is a <code>Tensor@<1, 1@></code>. For
* <code>spacedim=3</code> it is a <code>Tensor@<1, dim@></code>.
*/
typedef typename dealii::internal::CurlType<spacedim>::type curl_type;
/**
* Return the value of the vector components selected by this view, for
- * the shape function and quadrature point selected by the
- * arguments. Here, since the view represents a vector-valued part of the
- * FEValues object with <code>dim</code> components, the return type is a
- * tensor of rank 1 with <code>dim</code> components.
+ * the shape function and quadrature point selected by the arguments.
+ * Here, since the view represents a vector-valued part of the FEValues
+ * object with <code>dim</code> components, the return type is a tensor of
+ * rank 1 with <code>dim</code> components.
*
- * @param shape_function Number of the shape function to be
- * evaluated. Note that this number runs from zero to dofs_per_cell, even
- * in the case of an FEFaceValues or FESubfaceValues object.
+ * @param shape_function Number of the shape function to be evaluated.
+ * Note that this number runs from zero to dofs_per_cell, even in the case
+ * of an FEFaceValues or FESubfaceValues object.
*
* @param q_point Number of the quadrature point at which function is to
* be evaluated.
/**
* Return the vector curl of the vector components selected by this view,
- * for the shape function and quadrature point selected by the
- * arguments. For 1d this function does not make any sense. Thus it is not
+ * for the shape function and quadrature point selected by the arguments.
+ * For 1d this function does not make any sense. Thus it is not
* implemented for <code>spacedim=1</code>. In 2d the curl is defined as
* @f{equation*} \operatorname{curl}(u):=\frac{du_2}{dx} -\frac{du_1}{dy},
* @f} whereas in 3d it is given by @f{equation*}
/**
* Return the value of the vector components selected by this view, for
- * the shape function and quadrature point selected by the
- * arguments. Here, since the view represents a vector-valued part of the
- * FEValues object with <code>(dim*dim + dim)/2</code> components (the
- * unique components of a symmetric second-order tensor), the return type
- * is a symmetric tensor of rank 2.
+ * the shape function and quadrature point selected by the arguments.
+ * Here, since the view represents a vector-valued part of the FEValues
+ * object with <code>(dim*dim + dim)/2</code> components (the unique
+ * components of a symmetric second-order tensor), the return type is a
+ * symmetric tensor of rank 2.
*
- * @param shape_function Number of the shape function to be
- * evaluated. Note that this number runs from zero to dofs_per_cell, even
- * in the case of an FEFaceValues or FESubfaceValues object.
+ * @param shape_function Number of the shape function to be evaluated.
+ * Note that this number runs from zero to dofs_per_cell, even in the case
+ * of an FEFaceValues or FESubfaceValues object.
*
* @param q_point Number of the quadrature point at which function is to
* be evaluated.
/**
* Return the value of the vector components selected by this view, for
- * the shape function and quadrature point selected by the
- * arguments. Here, since the view represents a vector-valued part of the
- * FEValues object with <code>(dim*dim)</code> components (the unique
- * components of a second-order tensor), the return type is a tensor of
- * rank 2.
+ * the shape function and quadrature point selected by the arguments.
+ * Here, since the view represents a vector-valued part of the FEValues
+ * object with <code>(dim*dim)</code> components (the unique components of
+ * a second-order tensor), the return type is a tensor of rank 2.
*
- * @param shape_function Number of the shape function to be
- * evaluated. Note that this number runs from zero to dofs_per_cell, even
- * in the case of an FEFaceValues or FESubfaceValues object.
+ * @param shape_function Number of the shape function to be evaluated.
+ * Note that this number runs from zero to dofs_per_cell, even in the case
+ * of an FEFaceValues or FESubfaceValues object.
*
* @param q_point Number of the quadrature point at which function is to
* be evaluated.
std::vector<Tensor<1,spacedim> > boundary_forms;
/**
- * When asked for the value (or gradient, or Hessian) of shape function i's
- * c-th vector component, we need to look it up in the #shape_values,
- * #shape_gradients and #shape_hessians arrays. The question is where in
- * this array does the data for shape function i, component c reside. This is
- * what this table answers.
- *
- * The format of the table is as
- * follows:
- * - It has dofs_per_cell times
- * n_components entries.
- * - The entry that corresponds to
- * shape function i, component c
- * is <code>i * n_components + c</code>.
- * - The value stored at this
- * position indicates the row
- * in #shape_values and the
- * other tables where the
- * corresponding datum is stored
- * for all the quadrature points.
- *
- * In the general, vector-valued context, the number of components is larger
- * than one, but for a given shape function, not all vector components may be
- * nonzero (e.g., if a shape function is primitive, then exactly one vector
- * component is non-zero, while the others are all zero). For such zero
- * components, #shape_values and friends do not have a row. Consequently, for
- * vector components for which shape function i is zero, the entry in the
- * current table is numbers::invalid_unsigned_int.
- *
- * On the other hand, the table is guaranteed to have at least one valid
- * index for each shape function. In particular, for a primitive finite
- * element, each shape function has exactly one nonzero component and so for
- * each i, there is exactly one valid index within the range
- * <code>[i*n_components, (i+1)*n_components)</code>.
+ * When asked for the value (or gradient, or Hessian) of shape function i's
+ * c-th vector component, we need to look it up in the #shape_values,
+ * #shape_gradients and #shape_hessians arrays. The question is where in
+ * this array does the data for shape function i, component c reside. This
+ * is what this table answers.
+ *
+ * The format of the table is as follows: - It has dofs_per_cell times
+ * n_components entries. - The entry that corresponds to shape function i,
+ * component c is <code>i * n_components + c</code>. - The value stored at
+ * this position indicates the row in #shape_values and the other tables
+ * where the corresponding datum is stored for all the quadrature points.
+ *
+ * In the general, vector-valued context, the number of components is larger
+ * than one, but for a given shape function, not all vector components may
+ * be nonzero (e.g., if a shape function is primitive, then exactly one
+ * vector component is non-zero, while the others are all zero). For such
+ * zero components, #shape_values and friends do not have a row.
+ * Consequently, for vector components for which shape function i is zero,
+ * the entry in the current table is numbers::invalid_unsigned_int.
+ *
+ * On the other hand, the table is guaranteed to have at least one valid
+ * index for each shape function. In particular, for a primitive finite
+ * element, each shape function has exactly one nonzero component and so for
+ * each i, there is exactly one valid index within the range
+ * <code>[i*n_components, (i+1)*n_components)</code>.
*/
std::vector<unsigned int> shape_function_to_row_table;
* the same as defined by the quadrature formula passed to the constructor of
* the FEValues object above.
*
- * <h3>Member functions</h3>
+ * <h3>Member functions</h3>
*
- * The functions of this class fall into different cathegories:
- * <ul>
- * <li> shape_value(), shape_grad(), etc: return one of the values
- * of this object at a time. These functions are inlined, so this
- * is the suggested access to all finite element values. There
- * should be no loss in performance with an optimizing compiler. If
- * the finite element is vector valued, then these functions return
- * the only non-zero component of the requested shape
- * function. However, some finite elements have shape functions
- * that have more than one non-zero component (we call them
- * non-"primitive"), and in this case this set of functions will
- * throw an exception since they cannot generate a useful
- * result. Rather, use the next set of functions.
+ * The functions of this class fall into different cathegories:
+ * <ul>
+ * <li> shape_value(), shape_grad(), etc: return one of the values of this
+ * object at a time. These functions are inlined, so this is the suggested
+ * access to all finite element values. There should be no loss in performance
+ * with an optimizing compiler. If the finite element is vector valued, then
+ * these functions return the only non-zero component of the requested shape
+ * function. However, some finite elements have shape functions that have more
+ * than one non-zero component (we call them non-"primitive"), and in this
+ * case this set of functions will throw an exception since they cannot
+ * generate a useful result. Rather, use the next set of functions.
*
- * <li> shape_value_component(), shape_grad_component(), etc:
- * This is the same set of functions as above, except that for vector
- * valued finite elements they return only one vector component. This
- * is useful for elements of which shape functions have more than one
- * non-zero component, since then the above functions cannot be used,
- * and you have to walk over all (or only the non-zero) components of
- * the shape function using this set of functions.
+ * <li> shape_value_component(), shape_grad_component(), etc: This is the same
+ * set of functions as above, except that for vector valued finite elements
+ * they return only one vector component. This is useful for elements of which
+ * shape functions have more than one non-zero component, since then the above
+ * functions cannot be used, and you have to walk over all (or only the non-
+ * zero) components of the shape function using this set of functions.
*
- * <li> get_function_values(), get_function_gradients(), etc.: Compute a
- * finite element function or its derivative in quadrature points.
+ * <li> get_function_values(), get_function_gradients(), etc.: Compute a
+ * finite element function or its derivative in quadrature points.
*
- * <li> reinit: initialize the FEValues object for a certain cell.
- * This function is not in the present class but only in the derived
- * classes and has a variable call syntax.
- * See the docs for the derived classes for more information.
+ * <li> reinit: initialize the FEValues object for a certain cell. This
+ * function is not in the present class but only in the derived classes and
+ * has a variable call syntax. See the docs for the derived classes for more
+ * information.
* </ul>
*
*
* subface selected the last time the <tt>reinit</tt> function of the
* derived class was called.
*
- * If the shape function is vector-valued, then this returns the only
- * non-zero component. If the shape function has more than one non-zero
+ * If the shape function is vector-valued, then this returns the only non-
+ * zero component. If the shape function has more than one non-zero
* component (i.e. it is not primitive), then throw an exception of type
* ExcShapeFunctionNotPrimitive. In that case, use the
* shape_value_component() function.
* reference to the gradient's value is returned, there should be no major
* performance drawback.
*
- * If the shape function is vector-valued, then this returns the only
- * non-zero component. If the shape function has more than one non-zero
+ * If the shape function is vector-valued, then this returns the only non-
+ * zero component. If the shape function has more than one non-zero
* component (i.e. it is not primitive), then it will throw an exception of
* type ExcShapeFunctionNotPrimitive. In that case, use the
* shape_grad_component() function.
* one component. Since only a reference to the derivative values is
* returned, there should be no major performance drawback.
*
- * If the shape function is vector-valued, then this returns the only
- * non-zero component. If the shape function has more than one non-zero
+ * If the shape function is vector-valued, then this returns the only non-
+ * zero component. If the shape function has more than one non-zero
* component (i.e. it is not primitive), then throw an exception of type
* ExcShapeFunctionNotPrimitive. In that case, use the
* shape_grad_grad_component() function.
* current cell and point values are computed from that.
*
* This function may only be used if the finite element in use is a scalar
- * one, i.e. has only one vector component. To get values of
- * multi-component elements, there is another get_function_values() below,
+ * one, i.e. has only one vector component. To get values of multi-
+ * component elements, there is another get_function_values() below,
* returning a vector of vectors of results.
*
* @param[in] fe_function A vector of values that describes (globally) the
* is assume to already have the correct size.
*
* @post <code>gradients[q]</code> will contain the gradient of the field
- * described by fe_function at the $q$th quadrature
- * point. <code>gradients[q][d]</code> represents the derivative in
- * coordinate direction $d$ at quadrature point $q$.
+ * described by fe_function at the $q$th quadrature point.
+ * <code>gradients[q][d]</code> represents the derivative in coordinate
+ * direction $d$ at quadrature point $q$.
*
* @note The actual data type of the input vector may be either a
* Vector<T>, BlockVector<T>, or one of the sequential PETSc or
* is assume to already have the correct size.
*
* @post <code>hessians[q]</code> will contain the Hessian of the field
- * described by fe_function at the $q$th quadrature
- * point. <code>hessians[q][i][j]</code> represents the $(i,j)$th component
- * of the matrix of second derivatives at quadrature point $q$.
+ * described by fe_function at the $q$th quadrature point.
+ * <code>hessians[q][i][j]</code> represents the $(i,j)$th component of the
+ * matrix of second derivatives at quadrature point $q$.
*
* @note The actual data type of the input vector may be either a
* Vector<T>, BlockVector<T>, or one of the sequential PETSc or
* is assume to already have the correct size.
*
* @post <code>laplacians[q]</code> will contain the Laplacian of the field
- * described by fe_function at the $q$th quadrature
- * point. <code>gradients[q][i][j]</code> represents the $(i,j)$th component
- * of the matrix of second derivatives at quadrature point $q$.
+ * described by fe_function at the $q$th quadrature point.
+ * <code>gradients[q][i][j]</code> represents the $(i,j)$th component of the
+ * matrix of second derivatives at quadrature point $q$.
*
* @post For each component of the output vector, there holds
* <code>laplacians[q]=trace(hessians[q])</code>, where <tt>hessians</tt>
const DerivativeForm<1,dim,spacedim> &jacobian (const unsigned int quadrature_point) const;
/**
- * Return a reference to the array holding the values returned by jacobian().
+ * Return a reference to the array holding the values returned by
+ * jacobian().
*
* @dealiiRequiresUpdateFlags{update_jacobians}
*/
const DerivativeForm<2,dim,spacedim> &jacobian_grad (const unsigned int quadrature_point) const;
/**
- * Return a reference to the array holding the values returned by jacobian_grads().
+ * Return a reference to the array holding the values returned by
+ * jacobian_grads().
*
* @dealiiRequiresUpdateFlags{update_jacobian_grads}
*/
const DerivativeForm<1,spacedim,dim> &inverse_jacobian (const unsigned int quadrature_point) const;
/**
- * Return a reference to the array holding the values returned by inverse_jacobian().
+ * Return a reference to the array holding the values returned by
+ * inverse_jacobian().
*
* @dealiiRequiresUpdateFlags{update_inverse_jacobians}
*/
* See FEValuesBase
*
* @ingroup feaccess
- * @author Wolfgang Bangerth, 1998, Guido Kanschat, 2000, 2001
+ * @author Wolfgang Bangerth, 1998, Guido Kanschat, 2000, 2001
*/
template <int dim, int spacedim=dim>
class FEFaceValuesBase : public FEValuesBase<dim,spacedim>
namespace
{
/**
- * Return the symmetrized version of a
- * tensor whose n'th row equals the
- * second argument, with all other rows
- * equal to zero.
+ * Return the symmetrized version of a tensor whose n'th row equals the
+ * second argument, with all other rows equal to zero.
*/
inline
dealii::SymmetricTensor<2,1>
namespace FEValuesExtractors
{
/**
- * Extractor for a single scalar component
- * of a vector-valued element. The result
- * of applying an object of this type to an
- * FEValues, FEFaceValues or
- * FESubfaceValues object is of type
- * FEValuesViews::Scalar. The concept of
- * extractors is defined in the
- * documentation of the namespace
- * FEValuesExtractors and in the @ref
- * vector_valued module.
+ * Extractor for a single scalar component of a vector-valued element. The
+ * result of applying an object of this type to an FEValues, FEFaceValues or
+ * FESubfaceValues object is of type FEValuesViews::Scalar. The concept of
+ * extractors is defined in the documentation of the namespace
+ * FEValuesExtractors and in the @ref vector_valued module.
*
* @ingroup feaccess vector_valued
*/
struct Scalar
{
/**
- * The selected scalar component of the
- * vector.
+ * The selected scalar component of the vector.
*/
unsigned int component;
/**
- * Default constructor. Initialize the
- * object with an invalid component. This leads to
- * an object that can not be used, but it allows
- * objects of this kind to be put into arrays that
- * require a default constructor upon resizing the
- * array, and then later assigning a suitable
- * object to each element of the array.
+ * Default constructor. Initialize the object with an invalid component.
+ * This leads to an object that can not be used, but it allows objects of
+ * this kind to be put into arrays that require a default constructor upon
+ * resizing the array, and then later assigning a suitable object to each
+ * element of the array.
*/
Scalar ();
/**
- * Constructor. Take the selected
- * vector component as argument.
+ * Constructor. Take the selected vector component as argument.
*/
Scalar (const unsigned int component);
};
/**
- * Extractor for a vector of
- * <code>spacedim</code> components of a
- * vector-valued element. The value of
- * <code>spacedim</code> is defined by the
- * FEValues object the extractor is applied
- * to. The result of applying an object of
- * this type to an FEValues, FEFaceValues
- * or FESubfaceValues object is of type
- * FEValuesViews::Vector.
+ * Extractor for a vector of <code>spacedim</code> components of a vector-
+ * valued element. The value of <code>spacedim</code> is defined by the
+ * FEValues object the extractor is applied to. The result of applying an
+ * object of this type to an FEValues, FEFaceValues or FESubfaceValues
+ * object is of type FEValuesViews::Vector.
*
- * The concept of
- * extractors is defined in the
- * documentation of the namespace
- * FEValuesExtractors and in the @ref
- * vector_valued module.
+ * The concept of extractors is defined in the documentation of the
+ * namespace FEValuesExtractors and in the @ref vector_valued module.
*
- * Note that in the current context, a
- * vector is meant in the sense physics
- * uses it: it has <code>spacedim</code>
- * components that behave in specific ways
- * under coordinate system
- * transformations. Examples include
- * velocity or displacement fields. This is
- * opposed to how mathematics uses the word
- * "vector" (and how we use this word in
- * other contexts in the library, for
- * example in the Vector class), where it
- * really stands for a collection of
- * numbers. An example of this latter use
- * of the word could be the set of
- * concentrations of chemical species in a
- * flame; however, these are really just a
- * collection of scalar variables, since
- * they do not change if the coordinate
- * system is rotated, unlike the components
- * of a velocity vector, and consequently,
- * this class should not be used for this
- * context.
+ * Note that in the current context, a vector is meant in the sense physics
+ * uses it: it has <code>spacedim</code> components that behave in specific
+ * ways under coordinate system transformations. Examples include velocity
+ * or displacement fields. This is opposed to how mathematics uses the word
+ * "vector" (and how we use this word in other contexts in the library, for
+ * example in the Vector class), where it really stands for a collection of
+ * numbers. An example of this latter use of the word could be the set of
+ * concentrations of chemical species in a flame; however, these are really
+ * just a collection of scalar variables, since they do not change if the
+ * coordinate system is rotated, unlike the components of a velocity vector,
+ * and consequently, this class should not be used for this context.
*
* @ingroup feaccess vector_valued
*/
struct Vector
{
/**
- * The first component of the vector
- * view.
+ * The first component of the vector view.
*/
unsigned int first_vector_component;
/**
- * Default constructor. Initialize the
- * object with an invalid component. This leads to
- * an object that can not be used, but it allows
- * objects of this kind to be put into arrays that
- * require a default constructor upon resizing the
- * array, and then later assigning a suitable
- * object to each element of the array.
+ * Default constructor. Initialize the object with an invalid component.
+ * This leads to an object that can not be used, but it allows objects of
+ * this kind to be put into arrays that require a default constructor upon
+ * resizing the array, and then later assigning a suitable object to each
+ * element of the array.
*/
Vector ();
/**
- * Constructor. Take the first
- * component of the selected vector
- * inside the FEValues object as
- * argument.
+ * Constructor. Take the first component of the selected vector inside the
+ * FEValues object as argument.
*/
Vector (const unsigned int first_vector_component);
};
/**
- * Extractor for a symmetric tensor of a
- * rank specified by the template
- * argument. For a second order symmetric
- * tensor, this represents a collection of
- * <code>(dim*dim + dim)/2</code>
- * components of a vector-valued
- * element. The value of <code>dim</code>
- * is defined by the FEValues object the
- * extractor is applied to. The result of
- * applying an object of this type to an
- * FEValues, FEFaceValues or
- * FESubfaceValues object is of type
- * FEValuesViews::SymmetricTensor.
+ * Extractor for a symmetric tensor of a rank specified by the template
+ * argument. For a second order symmetric tensor, this represents a
+ * collection of <code>(dim*dim + dim)/2</code> components of a vector-
+ * valued element. The value of <code>dim</code> is defined by the FEValues
+ * object the extractor is applied to. The result of applying an object of
+ * this type to an FEValues, FEFaceValues or FESubfaceValues object is of
+ * type FEValuesViews::SymmetricTensor.
*
- * The concept of
- * extractors is defined in the
- * documentation of the namespace
- * FEValuesExtractors and in the @ref
- * vector_valued module.
+ * The concept of extractors is defined in the documentation of the
+ * namespace FEValuesExtractors and in the @ref vector_valued module.
*
* @ingroup feaccess vector_valued
*
struct SymmetricTensor
{
/**
- * The first component of the tensor
- * view.
+ * The first component of the tensor view.
*/
unsigned int first_tensor_component;
/**
- * Default constructor. Initialize the
- * object with an invalid component. This leads to
- * an object that can not be used, but it allows
- * objects of this kind to be put into arrays that
- * require a default constructor upon resizing the
- * array, and then later assigning a suitable
- * object to each element of the array.
+ * Default constructor. Initialize the object with an invalid component.
+ * This leads to an object that can not be used, but it allows objects of
+ * this kind to be put into arrays that require a default constructor upon
+ * resizing the array, and then later assigning a suitable object to each
+ * element of the array.
*/
SymmetricTensor ();
/**
- * Constructor. Take the first
- * component of the selected tensor
- * inside the FEValues object as
- * argument.
+ * Constructor. Take the first component of the selected tensor inside the
+ * FEValues object as argument.
*/
SymmetricTensor (const unsigned int first_tensor_component);
};
/**
- * Extractor for a (possible non-)symmetric tensor of a
- * rank specified by the template
- * argument. For a second order
- * tensor, this represents a collection of
- * <code>(dim*dim)</code>
- * components of a vector-valued
- * element. The value of <code>dim</code>
- * is defined by the FEValues object the
- * extractor is applied to. The result of
- * applying an object of this type to an
- * FEValues, FEFaceValues or
- * FESubfaceValues object is of type
+ * Extractor for a (possible non-)symmetric tensor of a rank specified by
+ * the template argument. For a second order tensor, this represents a
+ * collection of <code>(dim*dim)</code> components of a vector-valued
+ * element. The value of <code>dim</code> is defined by the FEValues object
+ * the extractor is applied to. The result of applying an object of this
+ * type to an FEValues, FEFaceValues or FESubfaceValues object is of type
* FEValuesViews::Tensor.
*
- * The concept of
- * extractors is defined in the
- * documentation of the namespace
- * FEValuesExtractors and in the @ref
- * vector_valued module.
+ * The concept of extractors is defined in the documentation of the
+ * namespace FEValuesExtractors and in the @ref vector_valued module.
*
* @ingroup feaccess vector_valued
*
struct Tensor
{
/**
- * The first component of the tensor
- * view.
+ * The first component of the tensor view.
*/
unsigned int first_tensor_component;
/**
- * Default constructor. Initialize the
- * object with an invalid component. This leads to
- * an object that can not be used, but it allows
- * objects of this kind to be put into arrays that
- * require a default constructor upon resizing the
- * array, and then later assigning a suitable
- * object to each element of the array.
+ * Default constructor. Initialize the object with an invalid component.
+ * This leads to an object that can not be used, but it allows objects of
+ * this kind to be put into arrays that require a default constructor upon
+ * resizing the array, and then later assigning a suitable object to each
+ * element of the array.
*/
Tensor ();
/**
- * Constructor. Take the first
- * component of the selected tensor
- * inside the FEValues object as
- * argument.
+ * Constructor. Take the first component of the selected tensor inside the
+ * FEValues object as argument.
*/
Tensor (const unsigned int first_tensor_component);
};
template <int dim, int spacedim> class FESubfaceValues;
/**
- * The transformation type used
- * for the Mapping::transform() functions.
+ * The transformation type used for the Mapping::transform() functions.
*
- * Special finite elements may
- * need special Mapping from the
- * reference cell to the actual
- * mesh cell. In order to be most
- * flexible, this enum provides
- * an extensible interface for
- * arbitrary
- * transformations. Nevertheless,
- * these must be implemented in
- * the transform() functions of
- * inheriting classes in order to
- * work.
+ * Special finite elements may need special Mapping from the reference cell to
+ * the actual mesh cell. In order to be most flexible, this enum provides an
+ * extensible interface for arbitrary transformations. Nevertheless, these
+ * must be implemented in the transform() functions of inheriting classes in
+ * order to work.
*
* @ingroup mapping
*/
/// Mapping of the gradient of a contravariant vector field (see Mapping::transform() for details)
mapping_contravariant_gradient = 0x0004,
/**
- * The Piola transform usually used for Hdiv elements.
- * Piola transform is the
- * standard transformation of
- * vector valued elements in
- * H<sup>div</sup>. It amounts
- * to a contravariant
- * transformation scaled by the
- * inverse of the volume
- * element.
+ * The Piola transform usually used for Hdiv elements. Piola transform is
+ * the standard transformation of vector valued elements in H<sup>div</sup>.
+ * It amounts to a contravariant transformation scaled by the inverse of the
+ * volume element.
*/
mapping_piola = 0x0100,
/**
- transformation for the gradient of a vector field corresponding to a
- mapping_piola transformation (see Mapping::transform() for details).
- */
+ * transformation for the gradient of a vector field corresponding to a
+ * mapping_piola transformation (see Mapping::transform() for details).
+ */
mapping_piola_gradient = 0x0101,
/// The mapping used for Nedelec elements
/**
- * curl-conforming elements are
- * mapped as covariant
- * vectors. Nevertheless, we
- * introduce a separate mapping
- * type, such that we can use
- * the same flag for the vector
- * and its gradient (see Mapping::transform() for details).
+ * curl-conforming elements are mapped as covariant vectors. Nevertheless,
+ * we introduce a separate mapping type, such that we can use the same flag
+ * for the vector and its gradient (see Mapping::transform() for details).
*/
mapping_nedelec = 0x0200,
/// The mapping used for Raviart-Thomas elements
/**
* Abstract base class for mapping classes.
*
- * The interface for filling the tables of FEValues is provided.
- * Everything else has to happen in derived classes.
+ * The interface for filling the tables of FEValues is provided. Everything
+ * else has to happen in derived classes.
*
- * The following paragraph applies to the implementation of
- * FEValues. Usage of the class is as follows: first, call the
- * functions @p update_once and @p update_each with the update
- * flags you need. This includes the flags needed by the
- * FiniteElement. Then call <tt>get_*_data</tt> and with the or'd
- * results. This will initialize and return some internal data
- * structures. On the first cell, call <tt>fill_fe_*_values</tt> with the
- * result of @p update_once. Finally, on each cell, use
- * <tt>fill_fe_*_values</tt> with the result of @p update_each to compute
- * values for a special cell.
+ * The following paragraph applies to the implementation of FEValues. Usage of
+ * the class is as follows: first, call the functions @p update_once and @p
+ * update_each with the update flags you need. This includes the flags needed
+ * by the FiniteElement. Then call <tt>get_*_data</tt> and with the or'd
+ * results. This will initialize and return some internal data structures.
+ * On the first cell, call <tt>fill_fe_*_values</tt> with the result of @p
+ * update_once. Finally, on each cell, use <tt>fill_fe_*_values</tt> with the
+ * result of @p update_each to compute values for a special cell.
*
* <h3>Mathematics of the mapping</h3>
*
- * The mapping is a transformation $\mathbf x = \Phi(\mathbf{\hat x})$
- * which maps the reference cell [0,1]<sup>dim</sup> to the actual
- * grid cell in R<sup>spacedim</sup>.
- * In order to describe the application of the mapping to
- * different objects, we introduce the notation for the Jacobian
- * $J(\mathbf{\hat x}) = \nabla\Phi(\mathbf{\hat x})$. For instance,
- * if dim=spacedim=2, we have
+ * The mapping is a transformation $\mathbf x = \Phi(\mathbf{\hat x})$ which
+ * maps the reference cell [0,1]<sup>dim</sup> to the actual grid cell in
+ * R<sup>spacedim</sup>. In order to describe the application of the mapping
+ * to different objects, we introduce the notation for the Jacobian
+ * $J(\mathbf{\hat x}) = \nabla\Phi(\mathbf{\hat x})$. For instance, if
+ * dim=spacedim=2, we have
* @f[
* J(\mathbf{\hat x}) = \left(\begin{matrix}
* \frac{\partial x}{\partial \hat x} & \frac{\partial x}{\partial \hat y}
* u(\mathbf x) = u\bigl(\Phi(\mathbf{\hat x})\bigr)
* = \hat u(\mathbf{\hat x}).
* @f]
- * Since finite element shape functions are usually defined on the
- * reference cell, nothing needs to be done for them. For a function
- * defined on the computational domain, the quadrature points need to
- * be mapped, which is done in fill_fe_values() if
- * @p update_quadrature_points is set in the update flags. The mapped
- * quadrature points are then accessed through FEValuesBase::quadrature_point().
+ * Since finite element shape functions are usually defined on the reference
+ * cell, nothing needs to be done for them. For a function defined on the
+ * computational domain, the quadrature points need to be mapped, which is
+ * done in fill_fe_values() if @p update_quadrature_points is set in the
+ * update flags. The mapped quadrature points are then accessed through
+ * FEValuesBase::quadrature_point().
*
* @todo Add a function <tt>transform_quadrature_points</tt> for this.
*
* @f]
*
* The transformed quadrature weights $\left|\text{det}J(\mathbf{\hat
- * x})\right|$ are accessed through FEValuesBase::JxW() and
- * computed in fill_fe_values(), if @p update_JxW_values is set in the
- * update flags.
+ * x})\right|$ are accessed through FEValuesBase::JxW() and computed in
+ * fill_fe_values(), if @p update_JxW_values is set in the update flags.
*
- * @todo Add a function <tt>transform_quadrature_weights</tt> for
- * this.
+ * @todo Add a function <tt>transform_quadrature_weights</tt> for this.
*
* @todo Add documentation on the codimension-one case
*
- * <h4>Mapping of vector fields, differential forms and gradients of vector fields</h4>
+ * <h4>Mapping of vector fields, differential forms and gradients of vector
+ * fields</h4>
*
- * The transfomation of vector fields, differential forms (gradients/jacobians) and
- * gradients of vector fields between the reference cell and the actual grid cell
- * follows the general form
+ * The transfomation of vector fields, differential forms
+ * (gradients/jacobians) and gradients of vector fields between the reference
+ * cell and the actual grid cell follows the general form
*
* @f[
* \mathbf v(\mathbf x) = \mathbf A(\mathbf{\hat x})
* \mathbf{\hat T}(\mathbf{\hat x}) \mathbf B(\mathbf{\hat x}),
* @f]
*
- * where <b>v</b> is a vector field or a differential form and
- * and <b>T</b> a tensor field of gradients.
- * The differential forms <b>A</b> and <b>B</b> are
- * determined by the MappingType enumerator.
- * These transformations are performed through the functions
- * transform(). See the documentation there for possible
- * choices.
+ * where <b>v</b> is a vector field or a differential form and and <b>T</b> a
+ * tensor field of gradients. The differential forms <b>A</b> and <b>B</b> are
+ * determined by the MappingType enumerator. These transformations are
+ * performed through the functions transform(). See the documentation there
+ * for possible choices.
*
* <h3>Technical notes</h3>
*
- * A hint to implementators: no function except the two functions
- * @p update_once and @p update_each may add any flags.
+ * A hint to implementators: no function except the two functions @p
+ * update_once and @p update_each may add any flags.
*
- * For more information about the <tt>spacedim</tt> template parameter
- * check the documentation of FiniteElement or the one of
- * Triangulation.
+ * For more information about the <tt>spacedim</tt> template parameter check
+ * the documentation of FiniteElement or the one of Triangulation.
*
* <h3>References</h3>
*
- * A general publication on differential geometry and finite elements
- * is the survey
+ * A general publication on differential geometry and finite elements is the
+ * survey
* <ul>
- * <li>Douglas N. Arnold, Richard S. Falk, and
- * Ragnar Winther. <i>Finite element exterior calculus: from
- * Hodge theory to numerical stability.</i>
+ * <li>Douglas N. Arnold, Richard S. Falk, and Ragnar Winther. <i>Finite
+ * element exterior calculus: from Hodge theory to numerical stability.</i>
* Bull. Amer. Math. Soc. (N.S.), 47:281-354, 2010. <a
* href="http://dx.doi.org/10.1090/S0273-0979-10-01278-4">DOI:
* 10.1090/S0273-0979-10-01278-4</a>.
* </ul>
*
* The description of the Piola transform has been taken from the <a
- * href="http://www.math.uh.edu/~rohop/spring_05/downloads/">lecture
- * notes</a> by Ronald H. W. Hoppe, University of Houston, Chapter 7.
+ * href="http://www.math.uh.edu/~rohop/spring_05/downloads/">lecture notes</a>
+ * by Ronald H. W. Hoppe, University of Houston, Chapter 7.
*
* @ingroup mapping
* @author Guido Kanschat, Ralf Hartmann 2000, 2001
virtual ~Mapping ();
/**
- * Transforms the point @p p on
- * the unit cell to the point
- * @p p_real on the real cell
- * @p cell and returns @p p_real.
+ * Transforms the point @p p on the unit cell to the point @p p_real on the
+ * real cell @p cell and returns @p p_real.
*/
virtual Point<spacedim>
transform_unit_to_real_cell (
const Point<dim> &p) const = 0;
/**
- * Transforms the point @p p on
- * the real @p cell to the corresponding
- * point on the unit cell, and
- * return its coordinates.
+ * Transforms the point @p p on the real @p cell to the corresponding point
+ * on the unit cell, and return its coordinates.
*
- * In the codimension one case,
- * this function returns the
- * normal projection of the real
- * point @p p on the curve or
- * surface identified by the @p
- * cell.
+ * In the codimension one case, this function returns the normal projection
+ * of the real point @p p on the curve or surface identified by the @p cell.
*
- * @note Polynomial mappings from
- * the reference (unit) cell coordinates
- * to the coordinate system of a real
- * cell are not always invertible if
- * the point for which the inverse
- * mapping is to be computed lies
- * outside the cell's boundaries.
- * In such cases, the current function
- * may fail to compute a point on
- * the reference cell whose image
- * under the mapping equals the given
- * point @p p. If this is the case
- * then this function throws an
- * exception of type
- * Mapping::ExcTransformationFailed .
- * Whether the given point @p p lies
- * outside the cell can therefore be
- * determined by checking whether the
- * return reference coordinates lie
- * inside of outside the reference
- * cell (e.g., using
- * GeometryInfo::is_inside_unit_cell)
- * or whether the exception mentioned
- * above has been thrown.
+ * @note Polynomial mappings from the reference (unit) cell coordinates to
+ * the coordinate system of a real cell are not always invertible if the
+ * point for which the inverse mapping is to be computed lies outside the
+ * cell's boundaries. In such cases, the current function may fail to
+ * compute a point on the reference cell whose image under the mapping
+ * equals the given point @p p. If this is the case then this function
+ * throws an exception of type Mapping::ExcTransformationFailed . Whether
+ * the given point @p p lies outside the cell can therefore be determined by
+ * checking whether the return reference coordinates lie inside of outside
+ * the reference cell (e.g., using GeometryInfo::is_inside_unit_cell) or
+ * whether the exception mentioned above has been thrown.
*/
virtual Point<dim>
transform_real_to_unit_cell (
const Point<spacedim> &p) const = 0;
/**
- * Base class for internal data
- * of finite element and mapping
- * objects. The internal
- * mechanism is that upon
- * construction of a @p FEValues
- * objects, it asks the mapping
- * and finite element classes
- * that are to be used to
- * allocate memory for their own
- * purpose in which they may
- * store data that only needs to
- * be computed once. For example,
- * most finite elements will
- * store the values of the shape
- * functions at the quadrature
- * points in this object, since
- * they do not change from cell
- * to cell and only need to be
- * computed once. Since different
- * @p FEValues objects using
- * different quadrature rules
- * might access the same finite
- * element object at the same
- * time, it is necessary to
- * create one such object per
- * @p FEValues object. Ownership
- * of this object is then
- * transferred to the
- * @p FEValues object, but a
- * pointer to this object is
- * passed to the finite element
- * object every time it shall
- * compute some data so that it
- * has access to the precomputed
+ * Base class for internal data of finite element and mapping objects. The
+ * internal mechanism is that upon construction of a @p FEValues objects, it
+ * asks the mapping and finite element classes that are to be used to
+ * allocate memory for their own purpose in which they may store data that
+ * only needs to be computed once. For example, most finite elements will
+ * store the values of the shape functions at the quadrature points in this
+ * object, since they do not change from cell to cell and only need to be
+ * computed once. Since different @p FEValues objects using different
+ * quadrature rules might access the same finite element object at the same
+ * time, it is necessary to create one such object per @p FEValues object.
+ * Ownership of this object is then transferred to the @p FEValues object,
+ * but a pointer to this object is passed to the finite element object every
+ * time it shall compute some data so that it has access to the precomputed
* values stored there.
*/
class InternalDataBase: public Subscriptor
public:
/**
- * Constructor. Sets
- * @p UpdateFlags to
- * @p update_default and
- * @p first_cell to @p true.
+ * Constructor. Sets @p UpdateFlags to @p update_default and @p first_cell
+ * to @p true.
*/
InternalDataBase ();
/**
- * Virtual destructor for
- * derived classes
+ * Virtual destructor for derived classes
*/
virtual ~InternalDataBase ();
/**
- * Values updated by the constructor or
- * by reinit.
+ * Values updated by the constructor or by reinit.
*/
UpdateFlags update_flags;
/**
- * Values computed by
- * constructor.
+ * Values computed by constructor.
*/
UpdateFlags update_once;
/**
- * Values updated on each
- * cell by reinit.
+ * Values updated on each cell by reinit.
*/
UpdateFlags update_each;
/**
- * If <tt>first_cell==true</tt>
- * this function returns
- * @p update_flags,
- * i.e. <tt>update_once|update_each</tt>.
- * If <tt>first_cell==false</tt>
- * it returns
- * @p update_each.
+ * If <tt>first_cell==true</tt> this function returns @p update_flags,
+ * i.e. <tt>update_once|update_each</tt>. If <tt>first_cell==false</tt> it
+ * returns @p update_each.
*/
UpdateFlags current_update_flags() const;
/**
- * Return whether we are
- * presently initializing
- * data for the first
- * cell. The value of the
- * field this function is
- * returning is set to
- * @p true in the
- * constructor, and cleared
- * by the @p FEValues class
- * after the first cell has
- * been initialized.
+ * Return whether we are presently initializing data for the first cell.
+ * The value of the field this function is returning is set to @p true in
+ * the constructor, and cleared by the @p FEValues class after the first
+ * cell has been initialized.
*
- * This function is used to
- * determine whether we need
- * to use the @p update_once
- * flags for computing data,
- * or whether we can use the
- * @p update_each flags.
+ * This function is used to determine whether we need to use the @p
+ * update_once flags for computing data, or whether we can use the @p
+ * update_each flags.
*/
bool is_first_cell () const;
/**
- * Set the @p first_cell
- * flag to @p false. Used by
- * the @p FEValues class to
- * indicate that we have
- * already done the work on
- * the first cell.
+ * Set the @p first_cell flag to @p false. Used by the @p FEValues class
+ * to indicate that we have already done the work on the first cell.
*/
virtual void clear_first_cell ();
/**
- * Return an estimate (in
- * bytes) or the memory
- * consumption of this
- * object.
+ * Return an estimate (in bytes) or the memory consumption of this object.
*/
virtual std::size_t memory_consumption () const;
/**
- * The determinant of the
- * Jacobian in each
- * quadrature point. Filled
- * if #update_volume_elements.
+ * The determinant of the Jacobian in each quadrature point. Filled if
+ * #update_volume_elements.
*/
std::vector<double> volume_elements;
/**
- * The positions of the
- * mapped (generalized)
- * support points.
+ * The positions of the mapped (generalized) support points.
*/
std::vector<Point<spacedim> > support_point_values;
private:
/**
- * The value returned by
- * @p is_first_cell.
+ * The value returned by @p is_first_cell.
*/
bool first_cell;
};
/**
- * Transform a field of vectors or 1-differential forms according to the selected
- * MappingType.
+ * Transform a field of vectors or 1-differential forms according to the
+ * selected MappingType.
*
- * @note Normally, this function is called by a finite element,
- * filling FEValues objects. For this finite element, there should be
- * an alias MappingType like @p mapping_bdm, @p mapping_nedelec, etc. This
- * alias should be preferred to using the types below.
+ * @note Normally, this function is called by a finite element, filling
+ * FEValues objects. For this finite element, there should be an alias
+ * MappingType like @p mapping_bdm, @p mapping_nedelec, etc. This alias
+ * should be preferred to using the types below.
*
* The mapping types currently implemented by derived classes are:
* <ul>
* \mathbf u(\mathbf x) = J(\mathbf{\hat x})\mathbf{\hat u}(\mathbf{\hat x}).
* @f]
* In physics, this is usually referred to as the contravariant
- * transformation. Mathematically, it is the push forward of a
- * vector field.
+ * transformation. Mathematically, it is the push forward of a vector field.
*
- * <li> @p mapping_covariant: maps a field of one-forms on the reference cell
- * to a field of one-forms on the physical cell.
- * (theoretically this would refer to a DerivativeForm<1, dim, 1> but it
- * canonically identified with a Tensor<1,dim>).
- * Mathematically, it is the pull back of the differential form
+ * <li> @p mapping_covariant: maps a field of one-forms on the reference
+ * cell to a field of one-forms on the physical cell. (theoretically this
+ * would refer to a DerivativeForm<1, dim, 1> but it canonically identified
+ * with a Tensor<1,dim>). Mathematically, it is the pull back of the
+ * differential form
* @f[
* \mathbf u(\mathbf x) = J(J^{T} J)^{-1}(\mathbf{\hat x})\mathbf{\hat
* u}(\mathbf{\hat x}).
* @f]
* Gradients of scalar differentiable functions are transformed this way.
*
- * <li> @p mapping_piola: A field of <i>n-1</i>-forms on the reference cell is also
- * represented by a vector field, but again transforms differently,
+ * <li> @p mapping_piola: A field of <i>n-1</i>-forms on the reference cell
+ * is also represented by a vector field, but again transforms differently,
* namely by the Piola transform
* @f[
* \mathbf u(\mathbf x) = \frac{1}{\text{det}J(\mathbf x)}
/**
- Transform a field of differential forms from the reference cell to the physical cell.
-
- It is useful to think of $\mathbf{T} = D \mathbf u$ and
- $\mathbf{\hat T} = \hat D \mathbf{\hat u}$, with $\mathbf u$ a vector field.
-
- The mapping types currently implemented by derived classes are:
- <ul>
- <li> @p mapping_covariant: maps a field of forms on the reference cell
- to a field of forms on the physical cell.
- Mathematically, it is the pull back of the differential form
- @f[
- \mathbf T(\mathbf x) = \mathbf{\hat T}(\mathbf{\hat x})
- J*(J^{T} J)^{-1}(\mathbf{\hat x}).
- @f]
- n the case when dim=spacedim the previous formula reduces to
- @f[
- \mathbf T(\mathbf x) = \mathbf{\hat u}(\mathbf{\hat x})
- J^{-1}(\mathbf{\hat x}).
- @f]
- Jacobians of spacedim-vector valued differentiable functions are transformed this way.
- </ul>
-
- @note It would have been more reasonable to make this transform a template function
- with the rank in <code>DerivativeForm@<1, dim, rank@></code>. Unfortunately C++ does not
- allow templatized virtual functions. This is why we identify
- <code>DerivativeForm@<1, dim, 1@></code> with a <code>Tensor@<1,dim@></code>
- when using mapping_covariant() in the function transform above this one.
- */
+ * Transform a field of differential forms from the reference cell to the
+ * physical cell. It is useful to think of $\mathbf{T} = D \mathbf u$ and
+ * $\mathbf{\hat T} = \hat D \mathbf{\hat u}$, with $\mathbf u$ a vector
+ * field. The mapping types currently implemented by derived classes are:
+ * <ul>
+ * <li> @p mapping_covariant: maps a field of forms on the reference cell to
+ * a field of forms on the physical cell. Mathematically, it is the pull
+ * back of the differential form
+ * @f[
+ * \mathbf T(\mathbf x) = \mathbf{\hat T}(\mathbf{\hat x})
+ * J*(J^{T} J)^{-1}(\mathbf{\hat x}).
+ * @f]
+ * n the case when dim=spacedim the previous formula reduces to
+ * @f[
+ * \mathbf T(\mathbf x) = \mathbf{\hat u}(\mathbf{\hat x})
+ * J^{-1}(\mathbf{\hat x}).
+ * @f]
+ * Jacobians of spacedim-vector valued differentiable functions are
+ * transformed this way.
+ * </ul>
+ * @note It would have been more reasonable to make this transform a
+ * template function with the rank in <code>DerivativeForm@<1, dim,
+ * rank@></code>. Unfortunately C++ does not allow templatized virtual
+ * functions. This is why we identify <code>DerivativeForm@<1, dim,
+ * 1@></code> with a <code>Tensor@<1,dim@></code> when using
+ * mapping_covariant() in the function transform above this one.
+ */
virtual
void
/**
- Transform a tensor field from the reference cell to the physical cell.
- This tensors are most of times the jacobians in the reference cell of
- vector fields that have been pulled back from the physical cell.
-
- The mapping types currently implemented by derived classes are:
- <ul>
-
- <li> @p mapping_contravariant_gradient, it
- assumes $\mathbf u(\mathbf x) = J \mathbf{\hat u}$ so that
- @f[
- \mathbf T(\mathbf x) =
- J(\mathbf{\hat x}) \mathbf{\hat T}(\mathbf{\hat x})
- J^{-1}(\mathbf{\hat x}).
- @f]
-
- <li> @p mapping_covariant_gradient, it
- assumes $\mathbf u(\mathbf x) = J^{-T} \mathbf{\hat u}$ so that
- @f[
- \mathbf T(\mathbf x) =
- J^{-T}(\mathbf{\hat x}) \mathbf{\hat T}(\mathbf{\hat x})
- J^{-1}(\mathbf{\hat x}).
- @f]
-
- <li> @p mapping_piola_gradient, it
- assumes $\mathbf u(\mathbf x) = \frac{1}{\text{det}J(\mathbf x)}
- J(\mathbf x) \mathbf{\hat u}(\mathbf x)$
- so that
- @f[
- \mathbf T(\mathbf x) =
- \frac{1}{\text{det}J(\mathbf x)}
- J(\mathbf{\hat x}) \mathbf{\hat T}(\mathbf{\hat x})
- J^{-1}(\mathbf{\hat x}).
- @f]
- </ul>
-
- @todo The formulas for mapping_covariant_gradient(),
- mapping_contravariant_gradient() and mapping_piola_gradient()
- are only true as stated for linear mappings.
- If, for example, the mapping is bilinear then there is a missing
- term associated with the derivative of J.
- */
+ * Transform a tensor field from the reference cell to the physical cell.
+ * This tensors are most of times the jacobians in the reference cell of
+ * vector fields that have been pulled back from the physical cell. The
+ * mapping types currently implemented by derived classes are:
+ * <ul>
+ * <li> @p mapping_contravariant_gradient, it assumes $\mathbf u(\mathbf x)
+ * = J \mathbf{\hat u}$ so that
+ * @f[
+ * \mathbf T(\mathbf x) =
+ * J(\mathbf{\hat x}) \mathbf{\hat T}(\mathbf{\hat x})
+ * J^{-1}(\mathbf{\hat x}).
+ * @f]
+ * <li> @p mapping_covariant_gradient, it assumes $\mathbf u(\mathbf x) =
+ * J^{-T} \mathbf{\hat u}$ so that
+ * @f[
+ * \mathbf T(\mathbf x) =
+ * J^{-T}(\mathbf{\hat x}) \mathbf{\hat T}(\mathbf{\hat x})
+ * J^{-1}(\mathbf{\hat x}).
+ * @f]
+ * <li> @p mapping_piola_gradient, it assumes $\mathbf u(\mathbf x) =
+ * \frac{1}{\text{det}J(\mathbf x)} J(\mathbf x) \mathbf{\hat u}(\mathbf x)$
+ * so that
+ * @f[
+ * \mathbf T(\mathbf x) =
+ * \frac{1}{\text{det}J(\mathbf x)}
+ * J(\mathbf{\hat x}) \mathbf{\hat T}(\mathbf{\hat x})
+ * J^{-1}(\mathbf{\hat x}).
+ * @f]
+ * </ul>
+ * @todo The formulas for mapping_covariant_gradient(),
+ * mapping_contravariant_gradient() and mapping_piola_gradient() are only
+ * true as stated for linear mappings. If, for example, the mapping is
+ * bilinear then there is a missing term associated with the derivative of
+ * J.
+ */
virtual
void
transform (const VectorSlice<const std::vector<Tensor<2, dim> > > input,
const typename Mapping<dim,spacedim>::InternalDataBase &internal) const DEAL_II_DEPRECATED;
/**
- * The transformed (generalized)
- * support point.
+ * The transformed (generalized) support point.
*/
const Point<spacedim> &support_point_value(
const unsigned int index,
const typename Mapping<dim,spacedim>::InternalDataBase &internal) const;
/**
- * The Jacobian
- * matrix of the transformation
- * in the (generalized) support
+ * The Jacobian matrix of the transformation in the (generalized) support
* point.
*/
const Tensor<2,spacedim> &support_point_gradient(
const typename Mapping<dim,spacedim>::InternalDataBase &internal) const;
/**
- * The inverse Jacobian
- * matrix of the transformation
- * in the (generalized) support
- * point.
+ * The inverse Jacobian matrix of the transformation in the (generalized)
+ * support point.
*/
const Tensor<2,spacedim> &support_point_inverse_gradient(
const unsigned int index,
const typename Mapping<dim,spacedim>::InternalDataBase &internal) const;
/**
- * Return a pointer to a copy of the
- * present object. The caller of this
- * copy then assumes ownership of it.
+ * Return a pointer to a copy of the present object. The caller of this copy
+ * then assumes ownership of it.
*
- * Since one can't create
- * objects of class Mapping, this
- * function of course has to be
- * implemented by derived classes.
+ * Since one can't create objects of class Mapping, this function of course
+ * has to be implemented by derived classes.
*
- * This function is mainly used by the
- * hp::MappingCollection class.
+ * This function is mainly used by the hp::MappingCollection class.
*/
virtual
Mapping<dim,spacedim> *clone () const = 0;
/**
- * Returns whether the mapping preserves
- * vertex locations, i.e. whether the
- * mapped location of the reference cell
- * vertices (given by
- * GeometryInfo::unit_cell_vertex())
- * equals the result of
+ * Returns whether the mapping preserves vertex locations, i.e. whether the
+ * mapped location of the reference cell vertices (given by
+ * GeometryInfo::unit_cell_vertex()) equals the result of
* <code>cell-@>vertex()</code>.
*
- * For example, implementations in
- * derived classes return @p true for
- * MappingQ, MappingQ1, MappingCartesian,
- * but @p false for MappingQEulerian,
+ * For example, implementations in derived classes return @p true for
+ * MappingQ, MappingQ1, MappingCartesian, but @p false for MappingQEulerian,
* MappingQ1Eulerian.
*/
virtual
/**
- * Computing the mapping between a
- * real space point and a point
- * in reference space failed, typically because the given point
- * lies outside the cell where the inverse mapping is not
- * unique.
+ * Computing the mapping between a real space point and a point in reference
+ * space failed, typically because the given point lies outside the cell
+ * where the inverse mapping is not unique.
*
* @ingroup Exceptions
*/
private:
/**
- * Indicate fields to be updated
- * in the constructor of
- * FEValues. Especially,
- * fields not asked for by
- * FEValues, but computed
- * for efficiency reasons will be
- * notified here.
+ * Indicate fields to be updated in the constructor of FEValues. Especially,
+ * fields not asked for by FEValues, but computed for efficiency reasons
+ * will be notified here.
*
* See @ref UpdateFlagsEssay.
*/
virtual UpdateFlags update_once (const UpdateFlags) const = 0;
/**
- * The same as update_once(),
- * but for the flags to be updated for
- * each grid cell.
+ * The same as update_once(), but for the flags to be updated for each grid
+ * cell.
*
* See @ref UpdateFlagsEssay.
*/
virtual UpdateFlags update_each (const UpdateFlags) const = 0;
/**
- * Prepare internal data
- * structures and fill in values
- * independent of the cell.
+ * Prepare internal data structures and fill in values independent of the
+ * cell.
*/
virtual InternalDataBase *
get_data (const UpdateFlags,
const Quadrature<dim> &quadrature) const = 0;
/**
- * Prepare internal data
- * structure for transformation
- * of faces and fill in values
- * independent of the cell.
+ * Prepare internal data structure for transformation of faces and fill in
+ * values independent of the cell.
*/
virtual InternalDataBase *
get_face_data (const UpdateFlags flags,
const Quadrature<dim-1>& quadrature) const = 0;
/**
- * Prepare internal data
- * structure for transformation
- * of children of faces and fill
- * in values independent of the
- * cell.
+ * Prepare internal data structure for transformation of children of faces
+ * and fill in values independent of the cell.
*/
virtual InternalDataBase *
get_subface_data (const UpdateFlags flags,
/**
- * Fill the transformation fields
- * of @p FEValues. Given a grid
- * cell and the quadrature points
- * on the unit cell, it computes
- * all values specified by
- * @p flags. The arrays to be
- * filled have to have the
- * correct size.
+ * Fill the transformation fields of @p FEValues. Given a grid cell and the
+ * quadrature points on the unit cell, it computes all values specified by
+ * @p flags. The arrays to be filled have to have the correct size.
*
- * Values are split into two
- * groups: first,
- * @p quadrature_points and
- * @p JxW_values are
- * filled with the quadrature
- * rule transformed to the
- * cell in physical space.
+ * Values are split into two groups: first, @p quadrature_points and @p
+ * JxW_values are filled with the quadrature rule transformed to the cell in
+ * physical space.
*
- * The second group contains the
- * matrices needed to transform
- * vector-valued functions,
- * namely
- * @p jacobians,
- * the derivatives
- * @p jacobian_grads,
- * and the inverse operations in
- * @p inverse_jacobians.
+ * The second group contains the matrices needed to transform vector-valued
+ * functions, namely @p jacobians, the derivatives @p jacobian_grads, and
+ * the inverse operations in @p inverse_jacobians.
*/
/* virtual void */
/* fill_fe_values (const typename Triangulation<dim,spacedim>::cell_iterator &cell, */
/* std::vector<Point<spacedim> > &quadrature_points, */
/* std::vector<double> &JxW_values) const = 0; */
- /** The function above adjusted
- * with the variable
- * cell_normal_vectors for the
+ /**
+ * The function above adjusted with the variable cell_normal_vectors for the
* case of codimension 1
*/
virtual void
/**
- * Performs the same as @p
- * fill_fe_values on a face.
- * Additionally, @p boundary_form
- * (see @ref GlossBoundaryForm)
- * and @p normal_vectors can be
- * computed on surfaces. Since
- * the boundary form already
- * contains the determinant of
- * the Jacobian of the
- * transformation, it is
- * sometimes more economic to use
- * the boundary form instead of
- * the product of the unit normal
- * and the transformed quadrature
- * weight.
+ * Performs the same as @p fill_fe_values on a face. Additionally, @p
+ * boundary_form (see @ref GlossBoundaryForm) and @p normal_vectors can be
+ * computed on surfaces. Since the boundary form already contains the
+ * determinant of the Jacobian of the transformation, it is sometimes more
+ * economic to use the boundary form instead of the product of the unit
+ * normal and the transformed quadrature weight.
*/
virtual void
fill_fe_face_values (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
std::vector<Point<spacedim> > &normal_vectors) const = 0;
/**
- * Give class @p FEValues access
- * to the private <tt>get_...data</tt>
- * and <tt>fill_fe_...values</tt>
- * functions.
+ * Give class @p FEValues access to the private <tt>get_...data</tt> and
+ * <tt>fill_fe_...values</tt> functions.
*/
friend class FEValuesBase<dim,spacedim>;
friend class FEValues<dim,spacedim>;
/*@{*/
/**
- * Mapping class that uses C1 (continuously differentiable) cubic
- * mappings of the boundary. This class is built atop of
- * MappingQ by simply determining the interpolation points for a
- * cubic mapping of the boundary differently: MappingQ chooses
- * them such that they interpolate the boundary, while this class
- * chooses them such that the discretized boundary is globally
+ * Mapping class that uses C1 (continuously differentiable) cubic mappings of
+ * the boundary. This class is built atop of MappingQ by simply determining
+ * the interpolation points for a cubic mapping of the boundary differently:
+ * MappingQ chooses them such that they interpolate the boundary, while this
+ * class chooses them such that the discretized boundary is globally
* continuously differentiable.
*
- * To use this class, make sure that the
- * Boundary::@p get_normals_at_vertices function is implemented
- * for the user's boundary object.
+ * To use this class, make sure that the Boundary::@p get_normals_at_vertices
+ * function is implemented for the user's boundary object.
*
- * For more information about the <tt>spacedim</tt> template parameter
- * check the documentation of FiniteElement or the one of
- * Triangulation.
+ * For more information about the <tt>spacedim</tt> template parameter check
+ * the documentation of FiniteElement or the one of Triangulation.
*
* @author Wolfgang Bangerth, 2001
*/
* located on bounding lines to the vector @p a. Points located on the line
* but on vertices are not included.
*
- * Needed by the <tt>compute_support_points_simple(laplace)</tt>
- * functions. For <tt>dim=1</tt> this function is empty.
+ * Needed by the <tt>compute_support_points_simple(laplace)</tt> functions.
+ * For <tt>dim=1</tt> this function is empty.
*
* This function chooses the respective points not such that they are
* interpolating the boundary (as does the base class), but rather such that
/*@{*/
/**
- * A class providing a mapping from the reference cell to cells that are axiparallel.
+ * A class providing a mapping from the reference cell to cells that are
+ * axiparallel.
*
- * This class maps the unit cell to a grid cell with surfaces parallel
- * to the coordinate lines/planes. It is specifically developed for
- * Cartesian meshes. In other words, the mapping is meant for cells for which the
- * mapping from the reference to the real cell is a scaling
- * along the coordinate directions: The transformation from reference coordinates
- * $\hat {\mathbf x}$ to real coordinates $\mathbf x$ on each cell is of the
- * form
- * @f{align*}
- * {\mathbf x}(\hat {\mathbf x})
- * =
- * \begin{pmatrix} h_x & 0 \\ 0 & h_y \end{pmatrix}
- * \hat{\mathbf x} + {\mathbf v}_0
- * @f}
- * in 2d, and
- * @f{align*}
- * {\mathbf x}(\hat {\mathbf x})
- * =
- * \begin{pmatrix} h_x & 0 & 0 \\ 0 & h_y & 0 \\ 0 & 0 & h_z \end{pmatrix}
- * \hat{\mathbf x} + {\mathbf v}_0
- * @f}
- * in 3d, where ${\mathbf v}_0$ is the bottom left vertex and $h_x,h_y,h_z$ are
- * the extents of the cell along the axes.
+ * This class maps the unit cell to a grid cell with surfaces parallel to the
+ * coordinate lines/planes. It is specifically developed for Cartesian meshes.
+ * In other words, the mapping is meant for cells for which the mapping from
+ * the reference to the real cell is a scaling along the coordinate
+ * directions: The transformation from reference coordinates $\hat {\mathbf
+ * x}$ to real coordinates $\mathbf x$ on each cell is of the form @f{align*}
+ * {\mathbf x}(\hat {\mathbf x}) = \begin{pmatrix} h_x & 0 \\ 0 & h_y
+ * \end{pmatrix} \hat{\mathbf x} + {\mathbf v}_0 @f} in 2d, and @f{align*}
+ * {\mathbf x}(\hat {\mathbf x}) = \begin{pmatrix} h_x & 0 & 0 \\ 0 & h_y & 0
+ * \\ 0 & 0 & h_z \end{pmatrix} \hat{\mathbf x} + {\mathbf v}_0 @f} in 3d,
+ * where ${\mathbf v}_0$ is the bottom left vertex and $h_x,h_y,h_z$ are the
+ * extents of the cell along the axes.
*
* The class is intended for efficiency, and it does not do a whole lot of
- * error checking. If you apply this mapping to a cell that does not conform to
- * the requirements above, you will get strange results.
+ * error checking. If you apply this mapping to a cell that does not conform
+ * to the requirements above, you will get strange results.
*
* @author Guido Kanschat, 2001; Ralf Hartmann, 2005
*/
const Point<dim> &p) const;
/**
- * Transforms the point @p p on
- * the real cell to the point
- * @p p_unit on the unit cell
- * @p cell and returns @p p_unit.
+ * Transforms the point @p p on the real cell to the point @p p_unit on the
+ * unit cell @p cell and returns @p p_unit.
*
- * Uses Newton iteration and the
- * @p transform_unit_to_real_cell
- * function.
+ * Uses Newton iteration and the @p transform_unit_to_real_cell function.
*/
virtual Point<dim>
transform_real_to_unit_cell (
/**
- * Return a pointer to a copy of the
- * present object. The caller of this
- * copy then assumes ownership of it.
+ * Return a pointer to a copy of the present object. The caller of this copy
+ * then assumes ownership of it.
*/
virtual
Mapping<dim, spacedim> *clone () const;
/**
- * Always returns @p true because
- * MappingCartesian preserves vertex
+ * Always returns @p true because MappingCartesian preserves vertex
* locations.
*/
bool preserves_vertex_locations () const;
protected:
/**
- * Storage for internal data of
- * the scaling.
+ * Storage for internal data of the scaling.
*/
class InternalData : public Mapping<dim, spacedim>::InternalDataBase
{
InternalData (const Quadrature<dim> &quadrature);
/**
- * Return an estimate (in
- * bytes) or the memory
- * consumption of this
- * object.
+ * Return an estimate (in bytes) or the memory consumption of this object.
*/
virtual std::size_t memory_consumption () const;
/**
- * Length of the cell in
- * different coordinate
- * directions, <i>h<sub>x</sub></i>,
- * <i>h<sub>y</sub></i>, <i>h<sub>z</sub></i>.
+ * Length of the cell in different coordinate directions,
+ * <i>h<sub>x</sub></i>, <i>h<sub>y</sub></i>, <i>h<sub>z</sub></i>.
*/
Tensor<1,dim> length;
double volume_element;
/**
- * Vector of all quadrature
- * points. Especially, all
- * points on all faces.
+ * Vector of all quadrature points. Especially, all points on all faces.
*/
std::vector<Point<dim> > quadrature_points;
};
/**
- * Do the computation for the
- * <tt>fill_*</tt> functions.
+ * Do the computation for the <tt>fill_*</tt> functions.
*/
void compute_fill (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
const unsigned int face_no,
virtual UpdateFlags update_each (const UpdateFlags) const;
/**
- * Value to indicate that a given
- * face or subface number is
- * invalid.
+ * Value to indicate that a given face or subface number is invalid.
*/
static const unsigned int invalid_face_number = numbers::invalid_unsigned_int;
};
* are therefore preferred over equidistant support points.
*
* For more details about Qp-mappings, see the `mapping' report at
- * <tt>deal.II/doc/reports/mapping_q/index.html</tt> in the `Reports'
- * section of `Documentation'.
+ * <tt>deal.II/doc/reports/mapping_q/index.html</tt> in the `Reports' section
+ * of `Documentation'.
*
- * For more information about the <tt>spacedim</tt> template parameter
- * check the documentation of FiniteElement or the one of
- * Triangulation.
+ * For more information about the <tt>spacedim</tt> template parameter check
+ * the documentation of FiniteElement or the one of Triangulation.
*
* @note Since the boundary description is closely tied to the unit cell
- * support points, new boundary descriptions need to explicitly use the
- * Gauss-Lobatto points.
+ * support points, new boundary descriptions need to explicitly use the Gauss-
+ * Lobatto points.
*
* @author Ralf Hartmann, 2000, 2001, 2005; Guido Kanschat 2000, 2001
*/
private:
/**
- * Ask the manifold descriptor to return intermediate points on
- * lines or faces. The function needs to return one or multiple
- * points (depending on the number of elements in the output vector
- * @p points that lie inside a line, quad or hex). Whether it is a
- * line, quad or hex doesn't really matter to this function but it
- * can be inferred from the number of input points in the @p
- * surrounding_points vector.
+ * Ask the manifold descriptor to return intermediate points on lines or
+ * faces. The function needs to return one or multiple points (depending on
+ * the number of elements in the output vector @p points that lie inside a
+ * line, quad or hex). Whether it is a line, quad or hex doesn't really
+ * matter to this function but it can be inferred from the number of input
+ * points in the @p surrounding_points vector.
*/
void get_intermediate_points(const Manifold<dim, spacedim> &manifold,
const std::vector<Point<spacedim> > &surrounding_points,
/**
- * Ask the manifold descriptor to return intermediate points on the
- * object pointed to by the TriaIterator @p iter. This function
- * tries to be backward compatible with respect to the differences
- * between Boundary<dim,spacedim> and Manifold<dim,spacedim>,
- * querying the first whenever the passed @p manifold can be
- * upgraded to a Boundary<dim,spacedim>.
+ * Ask the manifold descriptor to return intermediate points on the object
+ * pointed to by the TriaIterator @p iter. This function tries to be
+ * backward compatible with respect to the differences between
+ * Boundary<dim,spacedim> and Manifold<dim,spacedim>, querying the first
+ * whenever the passed @p manifold can be upgraded to a
+ * Boundary<dim,spacedim>.
*/
template <class TriaIterator>
void get_intermediate_points_on_object(const Manifold<dim, spacedim> &manifold,
* Needed by the @p laplace_on_quad function (for <tt>dim==2</tt>). Filled
* by the constructor.
*
- * Sizes:
- * laplace_on_quad_vector.size()= number of inner unit_support_points
+ * Sizes: laplace_on_quad_vector.size()= number of inner unit_support_points
* laplace_on_quad_vector[i].size()= number of outer unit_support_points,
- * i.e. unit_support_points on the boundary of the quad
+ * i.e. unit_support_points on the boundary of the quad
*
* For the definition of this vector see equation (8) of the `mapping'
* report.
/**
- * Mapping of general quadrilateral/hexahedra by d-linear shape
- * functions.
+ * Mapping of general quadrilateral/hexahedra by d-linear shape functions.
*
- * This function maps the unit cell to a general grid cell with
- * straight lines in $d$ dimensions (remark that in 3D the surfaces
- * may be curved, even if the edges are not). This is the well-known
- * mapping for polyhedral domains.
+ * This function maps the unit cell to a general grid cell with straight lines
+ * in $d$ dimensions (remark that in 3D the surfaces may be curved, even if
+ * the edges are not). This is the well-known mapping for polyhedral domains.
*
- * Shape function for this mapping are the same as for the finite
- * element FE_Q of order 1. Therefore, coupling these two yields
- * an isoparametric element.
+ * Shape function for this mapping are the same as for the finite element FE_Q
+ * of order 1. Therefore, coupling these two yields an isoparametric element.
*
- * For more information about the <tt>spacedim</tt> template parameter
- * check the documentation of FiniteElement or the one of
- * Triangulation.
+ * For more information about the <tt>spacedim</tt> template parameter check
+ * the documentation of FiniteElement or the one of Triangulation.
*
* @author Guido Kanschat, 2000, 2001; Ralf Hartmann, 2000, 2001, 2005
*/
const Point<dim> &p) const;
/**
- * Transforms the point @p p on
- * the real cell to the point
- * @p p_unit on the unit cell
- * @p cell and returns @p p_unit.
+ * Transforms the point @p p on the real cell to the point @p p_unit on the
+ * unit cell @p cell and returns @p p_unit.
*
- * Uses Newton iteration and the
- * @p transform_unit_to_real_cell
- * function.
+ * Uses Newton iteration and the @p transform_unit_to_real_cell function.
*
- * In the codimension one case,
- * this function returns the
- * normal projection of the real
- * point @p p on the curve or
- * surface identified by the @p
- * cell.
+ * In the codimension one case, this function returns the normal projection
+ * of the real point @p p on the curve or surface identified by the @p cell.
*
- * @note Polynomial mappings from
- * the reference (unit) cell coordinates
- * to the coordinate system of a real
- * cell are not always invertible if
- * the point for which the inverse
- * mapping is to be computed lies
- * outside the cell's boundaries.
- * In such cases, the current function
- * may fail to compute a point on
- * the reference cell whose image
- * under the mapping equals the given
- * point @p p. If this is the case
- * then this function throws an
- * exception of type
- * Mapping::ExcTransformationFailed .
- * Whether the given point @p p lies
- * outside the cell can therefore be
- * determined by checking whether the
- * return reference coordinates lie
- * inside of outside the reference
- * cell (e.g., using
- * GeometryInfo::is_inside_unit_cell)
- * or whether the exception mentioned
- * above has been thrown.
+ * @note Polynomial mappings from the reference (unit) cell coordinates to
+ * the coordinate system of a real cell are not always invertible if the
+ * point for which the inverse mapping is to be computed lies outside the
+ * cell's boundaries. In such cases, the current function may fail to
+ * compute a point on the reference cell whose image under the mapping
+ * equals the given point @p p. If this is the case then this function
+ * throws an exception of type Mapping::ExcTransformationFailed . Whether
+ * the given point @p p lies outside the cell can therefore be determined by
+ * checking whether the return reference coordinates lie inside of outside
+ * the reference cell (e.g., using GeometryInfo::is_inside_unit_cell) or
+ * whether the exception mentioned above has been thrown.
*/
virtual Point<dim>
transform_real_to_unit_cell (
protected:
/**
- This function and the next allow to generate the transform require by
- the virtual transform() in mapping, but unfortunately in C++ one cannot
- declare a virtual template function.
- */
+ * This function and the next allow to generate the transform require by the
+ * virtual transform() in mapping, but unfortunately in C++ one cannot
+ * declare a virtual template function.
+ */
template < int rank >
void
transform_fields(const VectorSlice<const std::vector<Tensor<rank,dim> > > input,
const typename Mapping<dim,spacedim>::InternalDataBase &internal,
const MappingType type) const;
/**
- see doc in transform_fields
- */
+ * see doc in transform_fields
+ */
template < int rank >
void
transform_gradients(const VectorSlice<const std::vector<Tensor<rank,dim> > > input,
const typename Mapping<dim,spacedim>::InternalDataBase &internal,
const MappingType type) const;
/**
- see doc in transform_fields
- */
+ * see doc in transform_fields
+ */
template < int rank >
void
transform_differential_forms(
/**
- * Return a pointer to a copy of the
- * present object. The caller of this
- * copy then assumes ownership of it.
+ * Return a pointer to a copy of the present object. The caller of this copy
+ * then assumes ownership of it.
*/
virtual
Mapping<dim,spacedim> *clone () const;
/**
- * Storage for internal data of
- * d-linear transformation.
+ * Storage for internal data of d-linear transformation.
*/
class InternalData : public Mapping<dim,spacedim>::InternalDataBase
{
public:
/**
- * Constructor. Pass the
- * number of shape functions.
+ * Constructor. Pass the number of shape functions.
*/
InternalData(const unsigned int n_shape_functions);
/**
- * Shape function at quadrature
- * point. Shape functions are
- * in tensor product order, so
- * vertices must be reordered
- * to obtain transformation.
+ * Shape function at quadrature point. Shape functions are in tensor
+ * product order, so vertices must be reordered to obtain transformation.
*/
double shape (const unsigned int qpoint,
const unsigned int shape_nr) const;
/**
- * Shape function at quadrature
- * point. See above.
+ * Shape function at quadrature point. See above.
*/
double &shape (const unsigned int qpoint,
const unsigned int shape_nr);
/**
- * Gradient of shape function
- * in quadrature point. See
- * above.
+ * Gradient of shape function in quadrature point. See above.
*/
Tensor<1,dim> derivative (const unsigned int qpoint,
const unsigned int shape_nr) const;
/**
- * Gradient of shape function
- * in quadrature point. See
- * above.
+ * Gradient of shape function in quadrature point. See above.
*/
Tensor<1,dim> &derivative (const unsigned int qpoint,
const unsigned int shape_nr);
/**
- * Second derivative of shape
- * function in quadrature
- * point. See above.
+ * Second derivative of shape function in quadrature point. See above.
*/
Tensor<2,dim> second_derivative (const unsigned int qpoint,
const unsigned int shape_nr) const;
/**
- * Second derivative of shape
- * function in quadrature
- * point. See above.
+ * Second derivative of shape function in quadrature point. See above.
*/
Tensor<2,dim> &second_derivative (const unsigned int qpoint,
const unsigned int shape_nr);
/**
- * Return an estimate (in
- * bytes) or the memory
- * consumption of this
- * object.
+ * Return an estimate (in bytes) or the memory consumption of this object.
*/
virtual std::size_t memory_consumption () const;
/**
- * Values of shape
- * functions. Access by
- * function @p shape.
+ * Values of shape functions. Access by function @p shape.
*
* Computed once.
*/
std::vector<double> shape_values;
/**
- * Values of shape function
- * derivatives. Access by
- * function @p derivative.
+ * Values of shape function derivatives. Access by function @p derivative.
*
* Computed once.
*/
std::vector<Tensor<1,dim> > shape_derivatives;
/**
- * Values of shape function
- * second derivatives. Access
- * by function
- * @p second_derivative.
+ * Values of shape function second derivatives. Access by function @p
+ * second_derivative.
*
* Computed once.
*/
std::vector<Tensor<2,dim> > shape_second_derivatives;
/**
- * Tensors of covariant
- * transformation at each of
- * the quadrature points. The
- * matrix stored is the
- * Jacobian * G^{-1},
- * where G = Jacobian^{t} * Jacobian,
- * is the first fundamental
- * form of the map;
- * if dim=spacedim then
- * it reduces to the transpose of the
- * inverse of the Jacobian
- * matrix, which itself is
- * stored in the
- * @p contravariant field of
- * this structure.
+ * Tensors of covariant transformation at each of the quadrature points.
+ * The matrix stored is the Jacobian * G^{-1}, where G = Jacobian^{t} *
+ * Jacobian, is the first fundamental form of the map; if dim=spacedim
+ * then it reduces to the transpose of the inverse of the Jacobian matrix,
+ * which itself is stored in the @p contravariant field of this structure.
*
* Computed on each cell.
*/
std::vector<DerivativeForm<1,dim, spacedim > > covariant;
/**
- * Tensors of contravariant
- * transformation at each of
- * the quadrature points. The
- * contravariant matrix is
- * the Jacobian of the
- * transformation,
+ * Tensors of contravariant transformation at each of the quadrature
+ * points. The contravariant matrix is the Jacobian of the transformation,
* i.e. $J_{ij}=dx_i/d\hat x_j$.
*
* Computed on each cell.
std::vector< DerivativeForm<1,dim,spacedim> > contravariant;
/**
- * Unit tangential vectors. Used
- * for the computation of
- * boundary forms and normal
- * vectors.
+ * Unit tangential vectors. Used for the computation of boundary forms and
+ * normal vectors.
*
- * This vector has
- * (dim-1)GeometryInfo::faces_per_cell
- * entries. The first
- * GeometryInfo::faces_per_cell
- * contain the vectors in the first
- * tangential direction for each
- * face; the second set of
- * GeometryInfo::faces_per_cell
- * entries contain the vectors in the
- * second tangential direction (only
- * in 3d, since there we have 2
- * tangential directions per face),
- * etc.
+ * This vector has (dim-1)GeometryInfo::faces_per_cell entries. The first
+ * GeometryInfo::faces_per_cell contain the vectors in the first
+ * tangential direction for each face; the second set of
+ * GeometryInfo::faces_per_cell entries contain the vectors in the second
+ * tangential direction (only in 3d, since there we have 2 tangential
+ * directions per face), etc.
*
* Filled once.
*/
std::vector<std::vector<Tensor<1,spacedim> > > aux;
/**
- * Stores the support points of
- * the mapping shape functions on
- * the @p cell_of_current_support_points.
+ * Stores the support points of the mapping shape functions on the @p
+ * cell_of_current_support_points.
*/
std::vector<Point<spacedim> > mapping_support_points;
/**
- * Stores the cell of which the
- * @p mapping_support_points are
- * stored.
+ * Stores the cell of which the @p mapping_support_points are stored.
*/
typename Triangulation<dim,spacedim>::cell_iterator cell_of_current_support_points;
/**
- * Default value of this flag
- * is @p true. If <tt>*this</tt>
- * is an object of a derived
- * class, this flag is set to
- * @p false.
+ * Default value of this flag is @p true. If <tt>*this</tt> is an object
+ * of a derived class, this flag is set to @p false.
*/
bool is_mapping_q1_data;
/**
- * Number of shape
- * functions. If this is a Q1
- * mapping, then it is simply
- * the number of vertices per
- * cell. However, since also
- * derived classes use this
- * class (e.g. the
- * Mapping_Q() class),
- * the number of shape
- * functions may also be
- * different.
+ * Number of shape functions. If this is a Q1 mapping, then it is simply
+ * the number of vertices per cell. However, since also derived classes
+ * use this class (e.g. the Mapping_Q() class), the number of shape
+ * functions may also be different.
*/
unsigned int n_shape_functions;
};
/**
- * Declare a convenience typedef
- * for the class that describes
- * offsets into quadrature
- * formulas projected onto faces
- * and subfaces.
+ * Declare a convenience typedef for the class that describes offsets into
+ * quadrature formulas projected onto faces and subfaces.
*/
typedef
typename QProjector<dim>::DataSetDescriptor
DataSetDescriptor;
/**
- * Implementation of the interface in
- * Mapping.
+ * Implementation of the interface in Mapping.
*/
virtual void
fill_fe_values (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
CellSimilarity::Similarity &cell_similarity) const;
/**
- * Implementation of the interface in
- * Mapping.
+ * Implementation of the interface in Mapping.
*/
virtual void
fill_fe_face_values (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
typename std::vector<Point<spacedim> > &normal_vectors) const ;
/**
- * Implementation of the interface in
- * Mapping.
+ * Implementation of the interface in Mapping.
*/
virtual void
fill_fe_subface_values (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
typename std::vector<Point<spacedim> > &normal_vectors) const ;
/**
- * Compute shape values and/or
- * derivatives.
+ * Compute shape values and/or derivatives.
*
- * Calls either the
- * @p compute_shapes_virtual of
- * this class or that of the
- * derived class, depending on
- * whether
- * <tt>data.is_mapping_q1_data</tt>
+ * Calls either the @p compute_shapes_virtual of this class or that of the
+ * derived class, depending on whether <tt>data.is_mapping_q1_data</tt>
* equals @p true or @p false.
*/
void compute_shapes (const std::vector<Point<dim> > &unit_points,
InternalData &data) const;
/**
- * Do the computations for the
- * @p get_data functions. Here,
- * the data vectors of
- * @p InternalData are
- * reinitialized to proper size
- * and shape values are computed.
+ * Do the computations for the @p get_data functions. Here, the data vectors
+ * of @p InternalData are reinitialized to proper size and shape values are
+ * computed.
*/
void compute_data (const UpdateFlags flags,
const Quadrature<dim> &quadrature,
InternalData &data) const;
/**
- * Do the computations for the
- * @p get_face_data
- * functions. Here, the data
- * vectors of @p InternalData
- * are reinitialized to proper
- * size and shape values and
- * derivatives are
- * computed. Furthermore
- * @p unit_tangential vectors of
- * the face are computed.
+ * Do the computations for the @p get_face_data functions. Here, the data
+ * vectors of @p InternalData are reinitialized to proper size and shape
+ * values and derivatives are computed. Furthermore @p unit_tangential
+ * vectors of the face are computed.
*/
void compute_face_data (const UpdateFlags flags,
const Quadrature<dim> &quadrature,
InternalData &data) const;
/**
- * Do the computation for the
- * <tt>fill_*</tt> functions.
+ * Do the computation for the <tt>fill_*</tt> functions.
*/
void compute_fill (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
const unsigned int npts,
std::vector<Point<spacedim> > &quadrature_points) const;
/**
- * Do the computation for the
- * <tt>fill_*</tt> functions.
+ * Do the computation for the <tt>fill_*</tt> functions.
*/
void compute_fill_face (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
const unsigned int face_no,
std::vector<Point<spacedim> > &normal_vectors) const;
/**
- * Compute shape values and/or
- * derivatives.
+ * Compute shape values and/or derivatives.
*/
virtual void compute_shapes_virtual (const std::vector<Point<dim> > &unit_points,
InternalData &data) const;
/**
- * Transforms a point @p p on
- * the unit cell to the point
- * @p p_real on the real cell
- * @p cell and returns @p p_real.
+ * Transforms a point @p p on the unit cell to the point @p p_real on the
+ * real cell @p cell and returns @p p_real.
*
- * This function is called by
- * @p transform_unit_to_real_cell
- * and multiple times (through the
- * Newton iteration) by
- * @p transform_real_to_unit_cell_internal.
+ * This function is called by @p transform_unit_to_real_cell and multiple
+ * times (through the Newton iteration) by @p
+ * transform_real_to_unit_cell_internal.
*
- * Takes a reference to an
- * @p InternalData that must
- * already include the shape
- * values at point @p p and the
- * mapping support points of the
- * cell.
+ * Takes a reference to an @p InternalData that must already include the
+ * shape values at point @p p and the mapping support points of the cell.
*
- * This @p InternalData argument
- * avoids multiple computations
- * of the shape values at point
- * @p p and especially multiple
- * computations of the mapping
+ * This @p InternalData argument avoids multiple computations of the shape
+ * values at point @p p and especially multiple computations of the mapping
* support points.
*/
Point<spacedim>
transform_unit_to_real_cell_internal (const InternalData &mdata) const;
/**
- * Transforms the point @p p on
- * the real cell to the corresponding
- * point on the unit cell
- * @p cell by a Newton
- * iteration.
+ * Transforms the point @p p on the real cell to the corresponding point on
+ * the unit cell @p cell by a Newton iteration.
*
- * Takes a reference to an
- * @p InternalData that is
- * assumed to be previously
- * created by the @p get_data
- * function with @p UpdateFlags
- * including
- * @p update_transformation_values
- * and
- * @p update_transformation_gradients
- * and a one point Quadrature
- * that includes the given
- * initial guess for the
- * transformation
- * @p initial_p_unit. Hence this
- * function assumes that
- * @p mdata already includes the
- * transformation shape values
- * and gradients computed at
- * @p initial_p_unit.
+ * Takes a reference to an @p InternalData that is assumed to be previously
+ * created by the @p get_data function with @p UpdateFlags including @p
+ * update_transformation_values and @p update_transformation_gradients and a
+ * one point Quadrature that includes the given initial guess for the
+ * transformation @p initial_p_unit. Hence this function assumes that @p
+ * mdata already includes the transformation shape values and gradients
+ * computed at @p initial_p_unit.
*
- * @p mdata will be changed by
- * this function.
+ * @p mdata will be changed by this function.
*/
Point<dim>
transform_real_to_unit_cell_internal (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
InternalData &mdata) const;
/**
- * Always returns @p true because
- * MappingQ1 preserves vertex locations.
+ * Always returns @p true because MappingQ1 preserves vertex locations.
*/
virtual
bool preserves_vertex_locations () const;
InternalData &mdata) const;
/**
- Compute an initial guess to pass to the Newton method in
- transform_real_to_unit_cell.
-
- For the initial guess we proceed in the following way:
- <ul>
- <li> find the least square dim-dimensional plane
- approximating the cell vertices, i.e. we find and affine
- map A x_hat + b from the reference cell to the real space.
- <li> Solve the equation A x_hat + b = p for x_hat
- <li> This x_hat is the initial solution used for the Newton Method.
- </ul>
-
- @note if dim<spacedim we first project p onto the plane.
- @note if dim==1 (for any spacedim) the initial guess is the exact solution
- and no Newton iteration is needed.
-
-
- Some details about how we compute the least square plane.
- We look for a spacedim x (dim + 1) matrix X such that
-
- X * M = Y
-
- where M is a (dim+1) x n_vertices matrix and Y a spacedim x n_vertices.
-
- And:
- The i-th column of M is unit_vertex[i] and the last row all 1's.
- The i-th column of Y is real_vertex[i].
-
- If we split X=[A|b], the least square approx is A x_hat+b
-
- Classically X = Y * (M^t (M M^t)^{-1})
-
- Let K = M^t * (M M^t)^{-1} = [KA Kb]
- this can be precomputed, and that is exactely
- what we do.
-
- Finally A = Y*KA and b = Y*Kb.
- */
+ * Compute an initial guess to pass to the Newton method in
+ * transform_real_to_unit_cell. For the initial guess we proceed in the
+ * following way:
+ * <ul>
+ * <li> find the least square dim-dimensional plane approximating the cell
+ * vertices, i.e. we find and affine map A x_hat + b from the reference cell
+ * to the real space.
+ * <li> Solve the equation A x_hat + b = p for x_hat
+ * <li> This x_hat is the initial solution used for the Newton Method.
+ * </ul>
+ * @note if dim<spacedim we first project p onto the plane. @note if dim==1
+ * (for any spacedim) the initial guess is the exact solution and no Newton
+ * iteration is needed. Some details about how we compute the least square
+ * plane. We look for a spacedim x (dim + 1) matrix X such that X * M = Y
+ * where M is a (dim+1) x n_vertices matrix and Y a spacedim x n_vertices.
+ * And: The i-th column of M is unit_vertex[i] and the last row all 1's. The
+ * i-th column of Y is real_vertex[i]. If we split X=[A|b], the least
+ * square approx is A x_hat+b Classically X = Y * (M^t (M M^t)^{-1}) Let
+ * K = M^t * (M M^t)^{-1} = [KA Kb] this can be precomputed, and that is
+ * exactely what we do. Finally A = Y*KA and b = Y*Kb.
+ */
Point<dim>
transform_real_to_unit_cell_initial_guess (const std::vector<Point<spacedim> > &vertex,
const Point<spacedim> &p) const;
private:
/**
- * Implementation of the interface in
- * Mapping.
+ * Implementation of the interface in Mapping.
*
* Description of effects:
* <ul>
- * <li> if @p update_quadrature_points
- * is required, the output will
- * contain
- * @p update_transformation_values. This
- * computes the values of the
- * transformation basis
- * polynomials at the unit cell
- * quadrature points.
- * <li> if any of
- * @p update_covariant_transformation,
- * @p update_contravariant_transformation,
- * @p update_JxW_values,
- * @p update_boundary_forms,
- * @p update_normal_vectors is
- * required, the output will
- * contain
- * @p update_transformation_gradients
- * to compute derivatives of the
- * transformation basis
- * polynomials.
+ * <li> if @p update_quadrature_points is required, the output will contain
+ * @p update_transformation_values. This computes the values of the
+ * transformation basis polynomials at the unit cell quadrature points.
+ * <li> if any of @p update_covariant_transformation, @p
+ * update_contravariant_transformation, @p update_JxW_values, @p
+ * update_boundary_forms, @p update_normal_vectors is required, the output
+ * will contain @p update_transformation_gradients to compute derivatives of
+ * the transformation basis polynomials.
* </ul>
*/
virtual UpdateFlags update_once (const UpdateFlags flags) const;
/**
- * Implementation of the interface in
- * Mapping.
+ * Implementation of the interface in Mapping.
*
- * Description of effects if
- * @p flags contains:
+ * Description of effects if @p flags contains:
* <ul>
- * <li> <code>update_quadrature_points</code> is
- * copied to the output to
- * compute the quadrature points
- * on the real cell.
- * <li> <code>update_JxW_values</code> is
- * copied and requires
- * @p update_boundary_forms on
- * faces. The latter, because the
- * surface element is just the
- * norm of the boundary form.
- * <li> <code>update_normal_vectors</code>
- * is copied and requires
- * @p update_boundary_forms. The
- * latter, because the normal
- * vector is the normalized
- * boundary form.
- * <li>
- * <code>update_covariant_transformation</code>
- * is copied and requires
- * @p update_contravariant_transformation,
- * since it is computed as the
+ * <li> <code>update_quadrature_points</code> is copied to the output to
+ * compute the quadrature points on the real cell.
+ * <li> <code>update_JxW_values</code> is copied and requires @p
+ * update_boundary_forms on faces. The latter, because the surface element
+ * is just the norm of the boundary form.
+ * <li> <code>update_normal_vectors</code> is copied and requires @p
+ * update_boundary_forms. The latter, because the normal vector is the
+ * normalized boundary form.
+ * <li> <code>update_covariant_transformation</code> is copied and requires
+ * @p update_contravariant_transformation, since it is computed as the
* inverse of the latter.
- * <li> <code>update_JxW_values</code> is
- * copied and requires
- * <code>update_contravariant_transformation</code>,
- * since it is computed as one
- * over determinant of the
- * latter.
- * <li> <code>update_boundary_forms</code>
- * is copied and requires
- * <code>update_contravariant_transformation</code>,
- * since the boundary form is
- * computed as the contravariant
- * image of the normal vector to
- * the unit cell.
+ * <li> <code>update_JxW_values</code> is copied and requires
+ * <code>update_contravariant_transformation</code>, since it is computed as
+ * one over determinant of the latter.
+ * <li> <code>update_boundary_forms</code> is copied and requires
+ * <code>update_contravariant_transformation</code>, since the boundary form
+ * is computed as the contravariant image of the normal vector to the unit
+ * cell.
* </ul>
*/
virtual UpdateFlags update_each (const UpdateFlags flags) const;
const Quadrature<dim-1>& quadrature) const;
/**
- * Computes the support points of
- * the mapping. For @p MappingQ1
- * these are the
- * vertices. However, other
- * classes may override this
- * function. In particular, the
- * MappingQ1Eulerian class does
- * exactly this by not computing
- * the support points from the
- * geometry of the current cell
- * but instead evaluating an
- * externally given displacement
- * field in addition to the
- * geometry of the cell.
+ * Computes the support points of the mapping. For @p MappingQ1 these are
+ * the vertices. However, other classes may override this function. In
+ * particular, the MappingQ1Eulerian class does exactly this by not
+ * computing the support points from the geometry of the current cell but
+ * instead evaluating an externally given displacement field in addition to
+ * the geometry of the cell.
*/
virtual void compute_mapping_support_points(
const typename Triangulation<dim,spacedim>::cell_iterator &cell,
std::vector<Point<spacedim> > &a) const;
/**
- * Number of shape functions. Is
- * simply the number of vertices
- * per cell for the Q1 mapping.
+ * Number of shape functions. Is simply the number of vertices per cell for
+ * the Q1 mapping.
*/
static const unsigned int n_shape_functions = GeometryInfo<dim>::vertices_per_cell;
};
/**
- * In order to avoid creation of static MappingQ1 objects at several
- * places in the library (in particular in backward compatibility
- * functions), we define a static MappingQ1 objects once and for all
- * places where it is needed.
+ * In order to avoid creation of static MappingQ1 objects at several places in
+ * the library (in particular in backward compatibility functions), we define
+ * a static MappingQ1 objects once and for all places where it is needed.
*/
template <int dim, int spacedim=dim>
struct StaticMappingQ1
/*@{*/
/**
- * Eulerian mapping of general unit cells by d-linear shape
- * functions. Each cell is thus shifted in space by values given to
- * the mapping through a finite element field.
+ * Eulerian mapping of general unit cells by d-linear shape functions. Each
+ * cell is thus shifted in space by values given to the mapping through a
+ * finite element field.
*
* <h3>Usage</h3>
*
- * The constructor of this class takes two arguments: a reference to
- * the vector that defines the mapping from the reference
- * configuration to the current configuration and a reference to the
- * DoFHandler. The vector should then represent a (flattened out
- * version of a) vector valued field defined at nodes defined by the
- * the DoFHandler, where the number of components of the vector
- * field equals the number of space dimensions. Thus, the
- * DoFHandler shall operate on a finite element that has as many
- * components as space dimensions. As an additional requirement, we
- * impose that it have as many degree of freedom per vertex as there
- * are space dimensions; since this object only evaluates the finite
- * element field at the vertices, the values
- * of all other degrees of freedom (not associated to vertices) are
- * ignored. These requirements are met if the finite element which the
- * given DoFHandler operates on is constructed as a system
- * element (FESystem) from @p dim continuous FE_Q()
- * objects.
+ * The constructor of this class takes two arguments: a reference to the
+ * vector that defines the mapping from the reference configuration to the
+ * current configuration and a reference to the DoFHandler. The vector should
+ * then represent a (flattened out version of a) vector valued field defined
+ * at nodes defined by the the DoFHandler, where the number of components of
+ * the vector field equals the number of space dimensions. Thus, the
+ * DoFHandler shall operate on a finite element that has as many components as
+ * space dimensions. As an additional requirement, we impose that it have as
+ * many degree of freedom per vertex as there are space dimensions; since this
+ * object only evaluates the finite element field at the vertices, the values
+ * of all other degrees of freedom (not associated to vertices) are ignored.
+ * These requirements are met if the finite element which the given DoFHandler
+ * operates on is constructed as a system element (FESystem) from @p dim
+ * continuous FE_Q() objects.
*
- * In many cases, the shift vector will also be the solution vector of
- * the problem under investigation. If this is not the case (i.e. the
- * number of components of the solution variable is not equal to the
- * space dimension, e.g. for scalar problems in <tt>dim>1</tt> where the
- * Eulerian coordinates only give a background field) or for coupled
- * problems where more variables are computed than just the flow
- * field), then a different DoFHandler has to be set up on the
- * given triangulation, and the shift vector has then to be associated
- * to it.
+ * In many cases, the shift vector will also be the solution vector of the
+ * problem under investigation. If this is not the case (i.e. the number of
+ * components of the solution variable is not equal to the space dimension,
+ * e.g. for scalar problems in <tt>dim>1</tt> where the Eulerian coordinates
+ * only give a background field) or for coupled problems where more variables
+ * are computed than just the flow field), then a different DoFHandler has to
+ * be set up on the given triangulation, and the shift vector has then to be
+ * associated to it.
*
* An example is shown below:
* @code
* MappingQ1Eulerian<dim> mymapping(map_points, flowfield_dof_handler);
* @endcode
*
- * Note that since the vector of shift values and the dof handler are
- * only associated to this object at construction time, you have to
- * make sure that whenever you use this object, the given objects
- * still represent valid data.
+ * Note that since the vector of shift values and the dof handler are only
+ * associated to this object at construction time, you have to make sure that
+ * whenever you use this object, the given objects still represent valid data.
*
- * To enable the use of the MappingQ1Eulerian class also in the context
- * of parallel codes using the PETSc wrapper classes, the type of
- * the vector can be specified as template parameter <tt>EulerVectorType</tt>
- * Not specifying this template argument in applications using the PETSc
- * vector classes leads to the construction of a copy of the vector
- * which is not acccessible afterwards!
+ * To enable the use of the MappingQ1Eulerian class also in the context of
+ * parallel codes using the PETSc wrapper classes, the type of the vector can
+ * be specified as template parameter <tt>EulerVectorType</tt> Not specifying
+ * this template argument in applications using the PETSc vector classes leads
+ * to the construction of a copy of the vector which is not acccessible
+ * afterwards!
*
- * For more information about the <tt>spacedim</tt> template parameter
- * check the documentation of FiniteElement or the one of
- * Triangulation.
+ * For more information about the <tt>spacedim</tt> template parameter check
+ * the documentation of FiniteElement or the one of Triangulation.
*
* @author Michael Stadler, 2001
*/
public:
/**
- * Constructor. It takes a
- * <tt>Vector<double> &</tt> as its
- * first argument to specify the
- * transformation of the whole
- * problem from the reference to
- * the current configuration.
- * The organization of the
- * elements in the @p Vector
- * must follow the concept how
- * deal.II stores solutions that
- * are associated to a
- * triangulation. This is
- * automatically the case if the
- * @p Vector represents the
- * solution of the previous step
- * of a nonlinear problem.
- * Alternatively, the @p Vector
- * can be initialized by
+ * Constructor. It takes a <tt>Vector<double> &</tt> as its first argument
+ * to specify the transformation of the whole problem from the reference to
+ * the current configuration. The organization of the elements in the @p
+ * Vector must follow the concept how deal.II stores solutions that are
+ * associated to a triangulation. This is automatically the case if the @p
+ * Vector represents the solution of the previous step of a nonlinear
+ * problem. Alternatively, the @p Vector can be initialized by
* <tt>DoFAccessor::set_dof_values()</tt>.
*/
MappingQ1Eulerian (const VECTOR &euler_transform_vectors,
const DoFHandler<dim,spacedim> &shiftmap_dof_handler);
/**
- * Return a pointer to a copy of the
- * present object. The caller of this
- * copy then assumes ownership of it.
+ * Return a pointer to a copy of the present object. The caller of this copy
+ * then assumes ownership of it.
*/
virtual
Mapping<dim,spacedim> *clone () const;
/**
- * Always returns @p false because
- * MappingQ1Eulerian does not in general
- * preserve vertex locations (unless the
- * translation vector happens to provide
- * for zero displacements at vertex
- * locations).
+ * Always returns @p false because MappingQ1Eulerian does not in general
+ * preserve vertex locations (unless the translation vector happens to
+ * provide for zero displacements at vertex locations).
*/
bool preserves_vertex_locations () const;
protected:
/**
- * Implementation of the interface in
- * MappingQ1. Overrides the function in
- * the base class, since we cannot use
- * any cell similarity for this class.
+ * Implementation of the interface in MappingQ1. Overrides the function in
+ * the base class, since we cannot use any cell similarity for this class.
*/
virtual void
fill_fe_values (const typename Triangulation<dim,spacedim>::cell_iterator &cell,
CellSimilarity::Similarity &cell_similarity) const;
/**
- * Reference to the vector of
- * shifts.
+ * Reference to the vector of shifts.
*/
SmartPointer<const VECTOR, MappingQ1Eulerian<dim,VECTOR,spacedim> > euler_transform_vectors;
/**
- * Pointer to the DoFHandler to
- * which the mapping vector is
- * associated.
+ * Pointer to the DoFHandler to which the mapping vector is associated.
*/
SmartPointer<const DoFHandler<dim,spacedim>,MappingQ1Eulerian<dim,VECTOR,spacedim> > shiftmap_dof_handler;
private:
/**
- * Computes the support points of
- * the mapping. For
- * @p MappingQ1Eulerian these
- * are the vertices.
+ * Computes the support points of the mapping. For @p MappingQ1Eulerian
+ * these are the vertices.
*/
virtual void compute_mapping_support_points(
const typename Triangulation<dim,spacedim>::cell_iterator &cell,
/*@{*/
/**
- * This class is an extension of the MappingQ1Eulerian
- * class to higher order Qp mappings. It is useful
- * when one wants to calculate shape function information on
- * a domain that is deforming as the computation proceeds.
+ * This class is an extension of the MappingQ1Eulerian class to higher order
+ * Qp mappings. It is useful when one wants to calculate shape function
+ * information on a domain that is deforming as the computation proceeds.
*
* <h3>Usage</h3>
*
- * The constructor of this class takes three arguments: the polynomial
- * degree of the desire Qp mapping, a reference to
- * the vector that defines the mapping from the initial
- * configuration to the current configuration, and a reference to the
- * DoFHandler. The most common case is to use the solution
- * vector for the problem under consideration as the shift vector.
- * The key reqirement is that the number of components
- * of the given vector field be equal to (or possibly greater than) the
- * number of space dimensions. If there are more components than space
- * dimensions (for example, if one is working with a coupled problem
- * where there are additional solution variables), the
- * first <tt>dim</tt> components are assumed to represent the displacement
- * field, and the remaining components are ignored. If this assumption
- * does not hold one may need to set up a separate DoFHandler on
+ * The constructor of this class takes three arguments: the polynomial degree
+ * of the desire Qp mapping, a reference to the vector that defines the
+ * mapping from the initial configuration to the current configuration, and a
+ * reference to the DoFHandler. The most common case is to use the solution
+ * vector for the problem under consideration as the shift vector. The key
+ * reqirement is that the number of components of the given vector field be
+ * equal to (or possibly greater than) the number of space dimensions. If
+ * there are more components than space dimensions (for example, if one is
+ * working with a coupled problem where there are additional solution
+ * variables), the first <tt>dim</tt> components are assumed to represent the
+ * displacement field, and the remaining components are ignored. If this
+ * assumption does not hold one may need to set up a separate DoFHandler on
* the triangulation and associate the desired shift vector to it.
*
- * Typically, the DoFHandler operates on a finite element that
- * is constructed as a system element (FESystem) from continuous FE_Q()
- * objects. An example is shown below:
+ * Typically, the DoFHandler operates on a finite element that is constructed
+ * as a system element (FESystem) from continuous FE_Q() objects. An example
+ * is shown below:
* @code
* FESystem<dim> fe(FE_Q<dim>(2), dim, FE_Q<dim>(1), 1);
* DoFHandler<dim> dof_handler(triangulation);
* MappingQEulerian<dim> q2_mapping(2,soln_vector,dof_handler);
* @endcode
*
- * In this example, our element consists of <tt>(dim+1)</tt> components.
- * Only the first <tt>dim</tt> components will be used, however, to define
- * the Q2 mapping. The remaining components are ignored.
+ * In this example, our element consists of <tt>(dim+1)</tt> components. Only
+ * the first <tt>dim</tt> components will be used, however, to define the Q2
+ * mapping. The remaining components are ignored.
*
- * Note that it is essential to call the distribute_dofs(...) function
- * before constructing a mapping object.
+ * Note that it is essential to call the distribute_dofs(...) function before
+ * constructing a mapping object.
*
* Also note that since the vector of shift values and the dof handler are
- * only associated to this object at construction time, you have to
- * make sure that whenever you use this object, the given objects
- * still represent valid data.
+ * only associated to this object at construction time, you have to make sure
+ * that whenever you use this object, the given objects still represent valid
+ * data.
*
- * To enable the use of the MappingQ1Eulerian class also in the context
- * of parallel codes using the PETSc wrapper classes, the type of
- * the vector can be specified as template parameter <tt>EulerVectorType</tt>
- * Not specifying this template argument in applications using the PETSc
- * vector classes leads to the construction of a copy of the vector
- * which is not acccessible afterwards!
+ * To enable the use of the MappingQ1Eulerian class also in the context of
+ * parallel codes using the PETSc wrapper classes, the type of the vector can
+ * be specified as template parameter <tt>EulerVectorType</tt> Not specifying
+ * this template argument in applications using the PETSc vector classes leads
+ * to the construction of a copy of the vector which is not acccessible
+ * afterwards!
*
* @author Joshua White, 2008
*/
* exposed on purpose).
*
* @todo Does it make sense to implement a more efficient representation
- * (internally and/or as a string)? If yes, something like a 64bit int
- * as in p4est would be a good option.
+ * (internally and/or as a string)? If yes, something like a 64bit int as in
+ * p4est would be a good option.
*/
class CellId
{
/**
- * In this namespace a number of classes is declared that may be used
- * as filters in the FilteredIterator class. The filters either check
- * for binary information (for example, the IteratorFilters::Active
- * filter class checks whether the object pointed to is active), or
- * for valued information by comparison with prescribed values (for
- * example, the LevelEqualTo filter class checks whether the level of
- * the object pointed to by the iterator under consideration is equal
- * to a value that was given to the filter upon construction.
+ * In this namespace a number of classes is declared that may be used as
+ * filters in the FilteredIterator class. The filters either check for binary
+ * information (for example, the IteratorFilters::Active filter class checks
+ * whether the object pointed to is active), or for valued information by
+ * comparison with prescribed values (for example, the LevelEqualTo filter
+ * class checks whether the level of the object pointed to by the iterator
+ * under consideration is equal to a value that was given to the filter upon
+ * construction.
*
- * For examples of use of these classes as well as requirements on
- * filters see the general description of the FilteredIterator class.
+ * For examples of use of these classes as well as requirements on filters see
+ * the general description of the FilteredIterator class.
*
* @ingroup Iterators
* @author Wolfgang Bangerth, 2002
namespace IteratorFilters
{
/**
- * Filter that evaluates to true if either the iterator points to an
- * active object or an iterator past the end.
+ * Filter that evaluates to true if either the iterator points to an active
+ * object or an iterator past the end.
*
* @ingroup Iterators
*/
{
public:
/**
- * Evaluate the iterator and return true if the object is active
- * or past the end.
+ * Evaluate the iterator and return true if the object is active or past
+ * the end.
*/
template <class Iterator>
bool operator () (const Iterator &i) const;
};
/**
- * Filter that evaluates to true if either the iterator points to an
- * object for which the user flag is set or an iterator past the
- * end. See @ref GlossUserFlags for information about user flags.
+ * Filter that evaluates to true if either the iterator points to an object
+ * for which the user flag is set or an iterator past the end. See @ref
+ * GlossUserFlags for information about user flags.
*
* @ingroup Iterators
*/
{
public:
/**
- * Evaluate the iterator and return true if the object has a set
- * user flag or past the end.
+ * Evaluate the iterator and return true if the object has a set user flag
+ * or past the end.
*/
template <class Iterator>
bool operator () (const Iterator &i) const;
/**
- * Filter that evaluates to true if either the iterator points to an
- * object for which the user flag is not set or an iterator past the
- * end. Inverse filter to the previous class.
+ * Filter that evaluates to true if either the iterator points to an object
+ * for which the user flag is not set or an iterator past the end. Inverse
+ * filter to the previous class.
*
* @ingroup Iterators
*/
{
public:
/**
- * Evaluate the iterator and return true if the object has an
- * unset user flag or past the end.
+ * Evaluate the iterator and return true if the object has an unset user
+ * flag or past the end.
*/
template <class Iterator>
bool operator () (const Iterator &i) const;
/**
- * Filter for iterators that evaluates to true if either the
- * iterator is past the end or the level of the object pointed to is
- * equal to a value given to the constructor.
+ * Filter for iterators that evaluates to true if either the iterator is
+ * past the end or the level of the object pointed to is equal to a value
+ * given to the constructor.
*
* @ingroup Iterators
*/
{
public:
/**
- * Constructor. Store the level which iterators shall have to be
- * evaluated to true.
+ * Constructor. Store the level which iterators shall have to be evaluated
+ * to true.
*/
LevelEqualTo (const unsigned int level);
/**
- * Evaluation operator. Returns true if either the level of the
- * object pointed to is equal to the stored value or the iterator
- * is past the end.
+ * Evaluation operator. Returns true if either the level of the object
+ * pointed to is equal to the stored value or the iterator is past the
+ * end.
*/
template <class Iterator>
bool operator () (const Iterator &i) const;
/**
- * Filter for iterators that evaluates to true if either the
- * iterator is past the end or the subdomain id of the object
- * pointed to is equal to a value given to the constructor, assuming
- * that the iterator allows querying for a subdomain id).
+ * Filter for iterators that evaluates to true if either the iterator is
+ * past the end or the subdomain id of the object pointed to is equal to a
+ * value given to the constructor, assuming that the iterator allows
+ * querying for a subdomain id).
*
* @ingroup Iterators
*/
{
public:
/**
- * Constructor. Store the subdomain which iterators shall have to
- * be evaluated to true.
+ * Constructor. Store the subdomain which iterators shall have to be
+ * evaluated to true.
*/
SubdomainEqualTo (const types::subdomain_id subdomain_id);
/**
- * Evaluation operator. Returns true if either the subdomain of
- * the object pointed to is equal to the stored value or the
- * iterator is past the end.
+ * Evaluation operator. Returns true if either the subdomain of the object
+ * pointed to is equal to the stored value or the iterator is past the
+ * end.
*/
template <class Iterator>
bool operator () (const Iterator &i) const;
/**
- * Filter for iterators that evaluates to true if a cell is owned by
- * the current processor, i.e., if it is a @ref
- * GlossLocallyOwnedCell "locally owned cell".
+ * Filter for iterators that evaluates to true if a cell is owned by the
+ * current processor, i.e., if it is a @ref GlossLocallyOwnedCell "locally
+ * owned cell".
*
- * This class is used in step-32, in connection with the methods of
- * the @ref distributed module.
+ * This class is used in step-32, in connection with the methods of the @ref
+ * distributed module.
*
* @ingroup Iterators
*/
/**
- * Filter for iterators that evaluates to true if th level subdomain
- * id of a cell is equal to the current processor id.
+ * Filter for iterators that evaluates to true if th level subdomain id of a
+ * cell is equal to the current processor id.
*
* @ingroup Iterators
*/
{
public:
/**
- * Evaluation operator. Returns true if the level subdomain id of
- * the cell is equal to the current processor id.
+ * Evaluation operator. Returns true if the level subdomain id of the cell
+ * is equal to the current processor id.
*/
template <class Iterator>
bool operator () (const Iterator &i) const;
/**
* This class provides a certain view on a range of triangulation or
- * DoFHandler iterators by only iterating over elements that satisfy a
- * given filter (called a <em>predicate</em>, following the notation
- * of the C++ standard library). Once initialized with a predicate and
- * a value for the iterator, a filtered iterator hops to the next or
- * previous element that satisfies the predicate if operators ++ or --
- * are invoked. Intermediate iterator values that lie in between but
- * do not satisfy the predicate are skipped. It is thus very simple to
- * write loops over a certain class of objects without the need to
- * explicitely write down the condition they have to satisfy in each
- * loop iteration. This in particular is helpful if functions are
- * called with a pair of iterators denoting a range on which they
- * shall act, by choosing a filtered iterator instead of usual ones.
+ * DoFHandler iterators by only iterating over elements that satisfy a given
+ * filter (called a <em>predicate</em>, following the notation of the C++
+ * standard library). Once initialized with a predicate and a value for the
+ * iterator, a filtered iterator hops to the next or previous element that
+ * satisfies the predicate if operators ++ or -- are invoked. Intermediate
+ * iterator values that lie in between but do not satisfy the predicate are
+ * skipped. It is thus very simple to write loops over a certain class of
+ * objects without the need to explicitely write down the condition they have
+ * to satisfy in each loop iteration. This in particular is helpful if
+ * functions are called with a pair of iterators denoting a range on which
+ * they shall act, by choosing a filtered iterator instead of usual ones.
*
- * This class is used in step-18 and
- * step-32.
+ * This class is used in step-18 and step-32.
*
*
* <h3>Predicates</h3>
*
- * The object that represent the condition an iterator has to satisfy
- * only have to provide an interface that allows to call the
- * evaluation operator, i.e. <code>bool operator() (const
- * BaseIterator&)</code>. This includes function pointers as well as
- * classes that implement an <code>bool operator ()(const
- * BaseIterator&)</code>. Then, the FilteredIterator will skip all
+ * The object that represent the condition an iterator has to satisfy only
+ * have to provide an interface that allows to call the evaluation operator,
+ * i.e. <code>bool operator() (const BaseIterator&)</code>. This includes
+ * function pointers as well as classes that implement an <code>bool operator
+ * ()(const BaseIterator&)</code>. Then, the FilteredIterator will skip all
* objects where the return value of this function is <code>false</code>.
*
*
* @code
* std::bind2nd (std::ptr_fun(&level_equal_to<active_cell_iterator>), 3)
* @endcode
- * is another valid predicate (here: a function that returns true if
- * either the iterator is past the end or the level is equal to the
- * second argument; this second argument is bound to a fixed value
- * using the @p std::bind2nd function).
+ * is another valid predicate (here: a function that returns true if either
+ * the iterator is past the end or the level is equal to the second argument;
+ * this second argument is bound to a fixed value using the @p std::bind2nd
+ * function).
*
* Finally, classes can be predicates. The following class is one:
* @code
* }
* };
* @endcode
- * and objects of this type can be used as predicates. Likewise, this
- * more complicated one can also be used:
+ * and objects of this type can be used as predicates. Likewise, this more
+ * complicated one can also be used:
* @code
* class SubdomainEqualTo
* {
* const types::subdomain_id subdomain_id;
* };
* @endcode
- * Objects like <code>SubdomainEqualTo(3)</code> can then be used as predicates.
+ * Objects like <code>SubdomainEqualTo(3)</code> can then be used as
+ * predicates.
*
- * Since whenever a predicate is evaluated it is checked that the
- * iterator checked is actually valid (i.e. not past the end), no
- * checks for this case have to be performed inside predicates.
+ * Since whenever a predicate is evaluated it is checked that the iterator
+ * checked is actually valid (i.e. not past the end), no checks for this case
+ * have to be performed inside predicates.
*
- * A number of filter classes are already implemented in the
- * IteratorFilters namespace, but writing different ones is
- * simple following the examples above.
+ * A number of filter classes are already implemented in the IteratorFilters
+ * namespace, but writing different ones is simple following the examples
+ * above.
*
*
* <h3>Initialization of filtered iterators</h3>
*
- * Filtered iterators are given a predicate at construction time which
- * cannot be changed any more. This behaviour would be expected if the
- * predicate would have been given as a template parameter to the
- * class, but since that would make the declaration of filtered
- * iterators a nightmare, we rather give the predicate as an
- * unchangeable entity to the constructor. Note that one can assign a
- * filtered iterator with one predicate to another filtered iterator
- * with another type; yet, this does <em>not</em> change the predicate
- * of the assigned-to iterator, only the pointer indicating the
+ * Filtered iterators are given a predicate at construction time which cannot
+ * be changed any more. This behaviour would be expected if the predicate
+ * would have been given as a template parameter to the class, but since that
+ * would make the declaration of filtered iterators a nightmare, we rather
+ * give the predicate as an unchangeable entity to the constructor. Note that
+ * one can assign a filtered iterator with one predicate to another filtered
+ * iterator with another type; yet, this does <em>not</em> change the
+ * predicate of the assigned-to iterator, only the pointer indicating the
* iterator is changed.
*
* If a filtered iterator is not assigned a value of the underlying
- * (unfiltered) iterator type, the default value is taken. If,
- * however, a value is given to the constructor, that value has either
- * to be past the end, or has to satisfy the predicate. For example,
- * if the predicate only evaluates to true if the level of an object
- * is equal to three, then <code>tria.begin_active(3)</code> would be a valid
- * choice while <code>tria.begin()</code> would not since the latter also
- * returns iterators to non-active cells which always start at level
- * 0.
+ * (unfiltered) iterator type, the default value is taken. If, however, a
+ * value is given to the constructor, that value has either to be past the
+ * end, or has to satisfy the predicate. For example, if the predicate only
+ * evaluates to true if the level of an object is equal to three, then
+ * <code>tria.begin_active(3)</code> would be a valid choice while
+ * <code>tria.begin()</code> would not since the latter also returns iterators
+ * to non-active cells which always start at level 0.
*
- * Since one often only has some iterator and wants to set a filtered
- * iterator to the first one that satisfies a predicate (for example,
- * the first one for which the user flag is set, or the first one with
- * a given subdomain id), there are assignement functions
- * #set_to_next_positive and #set_to_previous_positive that
- * assign the next or last previous iterator that satisfies the
- * predicate, i.e. they follow the list of iterators in either
- * direction until they find a matching one (or the past-the-end
+ * Since one often only has some iterator and wants to set a filtered iterator
+ * to the first one that satisfies a predicate (for example, the first one for
+ * which the user flag is set, or the first one with a given subdomain id),
+ * there are assignement functions #set_to_next_positive and
+ * #set_to_previous_positive that assign the next or last previous iterator
+ * that satisfies the predicate, i.e. they follow the list of iterators in
+ * either direction until they find a matching one (or the past-the-end
* iterator). Like the <code>operator=</code> they return the resulting value
* of the filtered iterator.
*
*
* <h3>Examples</h3>
*
- * The following call counts the number of active cells that
- * have a set user flag:
+ * The following call counts the number of active cells that have a set user
+ * flag:
* @code
* FilteredIterator<typename Triangulation<dim>::active_cell_iterator>
* begin (IteratorFilters::UserFlagSet()),
* end = tria.end();
* n_flagged_cells = std::distance (begin, end);
* @endcode
- * Note that by the @p set_to_next_positive call the first cell with
- * a set user flag was assigned to the @p begin iterator. For the
- * end iterator, no such call was necessary, since the past-the-end
- * iterator always satisfies all predicates.
+ * Note that by the @p set_to_next_positive call the first cell with a set
+ * user flag was assigned to the @p begin iterator. For the end iterator, no
+ * such call was necessary, since the past-the-end iterator always satisfies
+ * all predicates.
*
* The same can be achieved by the following snippet, though harder to read:
* @code
* .set_to_next_positive(tria.begin_active()),
* FI(IteratorFilters::UserFlagSet(), tria.end()));
* @endcode
- * It relies on the fact that if we create an unnamed filtered
- * iterator with a given predicate but no iterator value and assign it
- * the next positive value with respect to this predicate, it returns
- * itself which is then used as the first parameter to the
- * @p std::distance function. This procedure is not necessary for the
- * end element to this function here, since the past-the-end iterator
- * always satisfies the predicate so that we can assign this value to
+ * It relies on the fact that if we create an unnamed filtered iterator with a
+ * given predicate but no iterator value and assign it the next positive value
+ * with respect to this predicate, it returns itself which is then used as the
+ * first parameter to the @p std::distance function. This procedure is not
+ * necessary for the end element to this function here, since the past-the-end
+ * iterator always satisfies the predicate so that we can assign this value to
* the filtered iterator directly in the constructor.
*
* Finally, the following loop only assembles the matrix on cells with
* assemble_local_matrix (cell);
* @endcode
*
- * Since comparison between filtered and unfiltered iterators is
- * defined, we could as well have let the @p endc variable in the
- * last example be of type
- * Triangulation::active_cell_iterator since it is unchanged
- * and its value does not depend on the filter.
+ * Since comparison between filtered and unfiltered iterators is defined, we
+ * could as well have let the @p endc variable in the last example be of type
+ * Triangulation::active_cell_iterator since it is unchanged and its value
+ * does not depend on the filter.
*
* @ingroup grid
* @ingroup Iterators
{
public:
/**
- * Typedef to the accessor type
- * of the underlying iterator.
+ * Typedef to the accessor type of the underlying iterator.
*/
typedef typename BaseIterator::AccessorType AccessorType;
/**
- * Constructor. Set the iterator
- * to the default state and use
- * the given predicate for
- * filtering subsequent
- * assignement and iteration.
+ * Constructor. Set the iterator to the default state and use the given
+ * predicate for filtering subsequent assignement and iteration.
*/
template <typename Predicate>
FilteredIterator (Predicate p);
/**
- * Constructor. Use the given
- * predicate for filtering and
- * initialize the iterator with
- * the given value.
+ * Constructor. Use the given predicate for filtering and initialize the
+ * iterator with the given value.
*
- * If the initial value @p bi does
- * not satisfy the predicate @p p
- * then it is advanced until we
- * either hit the the
- * past-the-end iterator, or the
- * predicate is satisfied. This
- * allows, for example, to write
- * code like
+ * If the initial value @p bi does not satisfy the predicate @p p then it is
+ * advanced until we either hit the the past-the-end iterator, or the
+ * predicate is satisfied. This allows, for example, to write code like
* @code
* FilteredIterator<typename Triangulation<dim>::active_cell_iterator>
* cell (IteratorFilters::SubdomainEqualTo(13),
* triangulation.begin_active());
* @endcode
*
- * If the cell
- * <code>triangulation.begin_active()</code>
- * does not have a subdomain_id
- * equal to 13, then the iterator
- * will automatically be advanced
- * to the first cell that has.
+ * If the cell <code>triangulation.begin_active()</code> does not have a
+ * subdomain_id equal to 13, then the iterator will automatically be
+ * advanced to the first cell that has.
*/
template <typename Predicate>
FilteredIterator (Predicate p,
const BaseIterator &bi);
/**
- * Copy constructor. Copy the
- * predicate and iterator value
- * of the given argument.
+ * Copy constructor. Copy the predicate and iterator value of the given
+ * argument.
*/
FilteredIterator (const FilteredIterator &fi);
~FilteredIterator ();
/**
- * Assignment operator. Copy the
- * iterator value of the
- * argument, but as discussed in
- * the class documentation, the
- * predicate of the argument is
- * not copied. The iterator value
- * underlying the argument has to
- * satisfy the predicate of the
- * object assigned to, as given
- * at its construction time.
+ * Assignment operator. Copy the iterator value of the argument, but as
+ * discussed in the class documentation, the predicate of the argument is
+ * not copied. The iterator value underlying the argument has to satisfy the
+ * predicate of the object assigned to, as given at its construction time.
*/
FilteredIterator &operator = (const FilteredIterator &fi);
/**
- * Assignment operator. Copy the
- * iterator value of the
- * argument, and keep the
- * predicate of this object. The
- * given iterator value has to
- * satisfy the predicate of the
- * object assigned to, as given
- * at its construction time.
+ * Assignment operator. Copy the iterator value of the argument, and keep
+ * the predicate of this object. The given iterator value has to satisfy the
+ * predicate of the object assigned to, as given at its construction time.
*/
FilteredIterator &operator = (const BaseIterator &fi);
/**
- * Search for the next iterator
- * from @p bi onwards that
- * satisfies the predicate of
- * this object and assign it to
- * this object.
+ * Search for the next iterator from @p bi onwards that satisfies the
+ * predicate of this object and assign it to this object.
*
- * Since filtered iterators are
- * automatically converted to the
- * underlying base iterator type,
- * you can also give a filtered
- * iterator as argument to this
- * function.
+ * Since filtered iterators are automatically converted to the underlying
+ * base iterator type, you can also give a filtered iterator as argument to
+ * this function.
*/
FilteredIterator &
set_to_next_positive (const BaseIterator &bi);
/**
- * As above, but search for the
- * previous iterator from @p bi
- * backwards that satisfies the
- * predicate of this object and
- * assign it to this object.
+ * As above, but search for the previous iterator from @p bi backwards that
+ * satisfies the predicate of this object and assign it to this object.
*
- * Since filtered iterators are
- * automatically converted to the
- * underlying base iterator type,
- * you can also give a filtered
- * iterator as argument to this
- * function.
+ * Since filtered iterators are automatically converted to the underlying
+ * base iterator type, you can also give a filtered iterator as argument to
+ * this function.
*/
FilteredIterator &
set_to_previous_positive (const BaseIterator &bi);
/**
- * Compare for equality of the
- * underlying iterator values of
- * this and the given object.
+ * Compare for equality of the underlying iterator values of this and the
+ * given object.
*
- * We do not compare for equality
- * of the predicates.
+ * We do not compare for equality of the predicates.
*/
bool operator == (const FilteredIterator &fi) const;
/**
- * Compare for equality of the
- * underlying iterator value of
- * this object with the given
- * object.
+ * Compare for equality of the underlying iterator value of this object with
+ * the given object.
*
- * The predicate of this object
- * is irrelevant for this
- * operation.
+ * The predicate of this object is irrelevant for this operation.
*/
bool operator == (const BaseIterator &fi) const;
/**
- * Compare for inequality of the
- * underlying iterator values of
- * this and the given object.
+ * Compare for inequality of the underlying iterator values of this and the
+ * given object.
*
- * We do not compare for equality
- * of the predicates.
+ * We do not compare for equality of the predicates.
*/
bool operator != (const FilteredIterator &fi) const;
/**
- * Compare for inequality of the
- * underlying iterator value of
- * this object with the given
- * object.
+ * Compare for inequality of the underlying iterator value of this object
+ * with the given object.
*
- * The predicate of this object
- * is irrelevant for this
- * operation.
+ * The predicate of this object is irrelevant for this operation.
*/
bool operator != (const BaseIterator &fi) const;
/**
- * Compare for ordering of the
- * underlying iterator values of
- * this and the given object.
+ * Compare for ordering of the underlying iterator values of this and the
+ * given object.
*
- * We do not compare the
- * predicates.
+ * We do not compare the predicates.
*/
bool operator < (const FilteredIterator &fi) const;
/**
- * Compare for ordering of the
- * underlying iterator value of
- * this object with the given
- * object.
+ * Compare for ordering of the underlying iterator value of this object with
+ * the given object.
*
- * The predicate of this object
- * is irrelevant for this
- * operation.
+ * The predicate of this object is irrelevant for this operation.
*/
bool operator < (const BaseIterator &fi) const;
/**
- * Prefix advancement operator:
- * move to the next iterator
- * value satisfying the predicate
- * and return the new iterator
- * value.
+ * Prefix advancement operator: move to the next iterator value satisfying
+ * the predicate and return the new iterator value.
*/
FilteredIterator &operator ++ ();
/**
- * Postfix advancement operator:
- * move to the next iterator
- * value satisfying the predicate
- * and return the old iterator
- * value.
+ * Postfix advancement operator: move to the next iterator value satisfying
+ * the predicate and return the old iterator value.
*/
FilteredIterator operator ++ (int);
/**
- * Prefix decrement operator:
- * move to the previous iterator
- * value satisfying the predicate
- * and return the new iterator
- * value.
+ * Prefix decrement operator: move to the previous iterator value satisfying
+ * the predicate and return the new iterator value.
*/
FilteredIterator &operator -- ();
/**
- * Postfix advancement operator:
- * move to the previous iterator
- * value satisfying the predicate
- * and return the old iterator
- * value.
+ * Postfix advancement operator: move to the previous iterator value
+ * satisfying the predicate and return the old iterator value.
*/
FilteredIterator operator -- (int);
private:
/**
- * Base class to encapsulate a
- * predicate object. Since
- * predicates can be of different
- * types and we do not want to
- * code these types into the
- * template parameter list of the
- * filtered iterator class, we
- * use a base class with an
- * abstract function and
- * templatized derived classes
- * that implement the use of
- * actual predicate types through
- * the virtual function.
+ * Base class to encapsulate a predicate object. Since predicates can be of
+ * different types and we do not want to code these types into the template
+ * parameter list of the filtered iterator class, we use a base class with
+ * an abstract function and templatized derived classes that implement the
+ * use of actual predicate types through the virtual function.
*
* @ingroup Iterators
*/
{
public:
/**
- * Mark the destructor
- * virtual to allow
- * destruction through
- * pointers to the base
- * class.
+ * Mark the destructor virtual to allow destruction through pointers to
+ * the base class.
*/
virtual ~PredicateBase () {}
/**
- * Abstract function which in
- * derived classes denotes
- * the evaluation of the
- * predicate on the give
- * iterator.
+ * Abstract function which in derived classes denotes the evaluation of
+ * the predicate on the give iterator.
*/
virtual bool operator () (const BaseIterator &bi) const = 0;
/**
- * Generate a copy of this
- * object, i.e. of the actual
- * type of this pointer.
+ * Generate a copy of this object, i.e. of the actual type of this
+ * pointer.
*/
virtual PredicateBase *clone () const = 0;
};
/**
- * Actual implementation of the
- * above abstract base class. Use
- * a template parameter to denote
- * the actual type of the
- * predicate and store a copy of
- * it. When the virtual function
- * is called evaluate the given
- * iterator with the stored copy
- * of the predicate.
+ * Actual implementation of the above abstract base class. Use a template
+ * parameter to denote the actual type of the predicate and store a copy of
+ * it. When the virtual function is called evaluate the given iterator with
+ * the stored copy of the predicate.
*
* @ingroup Iterators
*/
{
public:
/**
- * Constructor. Take a
- * predicate and store a copy
- * of it.
+ * Constructor. Take a predicate and store a copy of it.
*/
PredicateTemplate (const Predicate &predicate);
/**
- * Evaluate the iterator with
- * the stored copy of the
- * predicate.
+ * Evaluate the iterator with the stored copy of the predicate.
*/
virtual bool operator () (const BaseIterator &bi) const;
/**
- * Generate a copy of this
- * object, i.e. of the actual
- * type of this pointer.
+ * Generate a copy of this object, i.e. of the actual type of this
+ * pointer.
*/
virtual PredicateBase *clone () const;
};
/**
- * Pointer to an object that
- * encapsulated the actual data
- * type of the predicate given to
- * the constructor.
+ * Pointer to an object that encapsulated the actual data type of the
+ * predicate given to the constructor.
*/
const PredicateBase *predicate;
/**
- * Create an object of type FilteredIterator given the base iterator
- * and predicate. This function makes the creation of temporary
- * objects (for example as function arguments) a lot simpler because
- * one does not have to explicitly specify the type of the base
- * iterator by hand -- it is deduced automatically here.
+ * Create an object of type FilteredIterator given the base iterator and
+ * predicate. This function makes the creation of temporary objects (for
+ * example as function arguments) a lot simpler because one does not have to
+ * explicitly specify the type of the base iterator by hand -- it is deduced
+ * automatically here.
*
- * @author Wolfgang Bangerth
- * @relates FilteredIterator
+ * @author Wolfgang Bangerth @relates FilteredIterator
*/
template <typename BaseIterator, typename Predicate>
FilteredIterator<BaseIterator>
* This namespace provides a collection of functions for generating
* triangulations for some basic geometries.
*
- * Some of these functions receive a flag @p colorize. If this is
- * set, parts of the boundary receive different boundary indicators
- * (@ref GlossBoundaryIndicator),
- * allowing them to be distinguished for the purpose of attaching geometry
- * objects and evaluating different boundary conditions.
+ * Some of these functions receive a flag @p colorize. If this is set, parts
+ * of the boundary receive different boundary indicators (@ref
+ * GlossBoundaryIndicator), allowing them to be distinguished for the purpose
+ * of attaching geometry objects and evaluating different boundary conditions.
*
* This namespace also provides a function
* GridGenerator::laplace_transformation that smoothly transforms a domain
- * into another one. This can be used to
- * transform basic geometries to more complicated ones, like a
- * shell to a grid of an airfoil, for example.
+ * into another one. This can be used to transform basic geometries to more
+ * complicated ones, like a shell to a grid of an airfoil, for example.
*
* @ingroup grid
*/
*/
/**
- * Initialize the given triangulation with a hypercube (line in 1D,
- * square in 2D, etc) consisting of exactly one cell. The hypercube
- * volume is the tensor product interval
- * $[left,right]^{\text{dim}}$ in the present number of
- * dimensions, where the limits are given as arguments. They default
- * to zero and unity, then producing the unit hypercube. If the
- * argument `colorize` is false, all boundary indicators are set to
- * zero ("not colorized") for 2d and 3d. If it is true, the boundary
- * is colorized as in hyper_rectangle(). In 1d the indicators are
- * always colorized, see hyper_rectangle().
+ * Initialize the given triangulation with a hypercube (line in 1D, square
+ * in 2D, etc) consisting of exactly one cell. The hypercube volume is the
+ * tensor product interval $[left,right]^{\text{dim}}$ in the present number
+ * of dimensions, where the limits are given as arguments. They default to
+ * zero and unity, then producing the unit hypercube. If the argument
+ * `colorize` is false, all boundary indicators are set to zero ("not
+ * colorized") for 2d and 3d. If it is true, the boundary is colorized as in
+ * hyper_rectangle(). In 1d the indicators are always colorized, see
+ * hyper_rectangle().
*
* @image html hyper_cubes.png
*
* material_id argument is a dim-dimensional array that, for each cell,
* indicates which material_id should be set. In addition, and this is the
* major new functionality, if the material_id of a cell is <tt>(unsigned
- * char)(-1)</tt>, then that cell is deleted from the triangulation,
- * i.e. the domain will have a void there.
+ * char)(-1)</tt>, then that cell is deleted from the triangulation, i.e.
+ * the domain will have a void there.
*/
template <int dim>
void
const bool colorize=false) DEAL_II_DEPRECATED;
/**
- * A parallelepiped. The first corner point is the origin. The
- * <tt>dim</tt> adjacent points are vectors describing the edges of
- * the parallelepiped with respect to the origin. Additional points
- * are sums of these dim vectors. Colorizing is done according to
- * hyper_rectangle().
+ * A parallelepiped. The first corner point is the origin. The <tt>dim</tt>
+ * adjacent points are vectors describing the edges of the parallelepiped
+ * with respect to the origin. Additional points are sums of these dim
+ * vectors. Colorizing is done according to hyper_rectangle().
*
- * @note This function silently reorders the vertices on the cells
- * to lexiographic ordering (see
- * <code>GridReordering::reorder_grid</code>). In other words, if
- * reodering of the vertices does occur, the ordering of vertices in
- * the array of <code>corners</code> will no longer refer to the
+ * @note This function silently reorders the vertices on the cells to
+ * lexiographic ordering (see <code>GridReordering::reorder_grid</code>). In
+ * other words, if reodering of the vertices does occur, the ordering of
+ * vertices in the array of <code>corners</code> will no longer refer to the
* same triangulation.
*
- * @note The triangulation needs to be void upon calling this
- * function.
+ * @note The triangulation needs to be void upon calling this function.
*/
template <int dim>
void
const bool colorize = false);
/**
- * A subdivided parallelepiped. The first corner point is the
- * origin. The <tt>dim</tt> adjacent points are vectors describing
- * the edges of the parallelepiped with respect to the
- * origin. Additional points are sums of these dim vectors. The
- * variable @p n_subdivisions designates the number of subdivisions
- * in each of the <tt>dim</tt> directions. Colorizing is done
- * according to hyper_rectangle().
+ * A subdivided parallelepiped. The first corner point is the origin. The
+ * <tt>dim</tt> adjacent points are vectors describing the edges of the
+ * parallelepiped with respect to the origin. Additional points are sums of
+ * these dim vectors. The variable @p n_subdivisions designates the number
+ * of subdivisions in each of the <tt>dim</tt> directions. Colorizing is
+ * done according to hyper_rectangle().
*
- * @note The triangulation needs to be void upon calling this
- * function.
+ * @note The triangulation needs to be void upon calling this function.
*/
template <int dim>
void
const bool colorize = false);
/**
- * A subdivided parallelepiped, ie. the same as above, but where the
- * number of subdivisions in each of the <tt>dim</tt> directions may
- * vary. Colorizing is done according to hyper_rectangle().
+ * A subdivided parallelepiped, ie. the same as above, but where the number
+ * of subdivisions in each of the <tt>dim</tt> directions may vary.
+ * Colorizing is done according to hyper_rectangle().
*
- * @note The triangulation needs to be void upon calling this
- * function.
+ * @note The triangulation needs to be void upon calling this function.
*/
template <int dim>
void
/**
* Initialize the given triangulation with a hyper-L (in 2d or 3d)
- * consisting of exactly
- * <tt>2^dim-1</tt> cells. It produces the hypercube with the interval
- * [<i>left,right</i>] without the hypercube made out of the interval
- * [<i>(a+b)/2,b</i>]. This will result in the classical L-shape in 2d.
- * The shape will look like the following in 3d:
+ * consisting of exactly <tt>2^dim-1</tt> cells. It produces the hypercube
+ * with the interval [<i>left,right</i>] without the hypercube made out of
+ * the interval [<i>(a+b)/2,b</i>]. This will result in the classical
+ * L-shape in 2d. The shape will look like the following in 3d:
*
* @image html hyper_l.png
*
* y=left</tt> to the center of the square at <tt>x=y=(left+right)/2</tt>.
*
* In 3d, the 2d domain is just extended in the <i>z</i>-direction, such
- * that a plane cuts the lower half of a rectangle in two.
-
- * This function is declared to exist for triangulations of all space
- * dimensions, but throws an error if called in 1d.
+ * that a plane cuts the lower half of a rectangle in two. This function is
+ * declared to exist for triangulations of all space dimensions, but throws
+ * an error if called in 1d.
*
* @note The triangulation needs to be void upon calling this function.
*/
* is zero (as is the default), then it is computed adaptively such that the
* resulting elements have the least aspect ratio.
*
- * In 3d, only certain numbers are allowed, 6 for a surface based
- * on a hexahedron (i.e. 6 panels on the inner sphere extruded in radial
+ * In 3d, only certain numbers are allowed, 6 for a surface based on a
+ * hexahedron (i.e. 6 panels on the inner sphere extruded in radial
* direction to form 6 cells), 12 for the rhombic dodecahedron, and 96 (see
* below). These give rise to the following meshes upon one refinement:
*
- * @image html hypershell3d-6.png
- * @image html hypershell3d-12.png
+ * @image html hypershell3d-6.png @image html hypershell3d-12.png
*
* Neither of these meshes is particularly good since one ends up with
* poorly shaped cells at the inner edge upon refinement. For example, this
* that the doubled radial lines on the cross section are artifacts of the
* visualization):
*
- * @image html hyper_shell_12_cut.png
- * @image html hyper_shell_96_cut.png
+ * @image html hyper_shell_12_cut.png @image html hyper_shell_96_cut.png
*
- * A different way to approach the problem with distorted cells
- * is to attach appropriate manifold descriptions to the geometry created
- * by this function. In the current context, this would involve the
+ * A different way to approach the problem with distorted cells is to attach
+ * appropriate manifold descriptions to the geometry created by this
+ * function. In the current context, this would involve the
* SphericalManifold class. An example of how this works and what it leads
- * to is shown in the documentation of the
- * @ref manifold "documentation module on manifolds".
+ * to is shown in the documentation of the @ref manifold "documentation
+ * module on manifolds".
*
* @note This function is declared to exist for triangulations of all space
* dimensions, but throws an error if called in 1d.
* @param R The radius of the circle, which forms the middle line of the
* torus containing the loop of cells. Must be greater than @p r.
*
- * @param r The inner radius of the
- * torus.
+ * @param r The inner radius of the torus.
*/
void torus (Triangulation<2,3> &tria,
const double R,
* in the middle. Square and circle are centered at the origin. In 3d, this
* geometry is extruded in $z$ direction to the interval $[0,L]$.
*
- * @image html cubes_hole.png
+ * @image html cubes_hole.png
*
* It is implemented in 2d and 3d, and takes the following arguments:
*
- * @arg @p inner_radius: radius of the
- * internal hole
- * @arg @p outer_radius: half of the edge length of the square
- * @arg @p L: extension in @p z-direction (only used in 3d)
- * @arg @p repetitions: number of subdivisions
- * along the @p z-direction
- * @arg @p colorize: whether to assign different
- * boundary indicators to different faces.
- * The colors are given in lexicographic
- * ordering for the flat faces (0 to 3 in 2d,
- * 0 to 5 in 3d) plus the curved hole
- * (4 in 2d, and 6 in 3d).
- * If @p colorize is set to false, then flat faces
- * get the number 0 and the hole gets number 1.
+ * @arg @p inner_radius: radius of the internal hole @arg @p outer_radius:
+ * half of the edge length of the square @arg @p L: extension in @p
+ * z-direction (only used in 3d) @arg @p repetitions: number of subdivisions
+ * along the @p z-direction @arg @p colorize: whether to assign different
+ * boundary indicators to different faces. The colors are given in
+ * lexicographic ordering for the flat faces (0 to 3 in 2d, 0 to 5 in 3d)
+ * plus the curved hole (4 in 2d, and 6 in 3d). If @p colorize is set to
+ * false, then flat faces get the number 0 and the hole gets number 1.
*/
template<int dim>
void hyper_cube_with_cylindrical_hole (
* together again. This results in a kind of moebius-loop.
*
* @param tria The triangulation to be worked on.
- * @param n_cells The number of cells in the loop. Must be greater than 4.
- * @param n_rotations The number of rotations (Pi/2 each) to be performed before glueing the loop together.
- * @param R The radius of the circle, which forms the middle line of the torus containing the loop of cells. Must be greater than @p r.
+ * @param n_cells The number of cells in the loop. Must be greater than
+ * 4.
+ * @param n_rotations The number of rotations (Pi/2 each) to be performed
+ * before glueing the loop together.
+ * @param R The radius of the circle, which forms the middle line
+ * of the torus containing the loop of cells. Must be greater than @p r.
* @param r The radius of the cylinder bend together as loop.
*/
void moebius (Triangulation<3,3> &tria,
Triangulation<dim, spacedim> &result);
/**
- * Given the two triangulations
- * specified as the first two
- * arguments, create the
- * triangulation that contains
- * the finest cells of both
- * triangulation and store it in
- * the third parameter. Previous
- * content of @p result will be
- * deleted.
- *
- * @note This function is intended
- * to create an adaptively refined
- * triangulation that contains the
- * <i>most refined cells</i> from
- * two input triangulations that
- * were derived from the <i>same</i>
- * coarse grid by adaptive refinement.
- * This is an operation sometimes
- * needed when one solves for two
- * variables of a coupled problem
- * on separately refined meshes on
- * the same domain (for example
- * because these variables have
- * boundary layers in different places)
- * but then needs to compute something
- * that involves both variables or
- * wants to output the result into a
- * single file. In both cases, in
- * order not to lose information,
- * the two solutions can not be
- * interpolated onto the respectively
- * other mesh because that may be
- * coarser than the ones on which
- * the variable was computed. Rather,
- * one needs to have a mesh for the
- * domain that is at least as fine
- * as each of the two initial meshes.
- * This function computes such a mesh.
- *
- * @note If you want to create
- * a mesh that is the merger of
- * two other coarse meshes, for
- * example in order to compose a mesh
- * for a complicated geometry from
- * meshes for simpler geometries,
- * then this is not the function for you. Instead, consider
- * GridGenerator::merge_triangulations().
+ * Given the two triangulations specified as the first two arguments, create
+ * the triangulation that contains the finest cells of both triangulation
+ * and store it in the third parameter. Previous content of @p result will
+ * be deleted.
+ *
+ * @note This function is intended to create an adaptively refined
+ * triangulation that contains the <i>most refined cells</i> from two input
+ * triangulations that were derived from the <i>same</i> coarse grid by
+ * adaptive refinement. This is an operation sometimes needed when one
+ * solves for two variables of a coupled problem on separately refined
+ * meshes on the same domain (for example because these variables have
+ * boundary layers in different places) but then needs to compute something
+ * that involves both variables or wants to output the result into a single
+ * file. In both cases, in order not to lose information, the two solutions
+ * can not be interpolated onto the respectively other mesh because that may
+ * be coarser than the ones on which the variable was computed. Rather, one
+ * needs to have a mesh for the domain that is at least as fine as each of
+ * the two initial meshes. This function computes such a mesh.
+ *
+ * @note If you want to create a mesh that is the merger of two other coarse
+ * meshes, for example in order to compose a mesh for a complicated geometry
+ * from meshes for simpler geometries, then this is not the function for
+ * you. Instead, consider GridGenerator::merge_triangulations().
*/
template <int dim, int spacedim>
void
/**
- * Take a 2d Triangulation that is being extruded in z direction
- * by the total height of @p height using @p n_slices slices (minimum is 2).
- * The boundary indicators of the faces of @p input are going to be assigned
- * to the corresponding side walls in z direction. The bottom and top
- * get the next two free boundary indicators.
+ * Take a 2d Triangulation that is being extruded in z direction by the
+ * total height of @p height using @p n_slices slices (minimum is 2). The
+ * boundary indicators of the faces of @p input are going to be assigned to
+ * the corresponding side walls in z direction. The bottom and top get the
+ * next two free boundary indicators.
*/
void
extrude_triangulation (const Triangulation<2, 2> &input,
Triangulation<3,3> &result);
/**
- * Given an input triangulation @p in_tria, this function makes a new
- * flat triangulation @p out_tria which contains a single level with
- * all active cells of the input triangulation. If spacedim1 and
- * spacedim2 are different, only the smallest spacedim components of
- * the vertices are copied over. This is useful to create a
- * Triangulation<2,3> out of a Triangulation<2,2>, or to project a
- * Triangulation<2,3> into a Triangulation<2,2>, by neglecting the z
- * components of the vertices.
+ * Given an input triangulation @p in_tria, this function makes a new flat
+ * triangulation @p out_tria which contains a single level with all active
+ * cells of the input triangulation. If spacedim1 and spacedim2 are
+ * different, only the smallest spacedim components of the vertices are
+ * copied over. This is useful to create a Triangulation<2,3> out of a
+ * Triangulation<2,2>, or to project a Triangulation<2,3> into a
+ * Triangulation<2,2>, by neglecting the z components of the vertices.
*
- * No internal checks are performed on the vertices, which are
- * assumed to make sense topologically in the target #spacedim2
- * dimensional space. If this is not the case, you will encounter
- * problems when using the triangulation later on.
+ * No internal checks are performed on the vertices, which are assumed to
+ * make sense topologically in the target #spacedim2 dimensional space. If
+ * this is not the case, you will encounter problems when using the
+ * triangulation later on.
*
- * All informations about cell manifold_ids and material ids are
- * copied from one triangulation to the other, and only the boundary
- * manifold_ids and boundary_ids are copied over from the faces of
- * @p in_tria to the faces of @p out_tria. If you need to specify
- * manifold ids on interior faces, they have to be specified
- * manually after the triangulation is created.
+ * All informations about cell manifold_ids and material ids are copied from
+ * one triangulation to the other, and only the boundary manifold_ids and
+ * boundary_ids are copied over from the faces of @p in_tria to the faces of
+ * @p out_tria. If you need to specify manifold ids on interior faces, they
+ * have to be specified manually after the triangulation is created.
*
* This function will fail if the input Triangulation is of type
* parallel::distributed::Triangulation, as well as when the input
*/
/**
- * @name Creating lower-dimensional meshes from parts of higher-dimensional meshes
+ * @name Creating lower-dimensional meshes from parts of higher-dimensional
+ * meshes
* @{
*/
#endif
/**
- * This function implements a boundary
- * subgrid extraction. Given a
- * <dim,spacedim>-Triangulation (the
- * "volume mesh") the function extracts a
- * subset of its boundary (the "surface
- * mesh"). The boundary to be extracted
- * is specified by a list of
- * boundary_ids. If none is specified
- * the whole boundary will be
- * extracted. The function is used in
- * step-38.
- *
- * The function also builds a mapping linking the
- * cells on the surface mesh to the
- * corresponding faces on the volume
- * one. This mapping is the return value
- * of the function.
- *
- * @note The function builds the surface
- * mesh by creating a coarse mesh from
- * the selected faces of the coarse cells
- * of the volume mesh. It copies the
- * boundary indicators of these faces to
- * the cells of the coarse surface
- * mesh. The surface mesh is then refined
- * in the same way as the faces of the
- * volume mesh are. In order to ensure
- * that the surface mesh has the same
- * vertices as the volume mesh, it is
- * therefore important that you assign
- * appropriate boundary objects through
- * Triangulation::set_boundary to the
- * surface mesh object before calling
- * this function. If you don't, the
- * refinement will happen under the
- * assumption that all faces are straight
- * (i.e using the StraightBoundary class)
- * rather than any curved boundary object
- * you may want to use to determine the
- * location of new vertices.
- *
- *
- * @tparam Container A type that satisfies the
- * requirements of a mesh container (see @ref GlossMeshAsAContainer).
- * The map that is returned will
- * be between cell
- * iterators pointing into the container describing the surface mesh
- * and face
- * iterators of the volume
- * mesh container. If the Container argument is
- * DoFHandler of hp::DoFHandler, then
- * the function will
- * re-build the triangulation
- * underlying the second argument
- * and return a map between
- * appropriate iterators into the Container arguments. However,
- * the function will not actually
- * distribute degrees of freedom
- * on this newly created surface
- * mesh.
- *
- * @note The algorithm outlined
- * above assumes that all faces
- * on higher refinement levels
- * always have exactly the same
- * boundary indicator as their
- * parent face. Consequently, we
- * can start with coarse level
- * faces and build the surface
- * mesh based on that. It would
- * not be very difficult to
- * extend the function to also
- * copy boundary indicators from
- * finer level faces to their
- * corresponding surface mesh
- * cells, for example to
- * accommodate different geometry
- * descriptions in the case of
- * curved boundaries.
+ * This function implements a boundary subgrid extraction. Given a
+ * <dim,spacedim>-Triangulation (the "volume mesh") the function extracts a
+ * subset of its boundary (the "surface mesh"). The boundary to be
+ * extracted is specified by a list of boundary_ids. If none is specified
+ * the whole boundary will be extracted. The function is used in step-38.
+ *
+ * The function also builds a mapping linking the cells on the surface mesh
+ * to the corresponding faces on the volume one. This mapping is the return
+ * value of the function.
+ *
+ * @note The function builds the surface mesh by creating a coarse mesh from
+ * the selected faces of the coarse cells of the volume mesh. It copies the
+ * boundary indicators of these faces to the cells of the coarse surface
+ * mesh. The surface mesh is then refined in the same way as the faces of
+ * the volume mesh are. In order to ensure that the surface mesh has the
+ * same vertices as the volume mesh, it is therefore important that you
+ * assign appropriate boundary objects through Triangulation::set_boundary
+ * to the surface mesh object before calling this function. If you don't,
+ * the refinement will happen under the assumption that all faces are
+ * straight (i.e using the StraightBoundary class) rather than any curved
+ * boundary object you may want to use to determine the location of new
+ * vertices.
+ *
+ *
+ * @tparam Container A type that satisfies the requirements of a mesh
+ * container (see @ref GlossMeshAsAContainer). The map that is returned will
+ * be between cell iterators pointing into the container describing the
+ * surface mesh and face iterators of the volume mesh container. If the
+ * Container argument is DoFHandler of hp::DoFHandler, then the function
+ * will re-build the triangulation underlying the second argument and return
+ * a map between appropriate iterators into the Container arguments.
+ * However, the function will not actually distribute degrees of freedom on
+ * this newly created surface mesh.
+ *
+ * @note The algorithm outlined above assumes that all faces on higher
+ * refinement levels always have exactly the same boundary indicator as
+ * their parent face. Consequently, we can start with coarse level faces and
+ * build the surface mesh based on that. It would not be very difficult to
+ * extend the function to also copy boundary indicators from finer level
+ * faces to their corresponding surface mesh cells, for example to
+ * accommodate different geometry descriptions in the case of curved
+ * boundaries.
*/
template <template <int,int> class Container, int dim, int spacedim>
#ifndef _MSC_VER
/**
* This function transforms the @p Triangulation @p tria smoothly to a
- * domain that is described by the boundary points in the map @p
- * new_points. This map maps the point indices to the boundary points in the
- * transformed domain.
+ * domain that is described by the boundary points in the map @p new_points.
+ * This map maps the point indices to the boundary points in the transformed
+ * domain.
*
* Note, that the @p Triangulation is changed in-place, therefore you don't
* need to keep two triangulations, but the given triangulation is changed
*
* In 1d, this function is not currently implemented.
*
- * An optional @p coefficient for the Laplace problem an be used to control the amount of
- * mesh deformation in different parts of the domain.
- * Larger values make cells less prone to deformation (effectively increasing their stiffness).
- * The coefficient is evaluated in the coordinate system of the old,
- * undeformed configuration of the triangulation as input, i.e., before
- * the transformation is applied.
- * Should this function be provided, sensible results can only be expected if
- * all coefficients are positive.
+ * An optional @p coefficient for the Laplace problem an be used to control
+ * the amount of mesh deformation in different parts of the domain. Larger
+ * values make cells less prone to deformation (effectively increasing their
+ * stiffness). The coefficient is evaluated in the coordinate system of the
+ * old, undeformed configuration of the triangulation as input, i.e., before
+ * the transformation is applied. Should this function be provided, sensible
+ * results can only be expected if all coefficients are positive.
*
* @deprecated This function has been moved to GridTools::laplace_transform
*/
/**
* This class implements an input mechanism for grid data. It allows to read a
* grid structure into a triangulation object. At present, UCD (unstructured
- * cell data), DB Mesh, XDA, Gmsh, Tecplot, NetCDF, UNV, VTK, and Cubit are supported as
- * input format for grid data. Any numerical data other than geometric
- * (vertex locations) and topological (how vertices form cells) information is
- * ignored.
+ * cell data), DB Mesh, XDA, Gmsh, Tecplot, NetCDF, UNV, VTK, and Cubit are
+ * supported as input format for grid data. Any numerical data other than
+ * geometric (vertex locations) and topological (how vertices form cells)
+ * information is ignored.
*
- * @note Since deal.II only supports line, quadrilateral and hexahedral meshes,
- * the functions in this class can only read meshes that consist exclusively
- * of such cells. If you absolutely need to work with a mesh that uses triangles
- * or tetrahedra, then your only option is to convert the mesh to quadrilaterals
- * and hexahedra. A tool that can do this is tethex, see
+ * @note Since deal.II only supports line, quadrilateral and hexahedral
+ * meshes, the functions in this class can only read meshes that consist
+ * exclusively of such cells. If you absolutely need to work with a mesh that
+ * uses triangles or tetrahedra, then your only option is to convert the mesh
+ * to quadrilaterals and hexahedra. A tool that can do this is tethex, see
* http://code.google.com/p/tethex/wiki/Tethex .
*
- * The mesh you read will form the coarsest level of a @p Triangulation object.
- * As such, it must not contain hanging nodes or other forms or adaptive
- * refinement and strange things will happen if the mesh represented by the
- * input file does in fact have them. This
- * is due to the fact that most mesh description formats do not store
- * neighborship information between cells, so the grid reading functions have
- * to regenerate it. They do so by checking whether two cells have a common
- * face. If there are hanging nodes in a triangulation, adjacent cells have no
- * common (complete) face, so the grid reader concludes that the adjacent
- * cells have no neighbors along these faces and must therefore be at the
- * boundary. In effect, an internal crack of the domain is introduced this
- * way. Since such cases are very hard to detect (how is GridIn supposed to
- * decide whether a place where the faces of two small cells coincide with
- * the face or a larger cell is in fact a hanging node associated with local
- * refinement, or is indeed meant to be a crack in the domain?), the library
- * does not make any attempt to catch such situations, and you will get a triangulation
- * that probably does not do what you want. If your goal is to save and later
- * read again a triangulation that has been adaptively refined, then this
- * class is not your solution; rather take a look at the
- * PersistentTriangulation class.
+ * The mesh you read will form the coarsest level of a @p Triangulation
+ * object. As such, it must not contain hanging nodes or other forms or
+ * adaptive refinement and strange things will happen if the mesh represented
+ * by the input file does in fact have them. This is due to the fact that most
+ * mesh description formats do not store neighborship information between
+ * cells, so the grid reading functions have to regenerate it. They do so by
+ * checking whether two cells have a common face. If there are hanging nodes
+ * in a triangulation, adjacent cells have no common (complete) face, so the
+ * grid reader concludes that the adjacent cells have no neighbors along these
+ * faces and must therefore be at the boundary. In effect, an internal crack
+ * of the domain is introduced this way. Since such cases are very hard to
+ * detect (how is GridIn supposed to decide whether a place where the faces of
+ * two small cells coincide with the face or a larger cell is in fact a
+ * hanging node associated with local refinement, or is indeed meant to be a
+ * crack in the domain?), the library does not make any attempt to catch such
+ * situations, and you will get a triangulation that probably does not do what
+ * you want. If your goal is to save and later read again a triangulation that
+ * has been adaptively refined, then this class is not your solution; rather
+ * take a look at the PersistentTriangulation class.
*
* @note It is not uncommon to experience unexpected problems when reading
* generated meshes for the first time using this class. If this applies to
- * you, be sure to read the documentation right until the end, and
- * also read the documentation of the GridReordering class.
+ * you, be sure to read the documentation right until the end, and also read
+ * the documentation of the GridReordering class.
*
- * To read grid data, the triangulation to be fed with has to be empty.
- * When giving a file which does not contain the assumed information or
- * which does not keep to the right format, the state of the triangulation
- * will be undefined afterwards. Upon input, only lines in one dimension
- * and line and quads in two dimensions are accepted. All other cell types
- * (e.g. triangles in two dimensions, quads and hexes in 3d) are rejected.
- * The vertex and cell numbering in the input file, which
- * need not be consecutively, is lost upon transfer to the triangulation
- * object, since this one needs consecutively numbered elements.
+ * To read grid data, the triangulation to be fed with has to be empty. When
+ * giving a file which does not contain the assumed information or which does
+ * not keep to the right format, the state of the triangulation will be
+ * undefined afterwards. Upon input, only lines in one dimension and line and
+ * quads in two dimensions are accepted. All other cell types (e.g. triangles
+ * in two dimensions, quads and hexes in 3d) are rejected. The vertex and cell
+ * numbering in the input file, which need not be consecutively, is lost upon
+ * transfer to the triangulation object, since this one needs consecutively
+ * numbered elements.
*
- * Material indicators are accepted to denote the material ID of cells and
- * to denote boundary part indication for lines in 2D. Read the according
- * sections in the documentation of the Triangulation class for
- * further details.
+ * Material indicators are accepted to denote the material ID of cells and to
+ * denote boundary part indication for lines in 2D. Read the according
+ * sections in the documentation of the Triangulation class for further
+ * details.
*
*
* <h3>Supported input formats</h3>
*
* At present, the following input formats are supported:
* <ul>
- * <li> @p UCD (unstructured cell data) format: this format is used
- * for grid input as well as data output. If there are data vectors in
- * the input file, they are ignored, as we are only interested in the
- * grid in this class. The UCD format requires the vertices to be
- * in following ordering: in 2d
+ * <li> @p UCD (unstructured cell data) format: this format is used for grid
+ * input as well as data output. If there are data vectors in the input file,
+ * they are ignored, as we are only interested in the grid in this class. The
+ * UCD format requires the vertices to be in following ordering: in 2d
* @verbatim
* 3-----2
* | |
* |/ / | |/
* 0-------1 0-------1
* @endverbatim
- * Note, that this ordering is different from the deal.II numbering
- * scheme, see the Triangulation class. The exact description of the
- * UCD format can be found in the AVS Explorer manual (see
- * http://www.avs.com). The @p UCD format can be read by the
- * read_ucd() function.
+ * Note, that this ordering is different from the deal.II numbering scheme,
+ * see the Triangulation class. The exact description of the UCD format can
+ * be found in the AVS Explorer manual (see http://www.avs.com). The @p UCD
+ * format can be read by the read_ucd() function.
*
* <li> <tt>DB mesh</tt> format: this format is used by the @p BAMG mesh
- * generator (see
- * http://www-rocq.inria.fr/gamma/cdrom/www/bamg/eng.htm. The
- * documentation of the format in the @p BAMG manual is very
- * incomplete, so we don't actually parse many of the fields of the
- * output since we don't know their meaning, but the data that is read
- * is enough to build up the mesh as intended by the mesh generator.
- * This format can be read by the read_dbmesh() function.
+ * generator (see http://www-rocq.inria.fr/gamma/cdrom/www/bamg/eng.htm. The
+ * documentation of the format in the @p BAMG manual is very incomplete, so we
+ * don't actually parse many of the fields of the output since we don't know
+ * their meaning, but the data that is read is enough to build up the mesh as
+ * intended by the mesh generator. This format can be read by the
+ * read_dbmesh() function.
*
- * <li> @p XDA format: this is a rather simple format used by the MGF
- * code. We don't have an exact specification of the format, but the reader
- * can read in several example files. If the reader does not grok your files,
- * it should be fairly simple to extend it.
+ * <li> @p XDA format: this is a rather simple format used by the MGF code. We
+ * don't have an exact specification of the format, but the reader can read in
+ * several example files. If the reader does not grok your files, it should be
+ * fairly simple to extend it.
*
- * <li> <tt>Gmsh 1.0 mesh</tt> format: this format is used by the @p
- * GMSH mesh generator (see http://www.geuz.org/gmsh/ ). The
- * documentation in the @p GMSH manual explains how to generate meshes
- * compatible with the deal.II library (i.e. quads rather than
- * triangles). In order to use this format, Gmsh has to output the
- * file in the old format 1.0. This is done adding the line
- * "Mesh.MshFileVersion = 1" to the input file.
+ * <li> <tt>Gmsh 1.0 mesh</tt> format: this format is used by the @p GMSH mesh
+ * generator (see http://www.geuz.org/gmsh/ ). The documentation in the @p
+ * GMSH manual explains how to generate meshes compatible with the deal.II
+ * library (i.e. quads rather than triangles). In order to use this format,
+ * Gmsh has to output the file in the old format 1.0. This is done adding the
+ * line "Mesh.MshFileVersion = 1" to the input file.
*
* <li> <tt>Gmsh 2.0 mesh</tt> format: this is a variant of the above format.
- * The read_msh() function automatically determines whether an input file
- * is version 1 or version 2.
+ * The read_msh() function automatically determines whether an input file is
+ * version 1 or version 2.
*
* <li> <tt>Tecplot</tt> format: this format is used by @p TECPLOT and often
* serves as a basis for data exchange between different applications. Note,
* read.
*
* <li> <tt>UNV</tt> format: this format is generated by the Salome mesh
- * generator, see http://www.salome-platform.org/ .
- * The sections of the format that the GridIn::read_unv function supports are
- * documented here:
+ * generator, see http://www.salome-platform.org/ . The sections of the format
+ * that the GridIn::read_unv function supports are documented here:
* <ul>
- * <li> section 2411: http://www.sdrl.uc.edu/universal-file-formats-for-modal-analysis-testing-1/file-format-storehouse/unv_2411.htm
- * <li> section 2412: http://www.sdrl.uc.edu/universal-file-formats-for-modal-analysis-testing-1/file-format-storehouse/unv_2412.htm
- * <li> section 2467: http://www.sdrl.uc.edu/universal-file-formats-for-modal-analysis-testing-1/file-format-storehouse/unv_2467.htm
- * <li> all sections of this format, even if they may not be supported in
- * our reader, can be found here:
- * http://www.sdrl.uc.edu/universal-file-formats-for-modal-analysis-testing-1/file-format-storehouse/file-formats
+ * <li> section 2411: http://www.sdrl.uc.edu/universal-file-formats-for-modal-
+ * analysis-testing-1/file-format-storehouse/unv_2411.htm
+ * <li> section 2412: http://www.sdrl.uc.edu/universal-file-formats-for-modal-
+ * analysis-testing-1/file-format-storehouse/unv_2412.htm
+ * <li> section 2467: http://www.sdrl.uc.edu/universal-file-formats-for-modal-
+ * analysis-testing-1/file-format-storehouse/unv_2467.htm
+ * <li> all sections of this format, even if they may not be supported in our
+ * reader, can be found here: http://www.sdrl.uc.edu/universal-file-formats-
+ * for-modal-analysis-testing-1/file-format-storehouse/file-formats
* </ul>
- * Note that Salome, let's say in 2D, can only make a quad mesh on an object that
- * has exactly 4 edges (or 4 pieces of the boundary). That means, that if you have
- * a more complicated object and would like to mesh it with quads, you will need
- * to decompose the object into >= 2 separate objects. Then 1) each of these
- * separate objects is meshed, 2) the appropriate groups of cells and/or faces
- * associated with each of these separate objects are created, 3) a compound
- * mesh is built up, and 4) all numbers that might be associated with some of
- * the internal faces of this compound mesh are removed.
+ * Note that Salome, let's say in 2D, can only make a quad mesh on an object
+ * that has exactly 4 edges (or 4 pieces of the boundary). That means, that if
+ * you have a more complicated object and would like to mesh it with quads,
+ * you will need to decompose the object into >= 2 separate objects. Then 1)
+ * each of these separate objects is meshed, 2) the appropriate groups of
+ * cells and/or faces associated with each of these separate objects are
+ * created, 3) a compound mesh is built up, and 4) all numbers that might be
+ * associated with some of the internal faces of this compound mesh are
+ * removed.
*
* <li> <tt>VTK</tt> format: VTK Unstructured Grid Legacy file reader
- * generator. The reader can handle only Unstructured Grid format of data
- * at present for 2D & 3D geometries.
- * The documentation for the general legacy vtk file, including Unstructured Grid format
- * can be found here:
+ * generator. The reader can handle only Unstructured Grid format of data at
+ * present for 2D & 3D geometries. The documentation for the general legacy
+ * vtk file, including Unstructured Grid format can be found here:
* http://www.cacr.caltech.edu/~slombey/asci/vtk/vtk_formats.simple.html
*
- * The VTK format requires the vertices to be
- * in following ordering: in 2d
+ * The VTK format requires the vertices to be in following ordering: in 2d
* @verbatim
* 3-----2
* | |
* plug-in script can be found on the deal.II wiki page,
* http://code.google.com/p/dealii/wiki/MeshInputAndOutput .
*
- * There is also a little program <code>bin/mesh_conversion</code> (in the directory
- * where deal.II was installed), written by Jean-Paul Pelteret, that can
- * convert Cubit ABAQUS files into the UCD format that can be read in as
- * discussed above. The program was designed with the intention of
- * exporting geometries with complex boundary condition surfaces and
- * multiple materials from Cubit - information which is currently not
- * easily obtained through Cubit's python interface. Using the the
- * program is simple: to use it, it needs to be built and run with the
- * command
+ * There is also a little program <code>bin/mesh_conversion</code> (in the
+ * directory where deal.II was installed), written by Jean-Paul Pelteret, that
+ * can convert Cubit ABAQUS files into the UCD format that can be read in as
+ * discussed above. The program was designed with the intention of exporting
+ * geometries with complex boundary condition surfaces and multiple materials
+ * from Cubit - information which is currently not easily obtained through
+ * Cubit's python interface. Using the the program is simple: to use it, it
+ * needs to be built and run with the command
* @code
* /path/to/deal.II/bin/mesh_conversion <spatial_dimension> /path/to/input_file.inp /path/to/output_file.ucd
* @endcode.
- * More information is available in the readme file included with the
- * program and located in the <code>contrib/mesh_conversion/README.txt</code> file in
- * the deal.II source directory tree. Note that the program's copyright remains with its author
- * and that it is under a separate license than the rest of the
- * library.
+ * More information is available in the readme file included with the program
+ * and located in the <code>contrib/mesh_conversion/README.txt</code> file in
+ * the deal.II source directory tree. Note that the program's copyright
+ * remains with its author and that it is under a separate license than the
+ * rest of the library.
*
* To build the program, see the <code>doc/readmes.html</code> and
* <code>doc/development/cmake.html</code> files.
*
* <h3>Structure of input grid data. The GridReordering class</h3>
*
- * It is your duty to use a correct numbering of vertices in the cell
- * list, i.e. for lines in 1d, you have to first give the vertex with
- * the lower coordinate value, then that with the higher coordinate
- * value. For quadrilaterals in two dimensions, the vertex indices in
- * the @p quad list have to be such that the vertices are numbered in
- * counter-clockwise sense.
+ * It is your duty to use a correct numbering of vertices in the cell list,
+ * i.e. for lines in 1d, you have to first give the vertex with the lower
+ * coordinate value, then that with the higher coordinate value. For
+ * quadrilaterals in two dimensions, the vertex indices in the @p quad list
+ * have to be such that the vertices are numbered in counter-clockwise sense.
*
- * In two dimensions, another difficulty occurs, which has to do with the sense
- * of a quadrilateral. A quad consists of four lines which have a direction,
- * which is per definitionem as follows:
+ * In two dimensions, another difficulty occurs, which has to do with the
+ * sense of a quadrilateral. A quad consists of four lines which have a
+ * direction, which is per definitionem as follows:
* @verbatim
* 3-->--2
* | |
* | |
* 0-->--1
* @endverbatim
- * Now, two adjacent cells must have a vertex numbering such that the direction
- * of the common side is the same. For example, the following two quads
+ * Now, two adjacent cells must have a vertex numbering such that the
+ * direction of the common side is the same. For example, the following two
+ * quads
* @verbatim
* 3---4---5
* | | |
* 0---1---2
* @endverbatim
- * may be characterised by the vertex numbers <tt>(0 1 4 3)</tt> and
- * <tt>(1 2 5 4)</tt>, since the middle line would get the direction <tt>1->4</tt>
- * when viewed from both cells. The numbering <tt>(0 1 4 3)</tt> and
- * <tt>(5 4 1 2)</tt> would not be allowed, since the left quad would give the
- * common line the direction <tt>1->4</tt>, while the right one would want
- * to use <tt>4->1</tt>, leading to an ambiguity. The Triangulation
- * object is capable of detecting this special case, which can be
- * eliminated by rotating the indices of the right quad by
- * two. However, it would not know what to do if you gave the vertex
- * indices <tt>(4 1 2 5)</tt>, since then it would have to rotate by one
- * element or three, the decision which to take is not yet
+ * may be characterised by the vertex numbers <tt>(0 1 4 3)</tt> and <tt>(1 2
+ * 5 4)</tt>, since the middle line would get the direction <tt>1->4</tt> when
+ * viewed from both cells. The numbering <tt>(0 1 4 3)</tt> and <tt>(5 4 1
+ * 2)</tt> would not be allowed, since the left quad would give the common
+ * line the direction <tt>1->4</tt>, while the right one would want to use
+ * <tt>4->1</tt>, leading to an ambiguity. The Triangulation object is capable
+ * of detecting this special case, which can be eliminated by rotating the
+ * indices of the right quad by two. However, it would not know what to do if
+ * you gave the vertex indices <tt>(4 1 2 5)</tt>, since then it would have to
+ * rotate by one element or three, the decision which to take is not yet
* implemented.
*
- * There are more ambiguous cases, where the triangulation may not
- * know what to do at all without the use of sophisticated
- * algorithms. Furthermore, similar problems exist in three space
- * dimensions, where faces and lines have orientations that need to be
- * taken care of.
+ * There are more ambiguous cases, where the triangulation may not know what
+ * to do at all without the use of sophisticated algorithms. Furthermore,
+ * similar problems exist in three space dimensions, where faces and lines
+ * have orientations that need to be taken care of.
*
- * For this reason, the <tt>read_*</tt> functions of this class that read
- * in grids in various input formats call the GridReordering
- * class to bring the order of vertices that define the cells into an
- * ordering that satisfies the requiremenets of the
- * Triangulation class. Be sure to read the documentation of
- * that class if you experience unexpected problems when reading grids
+ * For this reason, the <tt>read_*</tt> functions of this class that read in
+ * grids in various input formats call the GridReordering class to bring the
+ * order of vertices that define the cells into an ordering that satisfies the
+ * requiremenets of the Triangulation class. Be sure to read the documentation
+ * of that class if you experience unexpected problems when reading grids
* through this class.
*
*
{
public:
/**
- * List of possible mesh input
- * formats. These values are used
- * when calling the function
- * read() in order to determine
- * the actual reader to be
- * called.
+ * List of possible mesh input formats. These values are used when calling
+ * the function read() in order to determine the actual reader to be called.
*/
enum Format
{
GridIn ();
/**
- * Attach this triangulation
- * to be fed with the grid data.
+ * Attach this triangulation to be fed with the grid data.
*/
void attach_triangulation (Triangulation<dim,spacedim> &tria);
/**
- * Read from the given stream. If
- * no format is given,
- * GridIn::Format::Default is
- * used.
+ * Read from the given stream. If no format is given,
+ * GridIn::Format::Default is used.
*/
void read (std::istream &in, Format format=Default);
/**
- * Open the file given by the
- * string and call the previous
- * function read(). This function
- * uses the PathSearch mechanism
- * to find files. The file class
+ * Open the file given by the string and call the previous function read().
+ * This function uses the PathSearch mechanism to find files. The file class
* used is <code>MESH</code>.
*/
void read (const std::string &in, Format format=Default);
/**
- * Read grid data from an vtk file.
- * Numerical data is ignored.
+ * Read grid data from an vtk file. Numerical data is ignored.
*
* @author Mayank Sabharwal, Andreas Putz, 2013
*/
void read_vtk(std::istream &in);
/**
- * Read grid data from an unv
- * file as generated by the
- * Salome mesh generator.
- * Numerical data is ignored.
+ * Read grid data from an unv file as generated by the Salome mesh
+ * generator. Numerical data is ignored.
*
- * Note the comments on
- * generating this file format in
- * the general documentation of
- * this class.
+ * Note the comments on generating this file format in the general
+ * documentation of this class.
*/
void read_unv(std::istream &in);
/**
- * Read grid data from an ucd file.
- * Numerical data is ignored.
+ * Read grid data from an ucd file. Numerical data is ignored.
*/
void read_ucd (std::istream &in);
/**
- * Read grid data from a file
- * containing data in the DB mesh
- * format.
+ * Read grid data from a file containing data in the DB mesh format.
*/
void read_dbmesh (std::istream &in);
/**
- * Read grid data from a file
- * containing data in the XDA
- * format.
+ * Read grid data from a file containing data in the XDA format.
*/
void read_xda (std::istream &in);
/**
- * Read grid data from an msh
- * file, either version 1 or
- * version 2 of that file
- * format. The GMSH formats are
- * documented at
- * http://www.geuz.org/gmsh/ .
+ * Read grid data from an msh file, either version 1 or version 2 of that
+ * file format. The GMSH formats are documented at http://www.geuz.org/gmsh/
+ * .
*
- * @note The input function of
- * deal.II does not distinguish
- * between newline and other
- * whitespace. Therefore, deal.II
- * will be able to read files in
- * a slightly more general format
- * than Gmsh.
+ * @note The input function of deal.II does not distinguish between newline
+ * and other whitespace. Therefore, deal.II will be able to read files in a
+ * slightly more general format than Gmsh.
*/
void read_msh (std::istream &in);
/**
- * Read grid data from a NetCDF
- * file. The only data format
- * currently supported is the
- * <tt>TAU grid format</tt>.
+ * Read grid data from a NetCDF file. The only data format currently
+ * supported is the <tt>TAU grid format</tt>.
*
- * This function requires the
- * library to be linked with the
- * NetCDF library.
+ * This function requires the library to be linked with the NetCDF library.
*/
void read_netcdf (const std::string &filename);
/**
- * Read grid data from a file containing
- * tecplot ASCII data. This also works in
- * the absence of any tecplot
- * installation.
+ * Read grid data from a file containing tecplot ASCII data. This also works
+ * in the absence of any tecplot installation.
*/
void read_tecplot (std::istream &in);
/**
- * Returns the standard suffix
- * for a file in this format.
+ * Returns the standard suffix for a file in this format.
*/
static std::string default_suffix (const Format format);
/**
- * Return the enum Format for the
- * format name.
+ * Return the enum Format for the format name.
*/
static Format parse_format (const std::string &format_name);
/**
- * Return a list of implemented input
- * formats. The different names are
- * separated by vertical bar signs (<tt>`|'</tt>)
- * as used by the ParameterHandler
- * classes.
+ * Return a list of implemented input formats. The different names are
+ * separated by vertical bar signs (<tt>`|'</tt>) as used by the
+ * ParameterHandler classes.
*/
static std::string get_format_names ();
DeclException0 (ExcGmshNoCellInformation);
protected:
/**
- * Store address of the triangulation to
- * be fed with the data read in.
+ * Store address of the triangulation to be fed with the data read in.
*/
SmartPointer<Triangulation<dim,spacedim>,GridIn<dim,spacedim> > tria;
/**
- * This function can write the
- * raw cell data objects created
- * by the <tt>read_*</tt> functions in
- * Gnuplot format to a
- * stream. This is sometimes
- * handy if one would like to see
- * what actually was created, if
- * it is known that the data is
- * not correct in some way, but
- * the Triangulation class
- * refuses to generate a
- * triangulation because of these
- * errors. In particular, the
- * output of this class writes
- * out the cell numbers along
- * with the direction of the
- * faces of each cell. In
- * particular the latter
- * information is needed to
- * verify whether the cell data
- * objects follow the
- * requirements of the ordering
- * of cells and their faces,
- * i.e. that all faces need to
- * have unique directions and
- * specified orientations with
- * respect to neighboring cells
- * (see the documentations to
- * this class and the
- * GridReordering class).
+ * This function can write the raw cell data objects created by the
+ * <tt>read_*</tt> functions in Gnuplot format to a stream. This is
+ * sometimes handy if one would like to see what actually was created, if it
+ * is known that the data is not correct in some way, but the Triangulation
+ * class refuses to generate a triangulation because of these errors. In
+ * particular, the output of this class writes out the cell numbers along
+ * with the direction of the faces of each cell. In particular the latter
+ * information is needed to verify whether the cell data objects follow the
+ * requirements of the ordering of cells and their faces, i.e. that all
+ * faces need to have unique directions and specified orientations with
+ * respect to neighboring cells (see the documentations to this class and
+ * the GridReordering class).
*
- * The output of this function
- * consists of vectors for each
- * line bounding the cells
- * indicating the direction it
- * has with respect to the
- * orientation of this cell, and
- * the cell number. The whole
- * output is in a form such that
- * it can be read in by Gnuplot
- * and generate the full plot
- * without further ado by the
- * user.
+ * The output of this function consists of vectors for each line bounding
+ * the cells indicating the direction it has with respect to the orientation
+ * of this cell, and the cell number. The whole output is in a form such
+ * that it can be read in by Gnuplot and generate the full plot without
+ * further ado by the user.
*/
static void debug_output_grid (const std::vector<CellData<dim> > &cells,
const std::vector<Point<spacedim> > &vertices,
private:
/**
- * Skip empty lines in the input
- * stream, i.e. lines that
- * contain either nothing or only
- * whitespace.
+ * Skip empty lines in the input stream, i.e. lines that contain either
+ * nothing or only whitespace.
*/
static void skip_empty_lines (std::istream &in);
/**
- * Skip lines of comment that
- * start with the indicated
- * character (e.g. <tt>#</tt>)
- * following the point where the
- * given input stream presently
- * is. After the call to this
- * function, the stream is at the
- * start of the first line after
- * the comment lines, or at the
- * same position as before if
- * there were no lines of
- * comments.
+ * Skip lines of comment that start with the indicated character (e.g.
+ * <tt>#</tt>) following the point where the given input stream presently
+ * is. After the call to this function, the stream is at the start of the
+ * first line after the comment lines, or at the same position as before if
+ * there were no lines of comments.
*/
static void skip_comment_lines (std::istream &in,
const char comment_start);
/**
- * This function does the nasty work (due
- * to very lax conventions and different
- * versions of the tecplot format) of
- * extracting the important parameters from
- * a tecplot header, contained in the
- * string @p header. The other variables
- * are output variables, their value has no
- * influence on the function execution..
+ * This function does the nasty work (due to very lax conventions and
+ * different versions of the tecplot format) of extracting the important
+ * parameters from a tecplot header, contained in the string @p header. The
+ * other variables are output variables, their value has no influence on the
+ * function execution..
*/
static void parse_tecplot_header(std::string &header,
std::vector<unsigned int> &tecplot2deal,
bool &blocked);
/**
- * Input format used by read() if
- * no format is given.
+ * Input format used by read() if no format is given.
*/
Format default_format;
};
/**
- * Within this namespace, we define several structures that are used
- * to describe flags that can be given to grid output routines to
- * modify the default outfit of the grids written into a file. See the
- * different subclasses and the documentation of the GridOut
- * class for more details.
+ * Within this namespace, we define several structures that are used to
+ * describe flags that can be given to grid output routines to modify the
+ * default outfit of the grids written into a file. See the different
+ * subclasses and the documentation of the GridOut class for more details.
*
* @ingroup output
*/
bool write_measure;
/**
- * Write all faces, including interior faces. If <tt>false</tt>,
- * only boundary faces are written.
+ * Write all faces, including interior faces. If <tt>false</tt>, only
+ * boundary faces are written.
*/
bool write_all_faces;
struct Msh
{
/**
- * When writing a mesh, write boundary faces explicitly if their
- * boundary indicator is not the default boundary indicator, which
- * is zero. This is necessary if you later want to re-read the
- * grid and want to get the same boundary indicators for the
- * different parts of the boundary of the triangulation.
+ * When writing a mesh, write boundary faces explicitly if their boundary
+ * indicator is not the default boundary indicator, which is zero. This
+ * is necessary if you later want to re-read the grid and want to get the
+ * same boundary indicators for the different parts of the boundary of the
+ * triangulation.
*
- * It is not necessary if you only want to write the triangulation
- * to view or print it.
+ * It is not necessary if you only want to write the triangulation to view
+ * or print it.
*
* Default: @p false.
*/
bool write_faces;
/**
- * When writing a mesh, write boundary lines explicitly if their
- * boundary indicator is not the default boundary indicator,
- * which is zero. This is necessary if you later want to re-read
- * the grid and want to get the same boundary indicators for the
- * different parts of the boundary of the triangulation.
- *
- * It is not necessary if you only want to write the
- * triangulation to view or print it.
- *
- * This is used only if <tt>dim==3</tt>, and ignored in all other
- * cases.
- *
- * Default: @p false.
- */
+ * When writing a mesh, write boundary lines explicitly if their boundary
+ * indicator is not the default boundary indicator, which is zero. This
+ * is necessary if you later want to re-read the grid and want to get the
+ * same boundary indicators for the different parts of the boundary of the
+ * triangulation.
+ *
+ * It is not necessary if you only want to write the triangulation to view
+ * or print it.
+ *
+ * This is used only if <tt>dim==3</tt>, and ignored in all other cases.
+ *
+ * Default: @p false.
+ */
bool write_lines;
/**
struct Ucd
{
/**
- * Write a comment at the beginning of the file stating the date
- * of creation and some other data. While this is supported by
- * the UCD format (and the AVS program), some other programs get
- * confused by this, so the default is to not write a
- * preamble. However, a preamble can be written using this flag.
+ * Write a comment at the beginning of the file stating the date of
+ * creation and some other data. While this is supported by the UCD
+ * format (and the AVS program), some other programs get confused by this,
+ * so the default is to not write a preamble. However, a preamble can be
+ * written using this flag.
*
* Default: <code>false</code>.
*/
bool write_preamble;
/**
- * When writing a mesh, write boundary faces explicitly if their
- * boundary indicator is not the default boundary indicator, which
- * is zero. This is necessary if you later want to re-read the
- * grid and want to get the same boundary indicators for the
- * different parts of the boundary of the triangulation.
+ * When writing a mesh, write boundary faces explicitly if their boundary
+ * indicator is not the default boundary indicator, which is zero. This
+ * is necessary if you later want to re-read the grid and want to get the
+ * same boundary indicators for the different parts of the boundary of the
+ * triangulation.
*
- * It is not necessary if you only want to write the triangulation
- * to view or print it.
+ * It is not necessary if you only want to write the triangulation to view
+ * or print it.
*
* Default: @p false.
*/
bool write_faces;
/**
- * When writing a mesh, write boundary lines explicitly if their
- * boundary indicator is not the default boundary indicator, which
- * is zero. This is necessary if you later want to re-read the
- * grid and want to get the same boundary indicators for the
- * different parts of the boundary of the triangulation.
+ * When writing a mesh, write boundary lines explicitly if their boundary
+ * indicator is not the default boundary indicator, which is zero. This
+ * is necessary if you later want to re-read the grid and want to get the
+ * same boundary indicators for the different parts of the boundary of the
+ * triangulation.
*
- * It is not necessary if you only want to write the triangulation
- * to view or print it.
+ * It is not necessary if you only want to write the triangulation to view
+ * or print it.
*
- * This directive is ignored if
- * <tt>dim!=3</tt>.
+ * This directive is ignored if <tt>dim!=3</tt>.
*
- * Default: @p false.
+ * Default: @p false.
*/
bool write_lines;
struct Gnuplot
{
/**
- * Write the number of each cell into the output file before
- * starting with the lines it is composed of, as a comment. This
- * might be useful if you want to find out details about the grid,
- * for example the position of cells of which you know the
- * number. It enlarges the size of the output significantly,
- * however.
+ * Write the number of each cell into the output file before starting with
+ * the lines it is composed of, as a comment. This might be useful if you
+ * want to find out details about the grid, for example the position of
+ * cells of which you know the number. It enlarges the size of the output
+ * significantly, however.
*
* Default: @p false.
*/
/**
* Based on the vertices of the face and #n_boundary_face_points
- * additional points a tensor product mesh (tranformed to the real
- * space) of (#n_boundary_face_points+2)<sup>dim-1</sup> points is
- * plotted on each boundary face.
+ * additional points a tensor product mesh (tranformed to the real space)
+ * of (#n_boundary_face_points+2)<sup>dim-1</sup> points is plotted on
+ * each boundary face.
*/
unsigned int n_boundary_face_points;
/**
- * Flag. If true also inner cells are plotted with curved
- * boundaries. This is useful when for e.g. MappingQEulerian with
+ * Flag. If true also inner cells are plotted with curved boundaries. This
+ * is useful when for e.g. MappingQEulerian with
* #n_boundary_face_points>.
*/
bool curved_inner_cells;
};
/**
- * Flags describing the details of output for encapsulated
- * postscript. In this structure, the flags common to all
- * dimensions are listed. Flags which are specific to one space
- * dimension only are listed in derived classes.
+ * Flags describing the details of output for encapsulated postscript. In
+ * this structure, the flags common to all dimensions are listed. Flags
+ * which are specific to one space dimension only are listed in derived
+ * classes.
*
- * By default, the size of the picture is scaled such that the width
- * equals 300 units.
+ * By default, the size of the picture is scaled such that the width equals
+ * 300 units.
*
* @ingroup output
*/
struct EpsFlagsBase
{
/**
- * Enum denoting the possibilities whether the scaling should be
- * done such that the given @p size equals the width or the height
- * of the resulting picture.
+ * Enum denoting the possibilities whether the scaling should be done such
+ * that the given @p size equals the width or the height of the resulting
+ * picture.
*/
enum SizeType
{
SizeType size_type;
/**
- * Width or height of the output as given in postscript units This
- * usually is given by the strange unit 1/72 inch. Whether this is
- * height or width is specified by the flag @p size_type.
+ * Width or height of the output as given in postscript units This usually
+ * is given by the strange unit 1/72 inch. Whether this is height or width
+ * is specified by the flag @p size_type.
*
* Default is 300.
*/
double line_width;
/**
- * Should lines with a set @p user_flag be drawn in a different
- * color (red)? See @ref GlossUserFlags for information about
- * user flags.
- */
+ * Should lines with a set @p user_flag be drawn in a different color
+ * (red)? See @ref GlossUserFlags for information about user flags.
+ */
bool color_lines_on_user_flag;
/**
- * This is the number of points on a boundary face, that are
- * ploted additionally to the vertices of the face.
+ * This is the number of points on a boundary face, that are ploted
+ * additionally to the vertices of the face.
*
- * This is used if the mapping used is not the standard @p
- * MappingQ1 mapping.
+ * This is used if the mapping used is not the standard @p MappingQ1
+ * mapping.
*/
unsigned int n_boundary_face_points;
/**
- * Should lines be colored according to their refinement level?
- * This overrides color_lines_on_user_flag for all levels except
- * level 0. Colors are: level 0: black, other levels: rainbow
- * scale from blue to red.
+ * Should lines be colored according to their refinement level? This
+ * overrides color_lines_on_user_flag for all levels except level 0.
+ * Colors are: level 0: black, other levels: rainbow scale from blue to
+ * red.
*/
bool color_lines_level;
static void declare_parameters (ParameterHandler ¶m);
/**
- * Parse parameters of
- * ParameterHandler.
+ * Parse parameters of ParameterHandler.
*/
void parse_parameters (ParameterHandler ¶m);
};
/**
- * Flags describing the details of output for encapsulated
- * postscript for all dimensions not explicitly specialized
- * below. Some flags that are common to all dimensions are listed in
- * the base class.
+ * Flags describing the details of output for encapsulated postscript for
+ * all dimensions not explicitly specialized below. Some flags that are
+ * common to all dimensions are listed in the base class.
*
- * This class does not actually exist, we only here declare the
- * general template and declare explicit specializations below.
+ * This class does not actually exist, we only here declare the general
+ * template and declare explicit specializations below.
*
* @ingroup output
- */
+ */
template <int dim>
struct Eps
{};
struct Eps<2> : public EpsFlagsBase
{
/**
- * If this flag is set, then we place the number of the cell into
- * the middle of each cell. The default value is to not do this.
+ * If this flag is set, then we place the number of the cell into the
+ * middle of each cell. The default value is to not do this.
*
- * The format of the cell number written is <tt>level.index</tt>,
- * or simply @p index, depending on the value of the following
- * flag.
+ * The format of the cell number written is <tt>level.index</tt>, or
+ * simply @p index, depending on the value of the following flag.
*/
bool write_cell_numbers;
/**
- * If the cell numbers shall be written, using the above flag,
- * then the value of this flag determines whether the format shall
- * be <tt>level.index</tt>, or simply @p index. If @p true, the
- * first format is taken. Default is @p true.
+ * If the cell numbers shall be written, using the above flag, then the
+ * value of this flag determines whether the format shall be
+ * <tt>level.index</tt>, or simply @p index. If @p true, the first format
+ * is taken. Default is @p true.
*
- * The flag has obviously no effect if @p write_cell_numbers is @p
- * false.
+ * The flag has obviously no effect if @p write_cell_numbers is @p false.
*/
bool write_cell_number_level;
/**
- * Vertex numbers can be written onto the vertices. This is
- * controlled by the following flag. Default is @p false.
+ * Vertex numbers can be written onto the vertices. This is controlled by
+ * the following flag. Default is @p false.
*/
bool write_vertex_numbers;
double azimut_angle;
/**
- * Angle by which the viewers position projected onto the
- * x-y-plane is rotated around the z-axis, in positive sense when
- * viewed from above. The unit are degrees, and zero equals a
- * position above or below the negative y-axis.
+ * Angle by which the viewers position projected onto the x-y-plane is
+ * rotated around the z-axis, in positive sense when viewed from above.
+ * The unit are degrees, and zero equals a position above or below the
+ * negative y-axis.
*
* Default is the Gnuplot-default of 30.
*/
/**
* @deprecated Use the color_by enum instead.
*
- * Change color depending on level. Default is false, therefore,
- * color is coded by material or boundary id.
+ * Change color depending on level. Default is false, therefore, color is
+ * coded by material or boundary id.
*/
bool level_color DEAL_II_DEPRECATED;
/**
- * Code level to depth. Default is true. If false, color depends
- * on material or boundary id.
+ * Code level to depth. Default is true. If false, color depends on
+ * material or boundary id.
*
* Depth of the object is 900-level, if this value is true.
*/
Point<2> scaling;
/**
- * Offset of the graph. Before scaling, the coordinates are
- * shifted by this value. Default is zero in each direction.
+ * Offset of the graph. Before scaling, the coordinates are shifted by
+ * this value. Default is zero in each direction.
*/
Point<2> offset;
/**
- * Style for filling cells. Default is solid fill (20). This value
- * is forwarded unchanged into the corresponding field
- * <tt>fill_style</tt> of the polyline object of XFig.
+ * Style for filling cells. Default is solid fill (20). This value is
+ * forwarded unchanged into the corresponding field <tt>fill_style</tt> of
+ * the polyline object of XFig.
*/
int fill_style;
/**
- * Style for drawing border lines of polygons. Defaults to solid
- * (0) and is forwarded to XFig.
+ * Style for drawing border lines of polygons. Defaults to solid (0) and
+ * is forwarded to XFig.
*/
int line_style;
/**
* Cell labeling (fixed order).
*
- * The following booleans determine which properties of the cell
- * shall be displayed as text in the middle of each cell.
+ * The following booleans determine which properties of the cell shall be
+ * displayed as text in the middle of each cell.
*/
bool label_level_number; // default: true
bool label_cell_index; // default: true
/**
- * Flags for grid output in Vtk format. These flags are the same as
- * those declared in DataOutBase::VtkFlags.
+ * Flags for grid output in Vtk format. These flags are the same as those
+ * declared in DataOutBase::VtkFlags.
*
* @ingroup output
*/
/**
- * Flags for grid output in Vtu format. These flags are the same as
- * those declared in DataOutBase::VtuFlags.
+ * Flags for grid output in Vtu format. These flags are the same as those
+ * declared in DataOutBase::VtuFlags.
*
* @ingroup output
*/
* ofstream output_file("some_filename" + GridOut::default_suffix(output_format));
* GridOut().write (tria, output_file, output_format);
* @endcode
- * The function <tt>get_output_format_names()</tt> provides a list of possible names of
- * output formats in a string that is understandable by the ParameterHandler class.
+ * The function <tt>get_output_format_names()</tt> provides a list of possible
+ * names of output formats in a string that is understandable by the
+ * ParameterHandler class.
*
- * Note that here, we have created an unnamed object of type GridOut and called
- * one of its <tt>write_*</tt> functions. This looks like as if the respective function
- * could really be made @p static. This was not done in order to allow for
- * parameters to be passed to the different output functions in a way compatible
- * with the scheme of allowing the right output format to be selected at run-time
- * through the generic @p write function.
+ * Note that here, we have created an unnamed object of type GridOut and
+ * called one of its <tt>write_*</tt> functions. This looks like as if the
+ * respective function could really be made @p static. This was not done in
+ * order to allow for parameters to be passed to the different output
+ * functions in a way compatible with the scheme of allowing the right output
+ * format to be selected at run-time through the generic @p write function.
*
* In order to explain this, consider each function had one or more additional
- * parameters giving the details of output, for example position of the spectator
- * for 3d meshed, line thicknesses, etc. While this would allow each output
- * function any flexibility it needs, it would not allow us to use the generic
- * function @p write which is given a parameter determining the output format,
- * since it is impractical to give it a list of parameters for each and every
- * output format supported which it may then pass on to the respective output
- * function.
+ * parameters giving the details of output, for example position of the
+ * spectator for 3d meshed, line thicknesses, etc. While this would allow each
+ * output function any flexibility it needs, it would not allow us to use the
+ * generic function @p write which is given a parameter determining the output
+ * format, since it is impractical to give it a list of parameters for each
+ * and every output format supported which it may then pass on to the
+ * respective output function.
*
- * Rather, we have chosen to let each object of this class
- * GridOut have a set of parameters for each supported output
- * format. These are collected in structures GridOutFlags::Eps(),
- * GridOutFlags::Gnuplot(), etc declared in the GridOutFlags
- * namespace, and you can set your preferred flags like this:
+ * Rather, we have chosen to let each object of this class GridOut have a set
+ * of parameters for each supported output format. These are collected in
+ * structures GridOutFlags::Eps(), GridOutFlags::Gnuplot(), etc declared in
+ * the GridOutFlags namespace, and you can set your preferred flags like this:
* @code
* GridOut grid_out;
* GridOutFlags::Ucd ucd_flags;
* ... // write some file with data_out
* @endcode
* The respective output function then use the so-set flags. By default, they
- * are set to reasonable values as described above and in the documentation
- * of the different flags structures. Resetting the flags can
- * be done by calling <tt>grid_out.set_flags (GridOutFlags::Ucd());</tt>, since the
- * default constructor of each of the flags structures sets the parameters
- * to their initial values.
+ * are set to reasonable values as described above and in the documentation of
+ * the different flags structures. Resetting the flags can be done by calling
+ * <tt>grid_out.set_flags (GridOutFlags::Ucd());</tt>, since the default
+ * constructor of each of the flags structures sets the parameters to their
+ * initial values.
*
* The advantage of this approach is that it is possible to change the flags
* of one or more output formats according to your needs and later use the
- * generic @p write function; the actual output function then called will
- * use the flags as set before.
+ * generic @p write function; the actual output function then called will use
+ * the flags as set before.
*
* Note that some of the structures describing the flags of the different
- * output formats are empty since the respective format does not support
- * any flags. The structure and the @p set_flags function are provided
- * anyway. Note also that some of the structures may differ between the
- * dimensions supported by this class; they then have a template parameter,
- * as usual.
+ * output formats are empty since the respective format does not support any
+ * flags. The structure and the @p set_flags function are provided anyway.
+ * Note also that some of the structures may differ between the dimensions
+ * supported by this class; they then have a template parameter, as usual.
*
* @ingroup grid
* @ingroup output
- * @author Wolfgang Bangerth, Guido Kanschat, Luca Heltai, Stefan Nauber, Christian Wülker
+ * @author Wolfgang Bangerth, Guido Kanschat, Luca Heltai, Stefan Nauber,
+ * Christian Wülker
* @date 1999 - 2013
*/
class GridOut
{
public:
/**
- * Declaration of a name for each
- * of the different output
- * formats. These are used by the
- * generic output function
- * write() to determine the
- * actual output format.
+ * Declaration of a name for each of the different output formats. These are
+ * used by the generic output function write() to determine the actual
+ * output format.
*/
enum OutputFormat
{
GridOut ();
/**
- * Write triangulation in OpenDX
- * format.
+ * Write triangulation in OpenDX format.
*
- * Cells or faces are written
- * together with their level and
- * their material id or boundary
- * indicator, resp.
+ * Cells or faces are written together with their level and their material
+ * id or boundary indicator, resp.
*
- * Not implemented for the
- * codimension one case.
+ * Not implemented for the codimension one case.
*/
template <int dim, int spacedim>
void write_dx (const Triangulation<dim,spacedim> &tria,
std::ostream &out) const;
/**
- * Write the triangulation in the
- * gnuplot format.
+ * Write the triangulation in the gnuplot format.
*
- * In GNUPLOT format, each cell
- * is written as a sequence of
- * its confining lines. Apart
- * from the coordinates of the
- * line's end points, the level
- * and the material of the cell
- * are appended to each line of
- * output. Therefore, if you let
- * GNUPLOT draw a 2d grid as a 3d
- * plot, you will see more
- * refined cells being raised
- * against cells with less
- * refinement. Also, if you draw
- * a cut through a 3d grid, you
- * can extrude the refinement
- * level in the direction
- * orthogonal to the cut
- * plane. The same can be done
- * with the material id, which is
- * plotted after the level.
+ * In GNUPLOT format, each cell is written as a sequence of its confining
+ * lines. Apart from the coordinates of the line's end points, the level and
+ * the material of the cell are appended to each line of output. Therefore,
+ * if you let GNUPLOT draw a 2d grid as a 3d plot, you will see more refined
+ * cells being raised against cells with less refinement. Also, if you draw
+ * a cut through a 3d grid, you can extrude the refinement level in the
+ * direction orthogonal to the cut plane. The same can be done with the
+ * material id, which is plotted after the level.
*
- * A more useful application of
- * this feature is the following:
- * if you use the GNUPLOT
- * command (for a 2d grid here)
+ * A more useful application of this feature is the following: if you use
+ * the GNUPLOT command (for a 2d grid here)
* @verbatim
* splot [:][:][2.5:3.5] "grid_file.gnuplot" *
* @endverbatim
- * then the
- * whole x- and y-range will be
- * plotted, i.e. the whole grid,
- * but only those lines with a
- * z-value between 2.5 and
- * 3.5. Since the z-values were
- * chosen to be the level to
- * which a cell belongs, this
- * results in a plot of those
- * cells only that belong to
- * level 3 in this example. This
- * way, it is easy to produce
- * plots of the different levels
- * of grid.
+ * then the whole x- and y-range will be plotted, i.e. the whole grid, but
+ * only those lines with a z-value between 2.5 and 3.5. Since the z-values
+ * were chosen to be the level to which a cell belongs, this results in a
+ * plot of those cells only that belong to level 3 in this example. This
+ * way, it is easy to produce plots of the different levels of grid.
*
- * @p mapping is a pointer to a
- * mapping used for the
- * transformation of cells at the
- * boundary. If zero, then use
- * standard Q1 mapping.
+ * @p mapping is a pointer to a mapping used for the transformation of cells
+ * at the boundary. If zero, then use standard Q1 mapping.
*
- * Names and values of additional
- * flags controlling the output
- * can be found in the
- * documentation of the
- * GridOutFlags::Gnuplot() class.
+ * Names and values of additional flags controlling the output can be found
+ * in the documentation of the GridOutFlags::Gnuplot() class.
*
- * Not implemented for the
- * codimension one case.
+ * Not implemented for the codimension one case.
*/
template <int dim, int spacedim>
void write_gnuplot (const Triangulation<dim,spacedim> &tria,
/**
* Write the triangulation in the msh format.
*
- * Msh is the format used by Gmsh and it is described in the gmsh
- * user's guide. Besides the usual output of the grid only, you can
- * decide through additional flags (see below, and the documentation
- * of the GridOutFlags::Msh() class) whether boundary faces with
- * non-zero boundary indicator shall be written to the file
- * explicitly. This is useful, if you want to re-read the grid later
- * on, since <tt>deal.II</tt> sets the boundary indicator to zero by
- * default; therefore, to obtain the same triangulation as before,
- * you have to specify faces with differing boundary indicators
- * explicitly, which is done by this flag.
+ * Msh is the format used by Gmsh and it is described in the gmsh user's
+ * guide. Besides the usual output of the grid only, you can decide through
+ * additional flags (see below, and the documentation of the
+ * GridOutFlags::Msh() class) whether boundary faces with non-zero boundary
+ * indicator shall be written to the file explicitly. This is useful, if you
+ * want to re-read the grid later on, since <tt>deal.II</tt> sets the
+ * boundary indicator to zero by default; therefore, to obtain the same
+ * triangulation as before, you have to specify faces with differing
+ * boundary indicators explicitly, which is done by this flag.
*
- * Names and values of further flags controlling the output can be
- * found in the documentation of the GridOut::Msh() class.
+ * Names and values of further flags controlling the output can be found in
+ * the documentation of the GridOut::Msh() class.
*
* Works also in the codimension one case.
*/
/**
* Write the triangulation in the ucd format.
*
- * UCD (unstructured cell data) is the format used by AVS and some
- * other programs. It is described in the AVS developer's
- * guide. Besides the usual output of the grid only, you can decide
- * through additional flags (see below, and the documentation of the
- * GridOutFlags::Ucd() class) whether boundary faces with non-zero
- * boundary indicator shall be written to the file explicitly. This
- * is useful, if you want to re-read the grid later on, since
- * <tt>deal.II</tt> sets the boundary indicator to zero by default;
- * therefore, to obtain the same triangulation as before, you have
- * to specify faces with differing boundary indicators explicitly,
- * which is done by this flag.
+ * UCD (unstructured cell data) is the format used by AVS and some other
+ * programs. It is described in the AVS developer's guide. Besides the usual
+ * output of the grid only, you can decide through additional flags (see
+ * below, and the documentation of the GridOutFlags::Ucd() class) whether
+ * boundary faces with non-zero boundary indicator shall be written to the
+ * file explicitly. This is useful, if you want to re-read the grid later
+ * on, since <tt>deal.II</tt> sets the boundary indicator to zero by
+ * default; therefore, to obtain the same triangulation as before, you have
+ * to specify faces with differing boundary indicators explicitly, which is
+ * done by this flag.
*
- * Names and values of further flags controlling the output can be
- * found in the documentation of the GridOut::Ucd() class.
+ * Names and values of further flags controlling the output can be found in
+ * the documentation of the GridOut::Ucd() class.
*
* Works also for the codimension one case.
*/
/**
* Write the triangulation in the encapsulated postscript format.
*
- * In this format, each line of the triangulation is written
- * separately. We scale the picture such that either x-values or
- * y-values range between zero and a fixed size. The other axis is
- * scaled by the same factor. Which axis is taken to compute the
- * scale and the size of the box it shall fit into is determined by
- * the output flags (see below, and the documentation of the
- * GridOutFlags::Eps() class).
+ * In this format, each line of the triangulation is written separately. We
+ * scale the picture such that either x-values or y-values range between
+ * zero and a fixed size. The other axis is scaled by the same factor. Which
+ * axis is taken to compute the scale and the size of the box it shall fit
+ * into is determined by the output flags (see below, and the documentation
+ * of the GridOutFlags::Eps() class).
*
- * The bounding box is close to the triangulation on all four sides,
- * without an extra frame. The line width is chosen to be 0.5 by
- * default, but can be changed. The line width is to be compared
- * with the extension of the picture, of which the default is 300.
+ * The bounding box is close to the triangulation on all four sides, without
+ * an extra frame. The line width is chosen to be 0.5 by default, but can be
+ * changed. The line width is to be compared with the extension of the
+ * picture, of which the default is 300.
*
- * The flag @p color_lines_on_user_flag allows to draw lines with
- * the @p user_flag set to be drawn in red. The colors black and red
- * are defined as @p b and @p r in the preamble of the output file
- * and can be changed there according to need.
+ * The flag @p color_lines_on_user_flag allows to draw lines with the @p
+ * user_flag set to be drawn in red. The colors black and red are defined as
+ * @p b and @p r in the preamble of the output file and can be changed there
+ * according to need.
*
- * @p mapping is a pointer to a mapping used for the transformation
- * of cells at the boundary. If zero, then use standard Q1 mapping.
+ * @p mapping is a pointer to a mapping used for the transformation of cells
+ * at the boundary. If zero, then use standard Q1 mapping.
*
- * Names and values of additional flags controlling the output can
- * be found in the documentation of the GridOutFlags::Eps()
- * class. Especially the viewpoint for three dimensional grids is of
- * importance here.
+ * Names and values of additional flags controlling the output can be found
+ * in the documentation of the GridOutFlags::Eps() class. Especially the
+ * viewpoint for three dimensional grids is of importance here.
*
* Not implemented for the codimension one case.
*/
/**
* Write two-dimensional XFig-file.
*
- * This function writes all grid cells as polygons and optionally
- * boundary lines. Several parameters can be adjusted by the
- * XFigFlags control object.
+ * This function writes all grid cells as polygons and optionally boundary
+ * lines. Several parameters can be adjusted by the XFigFlags control
+ * object.
*
- * If levels are coded to depth, the complete grid hierarchy is
- * plotted with fine cells before their parents. This way, levels
- * can be switched on and off in xfig by selecting levels.
+ * If levels are coded to depth, the complete grid hierarchy is plotted with
+ * fine cells before their parents. This way, levels can be switched on and
+ * off in xfig by selecting levels.
*
* Polygons are either at depth 900-level or at 900+@p material_id,
- * depending on the flag @p level_depth. Accordingly, boundary edges
- * are at depth 800-level or at 800+@p boundary_id. Therefore,
- * boundary edges are alway in front of cells.
+ * depending on the flag @p level_depth. Accordingly, boundary edges are at
+ * depth 800-level or at 800+@p boundary_id. Therefore, boundary edges are
+ * alway in front of cells.
*
* Not implemented for the codimension one case.
*/
/**
* Write the triangulation in the SVG format.
*
- * SVG (Scalable Vector Graphics) is
- * an XML-based vector image format
- * developed and maintained by the
- * World Wide Web Consortium (W3C).
- * This function conforms to the
- * latest specification SVG 1.1,
- * released on August 16, 2011.
+ * SVG (Scalable Vector Graphics) is an XML-based vector image format
+ * developed and maintained by the World Wide Web Consortium (W3C). This
+ * function conforms to the latest specification SVG 1.1, released on August
+ * 16, 2011.
*
- * The cells of the triangulation are written as polygons with
- * additional lines at the boundary of the triangulation. A coloring
- * of the cells is further possible in order to visualize a certain
- * property of the cells such as their level or material id. A
- * colorbar can be drawn to encode the chosen coloring. Moreover, a
- * cell label can be added, showing level index, etc.
+ * The cells of the triangulation are written as polygons with additional
+ * lines at the boundary of the triangulation. A coloring of the cells is
+ * further possible in order to visualize a certain property of the cells
+ * such as their level or material id. A colorbar can be drawn to encode the
+ * chosen coloring. Moreover, a cell label can be added, showing level
+ * index, etc.
*
- * @note This function is currently only implemented for
- * two-dimensional grids in two
- * space dimensions.
+ * @note This function is currently only implemented for two-dimensional
+ * grids in two space dimensions.
*/
void write_svg (const Triangulation<2,2> &tria,
std::ostream &out) const;
/**
- * Write triangulation in MathGL script format. To interpret this
- * file a version of MathGL>=2.0.0 is required.
+ * Write triangulation in MathGL script format. To interpret this file a
+ * version of MathGL>=2.0.0 is required.
*
* To get a handle on the resultant MathGL script within a graphical
- * environment an interpreter is needed. A suggestion to start with
- * is <code>mglview</code>, which is bundled with MathGL.
- * <code>mglview</code> can interpret and display small-to-medium
- * MathGL scripts in a graphical window and enables conversion to
- * other formats such as EPS, PNG, JPG, SVG, as well as view/display
- * animations. Some minor editing, such as modifying the lighting or
- * alpha channels, can also be done.
+ * environment an interpreter is needed. A suggestion to start with is
+ * <code>mglview</code>, which is bundled with MathGL. <code>mglview</code>
+ * can interpret and display small-to-medium MathGL scripts in a graphical
+ * window and enables conversion to other formats such as EPS, PNG, JPG,
+ * SVG, as well as view/display animations. Some minor editing, such as
+ * modifying the lighting or alpha channels, can also be done.
*
* @note Not implemented for the codimension one case.
*/
std::ostream &out) const;
/**
- * Write grid to @p out according to the given data format. This
- * function simply calls the appropriate <tt>write_*</tt> function.
+ * Write grid to @p out according to the given data format. This function
+ * simply calls the appropriate <tt>write_*</tt> function.
*/
template <int dim, int spacedim>
void write (const Triangulation<dim,spacedim> &tria,
void set_flags (const GridOutFlags::Gnuplot &flags);
/**
- * Set flags for EPS output of a
- * one-dimensional triangulation
+ * Set flags for EPS output of a one-dimensional triangulation
*/
void set_flags (const GridOutFlags::Eps<1> &flags);
/**
- * Set flags for EPS output of a
- * two-dimensional triangulation
+ * Set flags for EPS output of a two-dimensional triangulation
*/
void set_flags (const GridOutFlags::Eps<2> &flags);
void set_flags (const GridOutFlags::Vtu &flags);
/**
- * Provide a function that can tell us which
- * suffix a given output format
+ * Provide a function that can tell us which suffix a given output format
* usually has. For example, it defines the following mappings:
* <ul>
* <li> @p OpenDX: <tt>.dx</tt>
* </ul>
* Similar mappings are provided for all implemented formats.
*
- * Since this function does not need data from this object, it is
- * static and can thus be called without creating an object of this
- * class.
+ * Since this function does not need data from this object, it is static and
+ * can thus be called without creating an object of this class.
*/
static std::string default_suffix (const OutputFormat output_format);
std::string default_suffix () const;
/**
- * Return the @p OutputFormat value corresponding to the given
- * string. If the string does not match any known format, an
- * exception is thrown.
+ * Return the @p OutputFormat value corresponding to the given string. If
+ * the string does not match any known format, an exception is thrown.
*
- * Since this function does not need data from this object, it is
- * static and can thus be called without creating an object of this
- * class. Its main purpose is to allow a program to use any
- * implemented output format without the need to extend the
- * program's parser each time a new format is implemented.
+ * Since this function does not need data from this object, it is static and
+ * can thus be called without creating an object of this class. Its main
+ * purpose is to allow a program to use any implemented output format
+ * without the need to extend the program's parser each time a new format is
+ * implemented.
*
- * To get a list of presently available format names, e.g. to give
- * it to the ParameterHandler class, use the function
- * get_output_format_names().
+ * To get a list of presently available format names, e.g. to give it to the
+ * ParameterHandler class, use the function get_output_format_names().
*/
static OutputFormat parse_output_format (const std::string &format_name);
/**
- * Return a list of implemented output formats. The different names
- * are separated by vertical bar signs (<tt>`|'</tt>) as used by the
+ * Return a list of implemented output formats. The different names are
+ * separated by vertical bar signs (<tt>`|'</tt>) as used by the
* ParameterHandler classes.
*/
static std::string get_output_format_names ();
void parse_parameters (ParameterHandler ¶m);
/**
- * Determine an estimate for the memory consumption (in bytes) of
- * this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
GridOutFlags::DX dx_flags;
/**
- * Flags for GMSH output. Can be changed by using the set_flags(const GridOutFlags::Msh&)
- * function.
+ * Flags for GMSH output. Can be changed by using the set_flags(const
+ * GridOutFlags::Msh&) function.
*/
GridOutFlags::Msh msh_flags;
/**
- * Flags for UCD output. Can be changed by using the set_flags(const GridOutFlags::Ucd&)
- * function.
+ * Flags for UCD output. Can be changed by using the set_flags(const
+ * GridOutFlags::Ucd&) function.
*/
GridOutFlags::Ucd ucd_flags;
/**
- * Flags to be used upon output of GNUPLOT data. Can be changed by
- * using the set_flags(const GridOutFlags::Gnuplot&) function.
+ * Flags to be used upon output of GNUPLOT data. Can be changed by using the
+ * set_flags(const GridOutFlags::Gnuplot&) function.
*/
GridOutFlags::Gnuplot gnuplot_flags;
/**
- * Flags to be used upon output of EPS
- * data in one space dimension. Can be
- * changed by using the set_flags(const GridOutFlags::Eps<1>&)
- * function.
+ * Flags to be used upon output of EPS data in one space dimension. Can be
+ * changed by using the set_flags(const GridOutFlags::Eps<1>&) function.
*/
GridOutFlags::Eps<1> eps_flags_1;
/**
- * Flags to be used upon output of EPS
- * data in two space dimensions. Can be
- * changed by using the @p set_flags
- * function.
+ * Flags to be used upon output of EPS data in two space dimensions. Can be
+ * changed by using the @p set_flags function.
*/
GridOutFlags::Eps<2> eps_flags_2;
/**
- * Flags to be used upon output of EPS
- * data in three space dimensions. Can be
- * changed by using the @p set_flags
- * function.
+ * Flags to be used upon output of EPS data in three space dimensions. Can
+ * be changed by using the @p set_flags function.
*/
GridOutFlags::Eps<3> eps_flags_3;
GridOutFlags::Vtu vtu_flags;
/**
- * Write the grid information about faces to @p out. Only those
- * faces are printed which are on the boundary and which have a
- * boundary indicator not equal to zero, since the latter is the
- * default for boundary faces.
+ * Write the grid information about faces to @p out. Only those faces are
+ * printed which are on the boundary and which have a boundary indicator not
+ * equal to zero, since the latter is the default for boundary faces.
*
- * Since cells and faces are continuously numbered, the @p
- * starting_index for the numbering of the faces is passed also.
+ * Since cells and faces are continuously numbered, the @p starting_index
+ * for the numbering of the faces is passed also.
*
* This function unfortunately can not be included in the regular @p
* write_msh function, since it needs special treatment for the case
- * <tt>dim==1</tt>, in which case the face iterators are
- * <tt>void*</tt>'s and lack the member functions which are
- * called. We would not actually call these functions, but the
- * compiler would complain anyway when compiling the function for
- * <tt>dim==1</tt>. Bad luck.
+ * <tt>dim==1</tt>, in which case the face iterators are <tt>void*</tt>'s
+ * and lack the member functions which are called. We would not actually
+ * call these functions, but the compiler would complain anyway when
+ * compiling the function for <tt>dim==1</tt>. Bad luck.
*/
template <int dim, int spacedim>
void write_msh_faces (const Triangulation<dim,spacedim> &tria,
std::ostream &out) const;
/**
- * Declaration of the specialization
- * of above function for 1d. Does
- * nothing.
+ * Declaration of the specialization of above function for 1d. Does nothing.
*/
void write_msh_faces (const Triangulation<1,1> &tria,
const unsigned int starting_index,
std::ostream &out) const;
/**
- * Declaration of the specialization
- * of above function for 1d, 2sd. Does
+ * Declaration of the specialization of above function for 1d, 2sd. Does
* nothing.
*/
void write_msh_faces (const Triangulation<1,2> &tria,
/**
- * Write the grid information about lines to @p out. Only those
- * lines are printed which are on the boundary and which have a
- * boundary indicator not equal to zero, since the latter is the
- * default for boundary faces.
+ * Write the grid information about lines to @p out. Only those lines are
+ * printed which are on the boundary and which have a boundary indicator not
+ * equal to zero, since the latter is the default for boundary faces.
*
- * Since cells and faces are continuously numbered, the @p
- * starting_index for the numbering of the lines is passed also.
+ * Since cells and faces are continuously numbered, the @p starting_index
+ * for the numbering of the lines is passed also.
*
* This function unfortunately can not be included in the regular @p
* write_msh function, since it needs special treatment for the case
- * <tt>dim==1</tt> and <tt>dim==2</tt>, in which case the edge
- * iterators are <tt>void*</tt>'s and lack the member functions
- * which are called. We would not actually call these functions, but
- * the compiler would complain anyway when compiling the function
- * for <tt>dim==1/2</tt>. Bad luck.
+ * <tt>dim==1</tt> and <tt>dim==2</tt>, in which case the edge iterators are
+ * <tt>void*</tt>'s and lack the member functions which are called. We would
+ * not actually call these functions, but the compiler would complain anyway
+ * when compiling the function for <tt>dim==1/2</tt>. Bad luck.
*/
template <int dim, int spacedim>
void write_msh_lines (const Triangulation<dim,spacedim> &tria,
std::ostream &out) const;
/**
- * Declaration of the specialization of above function for 1d. Does
- * nothing.
+ * Declaration of the specialization of above function for 1d. Does nothing.
*/
void write_msh_lines (const Triangulation<1,1> &tria,
const unsigned int starting_index,
std::ostream &out) const;
/**
- * Declaration of the specialization of above function for 1d,
- * 2sd. Does nothing.
+ * Declaration of the specialization of above function for 1d, 2sd. Does
+ * nothing.
*/
void write_msh_lines (const Triangulation<1,2> &tria,
const unsigned int starting_index,
const unsigned int starting_index,
std::ostream &out) const;
/**
- * Declaration of the specialization of above function for 2d. Does
- * nothing.
+ * Declaration of the specialization of above function for 2d. Does nothing.
*/
void write_msh_lines (const Triangulation<2,2> &tria,
const unsigned int starting_index,
std::ostream &out) const;
/**
- * Declaration of the specialization of above function for 2d,
- * 3sd. Does nothing.
+ * Declaration of the specialization of above function for 2d, 3sd. Does
+ * nothing.
*/
void write_msh_lines (const Triangulation<2,3> &tria,
const unsigned int starting_index,
std::ostream &out) const;
/**
- * Write the grid information about faces to @p out. Only those
- * faces are printed which are on the boundary and which have a
- * boundary indicator not equal to zero, since the latter is the
- * default for boundary faces.
+ * Write the grid information about faces to @p out. Only those faces are
+ * printed which are on the boundary and which have a boundary indicator not
+ * equal to zero, since the latter is the default for boundary faces.
*
- * Since cells and faces are continuously numbered, the @p
- * starting_index for the numbering of the faces is passed also.
+ * Since cells and faces are continuously numbered, the @p starting_index
+ * for the numbering of the faces is passed also.
*
* This function unfortunately can not be included in the regular @p
* write_ucd function, since it needs special treatment for the case
- * <tt>dim==1</tt>, in which case the face iterators are
- * <tt>void*</tt>'s and lack the member functions which are
- * called. We would not actually call these functions, but the
- * compiler would complain anyway when compiling the function for
- * <tt>dim==1</tt>. Bad luck.
+ * <tt>dim==1</tt>, in which case the face iterators are <tt>void*</tt>'s
+ * and lack the member functions which are called. We would not actually
+ * call these functions, but the compiler would complain anyway when
+ * compiling the function for <tt>dim==1</tt>. Bad luck.
*/
std::ostream &out) const;
/**
- * Declaration of the specialization of above function for 1d. Does
- * nothing.
+ * Declaration of the specialization of above function for 1d. Does nothing.
*/
void write_ucd_faces (const Triangulation<1,1> &tria,
const unsigned int starting_index,
std::ostream &out) const;
/**
- * Declaration of the specialization of above function for 1d,
- * 2sd. Does nothing.
+ * Declaration of the specialization of above function for 1d, 2sd. Does
+ * nothing.
*/
void write_ucd_faces (const Triangulation<1,2> &tria,
const unsigned int starting_index,
/**
- * Write the grid information about lines to @p out. Only those
- * lines are printed which are on the boundary and which have a
- * boundary indicator not equal to zero, since the latter is the
- * default for boundary lines.
+ * Write the grid information about lines to @p out. Only those lines are
+ * printed which are on the boundary and which have a boundary indicator not
+ * equal to zero, since the latter is the default for boundary lines.
*
* Since cells, faces and lines are continuously numbered, the @p
* starting_index for the numbering of the faces is passed also.
*
* This function unfortunately can not be included in the regular @p
* write_ucd function, since it needs special treatment for the case
- * <tt>dim==1/2</tt>, in which case the edge iterators are
- * <tt>void*</tt>'s and lack the member functions which are
- * called. We would not actually call these functions, but the
- * compiler would complain anyway when compiling the function for
- * <tt>dim==1/2</tt>. Bad luck.
+ * <tt>dim==1/2</tt>, in which case the edge iterators are <tt>void*</tt>'s
+ * and lack the member functions which are called. We would not actually
+ * call these functions, but the compiler would complain anyway when
+ * compiling the function for <tt>dim==1/2</tt>. Bad luck.
*/
std::ostream &out) const;
/**
- * Declaration of the specialization of above function for 1d. Does
- * nothing.
+ * Declaration of the specialization of above function for 1d. Does nothing.
*/
void write_ucd_lines (const Triangulation<1,1> &tria,
const unsigned int starting_index,
std::ostream &out) const;
/**
- * Declaration of the specialization of above function for 1d,
- * 2sd. Does nothing.
+ * Declaration of the specialization of above function for 1d, 2sd. Does
+ * nothing.
*/
void write_ucd_lines (const Triangulation<1,2> &tria,
const unsigned int starting_index,
/**
- * Declaration of the specialization of above function for 2d. Does
- * nothing.
+ * Declaration of the specialization of above function for 2d. Does nothing.
*/
void write_ucd_lines (const Triangulation<2,2> &tria,
const unsigned int starting_index,
std::ostream &out) const;
/**
- * Declaration of the specialization of above function for 2d,
- * 3sd. Does nothing.
+ * Declaration of the specialization of above function for 2d, 3sd. Does
+ * nothing.
*/
void write_ucd_lines (const Triangulation<2,3> &tria,
const unsigned int starting_index,
/**
- * This function projects a three-dimensional point (Point<3> point)
- * onto a two-dimensional image plane, specified by the position of
- * the camera viewing system (Point<3> camera_position), camera
- * direction (Point<3> camera_position), camera horizontal (Point<3>
- * camera_horizontal, necessary for the correct alignment of the
- * later images), and the focus of the camera (float camera_focus).
+ * This function projects a three-dimensional point (Point<3> point) onto a
+ * two-dimensional image plane, specified by the position of the camera
+ * viewing system (Point<3> camera_position), camera direction (Point<3>
+ * camera_position), camera horizontal (Point<3> camera_horizontal,
+ * necessary for the correct alignment of the later images), and the focus
+ * of the camera (float camera_focus).
*
* For SVG output of grids.
*/
float camera_focus);
/**
- * Return the number of faces in the triangulation which have a
- * boundary indicator not equal to zero. Only these faces are
- * explicitly printed in the <tt>write_*</tt> functions; all faces
- * with indicator numbers::internal_face_boundary_id are interior
- * ones and an indicator with value zero for faces at the boundary
-
- * are considered default.
+ * Return the number of faces in the triangulation which have a boundary
+ * indicator not equal to zero. Only these faces are explicitly printed in
+ * the <tt>write_*</tt> functions; all faces with indicator
+ * numbers::internal_face_boundary_id are interior ones and an indicator
+ * with value zero for faces at the boundary are considered default.
*
* This function always returns an empty list in one dimension.
*
- * The reason for this function is the same as for
- * write_ucd_faces(). See there for more information.
+ * The reason for this function is the same as for write_ucd_faces(). See
+ * there for more information.
*/
template <int dim, int spacedim>
unsigned int n_boundary_faces (const Triangulation<dim,spacedim> &tria) const;
/**
- * Declaration of the specialization of above function for
- * 1d. Simply returns zero.
+ * Declaration of the specialization of above function for 1d. Simply
+ * returns zero.
*/
unsigned int n_boundary_faces (const Triangulation<1,1> &tria) const;
/**
- * Declaration of the specialization of above function for 1d,
- * 2sd. Simply returns zero.
+ * Declaration of the specialization of above function for 1d, 2sd. Simply
+ * returns zero.
*/
unsigned int n_boundary_faces (const Triangulation<1,2> &tria) const;
unsigned int n_boundary_faces (const Triangulation<1,3> &tria) const;
/**
- * Return the number of lines in the triangulation which have a
- * boundary indicator not equal to zero. Only these lines are
- * explicitly printed in the <tt>write_*</tt> functions; all lines
- * with indicator numbers::internal_face_boundary_id are interior
- * ones and an indicator with value zero for faces at the boundary
- * are considered default.
+ * Return the number of lines in the triangulation which have a boundary
+ * indicator not equal to zero. Only these lines are explicitly printed in
+ * the <tt>write_*</tt> functions; all lines with indicator
+ * numbers::internal_face_boundary_id are interior ones and an indicator
+ * with value zero for faces at the boundary are considered default.
*
- * This function always returns an empty list in one and two
- * dimensions.
+ * This function always returns an empty list in one and two dimensions.
*
- * The reason for this function is the same as for
- * write_ucd_faces(). See there for more information.
+ * The reason for this function is the same as for write_ucd_faces(). See
+ * there for more information.
*/
template <int dim, int spacedim>
unsigned int n_boundary_lines (const Triangulation<dim,spacedim> &tria) const;
/**
- * Declaration of the specialization of above function for
- * 1d. Simply returns zero.
+ * Declaration of the specialization of above function for 1d. Simply
+ * returns zero.
*/
unsigned int n_boundary_lines (const Triangulation<1,1> &tria) const;
/**
- * Declaration of the specialization of above function for 1d,
- * 2sd. Simply returns zero.
+ * Declaration of the specialization of above function for 1d, 2sd. Simply
+ * returns zero.
*/
unsigned int n_boundary_lines (const Triangulation<1,2> &tria) const;
unsigned int n_boundary_lines (const Triangulation<1,3> &tria) const;
/**
- * Declaration of the specialization of above function for
- * 2d. Simply returns zero.
+ * Declaration of the specialization of above function for 2d. Simply
+ * returns zero.
*/
unsigned int n_boundary_lines (const Triangulation<2,2> &tria) const;
/**
- * Declaration of the specialization of above function for 2d,
- * 3sd. Simply returns zero.
+ * Declaration of the specialization of above function for 2d, 3sd. Simply
+ * returns zero.
*/
unsigned int n_boundary_lines (const Triangulation<2,3> &tria) const;
};
* Triangulation objects.
*
* The functions in this namespace form two categories. There are the
- * auxiliary functions refine() and coarsen(). More important for
- * users are the other functions, which implement refinement
- * strategies, as being found in the literature on adaptive finite
- * element methods. For mathematical discussion of these methods,
- * consider works by Dörfler, Morin, Nochetto, Rannacher,
- * Stevenson and many more.
+ * auxiliary functions refine() and coarsen(). More important for users are
+ * the other functions, which implement refinement strategies, as being found
+ * in the literature on adaptive finite element methods. For mathematical
+ * discussion of these methods, consider works by Dörfler, Morin,
+ * Nochetto, Rannacher, Stevenson and many more.
*
* @ingroup grid
* @author Wolfgang Bangerth, Thomas Richter, Guido Kanschat 1998, 2000, 2009
namespace GridRefinement
{
/**
- * This function provides a refinement strategy with predictable
- * growth of the mesh.
+ * This function provides a refinement strategy with predictable growth of
+ * the mesh.
*
* The function takes a vector of refinement @p criteria and two values
- * between zero and one denoting the fractions of cells to be refined
- * and coarsened. It flags cells for further processing by
+ * between zero and one denoting the fractions of cells to be refined and
+ * coarsened. It flags cells for further processing by
* Triangulation::execute_coarsening_and_refinement() according to the
* following greedy algorithm:
*
* <ol>
*
- * <li> Sort the cells according to descending values of @p criteria.
+ * <li> Sort the cells according to descending values of @p criteria.
*
- * <li> Set the refinement threshold to be the criterion belonging to
- * the cell at position @p top_fraction_of_cells times
- * Triangulation::n_active_cells().
+ * <li> Set the refinement threshold to be the criterion belonging to the
+ * cell at position @p top_fraction_of_cells times
+ * Triangulation::n_active_cells().
*
* <li> Set the coarsening threshold accordingly using the cell @p
- * bottom_fraction_of_cells times Triangulation::n_active_cells()
- * from the end of the sorted list.
+ * bottom_fraction_of_cells times Triangulation::n_active_cells() from the
+ * end of the sorted list.
*
- * <li> Use these two thresholds in calls to refine() and coarsen(),
- * respectively.
+ * <li> Use these two thresholds in calls to refine() and coarsen(),
+ * respectively.
*
* </ol>
*
- * As an example, with no coarsening, setting @p top_fraction_of_cells
- * to 1/3 will result in approximately doubling the number of cells in
- * two dimensions. The same effect in three dimensions is achieved by
- * refining 1/7th of the cells. These values are good initial guesses,
- * but should be adjusted depending on the singularity of approximated
- * function.
- *
- * The sorting of criteria is not done actually, since we only need
- * the threshold values in order to call refine() and coarsen(). The
- * order of cells with higher and of those with lower criteria is
- * irrelevant. Getting this value is accomplished by the @p
- * nth_element function of the <tt>C++</tt> standard library, which
- * takes only linear time in the number of elements, rather than <tt>N
- * log N</tt> for sorting all values.
- *
- * @warning This function only sets the coarsening and refinement
- * flags. The mesh is not changed until you call
+ * As an example, with no coarsening, setting @p top_fraction_of_cells to
+ * 1/3 will result in approximately doubling the number of cells in two
+ * dimensions. The same effect in three dimensions is achieved by refining
+ * 1/7th of the cells. These values are good initial guesses, but should be
+ * adjusted depending on the singularity of approximated function.
+ *
+ * The sorting of criteria is not done actually, since we only need the
+ * threshold values in order to call refine() and coarsen(). The order of
+ * cells with higher and of those with lower criteria is irrelevant. Getting
+ * this value is accomplished by the @p nth_element function of the
+ * <tt>C++</tt> standard library, which takes only linear time in the number
+ * of elements, rather than <tt>N log N</tt> for sorting all values.
+ *
+ * @warning This function only sets the coarsening and refinement flags. The
+ * mesh is not changed until you call
* Triangulation::execute_coarsening_and_refinement().
*
- * @arg @p criteria: the refinement criterion computed on each mesh
- * cell. Entries may not be negative.
+ * @arg @p criteria: the refinement criterion computed on each mesh cell.
+ * Entries may not be negative.
*
- * @arg @p top_fraction_of_cells is the fraction of cells to be
- * refined. If this number is zero, no cells will be refined. If it
- * equals one, the result will be flagging for global refinement.
+ * @arg @p top_fraction_of_cells is the fraction of cells to be refined. If
+ * this number is zero, no cells will be refined. If it equals one, the
+ * result will be flagging for global refinement.
*
* @arg @p bottom_fraction_of_cells is the fraction of cells to be
* coarsened. If this number is zero, no cells will be coarsened.
*
- * @arg @p max_n_cells can be used to specify a maximal number of
- * cells. If this number is going to be exceeded upon refinement, then
- * refinement and coarsening fractions are going to be adjusted in an
- * attempt to reach the maximum number of cells. Be aware though that
- * through proliferation of refinement due to
- * Triangulation::MeshSmoothing, this number is only an indicator. The
- * default value of this argument is to impose no limit on the number
- * of cells.
+ * @arg @p max_n_cells can be used to specify a maximal number of cells. If
+ * this number is going to be exceeded upon refinement, then refinement and
+ * coarsening fractions are going to be adjusted in an attempt to reach the
+ * maximum number of cells. Be aware though that through proliferation of
+ * refinement due to Triangulation::MeshSmoothing, this number is only an
+ * indicator. The default value of this argument is to impose no limit on
+ * the number of cells.
*/
template <int dim, class Vector, int spacedim>
void
const unsigned int max_n_cells = std::numeric_limits<unsigned int>::max());
/**
- * This function provides a refinement strategy controlling the
- * reduction of the error estimate.
+ * This function provides a refinement strategy controlling the reduction of
+ * the error estimate.
*
* Also known as the <b>bulk criterion</b>, this function computes the
- * thresholds for refinement and coarsening such that the @p criteria
- * of cells getting flagged for refinement make up for a certain
- * fraction of the total error. We explain its operation for
- * refinement, coarsening works analogously.
+ * thresholds for refinement and coarsening such that the @p criteria of
+ * cells getting flagged for refinement make up for a certain fraction of
+ * the total error. We explain its operation for refinement, coarsening
+ * works analogously.
*
- * Let <i>c<sub>K</sub></i> be the criterion of cell <i>K</i>. Then
- * the total error estimate is computed by the formula
+ * Let <i>c<sub>K</sub></i> be the criterion of cell <i>K</i>. Then the
+ * total error estimate is computed by the formula
* @f[
* E = \sum_{K\in \cal T} c_K.
* @f]
* refine_and_coarsen_fixed_number().
*
* @note The often used formula with squares on the left and right is
- * recovered by actually storing the square of <i>c<sub>K</sub></i> in
- * the vector @p criteria.
+ * recovered by actually storing the square of <i>c<sub>K</sub></i> in the
+ * vector @p criteria.
*
- * From the point of view of implementation, this time we really need
- * to sort the array of criteria. Just like the other strategy
- * described above, this function only computes the threshold values
- * and then passes over to refine() and coarsen().
+ * From the point of view of implementation, this time we really need to
+ * sort the array of criteria. Just like the other strategy described
+ * above, this function only computes the threshold values and then passes
+ * over to refine() and coarsen().
*
- * @arg @p criteria: the refinement criterion computed on each mesh
- * cell. Entries may not be negative.
+ * @arg @p criteria: the refinement criterion computed on each mesh cell.
+ * Entries may not be negative.
*
- * @arg @p top_fraction is the fraction of the total estimate which
- * should be refined. If this number is zero, no cells will be refined. If it
+ * @arg @p top_fraction is the fraction of the total estimate which should
+ * be refined. If this number is zero, no cells will be refined. If it
* equals one, the result will be flagging for global refinement.
*
- * @arg @p bottom_fraction is the fraction of the estimate
- * coarsened. If this number is zero, no cells will be coarsened.
+ * @arg @p bottom_fraction is the fraction of the estimate coarsened. If
+ * this number is zero, no cells will be coarsened.
*
- * @arg @p max_n_cells can be used to specify a maximal number of
- * cells. If this number is going to be exceeded upon refinement, then
- * refinement and coarsening fractions are going to be adjusted in an
- * attempt to reach the maximum number of cells. Be aware though that
- * through proliferation of refinement due to
- * Triangulation::MeshSmoothing, this number is only an indicator. The
- * default value of this argument is to impose no limit on the number
- * of cells.
+ * @arg @p max_n_cells can be used to specify a maximal number of cells. If
+ * this number is going to be exceeded upon refinement, then refinement and
+ * coarsening fractions are going to be adjusted in an attempt to reach the
+ * maximum number of cells. Be aware though that through proliferation of
+ * refinement due to Triangulation::MeshSmoothing, this number is only an
+ * indicator. The default value of this argument is to impose no limit on
+ * the number of cells.
*/
template <int dim, class Vector, int spacedim>
void
* argument to this function, then the error on the children (for all
* children together) will only be $2^{-\text{order}}\eta_K$ where
* <code>order</code> is the third argument of this function. This makes the
- * assumption that the error is only a local property on a mesh and can
- * be reduced by local refinement -- an assumption that is true for the
+ * assumption that the error is only a local property on a mesh and can be
+ * reduced by local refinement -- an assumption that is true for the
* interpolation operator, but not for the usual Galerkin projection,
* although it is approximately true for elliptic problems where the Greens
- * function decays quickly and the error here is not too much affected by
- * a too coarse mesh somewhere else.
+ * function decays quickly and the error here is not too much affected by a
+ * too coarse mesh somewhere else.
*
- * With this, we can define the objective function this function tries
- * to optimize. Let us assume that the mesh currently has $N_0$ cells.
- * Then, if we refine the $m$ cells with the largest errors, we expect
- * to get (in $d$ space dimensions)
+ * With this, we can define the objective function this function tries to
+ * optimize. Let us assume that the mesh currently has $N_0$ cells. Then, if
+ * we refine the $m$ cells with the largest errors, we expect to get (in $d$
+ * space dimensions)
* @f[
* N(m) = (N_0-m) + 2^d m = N_0 + (2^d-1)m
* @f]
- * cells ($N_0-m$ are not refined, and each of the $m$ cells we refine
- * yield $2^d$ child cells. On the other hand, with refining $m$ cells,
- * and using the assumptions above, we expect that the error will be
+ * cells ($N_0-m$ are not refined, and each of the $m$ cells we refine yield
+ * $2^d$ child cells. On the other hand, with refining $m$ cells, and using
+ * the assumptions above, we expect that the error will be
* @f[
* \eta^\text{exp}(m)
* =
* +
* \sum_{K, K\; \text{will be refined}} 2^{-\text{order}}\eta_K
* @f]
- * where the first sum extends over $N_0-m$ cells and the second
- * over the $m$ cells that will be refined. Note that $N(m)$
- * is an increasing function of $m$ whereas $\eta^\text{exp}(m)$
- * is a decreasing function.
+ * where the first sum extends over $N_0-m$ cells and the second over the
+ * $m$ cells that will be refined. Note that $N(m)$ is an increasing
+ * function of $m$ whereas $\eta^\text{exp}(m)$ is a decreasing function.
*
- * This function then tries to find that number $m$ of cells to refine
- * for which the objective function
+ * This function then tries to find that number $m$ of cells to refine for
+ * which the objective function
* @f[
* J(m) = N(m)^{\text{order}/d} \eta^\text{exp}(m)
* @f]
* is minimal.
*
- * The rationale for this function is two-fold. First, compared to
- * the refine_and_coarsen_fixed_fraction() and
- * refine_and_coarsen_fixed_number() functions, this function has
- * the property that if all refinement indicators are the same
- * (i.e., we have achieved a mesh where the error per cell is
- * equilibrated), then the entire mesh is refined. This is based on
- * the observation that a mesh with equilibrated error indicators is
- * the optimal mesh (i.e., has the least overall error) among all
- * meshes with the same number of cells. (For proofs of this, see
- * R. Becker, M. Braack, R. Rannacher: "Numerical simulation of
- * laminar flames at low Mach number with adaptive finite elements",
- * Combustion Theory and Modelling, Vol. 3, Nr. 3, p. 503-534 1999;
- * and W. Bangerth, R. Rannacher: "Adaptive Finite Element Methods
- * for Differential Equations", Birkhauser, 2003.)
- *
- * Second, the function uses the observation that ideally, the error
- * behaves like $e \approx c N^{-\alpha}$ with some constant
- * $\alpha$ that depends on the dimension and the finite element
- * degree. It should - given optimal mesh refinement - not depend so
- * much on the regularity of the solution, as it is based on the
- * idea, that all singularities can be resolved by refinement. Mesh
- * refinement is then based on the idea that we want to make
- * $c=e N^\alpha$ small. This corresponds to the functional $J(m)$
+ * The rationale for this function is two-fold. First, compared to the
+ * refine_and_coarsen_fixed_fraction() and refine_and_coarsen_fixed_number()
+ * functions, this function has the property that if all refinement
+ * indicators are the same (i.e., we have achieved a mesh where the error
+ * per cell is equilibrated), then the entire mesh is refined. This is based
+ * on the observation that a mesh with equilibrated error indicators is the
+ * optimal mesh (i.e., has the least overall error) among all meshes with
+ * the same number of cells. (For proofs of this, see R. Becker, M. Braack,
+ * R. Rannacher: "Numerical simulation of laminar flames at low Mach number
+ * with adaptive finite elements", Combustion Theory and Modelling, Vol. 3,
+ * Nr. 3, p. 503-534 1999; and W. Bangerth, R. Rannacher: "Adaptive Finite
+ * Element Methods for Differential Equations", Birkhauser, 2003.)
+ *
+ * Second, the function uses the observation that ideally, the error behaves
+ * like $e \approx c N^{-\alpha}$ with some constant $\alpha$ that depends
+ * on the dimension and the finite element degree. It should - given optimal
+ * mesh refinement - not depend so much on the regularity of the solution,
+ * as it is based on the idea, that all singularities can be resolved by
+ * refinement. Mesh refinement is then based on the idea that we want to
+ * make $c=e N^\alpha$ small. This corresponds to the functional $J(m)$
* above.
*
- * @note This function was originally implemented by Thomas
- * Richter. It follows a strategy described in T. Richter,
- * "Parallel Multigrid Method for Adaptive Finite Elements with
- * Application to 3D Flow Problems", PhD thesis, University of
- * Heidelberg, 2005. See in particular Section 4.3, pp. 42-43.
+ * @note This function was originally implemented by Thomas Richter. It
+ * follows a strategy described in T. Richter, "Parallel Multigrid Method
+ * for Adaptive Finite Elements with Application to 3D Flow Problems", PhD
+ * thesis, University of Heidelberg, 2005. See in particular Section 4.3,
+ * pp. 42-43.
*/
template <int dim, class Vector, int spacedim>
void
* Flag all mesh cells for which the value in @p criteria exceeds @p
* threshold for refinement, but only flag up to @p max_to_mark cells.
*
- * The vector @p criteria contains a nonnegative value for each active
- * cell, ordered in the canonical order of of
- * Triangulation::active_cell_iterator.
+ * The vector @p criteria contains a nonnegative value for each active cell,
+ * ordered in the canonical order of of Triangulation::active_cell_iterator.
*
- * The cells are only flagged for refinement, they are not actually
- * refined. To do so, you have to call
+ * The cells are only flagged for refinement, they are not actually refined.
+ * To do so, you have to call
* Triangulation::execute_coarsening_and_refinement().
*
- * This function does not implement a refinement strategy, it is more
- * a helper function for the actual strategies.
+ * This function does not implement a refinement strategy, it is more a
+ * helper function for the actual strategies.
*/
template <int dim, class Vector, int spacedim>
void refine (Triangulation<dim,spacedim> &tria,
const unsigned int max_to_mark = numbers::invalid_unsigned_int);
/**
- * Flag all mesh cells for which the value in @p criteria
- * is less than @p threshold for coarsening.
+ * Flag all mesh cells for which the value in @p criteria is less than @p
+ * threshold for coarsening.
*
* The vector @p criteria contains a nonnegative value for each active cell,
- * ordered in the canonical order of of
- * Triangulation::active_cell_iterator.
+ * ordered in the canonical order of of Triangulation::active_cell_iterator.
*
* The cells are only flagged for coarsening, they are not actually
* coarsened. To do so, you have to call
* Triangulation::execute_coarsening_and_refinement().
*
- * This function does not implement a refinement strategy, it is more
- * a helper function for the actual strategies.
+ * This function does not implement a refinement strategy, it is more a
+ * helper function for the actual strategies.
*/
template <int dim, class Vector, int spacedim>
void coarsen (Triangulation<dim,spacedim> &tria,
const double threshold);
/**
- * An exception thrown if the
- * vector with cell criteria contains
- * negative values
+ * An exception thrown if the vector with cell criteria contains negative
+ * values
*/
DeclException0(ExcNegativeCriteria);
/**
- * One of the threshold parameters
- * causes trouble. Or the
- * refinement and coarsening
- * thresholds overlap.
+ * One of the threshold parameters causes trouble. Or the refinement and
+ * coarsening thresholds overlap.
*/
DeclException0 (ExcInvalidParameterValue);
}
* deal.II triangulations.
*
* @note In contrast to the rest of the deal.II library, by default this class
- * uses the old deal.II numbering scheme, which was used up to deal.II
- * version 5.2 (but the main function of this class takes a flag that
- * specifies whether it should do an implicit conversion from the new
- * to the old format before doing its work, and then back again after
- * reordering). In this old format, the vertex and face ordering in 2d is assumed
- * to be
+ * uses the old deal.II numbering scheme, which was used up to deal.II version
+ * 5.2 (but the main function of this class takes a flag that specifies
+ * whether it should do an implicit conversion from the new to the old format
+ * before doing its work, and then back again after reordering). In this old
+ * format, the vertex and face ordering in 2d is assumed to be
* @verbatim
* 2
* 3--->---2
* |/ / | |/
* *-------* *-------*
* @endverbatim
- * After calling the GridReordering::reorder_cells() function the
- * CellData is still in this old numbering scheme. Hence, for creating
- * a Triangulation based on the resulting CellData the
+ * After calling the GridReordering::reorder_cells() function the CellData is
+ * still in this old numbering scheme. Hence, for creating a Triangulation
+ * based on the resulting CellData the
* Triangulation::create_triangulation_compatibility() (and not the
- * Triangulation::create_triangulation()) function must be used. For
- * a typical use of the reorder_cells() function see the
- * implementation of the GridIn <code>read_*()</code> functions.
+ * Triangulation::create_triangulation()) function must be used. For a
+ * typical use of the reorder_cells() function see the implementation of the
+ * GridIn <code>read_*()</code> functions.
*
*
* <h3>Statement of problems</h3>
*
- * Triangulations in deal.II have a special structure, in that there
- * are not only cells, but also faces, and in 3d also edges, that are
- * objects of their own right. Faces and edges have unique
- * orientations, and they have a specified orientation also with
- * respect to the cells that are adjacent. Thus, a line that separates
- * two cells in two space dimensions does not only have a direction,
- * but it must also have a well-defined orientation with respect to
- * the other lines bounding the two quadrilaterals adjacent to the
- * first line. Likewise definitions hold for three dimensional cells
- * and the objects (lines, quads) that separate them.
- *
- * For example, in two dimensions, a quad consists of four lines which
- * have a direction, which is by definition as follows:
+ * Triangulations in deal.II have a special structure, in that there are not
+ * only cells, but also faces, and in 3d also edges, that are objects of their
+ * own right. Faces and edges have unique orientations, and they have a
+ * specified orientation also with respect to the cells that are adjacent.
+ * Thus, a line that separates two cells in two space dimensions does not only
+ * have a direction, but it must also have a well-defined orientation with
+ * respect to the other lines bounding the two quadrilaterals adjacent to the
+ * first line. Likewise definitions hold for three dimensional cells and the
+ * objects (lines, quads) that separate them.
+ *
+ * For example, in two dimensions, a quad consists of four lines which have a
+ * direction, which is by definition as follows:
* @verbatim
* 3-->--2
* | |
* | |
* 0-->--1
* @endverbatim
- * Now, two adjacent cells must have a vertex numbering such that the direction
- * of the common side is the same. For example, the following two quads
+ * Now, two adjacent cells must have a vertex numbering such that the
+ * direction of the common side is the same. For example, the following two
+ * quads
* @verbatim
* 3---4---5
* | | |
* 0---1---2
* @endverbatim
- * may be characterised by the vertex numbers <tt>(0 1 4 3)</tt> and
- * <tt>(1 2 5 4)</tt>, since the middle line would get the direction <tt>1->4</tt>
- * when viewed from both cells. The numbering <tt>(0 1 4 3)</tt> and
- * <tt>(5 4 1 2)</tt> would not be allowed, since the left quad would give the
- * common line the direction <tt>1->4</tt>, while the right one would want
- * to use <tt>4->1</tt>, leading to an ambiguity.
- *
- * As a sidenote, we remark that if one adopts the idea that having
- * directions of faces is useful, then the orientation of the four
- * faces of a cell as shown above is almost necessary. In particular,
- * it is not possible to orient them such that they represent a
- * (counter-)clockwise sense, since then we couldn't already find a
- * valid orientation of the following patch of three cells:
+ * may be characterised by the vertex numbers <tt>(0 1 4 3)</tt> and <tt>(1 2
+ * 5 4)</tt>, since the middle line would get the direction <tt>1->4</tt> when
+ * viewed from both cells. The numbering <tt>(0 1 4 3)</tt> and <tt>(5 4 1
+ * 2)</tt> would not be allowed, since the left quad would give the common
+ * line the direction <tt>1->4</tt>, while the right one would want to use
+ * <tt>4->1</tt>, leading to an ambiguity.
+ *
+ * As a sidenote, we remark that if one adopts the idea that having directions
+ * of faces is useful, then the orientation of the four faces of a cell as
+ * shown above is almost necessary. In particular, it is not possible to
+ * orient them such that they represent a (counter-)clockwise sense, since
+ * then we couldn't already find a valid orientation of the following patch of
+ * three cells:
* @verbatim
* o
* / \
* | | |
* o---o---o
* @endverbatim
- * (The reader is asked to try to find a conforming choice of line
- * directions; it will soon be obvious that there can't exists such a
- * thing, even if we allow that there might be cells with clockwise
- * and counterclockwise orientation of the lines at the same time.)
- *
- * One might argue that the definition of unique directions for faces
- * and edges, and the definition of directions relative to the cells
- * they bound, is a misfeature of deal.II. In fact, it makes reading
- * in grids created by mesh generators rather difficult, as they
- * usually don't follow these conventions when generating their
- * output. On the other hand, there are good reasons to introduce such
- * conventions, as they can make programming much simpler in many
- * cases, leading to an increase in speed of some computations as one
- * can avoid expensive checks in many places because the orientation
- * of faces is known by assumption that it is guaranteed by the
- * triangulation.
- *
- * The purpose of this class is now to find an ordering for a given
- * set of cells such that the generated triangulation satisfies all
- * the requirements stated above. To this end, we will first show some
- * examples why this is a difficult problem, and then develop
- * algorithms that finds such a reordering. Note that the algorithm
- * operates on a set of CellData objects that are used to
- * describe a mesh to the triangulation class. These objects are, for
- * example, generated by the GridIn class, when reading in grids
- * from input files.
- *
- * As a last question for this first section: is it guaranteed that
- * such orientations of faces always exist for a given subdivision of
- * a domain into cells? The linear complexity algorithm described
- * below for 2d also proves that the answer is yes for 2d. For 3d, the
- * answer is no (which also underlines that using such orientations
- * might be an -- unfortunately uncurable -- misfeature of deal.II). A
- * simple counter-example in 3d illustrates this: take a string of 3d
- * cells and bend it together to a torus. Since opposing lines in a
- * cell need to have the same direction, there is a simple ordering
- * for them, for example all lines radially outward, tangentially
- * clockwise, and axially upward. However, if before joining the two
- * ends of the string of cells, the string is twisted by 180 degrees,
- * then no such orientation is possible any more, as can easily be
- * checked. In effect, some meshes could not be used in deal.II.
- * In order to overcome this problem, the <code>face_rotation</code>,
- * <code>face_flip</code> and <code>line_orientation</code> flags have
- * been introduced. With these, it is possible to treat all purely hexahedral
+ * (The reader is asked to try to find a conforming choice of line directions;
+ * it will soon be obvious that there can't exists such a thing, even if we
+ * allow that there might be cells with clockwise and counterclockwise
+ * orientation of the lines at the same time.)
+ *
+ * One might argue that the definition of unique directions for faces and
+ * edges, and the definition of directions relative to the cells they bound,
+ * is a misfeature of deal.II. In fact, it makes reading in grids created by
+ * mesh generators rather difficult, as they usually don't follow these
+ * conventions when generating their output. On the other hand, there are good
+ * reasons to introduce such conventions, as they can make programming much
+ * simpler in many cases, leading to an increase in speed of some computations
+ * as one can avoid expensive checks in many places because the orientation of
+ * faces is known by assumption that it is guaranteed by the triangulation.
+ *
+ * The purpose of this class is now to find an ordering for a given set of
+ * cells such that the generated triangulation satisfies all the requirements
+ * stated above. To this end, we will first show some examples why this is a
+ * difficult problem, and then develop algorithms that finds such a
+ * reordering. Note that the algorithm operates on a set of CellData objects
+ * that are used to describe a mesh to the triangulation class. These objects
+ * are, for example, generated by the GridIn class, when reading in grids from
+ * input files.
+ *
+ * As a last question for this first section: is it guaranteed that such
+ * orientations of faces always exist for a given subdivision of a domain into
+ * cells? The linear complexity algorithm described below for 2d also proves
+ * that the answer is yes for 2d. For 3d, the answer is no (which also
+ * underlines that using such orientations might be an -- unfortunately
+ * uncurable -- misfeature of deal.II). A simple counter-example in 3d
+ * illustrates this: take a string of 3d cells and bend it together to a
+ * torus. Since opposing lines in a cell need to have the same direction,
+ * there is a simple ordering for them, for example all lines radially
+ * outward, tangentially clockwise, and axially upward. However, if before
+ * joining the two ends of the string of cells, the string is twisted by 180
+ * degrees, then no such orientation is possible any more, as can easily be
+ * checked. In effect, some meshes could not be used in deal.II. In order to
+ * overcome this problem, the <code>face_rotation</code>,
+ * <code>face_flip</code> and <code>line_orientation</code> flags have been
+ * introduced. With these, it is possible to treat all purely hexahedral
* meshes. However, in order to reduce the effect of possible bugs, it should
- * still be tried to reorder a grid. Only if this procedure fails, the original
- * connectivity information should be used.
+ * still be tried to reorder a grid. Only if this procedure fails, the
+ * original connectivity information should be used.
*
*
* <h3>Examples of problems</h3>
*
- * As noted, reordering the vertex lists of cells such that the
- * resulting grid is not a trivial problem. In particular, it is often
- * not sufficient to only look at the neighborhood of a cell that
- * cannot be added to a set of other cells without violating the
- * requirements stated above. We will show two examples where this is
- * obvious.
- *
- * The first such example is the following, which we will call the
- * ``four cells at the end'' because of the four cells that close of
- * the right end of a row of three vertical cells each (in the
- * following picture we only show one such column of three cells at
- * the left, but we will indicate what happens if we prolong this
- * list):
+ * As noted, reordering the vertex lists of cells such that the resulting grid
+ * is not a trivial problem. In particular, it is often not sufficient to only
+ * look at the neighborhood of a cell that cannot be added to a set of other
+ * cells without violating the requirements stated above. We will show two
+ * examples where this is obvious.
+ *
+ * The first such example is the following, which we will call the ``four
+ * cells at the end'' because of the four cells that close of the right end of
+ * a row of three vertical cells each (in the following picture we only show
+ * one such column of three cells at the left, but we will indicate what
+ * happens if we prolong this list):
* @verbatim
* 9---10-----11
* | | / |
* ^ ^ \ |
* 0->-1------2
* @endverbatim
- * (This could for example be done by using the indices <tt>(0 1 4 3)</tt>, <tt>(3 4 7 6)</tt>,
- * <tt>(6 7 10 9)</tt> for the three cells). Now, you will not find a way of giving
- * indices for the right cells, without introducing either ambiguity for
- * one line or other, or without violating that within each cells, there must be
- * one vertex from which both lines are directed away and the opposite one to
- * which both adjacent lines point to.
+ * (This could for example be done by using the indices <tt>(0 1 4 3)</tt>,
+ * <tt>(3 4 7 6)</tt>, <tt>(6 7 10 9)</tt> for the three cells). Now, you will
+ * not find a way of giving indices for the right cells, without introducing
+ * either ambiguity for one line or other, or without violating that within
+ * each cells, there must be one vertex from which both lines are directed
+ * away and the opposite one to which both adjacent lines point to.
*
* The solution in this case is to renumber one of the three left cells, e.g.
* by reverting the sense of the line between vertices 7 and 10 by numbering
* | | | | | \ |
* o---o---o---o---o------o
* @endverbatim
- * Then we run into the same problem as above if we order the cells at
- * the left uniformly, thus forcing us to revert the ordering of one
- * cell (the one which we could order as <tt>(9 6 7 10)</tt>
- * above). However, since opposite lines have to have the same
- * direction, this in turn would force us to rotate the cell left of
- * it, and then the one left to that, and so on until we reach the
- * left end of the grid. This is therefore an example we we have to
- * track back right until the first column of three cells to find a
+ * Then we run into the same problem as above if we order the cells at the
+ * left uniformly, thus forcing us to revert the ordering of one cell (the one
+ * which we could order as <tt>(9 6 7 10)</tt> above). However, since opposite
+ * lines have to have the same direction, this in turn would force us to
+ * rotate the cell left of it, and then the one left to that, and so on until
+ * we reach the left end of the grid. This is therefore an example we we have
+ * to track back right until the first column of three cells to find a
* consistent ordering, if we had initially ordered them uniformly.
*
- * As a second example, consider the following simple grid, where the
- * order in which the cells are numbered is important:
+ * As a second example, consider the following simple grid, where the order in
+ * which the cells are numbered is important:
* @verbatim
* 3-----2-----o-----o ... o-----7-----6
* | | | | | | |
* | | | | | | |
* 0-----1-----o-----o ... o-----4-----5
* @endverbatim
- * We have here only indicated the numbers of the vertices that are
- * relevant. Assume that the user had given the cells 0 and 1 by the
- * vertex indices <tt>0 1 2 3</tt> and <tt>6 7 4 5</tt>. Then, if we follow this
- * orientation, the grid after creating the lines for these two cells
- * would look like this:
+ * We have here only indicated the numbers of the vertices that are relevant.
+ * Assume that the user had given the cells 0 and 1 by the vertex indices
+ * <tt>0 1 2 3</tt> and <tt>6 7 4 5</tt>. Then, if we follow this orientation,
+ * the grid after creating the lines for these two cells would look like this:
* @verbatim
* 3-->--2-----o-----o ... o-----7--<--6
* | | | | | | |
* | | | | | | |
* 0-->--1-----o-----o ... o-----4--<--5
* @endverbatim
- * Now, since opposite lines must point in the same direction, we can
- * only add the cells 2 through N-1 to cells 1 such that all vertical
- * lines point down. Then, however, we cannot add cell N in any
- * direction, as it would have two opposite lines that do not point in
- * the same direction. We would have to rotate either cell 0 or 1 in
- * order to be able to add all the other cells such that the
- * requirements of deal.II triangulations are met.
- *
- * These two examples demonstrate that if we have added a certain
- * number of cells in some orientation of faces and can't add the next
- * one without introducing faces that had already been added in another
- * direction, then it might not be sufficient to only rotate cells in
- * the neighborhood of the the cell that we failed to add. It might be
- * necessary to go back a long way and rotate cells that have been
- * entered long ago.
+ * Now, since opposite lines must point in the same direction, we can only add
+ * the cells 2 through N-1 to cells 1 such that all vertical lines point down.
+ * Then, however, we cannot add cell N in any direction, as it would have two
+ * opposite lines that do not point in the same direction. We would have to
+ * rotate either cell 0 or 1 in order to be able to add all the other cells
+ * such that the requirements of deal.II triangulations are met.
+ *
+ * These two examples demonstrate that if we have added a certain number of
+ * cells in some orientation of faces and can't add the next one without
+ * introducing faces that had already been added in another direction, then it
+ * might not be sufficient to only rotate cells in the neighborhood of the the
+ * cell that we failed to add. It might be necessary to go back a long way and
+ * rotate cells that have been entered long ago.
*
*
* <h3>Solution</h3>
*
- * From the examples above, it is obvious that if we encounter a cell
- * that cannot be added to the cells which have already been entered,
- * we can not usually point to a cell that is the culprit and that
- * must be entered in a different oreintation. Furthermore, even if we
- * knew which cell, there might be large number of cells that would
- * then cease to fit into the grid and which we would have to find a
- * different orientation as well (in the second example above, if we
- * rotated cell 1, then we would have to rotate the cells 1 through
- * N-1 as well).
- *
- * A brute force approach to this problem is the following: if
- * cell N can't be added, then try to rotate cell N-1. If we can't
- * rotate cell N-1 any more, then try to rotate cell N-2 and try to
- * add cell N with all orientations of cell N-1. And so
- * on. Algorithmically, we can visualize this by a tree structure,
- * where node N has as many children as there are possible
+ * From the examples above, it is obvious that if we encounter a cell that
+ * cannot be added to the cells which have already been entered, we can not
+ * usually point to a cell that is the culprit and that must be entered in a
+ * different oreintation. Furthermore, even if we knew which cell, there might
+ * be large number of cells that would then cease to fit into the grid and
+ * which we would have to find a different orientation as well (in the second
+ * example above, if we rotated cell 1, then we would have to rotate the cells
+ * 1 through N-1 as well).
+ *
+ * A brute force approach to this problem is the following: if cell N can't be
+ * added, then try to rotate cell N-1. If we can't rotate cell N-1 any more,
+ * then try to rotate cell N-2 and try to add cell N with all orientations of
+ * cell N-1. And so on. Algorithmically, we can visualize this by a tree
+ * structure, where node N has as many children as there are possible
* orientations of node N+1 (in two space dimensions, there are four
- * orientations in which each cell can be constructed from its four
- * vertices; for example, if the vertex indicaes are <tt>(0 1 2 3)</tt>,
- * then the four possibilities would be <tt>(0 1 2 3)</tt>, <tt>(1 2 3 0)</tt>,
- * <tt>(2 3 0 1)</tt>, and <tt>(3 0 1 2)</tt>). When adding one cell after the
- * other, we traverse this tree in a depth-first (pre-order)
- * fashion. When we encounter that one path from the root (cell 0) to
- * a leaf (the last cell) is not allowed (i.e. that the orientations
- * of the cells which are encoded in the path through the tree does
- * not lead to a valid triangulation), we have to track back and try
- * another path through the tree.
- *
- * In practice, of course, we do not follow each path to a final node
- * and then find out whether a path leads to a valid triangulation,
- * but rather use an inductive argument: if for all previously added
- * cells the triangulation is a valid one, then we can find out
- * whether a path through the tree can yield a valid triangulation by
- * checking whether entering the present cell would introduce any
- * faces that have a nonunique direction; if that is so, then we can
- * stop following all paths below this point and track back
- * immediately.
- *
- * Nevertheless, it is already obvious that the tree has <tt>4**N</tt>
- * leaves in two space dimensions, since each of the N cells can be
- * added in four orientations. Most of these nodes can be discarded
- * rapidly, since firstly the orientation of the first cell is
- * irrelevant, and secondly if we add one cell that has a neighbor
- * that has already been added, then there are already only two
- * possible orientations left, so the total number of checks we have
- * to make until we find a valid way is significantly smaller than
+ * orientations in which each cell can be constructed from its four vertices;
+ * for example, if the vertex indicaes are <tt>(0 1 2 3)</tt>, then the four
+ * possibilities would be <tt>(0 1 2 3)</tt>, <tt>(1 2 3 0)</tt>, <tt>(2 3 0
+ * 1)</tt>, and <tt>(3 0 1 2)</tt>). When adding one cell after the other, we
+ * traverse this tree in a depth-first (pre-order) fashion. When we encounter
+ * that one path from the root (cell 0) to a leaf (the last cell) is not
+ * allowed (i.e. that the orientations of the cells which are encoded in the
+ * path through the tree does not lead to a valid triangulation), we have to
+ * track back and try another path through the tree.
+ *
+ * In practice, of course, we do not follow each path to a final node and then
+ * find out whether a path leads to a valid triangulation, but rather use an
+ * inductive argument: if for all previously added cells the triangulation is
+ * a valid one, then we can find out whether a path through the tree can yield
+ * a valid triangulation by checking whether entering the present cell would
+ * introduce any faces that have a nonunique direction; if that is so, then we
+ * can stop following all paths below this point and track back immediately.
+ *
+ * Nevertheless, it is already obvious that the tree has <tt>4**N</tt> leaves
+ * in two space dimensions, since each of the N cells can be added in four
+ * orientations. Most of these nodes can be discarded rapidly, since firstly
+ * the orientation of the first cell is irrelevant, and secondly if we add one
+ * cell that has a neighbor that has already been added, then there are
+ * already only two possible orientations left, so the total number of checks
+ * we have to make until we find a valid way is significantly smaller than
* <tt>4**N</tt>. However, the algorithm is still exponential in time and
- * linear in memory (we only have to store the information for the
- * present path in form of a stack of orientations of cells that have
- * already been added).
+ * linear in memory (we only have to store the information for the present
+ * path in form of a stack of orientations of cells that have already been
+ * added).
*
- * In fact, the two examples above show that the exponential estimate
- * is not a pessimized one: we indeed have to track back to one of the
- * very first cells there to find a way to add all cells in a
- * consistent fashion.
+ * In fact, the two examples above show that the exponential estimate is not a
+ * pessimized one: we indeed have to track back to one of the very first cells
+ * there to find a way to add all cells in a consistent fashion.
*
- * This discouraging situation is greatly improved by the fact that we
- * have an alternative algorithm for 2d that is always linear in
- * runtime (discovered and implemented by Michael Anderson of TICAM,
- * University of Texas, in 2003), and that for 3d we can find an
- * algorithm that in practice is usually only roughly linear in time
- * and memory. We will describe these algorithms in the following.
+ * This discouraging situation is greatly improved by the fact that we have an
+ * alternative algorithm for 2d that is always linear in runtime (discovered
+ * and implemented by Michael Anderson of TICAM, University of Texas, in
+ * 2003), and that for 3d we can find an algorithm that in practice is usually
+ * only roughly linear in time and memory. We will describe these algorithms
+ * in the following.
*
*
* <h3>The 2d linear complexity algorithm</h3>
*
- * The algorithm uses the fact that opposite faces of a cell need to
- * have the same orientation. So you start with one arbitrary line,
- * choose an orientation. Then the orientation of the opposite face is
- * already fixed. Then go to the two cells across the two faces we
- * have fixed: for them, one face is fixed, so we can also fix the
- * opposite face. Go on with doing so. Eventually, we have done this
- * for a string of cells. Then take one of the non-fixed faces of a
- * cell which has already two fixed faces and do all this again.
- *
- * In more detail, the algorithm is best illustrated using an
- * example. We consider the mesh below:
+ * The algorithm uses the fact that opposite faces of a cell need to have the
+ * same orientation. So you start with one arbitrary line, choose an
+ * orientation. Then the orientation of the opposite face is already fixed.
+ * Then go to the two cells across the two faces we have fixed: for them, one
+ * face is fixed, so we can also fix the opposite face. Go on with doing so.
+ * Eventually, we have done this for a string of cells. Then take one of the
+ * non-fixed faces of a cell which has already two fixed faces and do all this
+ * again.
+ *
+ * In more detail, the algorithm is best illustrated using an example. We
+ * consider the mesh below:
* @verbatim
* 9------10-------11
* | | /|
* 0------1---------2
* @endverbatim
* First a cell is chosen ( (0,1,4,3) in this case). A single side of the cell
- * is oriented arbitrarily (3->4). This choice of orientation is then propogated
- * through the mesh, across sides and elements. (0->1), (6->7) and (9->10).
- * The involves edge-hopping and face hopping, giving a path through the mesh
- * shown in dots.
+ * is oriented arbitrarily (3->4). This choice of orientation is then
+ * propogated through the mesh, across sides and elements. (0->1), (6->7) and
+ * (9->10). The involves edge-hopping and face hopping, giving a path through
+ * the mesh shown in dots.
* @verbatim
* 9-->--10-------11
* | . | /|
* | | \|
* 0-->--1-->-------2
* @endverbatim
- * It is obvious that this algorithm has linear run-time, since it
- * only ever touches each face exactly once.
+ * It is obvious that this algorithm has linear run-time, since it only ever
+ * touches each face exactly once.
*
* The algorithm just described is implemented in a specialization of this
* class for the 2d case. A similar, but slightly more complex algorithm is
* here is how it works, and why it doesn't always work for large meshes since
* its run-time can be exponential in bad cases.
*
- * The first observation is that although there are counterexamples,
- * problems are usually local. For example, in the second example
- * mentioned above, if we had numbered the cells in a way that
- * neighboring cells have similar cell numbers, then the amount of
- * backtracking needed is greatly reduced. Therefore, in the
- * implementation of the algorithm, the first step is to renumber the
- * cells in a Cuthill-McKee fashion: start with the cell with the
- * least number of neighbors and assign to it the cell number
- * zero. Then find all neighbors of this cell and assign to them
- * consecutive further numbers. Then find their neighbors that have
- * not yet been numbered and assign to them numbers, and so
- * on. Graphically, this represents finding zones of cells
- * consecutively further away from the initial cells and number them
- * in this front-marching way. This already greatly improves locality
- * of problems and consequently reduced the necessary amount of
- * backtracking.
- *
- * The second point is that we can use some methods to prune the tree,
- * which usually lead to a valid orientation of all cells very
- * quickly.
- *
- * The first such method is based on the observation that if we
- * fail to insert one cell with number N, then this may not be due to
- * cell N-1 unless N-1 is a direct neighbor of N. The reason is
- * abvious: the chosen orientation of cell M could only affect the
- * possibilities to add cell N if either it were a direct neighbor or
- * if there were a sequence of cells that were added after M and that
- * connected cells M and N. Clearly, for M=N-1, the latter cannot be
- * the case. Conversely, if we fail to add cell N, then it is not
- * necessary to track back to cell N-1, but we can track back to the
- * neighbor of N with the largest cell index and which has already
- * been added.
- *
- * Unfortunately, this method can fail to yield a valid path through
- * the tree if not applied with care. Consider the following
- * situation, initially extracted from a mesh of 950 cells generated
- * automatically by the program BAMG (this program usually generates
- * meshes that are quite badly balanced, often have many -- sometimes
- * 10 or more -- neighbors of one vertex, and exposed several problems
- * in the initial algorithm; note also that the example is in 2d where
- * we now have the much better algorithm described above, but the same
- * observations also apply to 3d):
+ * The first observation is that although there are counterexamples, problems
+ * are usually local. For example, in the second example mentioned above, if
+ * we had numbered the cells in a way that neighboring cells have similar cell
+ * numbers, then the amount of backtracking needed is greatly reduced.
+ * Therefore, in the implementation of the algorithm, the first step is to
+ * renumber the cells in a Cuthill-McKee fashion: start with the cell with the
+ * least number of neighbors and assign to it the cell number zero. Then find
+ * all neighbors of this cell and assign to them consecutive further numbers.
+ * Then find their neighbors that have not yet been numbered and assign to
+ * them numbers, and so on. Graphically, this represents finding zones of
+ * cells consecutively further away from the initial cells and number them in
+ * this front-marching way. This already greatly improves locality of problems
+ * and consequently reduced the necessary amount of backtracking.
+ *
+ * The second point is that we can use some methods to prune the tree, which
+ * usually lead to a valid orientation of all cells very quickly.
+ *
+ * The first such method is based on the observation that if we fail to insert
+ * one cell with number N, then this may not be due to cell N-1 unless N-1 is
+ * a direct neighbor of N. The reason is abvious: the chosen orientation of
+ * cell M could only affect the possibilities to add cell N if either it were
+ * a direct neighbor or if there were a sequence of cells that were added
+ * after M and that connected cells M and N. Clearly, for M=N-1, the latter
+ * cannot be the case. Conversely, if we fail to add cell N, then it is not
+ * necessary to track back to cell N-1, but we can track back to the neighbor
+ * of N with the largest cell index and which has already been added.
+ *
+ * Unfortunately, this method can fail to yield a valid path through the tree
+ * if not applied with care. Consider the following situation, initially
+ * extracted from a mesh of 950 cells generated automatically by the program
+ * BAMG (this program usually generates meshes that are quite badly balanced,
+ * often have many -- sometimes 10 or more -- neighbors of one vertex, and
+ * exposed several problems in the initial algorithm; note also that the
+ * example is in 2d where we now have the much better algorithm described
+ * above, but the same observations also apply to 3d):
* @verbatim
* 13----------14----15
* | \ | |
* | | | |
* 0-----1-----2-----3
* @endverbatim
- * Note that there is a hole in the middle. Assume now that the user
- * described the first cell 0 by the vertex numbers <tt>2 3 7 6</tt>, and
- * cell 5 by <tt>15 14 10 11</tt>, and assume that cells 1, 2, 3, and 4 are
- * numbered such that 5 can be added in initial rotation. All other
- * cells are numbered in the usual way, i.e. starting at the bottom
- * left and counting counterclockwise. Given this description of
- * cells, the algorithm will start with cell zero and add one cell
- * after the other, up until the sixth one. Then the situation will be
- * the following:
+ * Note that there is a hole in the middle. Assume now that the user described
+ * the first cell 0 by the vertex numbers <tt>2 3 7 6</tt>, and cell 5 by
+ * <tt>15 14 10 11</tt>, and assume that cells 1, 2, 3, and 4 are numbered
+ * such that 5 can be added in initial rotation. All other cells are numbered
+ * in the usual way, i.e. starting at the bottom left and counting
+ * counterclockwise. Given this description of cells, the algorithm will start
+ * with cell zero and add one cell after the other, up until the sixth one.
+ * Then the situation will be the following:
* @verbatim
* 13----->---14--<--15
* | \ | |
* | | | |
* 0-->--1-->--2-->--3
* @endverbatim
- * Coming now to cell 7, we see that the two opposite lines at its top
- * and bottom have different directions; we will therefore find no
- * orientation of cell 7 in which it can be added without violation of
- * the consistency of the triangulation. According to the rule stated
- * above, we track back to the neighbor with greatest index, which is
- * cell 6, but since its bottom line is to the right, its top line
- * must be to the right as well, so we won't be able to find an
- * orientation of cell 6 such that 7 will fit into the
- * triangulation. Then, if we have finished all possible orientations
- * of cell 6, we track back to the neighbor of 6 with the largest
- * index and which has been added already. This would be cell
- * 0. However, we know that the orientation of cell 0 can't be
- * important, so we conclude that there is no possible way to orient
- * all the lines of the given cells such that they satisfy the
- * requirements if deal.II triangulations. We know that this can't be,
- * so it results in an exception be thrown.
- *
- * The bottom line of this example is that when we looked at all
- * possible orientations of cell 6, we couldn't find one such that
- * cell 7 could be added, and then decided to track back to cell 0. We
- * did not even attempt to turn cell 5, after which it would be simple
- * to add cell 7. Thus, the algorithm described above has to be
- * modified: we are only allowed to track back to that neighbor that
- * has already been added, with the largest cell index, if we fail to
- * add a cell in any orientation. If we track back further because we
- * have exhausted all possible orientations but could add the cell
- * (i.e. we track back since another cell, further down the road
- * couldn't be added, irrespective of the orientation of the cell
- * which we are presently considering), then we are not allowed to
- * track back to one of its neighbors, but have to track back only one
- * cell index.
- *
- * The second method to prune the tree is that usually we cannot add a
- * new cell since the orientation of one of its neighbors that have
- * already been added is wrong. Thus, if we may try to rotate one of
- * the neighbors (of course making sure that rotating that neighbor
- * does not violate the consistency of the triangulation) in order to
- * allow the present cell to be added.
- *
- * While the first method could be explained in terms of backtracking
- * in the tree of orientations more than one step at once, turning a
- * neighbor means jumping to a totally different place in the
- * tree. For both methods, one can find arguments that they will never
- * miss a path that is valid and only skip paths that are invalid
- * anyway.
- *
- * These two methods have proven extremely efficient. We have been
- * able to read very large grids (several ten thousands of cells)
- * without the need to track back much. In particular, the time to find
- * an ordering of the cells was found to be mostly linear in the
- * number of cells, and the time to reorder them is usually much
- * smaller (for example by one order of magnitude) than the time
- * needed to read the data from a file, and also to actually generate
- * the triangulation from this data using the
+ * Coming now to cell 7, we see that the two opposite lines at its top and
+ * bottom have different directions; we will therefore find no orientation of
+ * cell 7 in which it can be added without violation of the consistency of the
+ * triangulation. According to the rule stated above, we track back to the
+ * neighbor with greatest index, which is cell 6, but since its bottom line is
+ * to the right, its top line must be to the right as well, so we won't be
+ * able to find an orientation of cell 6 such that 7 will fit into the
+ * triangulation. Then, if we have finished all possible orientations of cell
+ * 6, we track back to the neighbor of 6 with the largest index and which has
+ * been added already. This would be cell 0. However, we know that the
+ * orientation of cell 0 can't be important, so we conclude that there is no
+ * possible way to orient all the lines of the given cells such that they
+ * satisfy the requirements if deal.II triangulations. We know that this can't
+ * be, so it results in an exception be thrown.
+ *
+ * The bottom line of this example is that when we looked at all possible
+ * orientations of cell 6, we couldn't find one such that cell 7 could be
+ * added, and then decided to track back to cell 0. We did not even attempt to
+ * turn cell 5, after which it would be simple to add cell 7. Thus, the
+ * algorithm described above has to be modified: we are only allowed to track
+ * back to that neighbor that has already been added, with the largest cell
+ * index, if we fail to add a cell in any orientation. If we track back
+ * further because we have exhausted all possible orientations but could add
+ * the cell (i.e. we track back since another cell, further down the road
+ * couldn't be added, irrespective of the orientation of the cell which we are
+ * presently considering), then we are not allowed to track back to one of its
+ * neighbors, but have to track back only one cell index.
+ *
+ * The second method to prune the tree is that usually we cannot add a new
+ * cell since the orientation of one of its neighbors that have already been
+ * added is wrong. Thus, if we may try to rotate one of the neighbors (of
+ * course making sure that rotating that neighbor does not violate the
+ * consistency of the triangulation) in order to allow the present cell to be
+ * added.
+ *
+ * While the first method could be explained in terms of backtracking in the
+ * tree of orientations more than one step at once, turning a neighbor means
+ * jumping to a totally different place in the tree. For both methods, one can
+ * find arguments that they will never miss a path that is valid and only skip
+ * paths that are invalid anyway.
+ *
+ * These two methods have proven extremely efficient. We have been able to
+ * read very large grids (several ten thousands of cells) without the need to
+ * track back much. In particular, the time to find an ordering of the cells
+ * was found to be mostly linear in the number of cells, and the time to
+ * reorder them is usually much smaller (for example by one order of
+ * magnitude) than the time needed to read the data from a file, and also to
+ * actually generate the triangulation from this data using the
* Triangulation::create_triangulation() function.
*
* @ingroup grid
public:
/**
- * This is the main function,
- * doing what is announced in
- * the general documentation of
- * this class for dim=2 and 3
- * and doing nothing for dim=1.
+ * This is the main function, doing what is announced in the general
+ * documentation of this class for dim=2 and 3 and doing nothing for dim=1.
*
- * If a consistent reordering is not
- * possible in dim=3, the original
- * connectivity data is restored.
+ * If a consistent reordering is not possible in dim=3, the original
+ * connectivity data is restored.
*
- * @param original_cells An object that contains the data that describes
- * the mesh.
- * @param use_new_style_ordering If true, then use the standard
- * ordering of vertices within a cell. If false (the default), then
- * use the "old-style" ordering of vertices within cells used by
- * deal.II before version 5.2 and as explained in the documentation
- * of this class.
+ * @param original_cells An object that contains the data that describes the
+ * mesh.
+ * @param use_new_style_ordering If true, then use the standard ordering of
+ * vertices within a cell. If false (the default), then use the "old-style"
+ * ordering of vertices within cells used by deal.II before version 5.2 and
+ * as explained in the documentation of this class.
*/
static void reorder_cells (std::vector<CellData<dim> > &original_cells,
const bool use_new_style_ordering = false);
/**
- * Grids generated by grid
- * generators may have an
- * orientation of cells which is
- * the inverse of the orientation
- * required by deal.II.
+ * Grids generated by grid generators may have an orientation of cells which
+ * is the inverse of the orientation required by deal.II.
*
- * In 2d and 3d this function checks
- * whether all cells have
- * negative or positive
- * measure/volume. In the former
- * case, all cells are inverted.
- * It does nothing in 1d.
+ * In 2d and 3d this function checks whether all cells have negative or
+ * positive measure/volume. In the former case, all cells are inverted. It
+ * does nothing in 1d.
*
- * The invertion of cells might
- * also work when only a subset
- * of all cells have negative
- * volume. However, grids
- * consisting of a mixture of
- * negative and positiv oriented
- * cells are very likely to be
- * broken. Therefore, an
- * exception is thrown, in case
- * cells are not uniformly
- * oriented.
+ * The invertion of cells might also work when only a subset of all cells
+ * have negative volume. However, grids consisting of a mixture of negative
+ * and positiv oriented cells are very likely to be broken. Therefore, an
+ * exception is thrown, in case cells are not uniformly oriented.
*
- * Note, that this function
- * should be called before
- * reorder_cells().
+ * Note, that this function should be called before reorder_cells().
*/
static void invert_all_cells_of_negative_grid(
const std::vector<Point<spacedim> > &all_vertices,
{
/**
- * Check whether a given
- * arrangement of cells is
- * already consisten. If this is
- * the case, then we skip the
- * reordering pass.
+ * Check whether a given arrangement of cells is already consisten. If
+ * this is the case, then we skip the reordering pass.
*
- * This function works by looping
- * over all cells, checking
- * whether one of its faces
- * already exists in a list of
- * edges, and if it already
- * exists in reverse order, then
- * return @p false. If it is not
- * already in the list, or in the
- * correct direction, then go on
- * with the next faces or cell.
+ * This function works by looping over all cells, checking whether one of
+ * its faces already exists in a list of edges, and if it already exists
+ * in reverse order, then return @p false. If it is not already in the
+ * list, or in the correct direction, then go on with the next faces or
+ * cell.
*/
bool
is_consistent (const std::vector<CellData<2> > &cells);
/**
- * Defines a variety of variables related to the connectivity of a
- * simple quad element. This includes the nodes on each edge, which
- * edges come into each node and what the default deal.II directions
- * are for the quad.
+ * Defines a variety of variables related to the connectivity of a simple
+ * quad element. This includes the nodes on each edge, which edges come
+ * into each node and what the default deal.II directions are for the
+ * quad.
*
* @verbatim
* s2
{
public:
/**
- * The nodes on each edge in
- * anti-clockwise order
- * { {0,1},{1,2},{2,3},{3,0} }
+ * The nodes on each edge in anti-clockwise order {
+ * {0,1},{1,2},{2,3},{3,0} }
*/
static const int EdgeToNode[4][2];
/**
- * The edges comin into each
- * node, in anti-clockwise
- * order
- * { {3,0},{0,1},{1,2},{2,3} }
+ * The edges comin into each node, in anti-clockwise order {
+ * {3,0},{0,1},{1,2},{2,3} }
*/
static const int NodeToEdge[4][2];
/**
- * The nodes on each edge in
- * "default direction order".
+ * The nodes on each edge in "default direction order".
* {{0,1},{1,2},{3,2},{0,3}}
*/
static const int DefaultOrientation[4][2];
/**
- * An enriched quad with information about how the mesh fits together
- * so that we can move around the mesh efficiently.
+ * An enriched quad with information about how the mesh fits together so
+ * that we can move around the mesh efficiently.
*
* @author Michael Anderson, 2003
*/
{
public:
/**
- * v0 - v3 are indexes of the
- * vertices of the quad, s0 -
- * s3 are indexes for the
- * sides of the quad
+ * v0 - v3 are indexes of the vertices of the quad, s0 - s3 are indexes
+ * for the sides of the quad
*/
MQuad (const unsigned int v0,
const unsigned int v1,
unsigned int side[4];
/**
- * Copy of the @p CellData object
- * from which we construct the
- * data of this object.
+ * Copy of the @p CellData object from which we construct the data of
+ * this object.
*/
CellData<2> original_cell_data;
};
/**
* The enriched side class containing connectivity information.
- * Orientation is from v0 to v1; Initially this should have v0<v1.
- * After global orientation could be either way.
+ * Orientation is from v0 to v1; Initially this should have v0<v1. After
+ * global orientation could be either way.
*
* @author Michael Anderson, 2003
*/
const unsigned int initv1);
/**
- * Return whether the sides
- * are equal, even if their
- * ends are reversed.
+ * Return whether the sides are equal, even if their ends are reversed.
*/
bool operator==(const MSide &s2) const;
struct SideRectify;
/**
- * Provides a side ordering,
- * s1<s2, without assuming
- * v0<v1 in either of the
- * sides.
+ * Provides a side ordering, s1<s2, without assuming v0<v1 in either of
+ * the sides.
*/
struct SideSortLess;
};
public:
/**
- * Do the work intended by
- * this class.
+ * Do the work intended by this class.
*/
void reorient(std::vector<CellData<2> > &quads);
private:
/**
- * Sets up the internal data
- * structures so that the we can
- * do side hopping and face
- * switching efficiently. This
- * means we need a whole bunch of
- * connectivity information
+ * Sets up the internal data structures so that the we can do side
+ * hopping and face switching efficiently. This means we need a whole
+ * bunch of connectivity information
*/
void build_graph (const std::vector<CellData<2> > &inquads);
/**
- * Orient the internal data
- * into deal.II format The
- * orientation algorith is as
- * follows
+ * Orient the internal data into deal.II format The orientation algorith
+ * is as follows
*
- * 1) Find an unoriented quad
- (A)
+ * 1) Find an unoriented quad (A)
*
- * 2) Orient an un_oriented
- side (s) of (A)
+ * 2) Orient an un_oriented side (s) of (A)
*
- * 3) side hop on (s) of (A)
- to get (B)
+ * 3) side hop on (s) of (A) to get (B)
*
- * 4) if opposite side to (s)
- * of (B) is unoriented
- * orient it
+ * 4) if opposite side to (s) of (B) is unoriented orient it
*
- * 5) repeat 3) and 4) until
- * side-hoppong fails (we've
- * reached a boundary) or (s)
- * has already been oriented
- * (we've closed a loop or
+ * 5) repeat 3) and 4) until side-hoppong fails (we've reached a
+ * boundary) or (s) has already been oriented (we've closed a loop or
* unoriented sides).
*
- * 6) Repeat 2), 3), 4) and
- * 5) on other unoriented
- * sides of (A)
+ * 6) Repeat 2), 3), 4) and 5) on other unoriented sides of (A)
*
- * 7) Choose a new unoriented
- * A.
+ * 7) Choose a new unoriented A.
*/
void orient();
/**
- * Get the (now correctly
- * oriented if we've called
- * orient) quads.
+ * Get the (now correctly oriented if we've called orient) quads.
*/
void get_quads(std::vector<CellData<2> > &outquads) const;
/**
- * Orient_side(qnum,lsn)
- * orients the local side lsn
- * of the quad qnum in the
- * triangulation. If the side
- * opposite lsn is oriented
- * then lsn is oriented to
- * match it. Otherwise it is
- * oriented in the "default"
+ * Orient_side(qnum,lsn) orients the local side lsn of the quad qnum in
+ * the triangulation. If the side opposite lsn is oriented then lsn is
+ * oriented to match it. Otherwise it is oriented in the "default"
* direction for the quad.
*/
void orient_side (const unsigned int quadnum,
const unsigned int localsidenum);
/**
- * Returns true if all sides
- * of the quad quadnum are
- * oriented.
+ * Returns true if all sides of the quad quadnum are oriented.
*/
bool is_fully_oriented_quad (const unsigned int quadnum) const;
/**
- * Returns true if the side lsn
- * of the quad quadnum is
- * oriented.
+ * Returns true if the side lsn of the quad quadnum is oriented.
*/
bool is_oriented_side (const unsigned int quadnum,
const unsigned int lsn) const;
/**
- * Returns true is the side is
- * oriented in the "default"
- * direction
+ * Returns true is the side is oriented in the "default" direction
*/
bool is_side_default_oriented (const unsigned int qnum,
const unsigned int lsn) const;
/**
- * Increases UnOrQLoc from
- * it's original value to the
- * next quad with an
- * unoriented side. Returns
- * true if there was another
- * unoriented quad.
+ * Increases UnOrQLoc from it's original value to the next quad with an
+ * unoriented side. Returns true if there was another unoriented quad.
*/
bool get_unoriented_quad (unsigned int &UnOrQLoc) const;
/**
- * Sets sidenum to the local
- * sidenumber of an
- * unoriented side of the
- * quad quadnum. Returns true
- * if such a side exists.
+ * Sets sidenum to the local sidenumber of an unoriented side of the
+ * quad quadnum. Returns true if such a side exists.
*/
bool get_unoriented_side (const unsigned int quadnum,
unsigned int &sidenum) const;
/**
- * side_hop(&qnum, &lsn) has
- * qnum being the quadnumber
- * of a quad in the
- * triangulation, and a local
- * side number. side_hop then
- * sets qnum to the
- * quadnumber across the
- * other side of the side,
- * and sets lsn so that
- * quads[qnum].sides[lsn] is
- * the same before and after
- * the call. if there is no
- * other quad on the other
- * side of the current quad,
- * then side_hop returns
- * false.
+ * side_hop(&qnum, &lsn) has qnum being the quadnumber of a quad in the
+ * triangulation, and a local side number. side_hop then sets qnum to
+ * the quadnumber across the other side of the side, and sets lsn so
+ * that quads[qnum].sides[lsn] is the same before and after the call.
+ * if there is no other quad on the other side of the current quad, then
+ * side_hop returns false.
*/
bool side_hop (unsigned int &qnum,
unsigned int &lsn) const;
/**
- * A list of enriched
- * sides/edges of the mesh.
+ * A list of enriched sides/edges of the mesh.
*/
std::vector<MSide> sides;
/**
- * A list of enriched quads
- * in the mesh.
+ * A list of enriched quads in the mesh.
*/
std::vector<MQuad> mquads;
};
namespace GridReordering3d
{
/**
- * A structure indicating the
- * direction of an edge. In the
- * implementation file, we define
- * three objects,
- * <tt>unoriented_edge</tt>,
- * <tt>forward_edge</tt>, and
- * <tt>backward_edge</tt>, that
- * denote whether an edge has
- * already been oriented, whether
- * it is in standard orientation,
- * or whether it has reverse
- * direction. The state that each
- * of these objects encode is
- * stored in the
- * <tt>orientation</tt> member
- * variable -- we would really
- * need only three such values,
- * which we pick in the
- * implementation file, and make
- * sure when we compare such
- * objects that only these three
- * special values are actually
- * used.
+ * A structure indicating the direction of an edge. In the implementation
+ * file, we define three objects, <tt>unoriented_edge</tt>,
+ * <tt>forward_edge</tt>, and <tt>backward_edge</tt>, that denote whether
+ * an edge has already been oriented, whether it is in standard
+ * orientation, or whether it has reverse direction. The state that each
+ * of these objects encode is stored in the <tt>orientation</tt> member
+ * variable -- we would really need only three such values, which we pick
+ * in the implementation file, and make sure when we compare such objects
+ * that only these three special values are actually used.
*
- * The reason for this way of
- * implementing things is as
- * follows. Usually, such a
- * property would be implemented
- * as an enum. However, in the
- * previous implementation, a
- * signed integer was used with
- * unoriented=0, forward=+1, and
- * backward=-1. A number of
- * operations, such as equality
- * of ordered edges were mapped
- * to checking whether the
- * product of two edge
- * orientations equals +1. Such
- * arithmetic isn't always
- * portable and sometimes flagged
- * when using -ftrapv with
- * gcc. Using this class instead
- * makes sure that there isn't
- * going to be any arithmetic
- * going on on edge orientations,
- * just comparisons for equality
- * or inequality.
+ * The reason for this way of implementing things is as follows. Usually,
+ * such a property would be implemented as an enum. However, in the
+ * previous implementation, a signed integer was used with unoriented=0,
+ * forward=+1, and backward=-1. A number of operations, such as equality
+ * of ordered edges were mapped to checking whether the product of two
+ * edge orientations equals +1. Such arithmetic isn't always portable and
+ * sometimes flagged when using -ftrapv with gcc. Using this class instead
+ * makes sure that there isn't going to be any arithmetic going on on edge
+ * orientations, just comparisons for equality or inequality.
*
* @author Wolfgang Bangerth, 2005
*/
};
/**
- * During building the
- * connectivity information we
- * don't need all the heavy duty
- * information about edges that
- * we will need later. So we can
- * save memory and time by using
- * a light-weight class for
- * edges. It stores the two
- * vertices, but no direction, so
- * we make the optimization to
- * store the vertex number in
- * sorted order to allow for
- * easier comparison of edge
- * objects.
+ * During building the connectivity information we don't need all the
+ * heavy duty information about edges that we will need later. So we can
+ * save memory and time by using a light-weight class for edges. It stores
+ * the two vertices, but no direction, so we make the optimization to
+ * store the vertex number in sorted order to allow for easier comparison
+ * of edge objects.
*/
struct CheapEdge
{
const unsigned int node1;
/**
- * Constructor. Take the
- * vertex numbers and store
- * them sorted.
+ * Constructor. Take the vertex numbers and store them sorted.
*/
CheapEdge (const unsigned int n0,
const unsigned int n1);
/**
- * Need a partial ordering
- * for the STL
+ * Need a partial ordering for the STL
*/
bool operator< (const CheapEdge &e2) const;
};
/**
- * A connectivity and orientation
- * aware edge class.
+ * A connectivity and orientation aware edge class.
*/
struct Edge
{
unsigned int nodes[2];
/**
- * Whether the edge has not
- * already been oriented,
- * points from node 0 to node
- * 1, or the reverse.
- * The initial state of
- * this flag is unoriented.
+ * Whether the edge has not already been oriented, points from node 0 to
+ * node 1, or the reverse. The initial state of this flag is unoriented.
*/
EdgeOrientation orientation_flag;
/**
- * Used to determine which
- * "sheet" or equivalence
- * class of parallel edges
- * the edge falls in when
- * oriented.
- * numbers::invalid_unsigned_int
- * means not yet
- * decided. This is also the
- * default value after
- * construction. Each edge
- * will later be assigned an
- * index greater than zero.
+ * Used to determine which "sheet" or equivalence class of parallel
+ * edges the edge falls in when oriented. numbers::invalid_unsigned_int
+ * means not yet decided. This is also the default value after
+ * construction. Each edge will later be assigned an index greater than
+ * zero.
*/
unsigned int group;
};
/**
- * A connectivity and orientation
- * aware cell.
+ * A connectivity and orientation aware cell.
*
- * The connectivity of the cell
- * is not contained within. (This
- * was for flexibility in using
- * deal.II's ordering of edges or
- * the XDA format etc.) For this
- * information we need the
- * ElemInfo class.
+ * The connectivity of the cell is not contained within. (This was for
+ * flexibility in using deal.II's ordering of edges or the XDA format
+ * etc.) For this information we need the ElemInfo class.
*
- * One thing we do know is that
- * the first four edges in the
- * edge class are parallel, as
- * are the second four, and the
- * third four.
+ * One thing we do know is that the first four edges in the edge class are
+ * parallel, as are the second four, and the third four.
*
- * TODO: Need to move connectivity information out
- * of cell and into edge.
+ * TODO: Need to move connectivity information out of cell and into edge.
*/
struct Cell
{
unsigned int nodes[GeometryInfo<3>::vertices_per_cell];
/**
- * Which way do the edges
- * point. Whether node 0 of
- * the edge is the base of
- * the edge in local element
- * (1) or node 1 is the base
- * (-1).
+ * Which way do the edges point. Whether node 0 of the edge is the base
+ * of the edge in local element (1) or node 1 is the base (-1).
*/
EdgeOrientation local_orientation_flags[GeometryInfo<3>::lines_per_cell];
/**
- * An internal flag used to
- * determine whether the cell
- * is in the queue of cells
- * to be oriented in the
- * current sheet.
+ * An internal flag used to determine whether the cell is in the queue
+ * of cells to be oriented in the current sheet.
*/
bool waiting_to_be_processed;
};
/**
- * This holds all the pieces for
- * orientation together.
+ * This holds all the pieces for orientation together.
*
- * Contains lists of nodes, edges
- * and cells. As well as the
- * information about how they all
- * connect together.
+ * Contains lists of nodes, edges and cells. As well as the information
+ * about how they all connect together.
*/
class Mesh
{
Mesh (const std::vector<CellData<3> > &incubes);
/**
- * Export the data of this
- * object to the deal.II
- * format that the
- * Triangulation class
- * wants as input.
+ * Export the data of this object to the deal.II format that the
+ * Triangulation class wants as input.
*/
void
export_to_deal_format (std::vector<CellData<3> > &outcubes) const;
std::vector<Cell> cell_list;
/**
- * Checks whether every cell
- * in the mesh is sensible.
+ * Checks whether every cell in the mesh is sensible.
*/
void sanity_check() const;
/**
- * Given the cell list, build
- * the edge list and all the
- * connectivity information
- * and other stuff that we
- * will need later.
+ * Given the cell list, build the edge list and all the connectivity
+ * information and other stuff that we will need later.
*/
void build_connectivity ();
/**
- * Unimplemented private copy
- * constructor to disable it.
+ * Unimplemented private copy constructor to disable it.
*/
Mesh (const Mesh &);
/**
- * Unimplemented private
- * assignment operator to
- * disable it.
+ * Unimplemented private assignment operator to disable it.
*/
Mesh &operator=(const Mesh &);
/**
- * Checks that each edge
- * going into a node is
- * correctly set up.
+ * Checks that each edge going into a node is correctly set up.
*/
void sanity_check_node (const Cell &cell,
const unsigned int local_node_num) const;
/**
- * Let the orienter access
- * out private fields.
+ * Let the orienter access out private fields.
*/
friend class Orienter;
};
/**
- * The class that orients the
- * edges of a triangulation in
- * 3d. The member variables
- * basically only store the
- * present state of the
- * algorithm.
+ * The class that orients the edges of a triangulation in 3d. The member
+ * variables basically only store the present state of the algorithm.
*/
class Orienter
{
public:
/**
- * Orient the given
- * mesh. Creates an object of
- * the present type and lets
- * that toil away at the
- * task.
+ * Orient the given mesh. Creates an object of the present type and lets
+ * that toil away at the task.
*
- * This function is the
- * single entry point to the
- * functionality of this
+ * This function is the single entry point to the functionality of this
* class.
*
- * Returns, whether a consistent
- * orientation of lines was possible
- * for the given mesh.
+ * Returns, whether a consistent orientation of lines was possible for
+ * the given mesh.
*/
static
bool
private:
/**
- * Internal representation of
- * the given list of cells,
- * including connectivity
- * information and the like.
+ * Internal representation of the given list of cells, including
+ * connectivity information and the like.
*/
Mesh mesh;
/**
- * The cube we're looking at
- * presently.
+ * The cube we're looking at presently.
*/
unsigned int cur_posn;
/**
- * We have fully oriented all
- * cubes before this one.
+ * We have fully oriented all cubes before this one.
*/
unsigned int marker_cube;
/**
- * The index of the sheet or
- * equivalence class we are
- * presently processing.
+ * The index of the sheet or equivalence class we are presently
+ * processing.
*/
unsigned int cur_edge_group;
/**
- * Indices of the cells to be
- * processed within the
- * present sheet. If a cell
- * is being processed
- * presently, it is taken
- * from this list.
+ * Indices of the cells to be processed within the present sheet. If a
+ * cell is being processed presently, it is taken from this list.
*/
std::vector<int> sheet_to_process;
/**
- * Which edges of the current
- * cell have been oriented
- * during the current iteration.
- * Is reset when moving on to
- * the next cube.
+ * Which edges of the current cell have been oriented during the current
+ * iteration. Is reset when moving on to the next cube.
*/
bool edge_orient_array[12];
/**
- * Constructor. Take a list
- * of cells and set up the
- * internal data structures
- * of the mesh member
- * variable.
+ * Constructor. Take a list of cells and set up the internal data
+ * structures of the mesh member variable.
*
- * Since it is
- * private, the only entry
- * point of this class is the
- * static function
- * orient_mesh().
+ * Since it is private, the only entry point of this class is the static
+ * function orient_mesh().
*/
Orienter (const std::vector<CellData<3> > &incubes);
/**
- * Orient all the edges of a
- * mesh.
+ * Orient all the edges of a mesh.
*
- * Returns, whether this action was
- * carried out successfully.
+ * Returns, whether this action was carried out successfully.
*/
bool orient_edges ();
/**
- * Given oriented edges,
- * rotate the cubes so that
- * the edges are in standard
- * direction.
+ * Given oriented edges, rotate the cubes so that the edges are in
+ * standard direction.
*/
void orient_cubes ();
bool get_next_unoriented_cube ();
/**
- * Return whether the cell
- * with cell number
- * @p cell_num is fully
+ * Return whether the cell with cell number @p cell_num is fully
* oriented.
*/
bool is_oriented (const unsigned int cell_num) const;
bool orient_next_unoriented_edge ();
/**
- * Return whether the cell is
- * consistenty oriented at
- * present (i.e. only
- * considering those edges
- * that are already
- * oriented. This is a sanity
- * check that should be
- * called from inside an
- * assert macro.
+ * Return whether the cell is consistenty oriented at present (i.e. only
+ * considering those edges that are already oriented. This is a sanity
+ * check that should be called from inside an assert macro.
*/
bool cell_is_consistent (const unsigned int cell_num) const;
/**
* This namespace is a collection of algorithms working on triangulations,
- * such as shifting or rotating triangulations, but also finding a
- * cell that contains a given point. See the descriptions of the
- * individual functions for more information.
+ * such as shifting or rotating triangulations, but also finding a cell that
+ * contains a given point. See the descriptions of the individual functions
+ * for more information.
*
* @ingroup grid
*/
namespace GridTools
{
/**
- * @name Information about meshes and cells
+ * @name Information about meshes and cells
*/
/*@{*/
/**
- * Return the diameter of a
- * triangulation. The diameter is
- * computed using only the
- * vertices, i.e. if the diameter
- * should be larger than the
- * maximal distance between
- * boundary vertices due to a
- * higher order mapping, then
- * this function will not catch
- * this.
+ * Return the diameter of a triangulation. The diameter is computed using
+ * only the vertices, i.e. if the diameter should be larger than the maximal
+ * distance between boundary vertices due to a higher order mapping, then
+ * this function will not catch this.
*/
template <int dim, int spacedim>
double diameter (const Triangulation<dim, spacedim> &tria);
/**
* Compute the volume (i.e. the dim-dimensional measure) of the
- * triangulation. We compute the measure using the integral
- * $\sum_K \int_K 1 \; dx$ where $K$ are the cells of the
- * given triangulation. The integral is approximated
- * via quadrature for which we need the mapping argument.
- *
- * If the triangulation is a dim-dimensional one embedded in
- * a higher dimensional space of dimension spacedim, then the
- * value returned is the dim-dimensional measure. For example,
- * for a two-dimensional triangulation in three-dimensional space,
- * the value returned is the area of the surface so described.
- * (This obviously makes sense since the spacedim-dimensional
- * measure of a dim-dimensional triangulation would always be
- * zero if dim @< spacedim.
+ * triangulation. We compute the measure using the integral $\sum_K \int_K 1
+ * \; dx$ where $K$ are the cells of the given triangulation. The integral
+ * is approximated via quadrature for which we need the mapping argument.
+ *
+ * If the triangulation is a dim-dimensional one embedded in a higher
+ * dimensional space of dimension spacedim, then the value returned is the
+ * dim-dimensional measure. For example, for a two-dimensional triangulation
+ * in three-dimensional space, the value returned is the area of the surface
+ * so described. (This obviously makes sense since the spacedim-dimensional
+ * measure of a dim-dimensional triangulation would always be zero if dim @<
+ * spacedim.
*
* This function also works for objects of type
- * parallel::distributed::Triangulation, in which case the
- * function is a collective operation.
+ * parallel::distributed::Triangulation, in which case the function is a
+ * collective operation.
*
* @param tria The triangulation.
- * @param mapping An optional argument used to denote the mapping
- * that should be used when describing whether cells are bounded
- * by straight or curved faces. The default is to use a $Q_1$
- * mapping, which corresponds to straight lines bounding the
- * cells.
- * @return The dim-dimensional measure of the domain described
- * by the triangulation, as discussed above.
+ * @param mapping An optional argument used to denote the mapping that
+ * should be used when describing whether cells are bounded by straight or
+ * curved faces. The default is to use a $Q_1$ mapping, which corresponds to
+ * straight lines bounding the cells. @return The dim-dimensional measure of
+ * the domain described by the triangulation, as discussed above.
*/
template <int dim, int spacedim>
double volume (const Triangulation<dim,spacedim> &tria,
const Mapping<dim,spacedim> &mapping = (StaticMappingQ1<dim,spacedim>::mapping));
/**
- * Return the diamater of the smallest
- * active cell of a triangulation. See
- * step-24 for an example
- * of use of this function.
+ * Return the diamater of the smallest active cell of a triangulation. See
+ * step-24 for an example of use of this function.
*/
template <int dim, int spacedim>
double
minimal_cell_diameter (const Triangulation<dim, spacedim> &triangulation);
/**
- * Return the diamater of the largest
- * active cell of a triangulation.
+ * Return the diamater of the largest active cell of a triangulation.
*/
template <int dim, int spacedim>
double
maximal_cell_diameter (const Triangulation<dim, spacedim> &triangulation);
/**
- * Given a list of vertices (typically
- * obtained using
- * Triangulation::get_vertices) as the
- * first, and a list of vertex indices
- * that characterize a single cell as the
- * second argument, return the measure
- * (area, volume) of this cell. If this
- * is a real cell, then you can get the
- * same result using
- * <code>cell-@>measure()</code>, but
- * this function also works for cells
- * that do not exist except that you make
- * it up by naming its vertices from the
- * list.
+ * Given a list of vertices (typically obtained using
+ * Triangulation::get_vertices) as the first, and a list of vertex indices
+ * that characterize a single cell as the second argument, return the
+ * measure (area, volume) of this cell. If this is a real cell, then you can
+ * get the same result using <code>cell-@>measure()</code>, but this
+ * function also works for cells that do not exist except that you make it
+ * up by naming its vertices from the list.
*/
template <int dim>
double cell_measure (const std::vector<Point<dim> > &all_vertices,
/*@}*/
/**
- * @name Functions supporting the creation of meshes
+ * @name Functions supporting the creation of meshes
*/
/*@{*/
/**
- * Remove vertices that are not
- * referenced by any of the
- * cells. This function is called
- * by all <tt>GridIn::read_*</tt>
- * functions to eliminate
- * vertices that are listed in
- * the input files but are not
- * used by the cells in the input
- * file. While these vertices
- * should not be in the input
- * from the beginning, they
- * sometimes are, most often when
- * some cells have been removed
- * by hand without wanting to
- * update the vertex lists, as
- * they might be lengthy.
- *
- * This function is called by all
- * <tt>GridIn::read_*</tt>
- * functions as the triangulation
- * class requires them to be
- * called with used vertices
- * only. This is so, since the
- * vertices are copied verbatim
- * by that class, so we have to
- * eliminate unused vertices
- * beforehand.
- *
- * Not implemented for the
- * codimension one case.
+ * Remove vertices that are not referenced by any of the cells. This
+ * function is called by all <tt>GridIn::read_*</tt> functions to eliminate
+ * vertices that are listed in the input files but are not used by the cells
+ * in the input file. While these vertices should not be in the input from
+ * the beginning, they sometimes are, most often when some cells have been
+ * removed by hand without wanting to update the vertex lists, as they might
+ * be lengthy.
+ *
+ * This function is called by all <tt>GridIn::read_*</tt> functions as the
+ * triangulation class requires them to be called with used vertices only.
+ * This is so, since the vertices are copied verbatim by that class, so we
+ * have to eliminate unused vertices beforehand.
+ *
+ * Not implemented for the codimension one case.
*/
template <int dim, int spacedim>
void delete_unused_vertices (std::vector<Point<spacedim> > &vertices,
SubCellData &subcelldata);
/**
- * Remove vertices that are duplicated,
- * due to the input of a structured grid,
- * for example. If these vertices are not
- * removed, the faces bounded by these
- * vertices become part of the boundary,
- * even if they are in the interior of
- * the mesh.
- *
- * This function is called by some
- * <tt>GridIn::read_*</tt> functions. Only
- * the vertices with indices in @p
- * considered_vertices are tested for
- * equality. This speeds up the algorithm,
- * which is quadratic and thus quite slow
- * to begin with. However, if you wish to
- * consider all vertices, simply pass an
- * empty vector.
- *
- * Two vertices are considered equal if
- * their difference in each coordinate
+ * Remove vertices that are duplicated, due to the input of a structured
+ * grid, for example. If these vertices are not removed, the faces bounded
+ * by these vertices become part of the boundary, even if they are in the
+ * interior of the mesh.
+ *
+ * This function is called by some <tt>GridIn::read_*</tt> functions. Only
+ * the vertices with indices in @p considered_vertices are tested for
+ * equality. This speeds up the algorithm, which is quadratic and thus quite
+ * slow to begin with. However, if you wish to consider all vertices, simply
+ * pass an empty vector.
+ *
+ * Two vertices are considered equal if their difference in each coordinate
* direction is less than @p tol.
*/
template <int dim, int spacedim>
/*@}*/
/**
- * @name Rotating, stretching and otherwise transforming meshes
+ * @name Rotating, stretching and otherwise transforming meshes
*/
/*@{*/
/**
- * Transform the vertices of the given
- * triangulation by applying the
+ * Transform the vertices of the given triangulation by applying the
* function object provided as first argument to all its vertices.
*
- * The transformation given as
- * argument is used to transform
- * each vertex. Its respective
- * type has to offer a
- * function-like syntax, i.e. the
- * predicate is either an object
- * of a type that has an
- * <tt>operator()</tt>, or it is a
- * pointer to the function. In
- * either case, argument and
- * return value have to be of
- * type <tt>Point@<spacedim@></tt>.
- *
- * @note If you are using a parallel::distributed::Triangulation you will have
- * hanging nodes in your local Triangulation even if your "global" mesh has
- * no hanging nodes. This will cause issues with wrong positioning of hanging
- * nodes in ghost cells if you call the current functions: The vertices of
- * all locally owned cells will be correct,
- * but the vertices of some ghost cells may not. This means that
- * computations like KellyErrorEstimator may give wrong answers. A safe approach is
- * to use this function prior to any refinement in parallel, if that is possible, but
- * not after you refine the mesh.
- *
- * This function is used in the
- * "Possibilities for extensions" section
- * of step-38. It is also used in step-49 and step-53.
+ * The transformation given as argument is used to transform each vertex.
+ * Its respective type has to offer a function-like syntax, i.e. the
+ * predicate is either an object of a type that has an <tt>operator()</tt>,
+ * or it is a pointer to the function. In either case, argument and return
+ * value have to be of type <tt>Point@<spacedim@></tt>.
+ *
+ * @note If you are using a parallel::distributed::Triangulation you will
+ * have hanging nodes in your local Triangulation even if your "global" mesh
+ * has no hanging nodes. This will cause issues with wrong positioning of
+ * hanging nodes in ghost cells if you call the current functions: The
+ * vertices of all locally owned cells will be correct, but the vertices of
+ * some ghost cells may not. This means that computations like
+ * KellyErrorEstimator may give wrong answers. A safe approach is to use
+ * this function prior to any refinement in parallel, if that is possible,
+ * but not after you refine the mesh.
+ *
+ * This function is used in the "Possibilities for extensions" section of
+ * step-38. It is also used in step-49 and step-53.
*/
template <int dim, typename Transformation, int spacedim>
void transform (const Transformation &transformation,
Triangulation<dim,spacedim> &triangulation);
/**
- * Shift each vertex of the
- * triangulation by the given
- * shift vector. This function
- * uses the transform()
- * function above, so the
- * requirements on the
- * triangulation stated there
- * hold for this function as
- * well.
+ * Shift each vertex of the triangulation by the given shift vector. This
+ * function uses the transform() function above, so the requirements on the
+ * triangulation stated there hold for this function as well.
*/
template <int dim, int spacedim>
void shift (const Point<spacedim> &shift_vector,
/**
- * Rotate all vertices of the
- * given two-dimensional
- * triangulation in
- * counter-clockwise sense around
- * the origin of the coordinate
- * system by the given angle
- * (given in radians, rather than
- * degrees). This function uses
- * the transform() function
- * above, so the requirements on
- * the triangulation stated there
- * hold for this function as
- * well.
+ * Rotate all vertices of the given two-dimensional triangulation in
+ * counter-clockwise sense around the origin of the coordinate system by the
+ * given angle (given in radians, rather than degrees). This function uses
+ * the transform() function above, so the requirements on the triangulation
+ * stated there hold for this function as well.
*/
void rotate (const double angle,
Triangulation<2> &triangulation);
/**
* Transform the given triangulation smoothly to a different domain where,
- * typically, each of the vertices at the boundary of the triangulation is mapped to
- * the corresponding points in the @p new_points map.
+ * typically, each of the vertices at the boundary of the triangulation is
+ * mapped to the corresponding points in the @p new_points map.
*
* The way this function works is that it solves a Laplace equation for each
* of the dim components of a displacement field that maps the current
* domain into one described by @p new_points . The @p new_points array
- * therefore represents the boundary values of this displacement field.
- * The function then evaluates this displacement field at each vertex in
- * the interior and uses it to place the mapped vertex where the
- * displacement field locates it. Because the solution of the Laplace
- * equation is smooth, this guarantees a smooth mapping from the old
- * domain to the new one.
- *
- * @param[in] new_points The locations where a subset of the existing vertices
- * are to be placed. Typically, this would be a map from the vertex indices
- * of all nodes on the boundary to their new locations, thus completely
- * specifying the geometry of the mapped domain. However, it may also include
- * interior points if necessary and it does not need to include all boundary
- * vertices (although you then lose control over the exact shape of the mapped
- * domain).
- *
- * @param[in,out] tria The Triangulation object. This object is changed in-place,
- * i.e., the previous locations of vertices are overwritten.
+ * therefore represents the boundary values of this displacement field. The
+ * function then evaluates this displacement field at each vertex in the
+ * interior and uses it to place the mapped vertex where the displacement
+ * field locates it. Because the solution of the Laplace equation is smooth,
+ * this guarantees a smooth mapping from the old domain to the new one.
+ *
+ * @param[in] new_points The locations where a subset of the existing
+ * vertices are to be placed. Typically, this would be a map from the vertex
+ * indices of all nodes on the boundary to their new locations, thus
+ * completely specifying the geometry of the mapped domain. However, it may
+ * also include interior points if necessary and it does not need to include
+ * all boundary vertices (although you then lose control over the exact
+ * shape of the mapped domain).
+ *
+ * @param[in,out] tria The Triangulation object. This object is changed in-
+ * place, i.e., the previous locations of vertices are overwritten.
*
* @param[in] coefficient An optional coefficient for the Laplace problem.
- * Larger values make cells less prone to deformation (effectively increasing their stiffness).
- * The coefficient is evaluated in the coordinate system of the old,
- * undeformed configuration of the triangulation as input, i.e., before
- * the transformation is applied.
- * Should this function be provided, sensible results can only be expected if
- * all coefficients are positive.
+ * Larger values make cells less prone to deformation (effectively
+ * increasing their stiffness). The coefficient is evaluated in the
+ * coordinate system of the old, undeformed configuration of the
+ * triangulation as input, i.e., before the transformation is applied.
+ * Should this function be provided, sensible results can only be expected
+ * if all coefficients are positive.
*
* @note This function is not currently implemented for the 1d case.
*/
const Function<dim,double> *coefficient = 0);
/**
- * Scale the entire triangulation
- * by the given factor. To
- * preserve the orientation of
- * the triangulation, the factor
- * must be positive.
- *
- * This function uses the
- * transform() function
- * above, so the requirements on
- * the triangulation stated there
- * hold for this function as
- * well.
+ * Scale the entire triangulation by the given factor. To preserve the
+ * orientation of the triangulation, the factor must be positive.
+ *
+ * This function uses the transform() function above, so the requirements on
+ * the triangulation stated there hold for this function as well.
*/
template <int dim, int spacedim>
void scale (const double scaling_factor,
Triangulation<dim, spacedim> &triangulation);
/**
- * Distort the given triangulation by randomly
- * moving around all the vertices
- * of the grid. The direction of
- * movement of each vertex is random, while the
- * length of the shift vector has
- * a value of @p factor times
- * the minimal length of the
- * active edges adjacent to this
- * vertex. Note that @p factor
- * should obviously be well below
- * <tt>0.5</tt>.
- *
- * If @p keep_boundary is set to
- * @p true (which is the
- * default), then boundary
- * vertices are not moved.
+ * Distort the given triangulation by randomly moving around all the
+ * vertices of the grid. The direction of movement of each vertex is
+ * random, while the length of the shift vector has a value of @p factor
+ * times the minimal length of the active edges adjacent to this vertex.
+ * Note that @p factor should obviously be well below <tt>0.5</tt>.
+ *
+ * If @p keep_boundary is set to @p true (which is the default), then
+ * boundary vertices are not moved.
*/
template <int dim, int spacedim>
void distort_random (const double factor,
/*@}*/
/**
- * @name Finding cells and vertices of a triangulation
+ * @name Finding cells and vertices of a triangulation
*/
/*@{*/
/**
- * Find and return the number of
- * the used vertex in a given
- * mesh that is located closest
- * to a given point.
+ * Find and return the number of the used vertex in a given mesh that is
+ * located closest to a given point.
*
- * @param container A variable of a type that satisfies the
- * requirements of a mesh container (see @ref GlossMeshAsAContainer).
- * @param p The point for which we want to find the closest vertex.
- * @return The index of the closest vertex found.
+ * @param container A variable of a type that satisfies the requirements of
+ * a mesh container (see @ref GlossMeshAsAContainer).
+ * @param p The point for which we want to find the closest vertex. @return
+ * The index of the closest vertex found.
*
* @author Ralf B. Schulz, 2006
*/
const Point<spacedim> &p);
/**
- * Find and return a vector of
- * iterators to active cells that
- * surround a given vertex with index @p vertex_index.
- *
- * For locally refined grids, the
- * vertex itself might not be a vertex
- * of all adjacent cells that are returned.
- * However, it will
- * always be either a vertex of a cell or be
- * a hanging node located on a face or an
- * edge of it.
- *
- * @param container A variable of a type that satisfies the
- * requirements of a mesh container (see @ref GlossMeshAsAContainer).
- * @param vertex_index The index of the vertex for which we try to
- * find adjacent cells.
- * @return A vector of cells that lie adjacent to the given vertex.
- *
- * @note If the point requested does not lie in any of the cells of
- * the mesh given, then this function throws an exception of type
- * GridTools::ExcPointNotFound. You can catch this exception and
- * decide what to do in that case.
- *
- * @note It isn't entirely clear at this time whether the function
- * does the right thing with anisotropically refined meshes. It needs
- * to be checked for this case.
+ * Find and return a vector of iterators to active cells that surround a
+ * given vertex with index @p vertex_index.
+ *
+ * For locally refined grids, the vertex itself might not be a vertex of all
+ * adjacent cells that are returned. However, it will always be either a
+ * vertex of a cell or be a hanging node located on a face or an edge of it.
+ *
+ * @param container A variable of a type that satisfies the requirements of
+ * a mesh container (see @ref GlossMeshAsAContainer).
+ * @param vertex_index The index of the vertex for which we try to find
+ * adjacent cells. @return A vector of cells that lie adjacent to the given
+ * vertex.
+ *
+ * @note If the point requested does not lie in any of the cells of the mesh
+ * given, then this function throws an exception of type
+ * GridTools::ExcPointNotFound. You can catch this exception and decide what
+ * to do in that case.
+ *
+ * @note It isn't entirely clear at this time whether the function does the
+ * right thing with anisotropically refined meshes. It needs to be checked
+ * for this case.
*/
template<int dim, template <int, int> class Container, int spacedim>
#ifndef _MSC_VER
/**
- * Find and return an iterator to the active cell that surrounds a
- * given point.
+ * Find and return an iterator to the active cell that surrounds a given
+ * point.
*
- * This is solely a wrapper function for the function of same name
- * below. A Q1 mapping is used for the boundary, and the iterator
- * to the cell in which the point resides is returned.
+ * This is solely a wrapper function for the function of same name below. A
+ * Q1 mapping is used for the boundary, and the iterator to the cell in
+ * which the point resides is returned.
*
- * It is recommended to use the other version of this function, as
- * it simultaneously delivers the local coordinate of the given
- * point without additional computational cost.
+ * It is recommended to use the other version of this function, as it
+ * simultaneously delivers the local coordinate of the given point without
+ * additional computational cost.
*
- * @param container A variable of a type that satisfies the
- * requirements of a mesh container (see @ref GlossMeshAsAContainer).
+ * @param container A variable of a type that satisfies the requirements of
+ * a mesh container (see @ref GlossMeshAsAContainer).
* @param p The point for which we want to find the surrounding cell.
* @return An iterator into the mesh container that points to the
- * surrounding cell.
- *
- * @note If the point requested does not lie in any of the cells of
- * the mesh given, then this function throws an exception of type
- * GridTools::ExcPointNotFound. You can catch this exception and
- * decide what to do in that case.
- *
- * @note When applied to a triangulation or DoF handler object based
- * on a parallel::distributed::Triangulation object, the cell
- * returned may in fact be a ghost or artificial cell (see
- * @ref GlossArtificialCell and @ref GlossGhostCell). If so,
- * many of the operations one may want to do on this cell
- * (e.g., evaluating the solution) may not be possible and you
- * will have to decide what to do in that case.
+ * surrounding cell.
+ *
+ * @note If the point requested does not lie in any of the cells of the mesh
+ * given, then this function throws an exception of type
+ * GridTools::ExcPointNotFound. You can catch this exception and decide what
+ * to do in that case.
+ *
+ * @note When applied to a triangulation or DoF handler object based on a
+ * parallel::distributed::Triangulation object, the cell returned may in
+ * fact be a ghost or artificial cell (see @ref GlossArtificialCell and @ref
+ * GlossGhostCell). If so, many of the operations one may want to do on this
+ * cell (e.g., evaluating the solution) may not be possible and you will
+ * have to decide what to do in that case.
*/
template <int dim, template <int,int> class Container, int spacedim>
#ifndef _MSC_VER
const Point<spacedim> &p);
/**
- * Find and return an iterator to the active cell that surrounds a
- * given point @p p.
- *
- * The algorithm used in this function proceeds by first looking for
- * vertex located closest to the given point, see
- * find_closest_vertex(). Secondly, all adjacent cells to this point
- * are found in the mesh, see find_cells_adjacent_to_vertex().
- * Lastly, for each of these cells, it is tested whether the point
- * is inside. This check is performed using arbitrary boundary
- * mappings. Still, it is possible that due to roundoff errors, the
- * point cannot be located exactly inside the unit cell. In this
- * case, even points at a very small distance outside the unit cell
- * are allowed.
- *
- * If a point lies on the boundary of two or more cells, then the
- * algorithm tries to identify the cell that is of highest
- * refinement level.
- *
- * @param mapping The mapping used to determine whether the given
- * point is inside a given cell.
- * @param container A variable of a type that satisfies the
- * requirements of a mesh container (see @ref GlossMeshAsAContainer).
+ * Find and return an iterator to the active cell that surrounds a given
+ * point @p p.
+ *
+ * The algorithm used in this function proceeds by first looking for vertex
+ * located closest to the given point, see find_closest_vertex(). Secondly,
+ * all adjacent cells to this point are found in the mesh, see
+ * find_cells_adjacent_to_vertex(). Lastly, for each of these cells, it is
+ * tested whether the point is inside. This check is performed using
+ * arbitrary boundary mappings. Still, it is possible that due to roundoff
+ * errors, the point cannot be located exactly inside the unit cell. In this
+ * case, even points at a very small distance outside the unit cell are
+ * allowed.
+ *
+ * If a point lies on the boundary of two or more cells, then the algorithm
+ * tries to identify the cell that is of highest refinement level.
+ *
+ * @param mapping The mapping used to determine whether the given point is
+ * inside a given cell.
+ * @param container A variable of a type that satisfies the requirements of
+ * a mesh container (see @ref GlossMeshAsAContainer).
* @param p The point for which we want to find the surrounding cell.
* @return An pair of an iterator into the mesh container that points to the
- * surrounding cell, and of the coordinates of that point inside the cell
- * in the reference coordinates of that cell. This local
- * position might be located slightly outside an actual unit cell,
- * due to numerical roundoff. Therefore, the point returned by this
- * function should be projected onto the unit cell, using
- * GeometryInfo::project_to_unit_cell(). This is not automatically
- * performed by the algorithm.
- *
- * @note If the point requested does not lie in any of the cells of
- * the mesh given, then this function throws an exception of type
- * GridTools::ExcPointNotFound. You can catch this exception and
- * decide what to do in that case.
- *
- * @note When applied to a triangulation or DoF handler object based
- * on a parallel::distributed::Triangulation object, the cell
- * returned may in fact be a ghost or artificial cell (see
- * @ref GlossArtificialCell and @ref GlossGhostCell). If so,
- * many of the operations one may want to do on this cell
- * (e.g., evaluating the solution) may not be possible and you
- * will have to decide what to do in that case.
+ * surrounding cell, and of the coordinates of that point inside the cell in
+ * the reference coordinates of that cell. This local position might be
+ * located slightly outside an actual unit cell, due to numerical roundoff.
+ * Therefore, the point returned by this function should be projected onto
+ * the unit cell, using GeometryInfo::project_to_unit_cell(). This is not
+ * automatically performed by the algorithm.
+ *
+ * @note If the point requested does not lie in any of the cells of the mesh
+ * given, then this function throws an exception of type
+ * GridTools::ExcPointNotFound. You can catch this exception and decide what
+ * to do in that case.
+ *
+ * @note When applied to a triangulation or DoF handler object based on a
+ * parallel::distributed::Triangulation object, the cell returned may in
+ * fact be a ghost or artificial cell (see @ref GlossArtificialCell and @ref
+ * GlossGhostCell). If so, many of the operations one may want to do on this
+ * cell (e.g., evaluating the solution) may not be possible and you will
+ * have to decide what to do in that case.
*/
template <int dim, template<int, int> class Container, int spacedim>
#ifndef _MSC_VER
const Point<spacedim> &p);
/**
- * A version of the previous function where we use that mapping on a
- * given cell that corresponds to the active finite element index of
- * that cell. This is obviously only useful for hp problems, since
- * the active finite element index for all other DoF handlers is
- * always zero.
- *
- * @note If the point requested does not lie in any of the cells of
- * the mesh given, then this function throws an exception of type
- * GridTools::ExcPointNotFound. You can catch this exception and
- * decide what to do in that case.
- *
- * @note When applied to a triangulation or DoF handler object based
- * on a parallel::distributed::Triangulation object, the cell
- * returned may in fact be a ghost or artificial cell (see
- * @ref GlossArtificialCell and @ref GlossGhostCell). If so,
- * many of the operations one may want to do on this cell
- * (e.g., evaluating the solution) may not be possible and you
- * will have to decide what to do in that case.
+ * A version of the previous function where we use that mapping on a given
+ * cell that corresponds to the active finite element index of that cell.
+ * This is obviously only useful for hp problems, since the active finite
+ * element index for all other DoF handlers is always zero.
+ *
+ * @note If the point requested does not lie in any of the cells of the mesh
+ * given, then this function throws an exception of type
+ * GridTools::ExcPointNotFound. You can catch this exception and decide what
+ * to do in that case.
+ *
+ * @note When applied to a triangulation or DoF handler object based on a
+ * parallel::distributed::Triangulation object, the cell returned may in
+ * fact be a ghost or artificial cell (see @ref GlossArtificialCell and @ref
+ * GlossGhostCell). If so, many of the operations one may want to do on this
+ * cell (e.g., evaluating the solution) may not be possible and you will
+ * have to decide what to do in that case.
*/
template <int dim, int spacedim>
std::pair<typename hp::DoFHandler<dim, spacedim>::active_cell_iterator, Point<dim> >
const Point<spacedim> &p);
/**
- * Return a list of all descendants of
- * the given cell that are active. For
- * example, if the current cell is once
- * refined but none of its children are
- * any further refined, then the returned
- * list will contain all its children.
- *
- * If the current cell is already active,
- * then the returned list is empty
- * (because the cell has no children that
- * may be active).
- *
- * @tparam Container A type that satisfies the
- * requirements of a mesh container (see @ref GlossMeshAsAContainer).
- * @param cell An iterator pointing to a cell of the mesh container.
- * @return A list of active descendants of the given cell
- *
- * @note Since in C++ the type of the Container
- * template argument can
- * not be deduced from a function call,
- * you will have to specify it after the
+ * Return a list of all descendants of the given cell that are active. For
+ * example, if the current cell is once refined but none of its children are
+ * any further refined, then the returned list will contain all its
+ * children.
+ *
+ * If the current cell is already active, then the returned list is empty
+ * (because the cell has no children that may be active).
+ *
+ * @tparam Container A type that satisfies the requirements of a mesh
+ * container (see @ref GlossMeshAsAContainer).
+ * @param cell An iterator pointing to a cell of the mesh container. @return
+ * A list of active descendants of the given cell
+ *
+ * @note Since in C++ the type of the Container template argument can not be
+ * deduced from a function call, you will have to specify it after the
* function name, as for example in
* @code
* GridTools::get_active_child_cells<DoFHandler<dim> > (cell)
get_active_child_cells (const typename Container::cell_iterator &cell);
/**
- * Extract the active cells around a given
- * cell @p cell and return them in the
- * vector @p active_neighbors.
+ * Extract the active cells around a given cell @p cell and return them in
+ * the vector @p active_neighbors.
*
- * @tparam Container A type that satisfies the
- * requirements of a mesh container (see @ref GlossMeshAsAContainer).
+ * @tparam Container A type that satisfies the requirements of a mesh
+ * container (see @ref GlossMeshAsAContainer).
* @param cell[in] An iterator pointing to a cell of the mesh container.
- * @param active_neighbors[out] A list of active descendants of the given cell
+ * @param active_neighbors[out] A list of active descendants of the given
+ * cell
*/
template <class Container>
void
/*@}*/
/**
- * @name Partitions and subdomains of triangulations
+ * @name Partitions and subdomains of triangulations
*/
/*@{*/
/**
- * Produce a sparsity pattern in which
- * nonzero entries indicate that two
- * cells are connected via a common
- * face. The diagonal entries of the
+ * Produce a sparsity pattern in which nonzero entries indicate that two
+ * cells are connected via a common face. The diagonal entries of the
* sparsity pattern are also set.
*
- * The rows and columns refer to the
- * cells as they are traversed in their
+ * The rows and columns refer to the cells as they are traversed in their
* natural order using cell iterators.
*/
template <int dim, int spacedim>
SparsityPattern &connectivity);
/**
- * Use the METIS partitioner to generate
- * a partitioning of the active cells
- * making up the entire domain. After
- * calling this function, the subdomain
- * ids of all active cells will have
- * values between zero and
- * @p n_partitions-1. You can access the
- * subdomain id of a cell by using
+ * Use the METIS partitioner to generate a partitioning of the active cells
+ * making up the entire domain. After calling this function, the subdomain
+ * ids of all active cells will have values between zero and @p
+ * n_partitions-1. You can access the subdomain id of a cell by using
* <tt>cell-@>subdomain_id()</tt>.
*
- * This function will generate an error
- * if METIS is not installed unless
- * @p n_partitions is one. I.e., you can
- * write a program so that it runs in the
- * single-processor single-partition case
- * without METIS installed, and only
- * requires METIS when multiple
- * partitions are required.
+ * This function will generate an error if METIS is not installed unless @p
+ * n_partitions is one. I.e., you can write a program so that it runs in the
+ * single-processor single-partition case without METIS installed, and only
+ * requires METIS when multiple partitions are required.
*/
template <int dim, int spacedim>
void
Triangulation<dim, spacedim> &triangulation);
/**
- * This function does the same as the
- * previous one, i.e. it partitions a
- * triangulation using METIS into a
- * number of subdomains identified by the
- * <code>cell-@>subdomain_id()</code>
- * flag.
- *
- * The difference to the previous
- * function is the second argument, a
- * sparsity pattern that represents the
- * connectivity pattern between cells.
- *
- * While the function above builds it
- * directly from the triangulation by
- * considering which cells neighbor each
- * other, this function can take a more
- * refined connectivity graph. The
- * sparsity pattern needs to be of size
- * $N\times N$, where $N$ is the number
- * of active cells in the
- * triangulation. If the sparsity pattern
- * contains an entry at position $(i,j)$,
- * then this means that cells $i$ and $j$
- * (in the order in which they are
- * traversed by active cell iterators)
- * are to be considered connected; METIS
- * will then try to partition the domain
- * in such a way that (i) the subdomains
- * are of roughly equal size, and (ii) a
- * minimal number of connections are
- * broken.
- *
- * This function is mainly useful in
- * cases where connections between cells
- * exist that are not present in the
- * triangulation alone (otherwise the
- * previous function would be the simpler
- * one to use). Such connections may
- * include that certain parts of the
- * boundary of a domain are coupled
- * through symmetric boundary conditions
- * or integrals (e.g. friction contact
- * between the two sides of a crack in
- * the domain), or if a numerical scheme
- * is used that not only connects
- * immediate neighbors but a larger
- * neighborhood of cells (e.g. when
- * solving integral equations).
- *
- * In addition, this function may be
- * useful in cases where the default
- * sparsity pattern is not entirely
- * sufficient. This can happen because
- * the default is to just consider face
- * neighbors, not neighboring cells that
- * are connected by edges or
- * vertices. While the latter couple when
- * using continuous finite elements, they
- * are typically still closely connected
- * in the neighborship graph, and METIS
- * will not usually cut important
- * connections in this case. However, if
- * there are vertices in the mesh where
- * many cells (many more than the common
- * 4 or 6 in 2d and 3d, respectively)
- * come together, then there will be a
- * significant number of cells that are
- * connected across a vertex, but several
- * degrees removed in the connectivity
- * graph built only using face
- * neighbors. In a case like this, METIS
- * may sometimes make bad decisions and
- * you may want to build your own
- * connectivity graph.
+ * This function does the same as the previous one, i.e. it partitions a
+ * triangulation using METIS into a number of subdomains identified by the
+ * <code>cell-@>subdomain_id()</code> flag.
+ *
+ * The difference to the previous function is the second argument, a
+ * sparsity pattern that represents the connectivity pattern between cells.
+ *
+ * While the function above builds it directly from the triangulation by
+ * considering which cells neighbor each other, this function can take a
+ * more refined connectivity graph. The sparsity pattern needs to be of size
+ * $N\times N$, where $N$ is the number of active cells in the
+ * triangulation. If the sparsity pattern contains an entry at position
+ * $(i,j)$, then this means that cells $i$ and $j$ (in the order in which
+ * they are traversed by active cell iterators) are to be considered
+ * connected; METIS will then try to partition the domain in such a way that
+ * (i) the subdomains are of roughly equal size, and (ii) a minimal number
+ * of connections are broken.
+ *
+ * This function is mainly useful in cases where connections between cells
+ * exist that are not present in the triangulation alone (otherwise the
+ * previous function would be the simpler one to use). Such connections may
+ * include that certain parts of the boundary of a domain are coupled
+ * through symmetric boundary conditions or integrals (e.g. friction contact
+ * between the two sides of a crack in the domain), or if a numerical scheme
+ * is used that not only connects immediate neighbors but a larger
+ * neighborhood of cells (e.g. when solving integral equations).
+ *
+ * In addition, this function may be useful in cases where the default
+ * sparsity pattern is not entirely sufficient. This can happen because the
+ * default is to just consider face neighbors, not neighboring cells that
+ * are connected by edges or vertices. While the latter couple when using
+ * continuous finite elements, they are typically still closely connected in
+ * the neighborship graph, and METIS will not usually cut important
+ * connections in this case. However, if there are vertices in the mesh
+ * where many cells (many more than the common 4 or 6 in 2d and 3d,
+ * respectively) come together, then there will be a significant number of
+ * cells that are connected across a vertex, but several degrees removed in
+ * the connectivity graph built only using face neighbors. In a case like
+ * this, METIS may sometimes make bad decisions and you may want to build
+ * your own connectivity graph.
*/
template <int dim, int spacedim>
void
Triangulation<dim,spacedim> &triangulation);
/**
- * For each active cell, return in the
- * output array to which subdomain (as
- * given by the <tt>cell->subdomain_id()</tt>
- * function) it belongs. The output array
- * is supposed to have the right size
- * already when calling this function.
- *
- * This function returns the association
- * of each cell with one subdomain. If
- * you are looking for the association of
- * each @em DoF with a subdomain, use the
- * <tt>DoFTools::get_subdomain_association</tt>
+ * For each active cell, return in the output array to which subdomain (as
+ * given by the <tt>cell->subdomain_id()</tt> function) it belongs. The
+ * output array is supposed to have the right size already when calling this
* function.
+ *
+ * This function returns the association of each cell with one subdomain. If
+ * you are looking for the association of each @em DoF with a subdomain, use
+ * the <tt>DoFTools::get_subdomain_association</tt> function.
*/
template <int dim, int spacedim>
void
std::vector<types::subdomain_id> &subdomain);
/**
- * Count how many cells are uniquely
- * associated with the given @p subdomain
+ * Count how many cells are uniquely associated with the given @p subdomain
* index.
*
- * This function may return zero
- * if there are no cells with the
- * given @p subdomain index. This
- * can happen, for example, if
- * you try to partition a coarse
- * mesh into more partitions (one
- * for each processor) than there
- * are cells in the mesh.
- *
- * This function returns the number of
- * cells associated with one
- * subdomain. If you are looking for the
- * association of @em DoFs with this
- * subdomain, use the
- * <tt>DoFTools::count_dofs_with_subdomain_association</tt>
+ * This function may return zero if there are no cells with the given @p
+ * subdomain index. This can happen, for example, if you try to partition a
+ * coarse mesh into more partitions (one for each processor) than there are
+ * cells in the mesh.
+ *
+ * This function returns the number of cells associated with one subdomain.
+ * If you are looking for the association of @em DoFs with this subdomain,
+ * use the <tt>DoFTools::count_dofs_with_subdomain_association</tt>
* function.
*/
template <int dim, int spacedim>
* For a triangulation, return a mask that represents which of its vertices
* are "owned" by the current process in the same way as we talk about
* locally owned cells or degrees of freedom (see @ref GlossLocallyOwnedCell
- * and @ref GlossLocallyOwnedDof). For the purpose of this function,
- * we define a locally owned vertex as follows: a vertex is owned by
- * that processor with the smallest subdomain id (which equals the MPI
- * rank of that processor) among all owners of cells adjacent to this vertex.
- * In other words, vertices that are in the interior of a partition
- * of the triangulation are owned by the owner of this partition; for
- * vertices that lie on the boundary between two or more partitions,
- * the owner is the processor with the least subdomain_id among all
- * adjacent subdomains.
+ * and @ref GlossLocallyOwnedDof). For the purpose of this function, we
+ * define a locally owned vertex as follows: a vertex is owned by that
+ * processor with the smallest subdomain id (which equals the MPI rank of
+ * that processor) among all owners of cells adjacent to this vertex. In
+ * other words, vertices that are in the interior of a partition of the
+ * triangulation are owned by the owner of this partition; for vertices that
+ * lie on the boundary between two or more partitions, the owner is the
+ * processor with the least subdomain_id among all adjacent subdomains.
*
* For sequential triangulations (as opposed to, for example,
* parallel::distributed::Triangulation), every user vertex is of course
* returns.
*
* @param triangulation The triangulation of which the function evaluates
- * which vertices are locally owned.
- * @return The subset of vertices, as described above. The length of the
- * returned array equals Triangulation.n_vertices() and may, consequently,
- * be larger than Triangulation::n_used_vertices().
+ * which vertices are locally owned. @return The subset of vertices, as
+ * described above. The length of the returned array equals
+ * Triangulation.n_vertices() and may, consequently, be larger than
+ * Triangulation::n_used_vertices().
*/
template <int dim, int spacedim>
std::vector<bool>
/*@}*/
/**
- * @name Comparing different meshes
+ * @name Comparing different meshes
*/
/*@{*/
/**
- * Given two mesh containers
- * (i.e. objects of type
- * Triangulation, DoFHandler,
- * hp::DoFHandler, or
- * MGDoFHandler) that are based
- * on the same coarse mesh, this
- * function figures out a set of
- * cells that are matched between
- * the two meshes and where at
- * most one of the meshes is more
- * refined on this cell. In other
- * words, it finds the smallest
- * cells that are common to both
- * meshes, and that together
- * completely cover the domain.
- *
- * This function is useful, for
- * example, in time-dependent or
- * nonlinear application, where
- * one has to integrate a
- * solution defined on one mesh
- * (e.g., the one from the
- * previous time step or
- * nonlinear iteration) against
- * the shape functions of another
- * mesh (the next time step, the
- * next nonlinear iteration). If,
- * for example, the new mesh is
- * finer, then one has to obtain
- * the solution on the coarse
- * mesh (mesh_1) and interpolate
- * it to the children of the
- * corresponding cell of
- * mesh_2. Conversely, if the new
- * mesh is coarser, one has to
- * express the coarse cell shape
- * function by a linear
- * combination of fine cell shape
- * functions. In either case, one
- * needs to loop over the finest
- * cells that are common to both
- * triangulations. This function
- * returns a list of pairs of
- * matching iterators to cells in
- * the two meshes that can be
- * used to this end.
- *
- * Note that the list of these
- * iterators is not necessarily
- * ordered, and does also not
- * necessarily coincide with the
- * order in which cells are
- * traversed in one, or both, of
- * the meshes given as arguments.
- *
- * @tparam Container A type that satisfies the
- * requirements of a mesh container (see @ref GlossMeshAsAContainer).
+ * Given two mesh containers (i.e. objects of type Triangulation,
+ * DoFHandler, hp::DoFHandler, or MGDoFHandler) that are based on the same
+ * coarse mesh, this function figures out a set of cells that are matched
+ * between the two meshes and where at most one of the meshes is more
+ * refined on this cell. In other words, it finds the smallest cells that
+ * are common to both meshes, and that together completely cover the domain.
+ *
+ * This function is useful, for example, in time-dependent or nonlinear
+ * application, where one has to integrate a solution defined on one mesh
+ * (e.g., the one from the previous time step or nonlinear iteration)
+ * against the shape functions of another mesh (the next time step, the next
+ * nonlinear iteration). If, for example, the new mesh is finer, then one
+ * has to obtain the solution on the coarse mesh (mesh_1) and interpolate it
+ * to the children of the corresponding cell of mesh_2. Conversely, if the
+ * new mesh is coarser, one has to express the coarse cell shape function by
+ * a linear combination of fine cell shape functions. In either case, one
+ * needs to loop over the finest cells that are common to both
+ * triangulations. This function returns a list of pairs of matching
+ * iterators to cells in the two meshes that can be used to this end.
+ *
+ * Note that the list of these iterators is not necessarily ordered, and
+ * does also not necessarily coincide with the order in which cells are
+ * traversed in one, or both, of the meshes given as arguments.
+ *
+ * @tparam Container A type that satisfies the requirements of a mesh
+ * container (see @ref GlossMeshAsAContainer).
*/
template <typename Container>
std::list<std::pair<typename Container::cell_iterator,
const Container &mesh_2);
/**
- * Return true if the two
- * triangulations are based on
- * the same coarse mesh. This is
- * determined by checking whether
- * they have the same number of
- * cells on the coarsest level,
- * and then checking that they
- * have the same vertices.
- *
- * The two meshes may have
- * different refinement histories
- * beyond the coarse mesh.
+ * Return true if the two triangulations are based on the same coarse mesh.
+ * This is determined by checking whether they have the same number of cells
+ * on the coarsest level, and then checking that they have the same
+ * vertices.
+ *
+ * The two meshes may have different refinement histories beyond the coarse
+ * mesh.
*/
template <int dim, int spacedim>
bool
const Triangulation<dim, spacedim> &mesh_2);
/**
- * The same function as above,
- * but working on arguments of
- * type DoFHandler,
- * hp::DoFHandler, or
- * MGDoFHandler. This function is
- * provided to allow calling
- * have_same_coarse_mesh for all
- * types of containers
- * representing triangulations or
- * the classes built on
- * triangulations.
- *
- * @tparam Container A type that satisfies the
- * requirements of a mesh container (see @ref GlossMeshAsAContainer).
+ * The same function as above, but working on arguments of type DoFHandler,
+ * hp::DoFHandler, or MGDoFHandler. This function is provided to allow
+ * calling have_same_coarse_mesh for all types of containers representing
+ * triangulations or the classes built on triangulations.
+ *
+ * @tparam Container A type that satisfies the requirements of a mesh
+ * container (see @ref GlossMeshAsAContainer).
*/
template <typename Container>
bool
/*@}*/
/**
- * @name Dealing with distorted cells
+ * @name Dealing with distorted cells
*/
/*@{*/
/**
- * Given a triangulation and a
- * list of cells whose children
- * have become distorted as a
- * result of mesh refinement, try
- * to fix these cells up by
+ * Given a triangulation and a list of cells whose children have become
+ * distorted as a result of mesh refinement, try to fix these cells up by
* moving the center node around.
*
- * The function returns a list of
- * cells with distorted children
- * that couldn't be fixed up for
- * whatever reason. The returned
- * list is therefore a subset of
- * the input argument.
- *
- * For a definition of the
- * concept of distorted cells,
- * see the
- * @ref GlossDistorted "glossary entry".
- * The first argument passed to the
- * current function is typically
- * the exception thrown by the
- * Triangulation::execute_coarsening_and_refinement
- * function.
+ * The function returns a list of cells with distorted children that
+ * couldn't be fixed up for whatever reason. The returned list is therefore
+ * a subset of the input argument.
+ *
+ * For a definition of the concept of distorted cells, see the @ref
+ * GlossDistorted "glossary entry". The first argument passed to the current
+ * function is typically the exception thrown by the
+ * Triangulation::execute_coarsening_and_refinement function.
*/
template <int dim, int spacedim>
typename Triangulation<dim,spacedim>::DistortedCellList
/*@}*/
/**
- * @name Extracting and creating patches of cells surrounding a single cell
+ * @name Extracting and creating patches of cells surrounding a single cell
*/
/*@{*/
* part of a face in common with the given cell, but not edge (in 3d) or
* vertex neighbors (in 2d and 3d).
*
- * The first element of the returned list is the cell provided as
- * argument. The remaining ones are neighbors: The function loops over all
- * faces of that given cell and checks if that face is not on the boundary of
- * the domain. Then, if the neighbor cell does not have any children (i.e., it
+ * The first element of the returned list is the cell provided as argument.
+ * The remaining ones are neighbors: The function loops over all faces of
+ * that given cell and checks if that face is not on the boundary of the
+ * domain. Then, if the neighbor cell does not have any children (i.e., it
* is either at the same refinement level as the current cell, or coarser)
* then this neighbor cell is added to the list of cells. Otherwise, if the
* neighbor cell is refined and therefore has children, then this function
* loops over all subfaces of current face adds the neighbors behind these
* sub-faces to the list to be returned.
*
- * @tparam Container A type that satisfies the
- * requirements of a mesh container (see @ref GlossMeshAsAContainer).
- * In C++, the compiler can not determine the type of <code>Container</code>
- * from the function call. You need to specify it as an explicit template
- * argument following the function name.
+ * @tparam Container A type that satisfies the requirements of a mesh
+ * container (see @ref GlossMeshAsAContainer). In C++, the compiler can not
+ * determine the type of <code>Container</code> from the function call. You
+ * need to specify it as an explicit template argument following the
+ * function name.
* @param cell[in] An iterator pointing to a cell of the mesh container.
* @return A list of active cells that form the patch around the given cell
*
- * @note Patches are often used in defining error estimators that require the
- * solution of a local problem on the patch surrounding each of the cells of
- * the mesh. This also requires manipulating the degrees of freedom associated
- * with the cells of a patch. To this end, there are further functions working
- * on patches in namespace DoFTools.
+ * @note Patches are often used in defining error estimators that require
+ * the solution of a local problem on the patch surrounding each of the
+ * cells of the mesh. This also requires manipulating the degrees of freedom
+ * associated with the cells of a patch. To this end, there are further
+ * functions working on patches in namespace DoFTools.
*
* @note In the context of a parallel distributed computation, it only makes
* sense to call this function on locally owned cells. This is because the
/*@}*/
/**
- * @name Lower-dimensional meshes for parts of higher-dimensional meshes
+ * @name Lower-dimensional meshes for parts of higher-dimensional meshes
*/
/*@{*/
/*@}*/
/**
- * @name Dealing with periodic domains
+ * @name Dealing with periodic domains
*/
/*@{*/
/**
- * Data type that provides all information necessary to create
- * periodicity constraints and a periodic p4est forest with respect to
- * two 'periodic' cell faces.
+ * Data type that provides all information necessary to create periodicity
+ * constraints and a periodic p4est forest with respect to two 'periodic'
+ * cell faces.
*/
template<typename CellIterator>
struct PeriodicFacePair
CellIterator cell[2];
/**
- * The local face indices (with respect to the specified cells) of the
- * two 'periodic' faces.
+ * The local face indices (with respect to the specified cells) of the two
+ * 'periodic' faces.
*/
unsigned int face_idx[2];
/**
- * The relative orientation of the first face with respect to the
- * second face as described in orthogonal_equality() and
+ * The relative orientation of the first face with respect to the second
+ * face as described in orthogonal_equality() and
* make_periodicity_constraints() (and stored as a bitset).
*/
std::bitset<3> orientation;
/**
- * A matrix that describes how vector valued DoFs of the first face
- * should be modified prior to constraining to the DoFs of the second
- * face. If the std::vector first_vector_components is non empty the
- * matrix is interpreted as a @p dim $\times$ @p dim rotation matrix
- * that is applied to all vector valued blocks listed in
- * @p first_vector_components of the FESystem. If
- * @p first_vector_components is empty the matrix is interpreted as an
- * interpolation matrix with size no_face_dofs $\times$ no_face_dofs.
- * For more details see make_periodicity_constraints() and the glossary
- * @ref GlossPeriodicConstraints "glossary entry on periodic boundary
- * conditions".
+ * A matrix that describes how vector valued DoFs of the first face should
+ * be modified prior to constraining to the DoFs of the second face. If
+ * the std::vector first_vector_components is non empty the matrix is
+ * interpreted as a @p dim $\times$ @p dim rotation matrix that is applied
+ * to all vector valued blocks listed in @p first_vector_components of the
+ * FESystem. If @p first_vector_components is empty the matrix is
+ * interpreted as an interpolation matrix with size no_face_dofs $\times$
+ * no_face_dofs. For more details see make_periodicity_constraints() and
+ * the glossary @ref GlossPeriodicConstraints "glossary entry on periodic
+ * boundary conditions".
*/
FullMatrix<double> matrix;
* An orthogonal equality test for faces.
*
* @p face1 and @p face2 are considered equal, if a one to one matching
- * between its vertices can be achieved via an orthogonal equality
- * relation.
+ * between its vertices can be achieved via an orthogonal equality relation.
*
- * Hereby, two vertices <tt>v_1</tt> and <tt>v_2</tt> are considered
- * equal, if $M\cdot v_1 + offset - v_2</code> is parallel to the unit
- * vector in unit direction @p direction. If the parameter @p matrix
- * is a reference to a spacedim x spacedim matrix, $M$ is set to @p
- * matrix, otherwise $M$ is the identity matrix.
+ * Hereby, two vertices <tt>v_1</tt> and <tt>v_2</tt> are considered equal,
+ * if $M\cdot v_1 + offset - v_2</code> is parallel to the unit vector in
+ * unit direction @p direction. If the parameter @p matrix is a reference to
+ * a spacedim x spacedim matrix, $M$ is set to @p matrix, otherwise $M$ is
+ * the identity matrix.
*
* If the matching was successful, the _relative_ orientation of @p face1
- * with respect to @p face2 is returned in the bitset @p orientation,
- * where
+ * with respect to @p face2 is returned in the bitset @p orientation, where
* @code
* orientation[0] -> face_orientation
* orientation[1] -> face_flip
* <tt>face_rotation</tt> is always <tt>false</tt>, and face_flip has the
* meaning of <tt>line_flip</tt>. More precisely in 3d:
*
- * <tt>face_orientation</tt>:
- * <tt>true</tt> if @p face1 and @p face2 have the same orientation.
- * Otherwise, the vertex indices of @p face1 match the vertex indices of
- * @p face2 in the following manner:
+ * <tt>face_orientation</tt>: <tt>true</tt> if @p face1 and @p face2 have
+ * the same orientation. Otherwise, the vertex indices of @p face1 match the
+ * vertex indices of @p face2 in the following manner:
*
* @code
* face1: face2:
* 0 - 2 0 - 1
* @endcode
*
- * <tt>face_flip</tt>:
- * <tt>true</tt> if the matched vertices are rotated by 180 degrees:
+ * <tt>face_flip</tt>: <tt>true</tt> if the matched vertices are rotated by
+ * 180 degrees:
*
* @code
* face1: face2:
* 3 - 2 0 - 1
* @endcode
*
- * <tt>face_rotation</tt>: <tt>true</tt> if the matched vertices are
- * rotated by 90 degrees counterclockwise:
+ * <tt>face_rotation</tt>: <tt>true</tt> if the matched vertices are rotated
+ * by 90 degrees counterclockwise:
*
* @code
* face1: face2:
* 1 - 3 0 - 1
* @endcode
*
- * and any combination of that...
- * More information on the topic can be found in the
- * @ref GlossFaceOrientation "glossary" article.
+ * and any combination of that... More information on the topic can be found
+ * in the @ref GlossFaceOrientation "glossary" article.
*
* @author Matthias Maier, 2012
*/
/**
- * This function will collect periodic face pairs on the
- * coarsest mesh level of the given @p container (a Triangulation or
- * DoFHandler) and add them to the vector @p matched_pairs leaving the
- * original contents intact.
+ * This function will collect periodic face pairs on the coarsest mesh level
+ * of the given @p container (a Triangulation or DoFHandler) and add them to
+ * the vector @p matched_pairs leaving the original contents intact.
*
- * Define a 'first' boundary as all boundary faces having boundary_id
- * @p b_id1 and a 'second' boundary consisting of all faces belonging
- * to @p b_id2.
+ * Define a 'first' boundary as all boundary faces having boundary_id @p
+ * b_id1 and a 'second' boundary consisting of all faces belonging to @p
+ * b_id2.
*
- * This function tries to match all faces belonging to the first
- * boundary with faces belonging to the second boundary with the help
- * of orthogonal_equality().
+ * This function tries to match all faces belonging to the first boundary
+ * with faces belonging to the second boundary with the help of
+ * orthogonal_equality().
*
* The bitset that is returned inside of PeriodicFacePair encodes the
- * _relative_ orientation of the first face with respect to the second
- * face, see the documentation of orthogonal_equality() for further details.
+ * _relative_ orientation of the first face with respect to the second face,
+ * see the documentation of orthogonal_equality() for further details.
*
- * The @p direction refers to the space direction in which periodicity
- * is enforced.
+ * The @p direction refers to the space direction in which periodicity is
+ * enforced.
*
* The @p offset is a vector tangential to the faces that is added to the
* location of vertices of the 'first' boundary when attempting to match
- * them to the corresponding vertices of the 'second' boundary. This can
- * be used to implement conditions such as $u(0,y)=u(1,y+1)$.
- *
- * Optionally a (dim x dim) rotation matrix @p matrix along with a vector
- * @p first_vector_components can be specified that describes how vector
- * valued DoFs of the first face should be modified prior to constraining
- * to the DoFs of the second face. If @p first_vector_components is non
- * empty the matrix is interpreted as a rotation matrix that is applied
- * to all vector valued blocks listed in @p first_vector_components of
- * the FESystem. For more details see make_periodicity_constraints() and
- * the glossary
- * @ref GlossPeriodicConstraints "glossary entry on periodic boundary conditions".
+ * them to the corresponding vertices of the 'second' boundary. This can be
+ * used to implement conditions such as $u(0,y)=u(1,y+1)$.
+ *
+ * Optionally a (dim x dim) rotation matrix @p matrix along with a vector @p
+ * first_vector_components can be specified that describes how vector valued
+ * DoFs of the first face should be modified prior to constraining to the
+ * DoFs of the second face. If @p first_vector_components is non empty the
+ * matrix is interpreted as a rotation matrix that is applied to all vector
+ * valued blocks listed in @p first_vector_components of the FESystem. For
+ * more details see make_periodicity_constraints() and the glossary @ref
+ * GlossPeriodicConstraints "glossary entry on periodic boundary
+ * conditions".
*
* @tparam Container A type that satisfies the requirements of a mesh
* container (see @ref GlossMeshAsAContainer).
/**
- * This compatibility version of collect_periodic_face_pairs() only works
- * on grids with cells in @ref GlossFaceOrientation "standard orientation".
+ * This compatibility version of collect_periodic_face_pairs() only works on
+ * grids with cells in @ref GlossFaceOrientation "standard orientation".
*
- * Instead of defining a 'first' and 'second' boundary with the help of
- * two boundary_indicators this function defines a 'left' boundary as all
- * faces with local face index <code>2*dimension</code> and boundary
- * indicator @p b_id and, similarly, a 'right' boundary consisting of all
- * face with local face index <code>2*dimension+1</code> and boundary
- * indicator @p b_id.
+ * Instead of defining a 'first' and 'second' boundary with the help of two
+ * boundary_indicators this function defines a 'left' boundary as all faces
+ * with local face index <code>2*dimension</code> and boundary indicator @p
+ * b_id and, similarly, a 'right' boundary consisting of all face with local
+ * face index <code>2*dimension+1</code> and boundary indicator @p b_id.
*
* This function will collect periodic face pairs on the coarsest mesh level
* and add them to @p matched_pairs leaving the original contents intact.
*
- * Optionally a rotation matrix @p matrix along with a vector
- * @p first_vector_components can be specified that describes how vector
- * valued DoFs of the first face should be modified prior to constraining
- * to the DoFs of the second face. If @p first_vector_components is non
- * empty the matrix is interpreted as a rotation matrix that is applied
- * to all vector valued blocks listet in @p first_vector_components of
- * the FESystem. For more details see make_periodicity_constraints() and
- * the glossary @ref GlossPeriodicConstraints "glossary entry on periodic
- * boundary conditions".
+ * Optionally a rotation matrix @p matrix along with a vector @p
+ * first_vector_components can be specified that describes how vector valued
+ * DoFs of the first face should be modified prior to constraining to the
+ * DoFs of the second face. If @p first_vector_components is non empty the
+ * matrix is interpreted as a rotation matrix that is applied to all vector
+ * valued blocks listet in @p first_vector_components of the FESystem. For
+ * more details see make_periodicity_constraints() and the glossary @ref
+ * GlossPeriodicConstraints "glossary entry on periodic boundary
+ * conditions".
*
- * @tparam Container A type that satisfies the
- * requirements of a mesh container (see @ref GlossMeshAsAContainer).
+ * @tparam Container A type that satisfies the requirements of a mesh
+ * container (see @ref GlossMeshAsAContainer).
*
* @note This version of collect_periodic_face_pairs() will not work on
- * meshes with cells not in @ref GlossFaceOrientation
- * "standard orientation".
+ * meshes with cells not in @ref GlossFaceOrientation "standard
+ * orientation".
*
* @author Daniel Arndt, Matthias Maier, 2013, 2014
*/
/*@}*/
/**
- * @name Exceptions
+ * @name Exceptions
*/
/*@{*/
/**
- * This class provides a map between two grids which are derived from
- * the same coarse grid. For each cell iterator of the source map, it provides
- * the respective cell iterator on the destination map, through its
- * <tt>operator []</tt>.
+ * This class provides a map between two grids which are derived from the same
+ * coarse grid. For each cell iterator of the source map, it provides the
+ * respective cell iterator on the destination map, through its <tt>operator
+ * []</tt>.
*
* Usually, the two grids will be refined differently. Then, the value
* returned for an iterator on the source grid will be either:
* <ul>
- * <li> The same cell on the destination grid, if it exists there;
- * <li> The most refined cell of the destination grid from which the
- * pendant of the source cell could be obtained by refinement. This
- * cell is always active and has a refinement level less than that
- * of the source cell.
+ * <li> The same cell on the destination grid, if it exists there;
+ * <li> The most refined cell of the destination grid from which the pendant
+ * of the source cell could be obtained by refinement. This cell is always
+ * active and has a refinement level less than that of the source cell.
* </ul>
- * Keys for this map are all cells on the source grid, whether active or
- * not.
+ * Keys for this map are all cells on the source grid, whether active or not.
*
* For example, consider these two one-dimensional grids:
* @verbatim
* x-----x-----x-----x-----x
* 1 2 3 4
* @endverbatim
- * (Cell numbers are only given as an example and will not correspond
- * to real cell iterator's indices.) The mapping from grid 1 to grid 2
- * will then be as follows:
+ * (Cell numbers are only given as an example and will not correspond to real
+ * cell iterator's indices.) The mapping from grid 1 to grid 2 will then be as
+ * follows:
* @verbatim
* Cell on grid 1 Cell on grid 2
* 1 ------------------> 1
* valid keys. For example, the mapping for the mother cell of cells 1 and 2
* on the first grid will point to cell 1 on the second grid.
*
- * The implementation of this class is such that not only cell
- * iterators into triangulations can be mapped, but also iterators
- * into objects of type DoFHandler, hp::DoFHandler and
- * MGDoFHandler. The extension to other classes offering iterator
- * functions and some minor additional requirements is simple.
+ * The implementation of this class is such that not only cell iterators into
+ * triangulations can be mapped, but also iterators into objects of type
+ * DoFHandler, hp::DoFHandler and MGDoFHandler. The extension to other classes
+ * offering iterator functions and some minor additional requirements is
+ * simple.
*
- * Note that this class could in principle be based on the C++ <tt>map<Key,Value></tt>
- * data type. Instead, it uses another data format which is more effective both
- * in terms of computing time for access as well as with regard to memory
- * consumpion.
+ * Note that this class could in principle be based on the C++
+ * <tt>map<Key,Value></tt> data type. Instead, it uses another data format
+ * which is more effective both in terms of computing time for access as well
+ * as with regard to memory consumpion.
*
*
* <h3>Usage</h3>
* @endverbatim
*
* Note that the template parameters to this class have to be given as
- * <tt>InterGridMap<DoFHandler<2> ></tt>, which here is DoFHandler
- * (and could equally well be Triangulation, PersistentTriangulation,
- * hp::DoFHandler or MGDoFHandler).
+ * <tt>InterGridMap<DoFHandler<2> ></tt>, which here is DoFHandler (and could
+ * equally well be Triangulation, PersistentTriangulation, hp::DoFHandler or
+ * MGDoFHandler).
*
* @ingroup grid
* @author Wolfgang Bangerth, 1999
public:
/**
- * Typedef to the iterator type of
- * the grid class under consideration.
+ * Typedef to the iterator type of the grid class under consideration.
*/
typedef typename GridClass::cell_iterator cell_iterator;
/**
- * Constructor setting the class
- * name arguments in the
- * SmartPointer members.
+ * Constructor setting the class name arguments in the SmartPointer members.
*/
InterGridMap();
/**
- * Create the mapping between the two
- * grids.
+ * Create the mapping between the two grids.
*/
void make_mapping (const GridClass &source_grid,
const GridClass &destination_grid);
/**
- * Access operator: give a cell
- * on the source grid and receive
- * the respective cell on the
- * other grid, or if that does not
- * exist, the most refined cell
- * of which the source cell would
- * be created if it were further
+ * Access operator: give a cell on the source grid and receive the
+ * respective cell on the other grid, or if that does not exist, the most
+ * refined cell of which the source cell would be created if it were further
* refined.
*/
cell_iterator operator [] (const cell_iterator &source_cell) const;
void clear ();
/**
- * Return a pointer to the source
- * grid.
+ * Return a pointer to the source grid.
*/
const GridClass &get_source_grid () const;
/**
- * Return a pointer to the
- * destination grid.
+ * Return a pointer to the destination grid.
*/
const GridClass &get_destination_grid () const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
private:
/**
- * The actual data. Hold one iterator
- * for each cell on each level.
+ * The actual data. Hold one iterator for each cell on each level.
*/
std::vector<std::vector<cell_iterator> > mapping;
SmartPointer<const GridClass,InterGridMap<GridClass> > destination_grid;
/**
- * Set the mapping for the pair of
- * cells given. These shall match
- * in level of refinement and all
- * other properties.
+ * Set the mapping for the pair of cells given. These shall match in level
+ * of refinement and all other properties.
*/
void set_mapping (const cell_iterator &src_cell,
const cell_iterator &dst_cell);
/**
- * Set the value of the key @p src_cell
- * to @p dst_cell. Do so as well for
- * all the children and their children
- * of @p src_cell. This function is
- * used for cells which are more
- * refined on @p src_grid than on
- * @p dst_grid; then all values of
- * the hierarchy of cells and their
- * children point to one cell on the
- * @p dst_grid.
+ * Set the value of the key @p src_cell to @p dst_cell. Do so as well for
+ * all the children and their children of @p src_cell. This function is used
+ * for cells which are more refined on @p src_grid than on @p dst_grid; then
+ * all values of the hierarchy of cells and their children point to one cell
+ * on the @p dst_grid.
*/
void set_entries_to_cell (const cell_iterator &src_cell,
const cell_iterator &dst_cell);
/**
- * We collect here some helper functions used in the
- * Manifold<dim,spacedim> classes.
+ * We collect here some helper functions used in the Manifold<dim,spacedim>
+ * classes.
*/
namespace Manifolds
{
/**
- * Given a general mesh iterator, construct a quadrature with the
- * Laplace weights or with uniform weights according the parameter
- * @p with_laplace, and with all relevant points of the iterator:
- * vertices, line centers and/or face centers, which can be called
- * when creating new vertices in the manifold routines.
- */
+ * Given a general mesh iterator, construct a quadrature with the Laplace
+ * weights or with uniform weights according the parameter @p with_laplace,
+ * and with all relevant points of the iterator: vertices, line centers
+ * and/or face centers, which can be called when creating new vertices in
+ * the manifold routines.
+ */
template <typename OBJECT>
Quadrature<OBJECT::AccessorType::space_dimension>
get_default_quadrature(const OBJECT &obj, bool with_laplace = false);
/**
- * This class is used to represent a manifold to a triangulation.
- * When a triangulation creates a new vertex on this manifold, it
- * determines the new vertex' coordinates through the following
- * function:
+ * This class is used to represent a manifold to a triangulation. When a
+ * triangulation creates a new vertex on this manifold, it determines the new
+ * vertex' coordinates through the following function:
*
* @code
* ...
* Point<spacedim> new_vertex = manifold.get_new_point (quadrature);
* ...
* @endcode
- * @p quadrature is a Quadrature<spacedim> object, which contains a
- * collection of points in @p spacedim dimension, and a collection of
- * weights (Note that unlike almost all other cases in the library,
- * we here interpret the points in the quadrature object to be in
- * real space, not on the reference cell.)
+ * @p quadrature is a Quadrature<spacedim> object, which contains a collection
+ * of points in @p spacedim dimension, and a collection of weights (Note that
+ * unlike almost all other cases in the library, we here interpret the points
+ * in the quadrature object to be in real space, not on the reference cell.)
*
- * Internaly, the get_new_point() function calls the
- * project_to_manifold() function after computing the weighted
- * average of the quadrature points. This allows end users to only
- * overload project_to_manifold() for simple situations.
+ * Internaly, the get_new_point() function calls the project_to_manifold()
+ * function after computing the weighted average of the quadrature points.
+ * This allows end users to only overload project_to_manifold() for simple
+ * situations.
*
- * Should a finer control be necessary, then get_new_point() can be
- * overloaded.
+ * Should a finer control be necessary, then get_new_point() can be
+ * overloaded.
*
- * FlatManifold is the specialization from which StraigthBoundary is
- * derived, where the project_to_manifold() function is the identity.
+ * FlatManifold is the specialization from which StraigthBoundary is derived,
+ * where the project_to_manifold() function is the identity.
*
* @ingroup manifold
* @author Luca Heltai, 2014
virtual ~Manifold ();
/**
- * Return the point which shall become the new vertex surrounded by
- * the given points which make up the quadrature. We use a
- * quadrature object, which should be filled with the surrounding
- * points together with appropriate weights.
+ * Return the point which shall become the new vertex surrounded by the
+ * given points which make up the quadrature. We use a quadrature object,
+ * which should be filled with the surrounding points together with
+ * appropriate weights.
*
* In its default implementation it calls internally the function
- * project_to_manifold. User classes can get away by simply
- * implementing that method.
+ * project_to_manifold. User classes can get away by simply implementing
+ * that method.
*/
virtual
Point<spacedim>
get_new_point(const Quadrature<spacedim> &quad) const;
/**
- * Given a point which lies close to the given manifold, it modifies
- * it and projects it to manifold itself.
+ * Given a point which lies close to the given manifold, it modifies it and
+ * projects it to manifold itself.
*
* This class is used by the default implementation of the function
- * get_new_point(). It should be made pure virtual, but for
- * historical reason, derived classes like Boundary<dim, spacedim>
- * do not implement it. The default behavior of this class, however,
- * is to throw an exception when called.
+ * get_new_point(). It should be made pure virtual, but for historical
+ * reason, derived classes like Boundary<dim, spacedim> do not implement it.
+ * The default behavior of this class, however, is to throw an exception
+ * when called.
*
- * If your manifold is simple, you could implement this function
- * only, and the default behavior should work out of the box.
+ * If your manifold is simple, you could implement this function only, and
+ * the default behavior should work out of the box.
*/
virtual
Point<spacedim> project_to_manifold (const std::vector<Point<spacedim> > &surrounding_points,
const Point<spacedim> &candidate) const;
/**
- * Backward compatibility interface. Return the point which shall
- * become the new middle vertex of the two children of a regular
- * line. In 2D, this line is a line at the boundary, while in 3d, it
- * is bounding a face at the boundary (the lines therefore is also
- * on the boundary).
+ * Backward compatibility interface. Return the point which shall become
+ * the new middle vertex of the two children of a regular line. In 2D, this
+ * line is a line at the boundary, while in 3d, it is bounding a face at the
+ * boundary (the lines therefore is also on the boundary).
*
- * The default implementation of this function
- * passes its argument to the Manifolds::get_default_quadrature()
- * function, and then calls the
- * Manifold<dim,spacedim>::get_new_point() function. User derived
- * classes can overload Manifold<dim,spacedim>::get_new_point() or
- * Manifold<dim,spacedim>::project_to_surface(), which is called by
- * the default implementation of
- * Manifold<dim,spacedim>::get_new_point().
+ * The default implementation of this function passes its argument to the
+ * Manifolds::get_default_quadrature() function, and then calls the
+ * Manifold<dim,spacedim>::get_new_point() function. User derived classes
+ * can overload Manifold<dim,spacedim>::get_new_point() or
+ * Manifold<dim,spacedim>::project_to_surface(), which is called by the
+ * default implementation of Manifold<dim,spacedim>::get_new_point().
*/
virtual
Point<spacedim>
get_new_point_on_line (const typename Triangulation<dim,spacedim>::line_iterator &line) const;
/**
- * Backward compatibility interface. Return the point which shall
- * become the common point of the four children of a quad at the
- * boundary in three or more spatial dimensions. This function
- * therefore is only useful in at least three dimensions and should
- * not be called for lower dimensions.
+ * Backward compatibility interface. Return the point which shall become the
+ * common point of the four children of a quad at the boundary in three or
+ * more spatial dimensions. This function therefore is only useful in at
+ * least three dimensions and should not be called for lower dimensions.
*
* This function is called after the four lines bounding the given @p quad
* are refined, so you may want to use the information provided by
* <tt>quad->line(i)->child(j)</tt>, <tt>i=0...3</tt>, <tt>j=0,1</tt>.
*
- * The default implementation of this function passes its argument
- * to the Manifolds::get_default_quadrature() function, and then
- * calls the Manifold<dim,spacedim>::get_new_point() function. User
- * derived classes can overload
- * Manifold<dim,spacedim>::get_new_point() or
- * Manifold<dim,spacedim>::project_to_surface(), which is called by
- * the default implementation of
- * Manifold<dim,spacedim>::get_new_point().
+ * The default implementation of this function passes its argument to the
+ * Manifolds::get_default_quadrature() function, and then calls the
+ * Manifold<dim,spacedim>::get_new_point() function. User derived classes
+ * can overload Manifold<dim,spacedim>::get_new_point() or
+ * Manifold<dim,spacedim>::project_to_surface(), which is called by the
+ * default implementation of Manifold<dim,spacedim>::get_new_point().
*/
virtual
Point<spacedim>
get_new_point_on_quad (const typename Triangulation<dim,spacedim>::quad_iterator &quad) const;
/**
- * Backward compatibility interface. Return the point which shall
- * become the common point of the eight children of a hex in three
- * or spatial dimensions. This function therefore is only useful in
- * at least three dimensions and should not be called for lower
- * dimensions.
+ * Backward compatibility interface. Return the point which shall become
+ * the common point of the eight children of a hex in three or spatial
+ * dimensions. This function therefore is only useful in at least three
+ * dimensions and should not be called for lower dimensions.
*
- * This function is called after the all the bounding objects of the
- * given @p hex are refined, so you may want to use the information
- * provided by <tt>hex->quad(i)->line(j)->child(k)</tt>,
- * <tt>i=0...5</tt>, <tt>j=0...3</tt>, <tt>k=0,1</tt>.
+ * This function is called after the all the bounding objects of the given
+ * @p hex are refined, so you may want to use the information provided by
+ * <tt>hex->quad(i)->line(j)->child(k)</tt>, <tt>i=0...5</tt>,
+ * <tt>j=0...3</tt>, <tt>k=0,1</tt>.
*
- * The default implementation of this function passes its argument
- * to the Manifolds::get_default_quadrature() function, and then
- * calls the Manifold<dim,spacedim>::get_new_point() function. User
- * derived classes can overload
- * Manifold<dim,spacedim>::get_new_point() or
- * Manifold<dim,spacedim>::project_to_surface(), which is called by
- * the default implementation of
- * Manifold<dim,spacedim>::get_new_point().
+ * The default implementation of this function passes its argument to the
+ * Manifolds::get_default_quadrature() function, and then calls the
+ * Manifold<dim,spacedim>::get_new_point() function. User derived classes
+ * can overload Manifold<dim,spacedim>::get_new_point() or
+ * Manifold<dim,spacedim>::project_to_surface(), which is called by the
+ * default implementation of Manifold<dim,spacedim>::get_new_point().
*/
virtual
Point<spacedim>
/**
* Backward compatibility interface. Depending on <tt>dim=2</tt> or
- * <tt>dim=3</tt> this function calls the get_new_point_on_line or
- * the get_new_point_on_quad function. It throws an exception for
- * <tt>dim=1</tt>. This wrapper allows dimension independent
- * programming.
+ * <tt>dim=3</tt> this function calls the get_new_point_on_line or the
+ * get_new_point_on_quad function. It throws an exception for
+ * <tt>dim=1</tt>. This wrapper allows dimension independent programming.
*/
Point<spacedim>
get_new_point_on_face (const typename Triangulation<dim,spacedim>::face_iterator &face) const;
/**
* Backward compatibility interface. Depending on <tt>dim=1</tt>,
* <tt>dim=2</tt> or <tt>dim=3</tt> this function calls the
- * get_new_point_on_line, get_new_point_on_quad or the
- * get_new_point_on_hex function. This wrapper allows dimension
- * independent programming.
+ * get_new_point_on_line, get_new_point_on_quad or the get_new_point_on_hex
+ * function. This wrapper allows dimension independent programming.
*/
Point<spacedim>
get_new_point_on_cell (const typename Triangulation<dim,spacedim>::cell_iterator &cell) const;
/**
- * Specialization of Manifold<dim,spacedim>, which represent a
- * possibly periodic Euclidean space of dimension @p dim embedded in
- * the Euclidean space of @p spacedim dimensions. The main
- * characteristic of this Manifold is the fact that the function
- * FlatManifold<dim,spacedim>::project_to_manifold() is the identity
- * function.
+ * Specialization of Manifold<dim,spacedim>, which represent a possibly
+ * periodic Euclidean space of dimension @p dim embedded in the Euclidean
+ * space of @p spacedim dimensions. The main characteristic of this Manifold
+ * is the fact that the function
+ * FlatManifold<dim,spacedim>::project_to_manifold() is the identity function.
*
- * @ingroup manifold
+ * @ingroup manifold
*
- * @author Luca Heltai, 2014
+ * @author Luca Heltai, 2014
*/
template <int dim, int spacedim=dim>
class FlatManifold: public Manifold<dim, spacedim>
{
public:
/**
- * Default constructor. The optional argument can be used to specify
- * the periodicity of the spacedim-dimensional manifold (one period
- * per direction). A periodicity value of zero means that along that
- * direction there is no periodicity. By default no periodicity is
- * assumed.
+ * Default constructor. The optional argument can be used to specify the
+ * periodicity of the spacedim-dimensional manifold (one period per
+ * direction). A periodicity value of zero means that along that direction
+ * there is no periodicity. By default no periodicity is assumed.
*
- * Periodicity affects the way a middle point is computed. It is
- * assumed that if two points are more than half period distant,
- * then the distance should be computed by crossing the periodicity
- * boundary, i.e., the average is computed by adding a full period
- * to the sum of the two. For example, if along direction 0 we have
- * 2*pi periodicity, then the average of (2*pi-eps) and (eps) is not
- * pi, but 2*pi (or zero), since, on a periodic manifold, these two
- * points are at distance 2*eps and not (2*pi-eps). Special cases
- * are taken into account, to ensure that the behavior is always as
- * expected. The third argument is used as a relative tolerance when
- * computing distances.
+ * Periodicity affects the way a middle point is computed. It is assumed
+ * that if two points are more than half period distant, then the distance
+ * should be computed by crossing the periodicity boundary, i.e., the
+ * average is computed by adding a full period to the sum of the two. For
+ * example, if along direction 0 we have 2*pi periodicity, then the average
+ * of (2*pi-eps) and (eps) is not pi, but 2*pi (or zero), since, on a
+ * periodic manifold, these two points are at distance 2*eps and not (2*pi-
+ * eps). Special cases are taken into account, to ensure that the behavior
+ * is always as expected. The third argument is used as a relative tolerance
+ * when computing distances.
*
* Periodicity will be intended in the following way: the domain is
- * considered to be the box contained in [Point<spacedim>(),
- * periodicity) where the right extreme is excluded. If any of the
- * components of this box has zero length, then no periodicity is
- * computed in that direction. Whenever a function that tries to
- * compute averages is called, an exception will be thrown if one of
- * the points which you are using for the average lies outside the
- * periodicity box. The return points are garanteed to lie in the
- * perodicity box plus or minus tolerance*periodicity.norm().
+ * considered to be the box contained in [Point<spacedim>(), periodicity)
+ * where the right extreme is excluded. If any of the components of this box
+ * has zero length, then no periodicity is computed in that direction.
+ * Whenever a function that tries to compute averages is called, an
+ * exception will be thrown if one of the points which you are using for the
+ * average lies outside the periodicity box. The return points are garanteed
+ * to lie in the perodicity box plus or minus tolerance*periodicity.norm().
*/
FlatManifold (const Point<spacedim> periodicity=Point<spacedim>(),
const double tolerance=1e-10);
/**
* Let the new point be the average sum of surrounding vertices.
*
- * This particular implementation constructs the weighted average of
- * the surrounding points, and then calls internally the function
- * project_to_manifold. The reason why we do it this way, is to
- * allow lazy programmers to implement only the project_to_manifold
- * function for their own Manifold classes which are small (or
- * trivial) perturbations of a flat manifold. This is the case
- * whenever the coarse mesh is a decent approximation of the
- * manifold geometry. In this case, the middle point of a cell is
- * close to true middle point of the manifold, and a projection may
- * suffice.
+ * This particular implementation constructs the weighted average of the
+ * surrounding points, and then calls internally the function
+ * project_to_manifold. The reason why we do it this way, is to allow lazy
+ * programmers to implement only the project_to_manifold function for their
+ * own Manifold classes which are small (or trivial) perturbations of a flat
+ * manifold. This is the case whenever the coarse mesh is a decent
+ * approximation of the manifold geometry. In this case, the middle point of
+ * a cell is close to true middle point of the manifold, and a projection
+ * may suffice.
*
- * For most simple geometries, it is possible to get reasonable
- * results by deriving your own Manifold class from FlatManifold,
- * and write a new interface only for the project_to_manifold
- * function. You will have good approximations also with large
- * deformations, as long as in the coarsest mesh size you are trying
- * to refine, the middle point is not too far from the manifold mid
- * point, i.e., as long as the coarse mesh size is small enough.
+ * For most simple geometries, it is possible to get reasonable results by
+ * deriving your own Manifold class from FlatManifold, and write a new
+ * interface only for the project_to_manifold function. You will have good
+ * approximations also with large deformations, as long as in the coarsest
+ * mesh size you are trying to refine, the middle point is not too far from
+ * the manifold mid point, i.e., as long as the coarse mesh size is small
+ * enough.
*/
virtual Point<spacedim>
get_new_point(const Quadrature<spacedim> &quad) const;
/**
- * Project to FlatManifold. This is the identity function for flat,
- * Euclidean spaces. Note however that this function can be
- * overloaded by derived classes, which will then benefit from the
- * logic behind the get_new_point class which are often very
- * similar (if not identical) to the one implemented in this class.
+ * Project to FlatManifold. This is the identity function for flat,
+ * Euclidean spaces. Note however that this function can be overloaded by
+ * derived classes, which will then benefit from the logic behind the
+ * get_new_point class which are often very similar (if not identical) to
+ * the one implemented in this class.
*/
virtual
Point<spacedim> project_to_manifold (const std::vector<Point<spacedim> > &points,
const Point<spacedim> &candidate) const;
private:
/**
- * The periodicity of this Manifold. Periodicity affects the way a
- * middle point is computed. It is assumed that if two points are
- * more than half period distant, then the distance should be
- * computed by crossing the periodicity boundary, i.e., the average
- * is computed by adding a full period to the sum of the two. For
- * example, if along direction 0 we have 2*pi periodicity, then the
- * average of (2*pi-eps) and (eps) is not pi, but 2*pi (or zero),
- * since, on a periodic manifold, these two points are at distance
- * 2*eps and not (2*pi-eps).
+ * The periodicity of this Manifold. Periodicity affects the way a middle
+ * point is computed. It is assumed that if two points are more than half
+ * period distant, then the distance should be computed by crossing the
+ * periodicity boundary, i.e., the average is computed by adding a full
+ * period to the sum of the two. For example, if along direction 0 we have
+ * 2*pi periodicity, then the average of (2*pi-eps) and (eps) is not pi, but
+ * 2*pi (or zero), since, on a periodic manifold, these two points are at
+ * distance 2*eps and not (2*pi-eps).
*
- * A periodicity 0 along one direction means no periodicity. This is
- * the default value for all directions.
+ * A periodicity 0 along one direction means no periodicity. This is the
+ * default value for all directions.
*/
const Point<spacedim> periodicity;
<< ", " << arg3[arg4] << "), bailing out.");
/**
- * Relative tolerance. This tolerance is used to compute distances
- * in double precision.
+ * Relative tolerance. This tolerance is used to compute distances in double
+ * precision.
*/
const double tolerance;
};
/**
- * This class describes mappings that can be expressed in terms
- * of charts. Specifically, this class with its template arguments
- * describes a chart of dimension chartdim, which is part of a
- * Manifold<dim,spacedim> and is used in an object of type
- * Triangulation<dim,spacedim>: It specializes a Manifold of
- * dimension chartdim embedded in a manifold of dimension spacedim,
- * for which you have explicit pull_back() and push_forward()
- * transformations. Its use is explained in great detail in step-53.
+ * This class describes mappings that can be expressed in terms of charts.
+ * Specifically, this class with its template arguments describes a chart of
+ * dimension chartdim, which is part of a Manifold<dim,spacedim> and is used
+ * in an object of type Triangulation<dim,spacedim>: It specializes a
+ * Manifold of dimension chartdim embedded in a manifold of dimension
+ * spacedim, for which you have explicit pull_back() and push_forward()
+ * transformations. Its use is explained in great detail in step-53.
*
- * This is a helper class which is useful when you have an explicit
- * map from an Euclidean space of dimension chartdim to an Euclidean
- * space of dimension spacedim which represents your manifold, i.e.,
- * when your manifold $\mathcal{M}$ can be represented by a map
- * \f[
- * F: \mathcal{B} \subset R^{\text{chartdim}} \mapsto \mathcal{M}
- * \subset R^{\text{spacedim}}
- * \f]
- * (the push_forward() function)
- * and that admits the inverse transformation
- * \f[
- * F^{-1}: \mathcal{M}
- * \subset R^{\text{spacedim}} \mapsto
- * \mathcal{B} \subset R^{\text{chartdim}}
- * \f]
- * (the pull_back() function).
+ * This is a helper class which is useful when you have an explicit map from
+ * an Euclidean space of dimension chartdim to an Euclidean space of dimension
+ * spacedim which represents your manifold, i.e., when your manifold
+ * $\mathcal{M}$ can be represented by a map \f[ F: \mathcal{B} \subset
+ * R^{\text{chartdim}} \mapsto \mathcal{M} \subset R^{\text{spacedim}} \f]
+ * (the push_forward() function) and that admits the inverse transformation
+ * \f[ F^{-1}: \mathcal{M} \subset R^{\text{spacedim}} \mapsto \mathcal{B}
+ * \subset R^{\text{chartdim}} \f] (the pull_back() function).
*
- * The get_new_point() function of the ChartManifold class is
- * implemented by calling the pull_back() method for all
- * #surrounding_points, computing their weighted average in the
- * chartdim Euclidean space, and calling the push_forward() method
- * with the resulting point, i.e., \f[ p^{\text{new}} = F(\sum_i w_i
- * F^{-1}(p_i)). \f]
+ * The get_new_point() function of the ChartManifold class is implemented by
+ * calling the pull_back() method for all #surrounding_points, computing their
+ * weighted average in the chartdim Euclidean space, and calling the
+ * push_forward() method with the resulting point, i.e., \f[ p^{\text{new}} =
+ * F(\sum_i w_i F^{-1}(p_i)). \f]
*
- * Derived classes are required to implement the push_forward() and
- * the pull_back() methods. All other functions required by mappings
- * will then be provided by this class.
+ * Derived classes are required to implement the push_forward() and the
+ * pull_back() methods. All other functions required by mappings will then be
+ * provided by this class.
*
- * The dimension arguments #chartdim, #dim and #spacedim must
- * satisfy the following relationships:
+ * The dimension arguments #chartdim, #dim and #spacedim must satisfy the
+ * following relationships:
* @code
* dim <= spacedim
* chartdim <= spacedim
* @endcode
- * However, there is no a priori relationship between #dim and
- * #chartdim. For example, if you want to describe a mapping
- * for an edge (a 1d object) in a 2d triangulation embedded in
- * 3d space, you could do so by parameterizing it via a line
+ * However, there is no a priori relationship between #dim and #chartdim. For
+ * example, if you want to describe a mapping for an edge (a 1d object) in a
+ * 2d triangulation embedded in 3d space, you could do so by parameterizing it
+ * via a line
* @f[
* F: [0,1] \rightarrow {\mathbb R}^3
* @f]
- * in which case #chartdim is 1. On the other hand, there is
- * no reason why one can't describe this as a mapping
+ * in which case #chartdim is 1. On the other hand, there is no reason why one
+ * can't describe this as a mapping
* @f[
* F: {\mathbb R}^3 \rightarrow {\mathbb R}^3
* @f]
- * in such a way that the line $[0,1]\times \{0\}\times \{0\}$ happens to be
- * mapped onto the edge in question. Here, #chartdim is 3. This may seem
- * cumbersome but satisfies the requirements of an invertible function $F$
- * just fine as long as it is possible to get from the edge to the pull-back
- * space and then back again. Finally, given that we are dealing with a 2d
- * triangulation in 3d, one will often have a mapping from, say, the 2d unit
- * square or unit disk to the domain in 3d space, and the edge in question
- * may simply be the mapped edge of the unit domain in 2d space. In
- * this case, #chartdim is 2.
+ * in such a way that the line $[0,1]\times \{0\}\times \{0\}$ happens to be
+ * mapped onto the edge in question. Here, #chartdim is 3. This may seem
+ * cumbersome but satisfies the requirements of an invertible function $F$
+ * just fine as long as it is possible to get from the edge to the pull-back
+ * space and then back again. Finally, given that we are dealing with a 2d
+ * triangulation in 3d, one will often have a mapping from, say, the 2d unit
+ * square or unit disk to the domain in 3d space, and the edge in question may
+ * simply be the mapped edge of the unit domain in 2d space. In this case,
+ * #chartdim is 2.
*
- * @ingroup manifold
+ * @ingroup manifold
*
- * @author Luca Heltai, 2013, 2014
+ * @author Luca Heltai, 2013, 2014
*/
template <int dim, int spacedim=dim, int chartdim=dim>
class ChartManifold: public Manifold<dim,spacedim>
{
public:
/**
- * Constructor. The optional argument can be used to specify the
- * periodicity of the chartdim-dimensional manifold (one period per
- * direction). A periodicity value of zero means that along that
- * direction there is no periodicity. By default no periodicity is
- * assumed.
+ * Constructor. The optional argument can be used to specify the periodicity
+ * of the chartdim-dimensional manifold (one period per direction). A
+ * periodicity value of zero means that along that direction there is no
+ * periodicity. By default no periodicity is assumed.
*
- * Periodicity affects the way a middle point is computed. It is
- * assumed that if two points are more than half period distant,
- * then the distance should be computed by crossing the periodicity
- * boundary, i.e., then the average is computed by adding a full
- * period to the sum of the two. For example, if along direction 0
- * we have 2*pi periodicity, then the average of (2*pi-eps) and
- * (eps) is not pi, but 2*pi (or zero), since, on the manifold,
- * these two points are at distance 2*eps and not (2*pi-eps)
+ * Periodicity affects the way a middle point is computed. It is assumed
+ * that if two points are more than half period distant, then the distance
+ * should be computed by crossing the periodicity boundary, i.e., then the
+ * average is computed by adding a full period to the sum of the two. For
+ * example, if along direction 0 we have 2*pi periodicity, then the average
+ * of (2*pi-eps) and (eps) is not pi, but 2*pi (or zero), since, on the
+ * manifold, these two points are at distance 2*eps and not (2*pi-eps)
*/
ChartManifold(const Point<chartdim> periodicity=Point<chartdim>());
/**
- * Destructor. Does nothing here, but needs to be declared to make
- * it virtual.
+ * Destructor. Does nothing here, but needs to be declared to make it
+ * virtual.
*/
virtual ~ChartManifold ();
/**
- * Refer to the general documentation of this class and the
- * documentation of the base class for more information.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class for more information.
*/
virtual Point<spacedim>
get_new_point(const Quadrature<spacedim> &quad) const;
* Pull back the given point in spacedim to the Euclidean chartdim
* dimensional space.
*
- * Refer to the general documentation of this class for more
- * information.
+ * Refer to the general documentation of this class for more information.
*/
virtual Point<chartdim>
pull_back(const Point<spacedim> &space_point) const = 0;
/**
- * Given a point in the chartdim dimensional Euclidean space, this
- * method returns a point on the manifold embedded in the spacedim
- * Euclidean space.
+ * Given a point in the chartdim dimensional Euclidean space, this method
+ * returns a point on the manifold embedded in the spacedim Euclidean space.
*
- * Refer to the general documentation of this class for more
- * information.
+ * Refer to the general documentation of this class for more information.
*/
virtual Point<spacedim>
push_forward(const Point<chartdim> &chart_point) const = 0;
private:
/**
- * The sub_manifold object is used to compute the average of the
- * points in the chart coordinates system.
+ * The sub_manifold object is used to compute the average of the points in
+ * the chart coordinates system.
*/
const FlatManifold<dim,chartdim> sub_manifold;
};
* Manifold description for a spherical space coordinate system.
*
* You can use this Manifold object to describe any sphere, circle,
- * hypersphere or hyperdisc in two or three dimensions, both as a
- * co-dimension one manifold descriptor or as co-dimension zero
- * manifold descriptor.
+ * hypersphere or hyperdisc in two or three dimensions, both as a co-dimension
+ * one manifold descriptor or as co-dimension zero manifold descriptor.
*
- * The two template arguments match the meaning of the two template
- * arguments in Triangulation<dim, spacedim>, however this Manifold
- * can be used to describe both thin and thick objects, and the
- * behavior is identical when dim <= spacedim, i.e., the functionality
- * of SphericalManifold<2,3> is identical to SphericalManifold<3,3>.
+ * The two template arguments match the meaning of the two template arguments
+ * in Triangulation<dim, spacedim>, however this Manifold can be used to
+ * describe both thin and thick objects, and the behavior is identical when
+ * dim <= spacedim, i.e., the functionality of SphericalManifold<2,3> is
+ * identical to SphericalManifold<3,3>.
*
- * The two dimensional implementation of this class works by
- * transforming points to spherical coordinates, taking the average in
- * that coordinate system, and then transforming back the point to
- * Cartesian coordinates. For the three dimensional case, we use a
- * simpler approach: we take the average of the norm of the points,
- * and use this value to shift the average point along the radial
- * direction. In order for this manifold to work correctly, it cannot
- * be attached to cells containing the center of the coordinate
- * system. This point is a singular point of the coordinate
- * transformation, and there taking averages does not make any sense.
+ * The two dimensional implementation of this class works by transforming
+ * points to spherical coordinates, taking the average in that coordinate
+ * system, and then transforming back the point to Cartesian coordinates. For
+ * the three dimensional case, we use a simpler approach: we take the average
+ * of the norm of the points, and use this value to shift the average point
+ * along the radial direction. In order for this manifold to work correctly,
+ * it cannot be attached to cells containing the center of the coordinate
+ * system. This point is a singular point of the coordinate transformation,
+ * and there taking averages does not make any sense.
*
* @ingroup manifold
*
{
public:
/**
- * The Constructor takes the center of the spherical coordinates
- * system. This class uses the pull_back and push_forward mechanism
- * to transform from Cartesian to spherical coordinate systems,
- * taking into account the periodicity of base Manifold in two
- * dimensions, while in three dimensions it takes the middle point,
- * and project it along the radius using the average radius of the
- * surrounding points.
+ * The Constructor takes the center of the spherical coordinates system.
+ * This class uses the pull_back and push_forward mechanism to transform
+ * from Cartesian to spherical coordinate systems, taking into account the
+ * periodicity of base Manifold in two dimensions, while in three dimensions
+ * it takes the middle point, and project it along the radius using the
+ * average radius of the surrounding points.
*/
SphericalManifold(const Point<spacedim> center = Point<spacedim>());
/**
- * Pull back the given point from the Euclidean space. Will return
- * the polar coordinates associated with the point @p
- * space_point. Only used when spacedim = 2.
+ * Pull back the given point from the Euclidean space. Will return the polar
+ * coordinates associated with the point @p space_point. Only used when
+ * spacedim = 2.
*/
virtual Point<spacedim>
pull_back(const Point<spacedim> &space_point) const;
/**
- * Given a point in the spherical coordinate system, this method
- * returns the Euclidean coordinates associated to the polar
- * coordinates @p chart_point. Only used when spacedim = 3.
+ * Given a point in the spherical coordinate system, this method returns the
+ * Euclidean coordinates associated to the polar coordinates @p chart_point.
+ * Only used when spacedim = 3.
*/
virtual Point<spacedim>
push_forward(const Point<spacedim> &chart_point) const;
* Let the new point be the average sum of surrounding vertices.
*
* In the two dimensional implementation, we use the pull_back and
- * push_forward mechanism. For three dimensions, this does not work
- * well, so we overload the get_new_point function directly.
+ * push_forward mechanism. For three dimensions, this does not work well, so
+ * we overload the get_new_point function directly.
*/
virtual Point<spacedim>
get_new_point(const Quadrature<spacedim> &quad) const;
const Point<spacedim> center;
private:
- /** Helper function which returns the periodicity associated with
- this coordinate system, according to dim, chartdim, and
- spacedim. */
+ /**
+ * Helper function which returns the periodicity associated with this
+ * coordinate system, according to dim, chartdim, and spacedim.
+ */
static Point<spacedim> get_periodicity();
};
/**
* Cylindrical Manifold description. In three dimensions, points are
- * transformed using a cylindrical coordinate system along the
- * <tt>x-</tt>, <tt>y-</tt> or <tt>z</tt>-axis (when using the first
- * constructor of this class), or an arbitrarily oriented cylinder
- * described by the direction of its axis and a point located on the
- * axis.
+ * transformed using a cylindrical coordinate system along the <tt>x-</tt>,
+ * <tt>y-</tt> or <tt>z</tt>-axis (when using the first constructor of this
+ * class), or an arbitrarily oriented cylinder described by the direction of
+ * its axis and a point located on the axis.
*
- * This class was developed to be used in conjunction with the @p
- * cylinder or @p cylinder_shell functions of GridGenerator. This
- * function will throw an exception whenever spacedim is not equal to
- * three.
+ * This class was developed to be used in conjunction with the @p cylinder or
+ * @p cylinder_shell functions of GridGenerator. This function will throw an
+ * exception whenever spacedim is not equal to three.
*
* @ingroup manifold
*
{
public:
/**
- * Constructor. Using default values for the constructor arguments
- * yields a cylinder along the x-axis (<tt>axis=0</tt>). Choose
- * <tt>axis=1</tt> or <tt>axis=2</tt> for a tube along the y- or
- * z-axis, respectively. The tolerance value is used to determine
- * if a point is on the axis.
+ * Constructor. Using default values for the constructor arguments yields a
+ * cylinder along the x-axis (<tt>axis=0</tt>). Choose <tt>axis=1</tt> or
+ * <tt>axis=2</tt> for a tube along the y- or z-axis, respectively. The
+ * tolerance value is used to determine if a point is on the axis.
*/
CylindricalManifold (const unsigned int axis = 0,
const double tolerance = 1e-10);
/**
- * Constructor. If constructed with this constructor, the manifold
- * described is a cylinder with an axis that points in direction
- * #direction and goes through the given #point_on_axis. The
- * direction may be arbitrarily scaled, and the given point may be
- * any point on the axis. The tolerance value is used to determine
- * if a point is on the axis.
+ * Constructor. If constructed with this constructor, the manifold described
+ * is a cylinder with an axis that points in direction #direction and goes
+ * through the given #point_on_axis. The direction may be arbitrarily
+ * scaled, and the given point may be any point on the axis. The tolerance
+ * value is used to determine if a point is on the axis.
*/
CylindricalManifold (const Point<spacedim> &direction,
const Point<spacedim> &point_on_axis,
const double tolerance = 1e-10);
/**
- * Compute new points on the CylindricalManifold. See the documentation
- * of the base class for a detailed description of what this
- * function does.
- */
+ * Compute new points on the CylindricalManifold. See the documentation of
+ * the base class for a detailed description of what this function does.
+ */
virtual Point<spacedim>
get_new_point(const Quadrature<spacedim> &quad) const;
* Function<spacedim> and Function<chartdim> objects describing the
* push_forward() and pull_back() functions.
*
- * You can use this Manifold object to describe any arbitray shape
- * domain, as long as you can express it in terms of an invertible
- * map, for which you provide both the forward expression, and the
- * inverse expression.
+ * You can use this Manifold object to describe any arbitray shape domain, as
+ * long as you can express it in terms of an invertible map, for which you
+ * provide both the forward expression, and the inverse expression.
*
- * In debug mode, a check is performed to verify that the
- * tranformations are actually one the inverse of the other.
+ * In debug mode, a check is performed to verify that the tranformations are
+ * actually one the inverse of the other.
*
* @ingroup manifold
*
{
public:
/**
- * Explicit functions constructor. Takes a push_forward function of
- * spacedim components, and a pull_back function of chartdim
- * components. See the documentation of the base class ChartManifold
- * for the meaning of the optional #periodicity argument.
+ * Explicit functions constructor. Takes a push_forward function of spacedim
+ * components, and a pull_back function of chartdim components. See the
+ * documentation of the base class ChartManifold for the meaning of the
+ * optional #periodicity argument.
*
- * The tolerance argument is used in debug mode to actually check
- * that the two functions are one the inverse of the other.
+ * The tolerance argument is used in debug mode to actually check that the
+ * two functions are one the inverse of the other.
*/
FunctionManifold(const Function<chartdim> &push_forward_function,
const Function<spacedim> &pull_back_function,
const double tolerance=1e-10);
/**
- * Expressions constructor. Takes the expressions of the
- * push_forward function of spacedim components, and of the
- * pull_back function of chartdim components. See the documentation
- * of the base class ChartManifold for the meaning of the optional
- * #periodicity argument.
+ * Expressions constructor. Takes the expressions of the push_forward
+ * function of spacedim components, and of the pull_back function of
+ * chartdim components. See the documentation of the base class
+ * ChartManifold for the meaning of the optional #periodicity argument.
*
- * The strings should be the readable by the default constructor of
- * the FunctionParser classes. You can specify custom variable
- * expressions with the last two optional arguments. If you don't,
- * the default names are used, i.e., "x,y,z".
+ * The strings should be the readable by the default constructor of the
+ * FunctionParser classes. You can specify custom variable expressions with
+ * the last two optional arguments. If you don't, the default names are
+ * used, i.e., "x,y,z".
*
- * The tolerance argument is used in debug mode to actually check
- * that the two functions are one the inverse of the other.
+ * The tolerance argument is used in debug mode to actually check that the
+ * two functions are one the inverse of the other.
*/
FunctionManifold(const std::string push_forward_expression,
const std::string pull_back_expression,
/**
* Given a point in the chartdim coordinate system, uses the
- * push_forward_function to compute the push_forward of points in
- * #chardim space dimensions to #spacedim space dimensions.
+ * push_forward_function to compute the push_forward of points in #chardim
+ * space dimensions to #spacedim space dimensions.
*/
virtual Point<spacedim>
push_forward(const Point<chartdim> &chart_point) const;
/**
* Given a point in the spacedim coordinate system, uses the
- * pull_back_function to compute the pull_back of points in
- * #spacedim space dimensions to #chartdim space dimensions.
+ * pull_back_function to compute the pull_back of points in #spacedim space
+ * dimensions to #chartdim space dimensions.
*/
virtual Point<chartdim>
pull_back(const Point<spacedim> &space_point) const;
FunctionManifold<dim,spacedim,chartdim> > pull_back_function;
/**
- * Relative tolerance. In debug mode, we check that the two
- * functions provided at construction time are actually one the
- * inverse of the other. This value is used as relative tolerance in
- * this check.
+ * Relative tolerance. In debug mode, we check that the two functions
+ * provided at construction time are actually one the inverse of the other.
+ * This value is used as relative tolerance in this check.
*/
const double tolerance;
/**
- * Check ownership of the smart pointers. Indicates whether this
- * class is the owner of the objects pointed to by the previous two
- * member variables. This value is set in the constructor of the
- * class. If #true, then the destructor will delete the function
- * objects pointed to be the two pointers.
+ * Check ownership of the smart pointers. Indicates whether this class is
+ * the owner of the objects pointed to by the previous two member variables.
+ * This value is set in the constructor of the class. If #true, then the
+ * destructor will delete the function objects pointed to be the two
+ * pointers.
*/
const bool owns_pointers;
};
/**
* This class handles the history of a triangulation and can rebuild it after
- * it was deleted some time before. Its main purpose is support for
- * time-dependent problems where one frequently deletes a triangulation due
- * to memory pressure and later wants to rebuild it; this class has all the
- * information to rebuild it exactly as it was before including the mapping
- * of cell numbers to the geometrical cells.
+ * it was deleted some time before. Its main purpose is support for time-
+ * dependent problems where one frequently deletes a triangulation due to
+ * memory pressure and later wants to rebuild it; this class has all the
+ * information to rebuild it exactly as it was before including the mapping of
+ * cell numbers to the geometrical cells.
*
- * Basically, this is a drop-in replacement for the triangulation. Since it
- * is derived from the Triangulation class, it shares all the
- * functionality, but it overrides some virtual functions and adds some
- * functions, too. The main change to the base class is that it overrides
- * the @p execute_coarsening_and_refinement function, where the new version
- * first stores all refinement and coarsening flags and only then calls the
- * respective function of the base class. The stored flags may later be
- * used to restore the grid just as it was before. Some other functions
- * have been extended slightly as well, see their documentation for more
- * information.
+ * Basically, this is a drop-in replacement for the triangulation. Since it is
+ * derived from the Triangulation class, it shares all the functionality, but
+ * it overrides some virtual functions and adds some functions, too. The main
+ * change to the base class is that it overrides the @p
+ * execute_coarsening_and_refinement function, where the new version first
+ * stores all refinement and coarsening flags and only then calls the
+ * respective function of the base class. The stored flags may later be used
+ * to restore the grid just as it was before. Some other functions have been
+ * extended slightly as well, see their documentation for more information.
*
* We note that since the triangulation is created in exactly the same state
* as it was before, other objects working on it should result in the same
* state as well. This holds in particular for the DoFHandler object, which
* will assign the same degrees of freedom to the original cells and the ones
- * after reconstruction of the triangulation. You can therefore safely use data
- * vectors computed on the original grid on the reconstructed grid as well.
+ * after reconstruction of the triangulation. You can therefore safely use
+ * data vectors computed on the original grid on the reconstructed grid as
+ * well.
*
*
- * <h3>Usage</h3>
- * You can use objects of this class almost in the same way as objects of the
- * Triangulation class. One of the few differences is that you can only
- * construct such an object by giving a coarse grid to the constructor. The
- * coarse grid will be used to base the triangulation on, and therefore the
- * lifetime of the coarse grid has to be longer than the lifetime of the
- * object of this class.
+ * <h3>Usage</h3> You can use objects of this class almost in the same way as
+ * objects of the Triangulation class. One of the few differences is that you
+ * can only construct such an object by giving a coarse grid to the
+ * constructor. The coarse grid will be used to base the triangulation on, and
+ * therefore the lifetime of the coarse grid has to be longer than the
+ * lifetime of the object of this class.
*
* Basically, usage looks like this:
* @code
* };
* @endcode
*
- * Note that initially, the PersistentTriangulation object does not
- * constitute a triangulation; it only becomes one after @p restore is first
- * called. Note also that the @p execute_coarsening_and_refinement stores
- * all necessary flags for later reconstruction using the @p restore function.
- * Triangulation::clear() resets the underlying triangulation to a
- * virgin state, but does not affect the stored refinement flags needed for
- * later reconstruction and does also not touch the coarse grid which is
- * used within restore().
+ * Note that initially, the PersistentTriangulation object does not constitute
+ * a triangulation; it only becomes one after @p restore is first called. Note
+ * also that the @p execute_coarsening_and_refinement stores all necessary
+ * flags for later reconstruction using the @p restore function.
+ * Triangulation::clear() resets the underlying triangulation to a virgin
+ * state, but does not affect the stored refinement flags needed for later
+ * reconstruction and does also not touch the coarse grid which is used within
+ * restore().
*
* @ingroup grid
* @author Wolfgang Bangerth, 1999
{
public:
/**
- * Make the dimension available
- * in function templates.
+ * Make the dimension available in function templates.
*/
static const unsigned int dimension = dim;
static const unsigned int spacedimension = spacedim;
/**
- * Build up the triangulation from the
- * coarse grid in future. Copy smoothing
- * flags, etc from that grid as well.
- * Note that the initial state of the
- * triangulation is empty, until
- * @p restore_grid is called for the
- * first time.
+ * Build up the triangulation from the coarse grid in future. Copy smoothing
+ * flags, etc from that grid as well. Note that the initial state of the
+ * triangulation is empty, until @p restore_grid is called for the first
+ * time.
*
- * The coarse grid must persist until
- * the end of this object, since it will
- * be used upon reconstruction of the
- * grid.
+ * The coarse grid must persist until the end of this object, since it will
+ * be used upon reconstruction of the grid.
*/
PersistentTriangulation (const Triangulation<dim, spacedim> &coarse_grid);
/**
- * Copy constructor. This operation
- * is only allowed, if the triangulation
- * underlying the object to be copied
- * is presently empty. Refinement flags
- * as well as the pointer to the
- * coarse grid are copied, however.
+ * Copy constructor. This operation is only allowed, if the triangulation
+ * underlying the object to be copied is presently empty. Refinement flags
+ * as well as the pointer to the coarse grid are copied, however.
*/
PersistentTriangulation (const PersistentTriangulation<dim, spacedim> &old_tria);
virtual ~PersistentTriangulation ();
/**
- * Overloaded version of the same
- * function in the base class which
- * stores the refinement and coarsening
- * flags for later reconstruction of the
- * triangulation and after that calls
- * the respective function of the
- * base class.
+ * Overloaded version of the same function in the base class which stores
+ * the refinement and coarsening flags for later reconstruction of the
+ * triangulation and after that calls the respective function of the base
+ * class.
*/
virtual void execute_coarsening_and_refinement ();
/**
- * Restore the grid according to
- * the saved data. For this, the
- * coarse grid is copied and the
- * grid is stepwise rebuilt using
- * the saved flags.
+ * Restore the grid according to the saved data. For this, the coarse grid
+ * is copied and the grid is stepwise rebuilt using the saved flags.
*
- * Note that this function will result in
- * an error if the underlying
- * triangulation is not empty, i.e. it
- * will only succeed if this object is
- * newly created or the <tt>clear()</tt>
- * function of the base class was called
- * on it before.
+ * Note that this function will result in an error if the underlying
+ * triangulation is not empty, i.e. it will only succeed if this object is
+ * newly created or the <tt>clear()</tt> function of the base class was
+ * called on it before.
*
- * Repeatedly calls the
- * <tt>restore(unsigned int)</tt>
- * function in a loop over all
- * refinement steps.
+ * Repeatedly calls the <tt>restore(unsigned int)</tt> function in a loop
+ * over all refinement steps.
*/
void restore ();
/**
- * Differential restore. Performs
- * the @p step_noth local
- * refinement and coarsening step.
- * Step 0 stands for the copying
- * of the coarse grid.
+ * Differential restore. Performs the @p step_noth local refinement and
+ * coarsening step. Step 0 stands for the copying of the coarse grid.
*
- * This function will only
- * succeed if the triangulation
- * is in just the state it were
- * if restore would have been
- * called from
+ * This function will only succeed if the triangulation is in just the state
+ * it were if restore would have been called from
* <tt>step=0...step_no-1</tt> before.
*/
void restore (const unsigned int step_no);
/**
- * Returns the number of
- * refinement and coarsening
- * steps. This is given by the
- * size of the @p refine_flags
- * vector.
+ * Returns the number of refinement and coarsening steps. This is given by
+ * the size of the @p refine_flags vector.
*/
unsigned int n_refinement_steps () const;
/**
- * Overload this function to use
- * @p tria as a new coarse grid. The
- * present triangulation and all
- * refinement and coarsening flags
- * storing its history are deleted,
- * and the state of the underlying
- * triangulation is reset to be
- * empty, until @p restore_grid is
- * called the next time.
+ * Overload this function to use @p tria as a new coarse grid. The present
+ * triangulation and all refinement and coarsening flags storing its history
+ * are deleted, and the state of the underlying triangulation is reset to be
+ * empty, until @p restore_grid is called the next time.
*
- * The coarse grid must persist until
- * the end of this object, since it will
- * be used upon reconstruction of the
- * grid.
+ * The coarse grid must persist until the end of this object, since it will
+ * be used upon reconstruction of the grid.
*/
virtual void copy_triangulation (const Triangulation<dim, spacedim> &tria);
/**
- * Throw an error, since this function
- * is not useful in the context of this
+ * Throw an error, since this function is not useful in the context of this
* class.
*/
virtual void create_triangulation (const std::vector<Point<spacedim> > &vertices,
const SubCellData &subcelldata);
/**
- * An overload of the respective function
- * of the base class.
+ * An overload of the respective function of the base class.
*
- * Throw an error, since this function
- * is not useful in the context of this
+ * Throw an error, since this function is not useful in the context of this
* class.
*/
virtual void create_triangulation_compatibility (
const SubCellData &subcelldata);
/**
- * Writes all refine and coarsen
- * flags to the ostream @p out.
+ * Writes all refine and coarsen flags to the ostream @p out.
*/
virtual void write_flags(std::ostream &out) const;
/**
- * Reads all refine and coarsen flags
- * that previously were written by
- * <tt>write_flags(...)</tt>. This is especially
- * useful for rebuilding the triangulation
- * after the end or breakdown of a program
- * and its restart.
+ * Reads all refine and coarsen flags that previously were written by
+ * <tt>write_flags(...)</tt>. This is especially useful for rebuilding the
+ * triangulation after the end or breakdown of a program and its restart.
*/
virtual void read_flags(std::istream &in);
/**
- * Clears all flags. Retains the
- * same coarse grid.
+ * Clears all flags. Retains the same coarse grid.
*/
virtual void clear_flags();
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
virtual std::size_t memory_consumption () const;
private:
/**
- * This grid shall be used as coarse
- * grid.
+ * This grid shall be used as coarse grid.
*/
SmartPointer<const Triangulation<dim,spacedim>,PersistentTriangulation<dim,spacedim> > coarse_grid;
/**
- * Vectors holding the refinement and
- * coarsening flags of the different
- * sweeps on this time level. The
- * vectors therefore hold the history
- * of the grid.
+ * Vectors holding the refinement and coarsening flags of the different
+ * sweeps on this time level. The vectors therefore hold the history of the
+ * grid.
*/
std::vector<std::vector<bool> > refine_flags;
template <typename> class TriaObjects;
/**
- * Forward declaration of a class into
- * which we put much of the
- * implementation of the Triangulation
- * class. See the .cc file for more
+ * Forward declaration of a class into which we put much of the
+ * implementation of the Triangulation class. See the .cc file for more
* information.
*/
struct Implementation;
/**
* A structure to describe individual cells and passed as argument to
- * Triangulation::create_triangulation(). It
- * contains all data needed to construct a cell, namely the indices of the
- * vertices, the material or boundary indicator (depending on whether it
- * represents a cell or a face), and a manifold id to describe the manifold
- * this object belongs to.
+ * Triangulation::create_triangulation(). It contains all data needed to
+ * construct a cell, namely the indices of the vertices, the material or
+ * boundary indicator (depending on whether it represents a cell or a face),
+ * and a manifold id to describe the manifold this object belongs to.
*
* This structure is also used to represent data for faces and edge as part of
* the SubCellData class. In that case the #vertices array needs to represent
* the vertices of a face or edge of a cell listed in the argument to
- * Triangulation::create_triangulation() that denotes the faces. It can be used
- * to attach boundary indicators to faces.
+ * Triangulation::create_triangulation() that denotes the faces. It can be
+ * used to attach boundary indicators to faces.
*
* @ingroup grid
*/
struct CellData
{
/**
- * Indices of the vertices of
- * this cell.
+ * Indices of the vertices of this cell.
*/
unsigned int vertices[GeometryInfo<structdim>::vertices_per_cell];
/**
- * Material or boundary indicator
- * of this cell. The material_id
- * may be used to denote
- * different coefficients, etc.
+ * Material or boundary indicator of this cell. The material_id may be used
+ * to denote different coefficients, etc.
*
- * Note that if this object is part of a
- * SubCellData object, then it represents
- * a face or edge of a cell. In this case
- * one should use the field boundary_id
- * instead of material_id.
+ * Note that if this object is part of a SubCellData object, then it
+ * represents a face or edge of a cell. In this case one should use the
+ * field boundary_id instead of material_id.
*/
union
{
};
/**
- * Manifold identificator of this object. This identificator should
- * be used to identify the manifold to which this object belongs,
- * and from which this object will collect information on how to add
- * points upon refinement.
+ * Manifold identificator of this object. This identificator should be used
+ * to identify the manifold to which this object belongs, and from which
+ * this object will collect information on how to add points upon
+ * refinement.
*/
types::manifold_id manifold_id;
/**
- * Default constructor. Sets the member variables to the following values:
- * - vertex indices to invalid values
- * - boundary or material id zero (the default for boundary or material ids)
- * - manifold id to numbers::invalid_manifold_id
+ * Default constructor. Sets the member variables to the following values: -
+ * vertex indices to invalid values - boundary or material id zero (the
+ * default for boundary or material ids) - manifold id to
+ * numbers::invalid_manifold_id
*/
CellData ();
};
/**
- * Structure to be passed to Triangulation::create_triangulation function to
- * describe boundary information.
- *
- * This structure is the same for all dimensions, since we use an input
- * function which is the same for all dimensions. The content of objects
- * of this structure varies with the dimensions, however.
- *
- * Since in one dimension, there is no boundary information apart
- * from the two end points of the interval, this structure does not contain
- * anything and exists only for consistency, to allow a common interface
- * for all space dimensions. All fields should always be empty.
- *
- * Boundary data in 2D consists
- * of a list of lines which belong to a given boundary component. A
- * boundary component is a list of lines which are given a common
- * number describing the boundary condition to hold on this part of the
- * boundary. The triangulation creation function gives lines not in this
- * list either the boundary indicator zero (if on the boundary) or
- * numbers::internal_face_boundary_id (if in the interior). Explicitely giving a
- * line the indicator numbers::internal_face_boundary_id will result in an error, as well as giving
- * an interior line a boundary indicator.
+ * Structure to be passed to Triangulation::create_triangulation function to
+ * describe boundary information.
+ *
+ * This structure is the same for all dimensions, since we use an input
+ * function which is the same for all dimensions. The content of objects of
+ * this structure varies with the dimensions, however.
+ *
+ * Since in one dimension, there is no boundary information apart from the two
+ * end points of the interval, this structure does not contain anything and
+ * exists only for consistency, to allow a common interface for all space
+ * dimensions. All fields should always be empty.
+ *
+ * Boundary data in 2D consists of a list of lines which belong to a given
+ * boundary component. A boundary component is a list of lines which are given
+ * a common number describing the boundary condition to hold on this part of
+ * the boundary. The triangulation creation function gives lines not in this
+ * list either the boundary indicator zero (if on the boundary) or
+ * numbers::internal_face_boundary_id (if in the interior). Explicitely giving
+ * a line the indicator numbers::internal_face_boundary_id will result in an
+ * error, as well as giving an interior line a boundary indicator.
*
* @ingroup grid
*/
struct SubCellData
{
/**
- * Each record of this vector describes
- * a line on the boundary and its boundary
- * indicator.
+ * Each record of this vector describes a line on the boundary and its
+ * boundary indicator.
*/
std::vector<CellData<1> > boundary_lines;
/**
- * Each record of this vector describes
- * a quad on the boundary and its boundary
- * indicator.
+ * Each record of this vector describes a quad on the boundary and its
+ * boundary indicator.
*/
std::vector<CellData<2> > boundary_quads;
/**
- * This function checks whether the vectors
- * which may not be used in a given
- * dimension are really empty. I.e.,
- * whether the <tt>boundary_*</tt> arrays are
- * empty when in one space dimension
- * and whether the @p boundary_quads
+ * This function checks whether the vectors which may not be used in a given
+ * dimension are really empty. I.e., whether the <tt>boundary_*</tt> arrays
+ * are empty when in one space dimension and whether the @p boundary_quads
* array is empty when in two dimensions.
*
- * Since this structure is the same for all
- * dimensions, the actual dimension has
- * to be given as a parameter.
+ * Since this structure is the same for all dimensions, the actual dimension
+ * has to be given as a parameter.
*/
bool check_consistency (const unsigned int dim) const;
};
namespace internal
{
/**
- * A namespace for classes internal to the
- * triangulation classes and helpers.
+ * A namespace for classes internal to the triangulation classes and
+ * helpers.
*/
namespace Triangulation
{
/**
- * Cache class used to store the number of used and active elements
- * (lines or quads etc) within the levels of a triangulation. This
- * is only the declaration of the template, concrete instantiations
- * are below.
+ * Cache class used to store the number of used and active elements (lines
+ * or quads etc) within the levels of a triangulation. This is only the
+ * declaration of the template, concrete instantiations are below.
*
- * In the old days, whenever one wanted to access one of these
- * numbers, one had to perform a loop over all lines, e.g., and count
- * the elements until we hit the end iterator. This is time consuming
- * and since access to the number of lines etc is a rather frequent
- * operation, this was not an optimal solution.
+ * In the old days, whenever one wanted to access one of these numbers,
+ * one had to perform a loop over all lines, e.g., and count the elements
+ * until we hit the end iterator. This is time consuming and since access
+ * to the number of lines etc is a rather frequent operation, this was not
+ * an optimal solution.
*
* @author Wolfgang Bangerth, 1999
*/
};
/**
- * Cache class used to store the number of used and active elements
- * (lines or quads etc) within the levels of a triangulation. This
- * specialization stores the numbers of lines.
+ * Cache class used to store the number of used and active elements (lines
+ * or quads etc) within the levels of a triangulation. This specialization
+ * stores the numbers of lines.
*
- * In the old days, whenever one wanted to access one of these
- * numbers, one had to perform a loop over all lines, e.g., and count
- * the elements until we hit the end iterator. This is time consuming
- * and since access to the number of lines etc is a rather frequent
- * operation, this was not an optimal solution.
+ * In the old days, whenever one wanted to access one of these numbers,
+ * one had to perform a loop over all lines, e.g., and count the elements
+ * until we hit the end iterator. This is time consuming and since access
+ * to the number of lines etc is a rather frequent operation, this was not
+ * an optimal solution.
*
* @author Wolfgang Bangerth, 1999
*/
struct NumberCache<1>
{
/**
- * The number of levels on
- * which we have used
- * objects.
+ * The number of levels on which we have used objects.
*/
unsigned int n_levels;
/**
- * Number of used lines in the whole
- * triangulation.
+ * Number of used lines in the whole triangulation.
*/
unsigned int n_lines;
/**
- * Array holding the number of used
- * lines on each level.
+ * Array holding the number of used lines on each level.
*/
std::vector<unsigned int> n_lines_level;
/**
- * Number of active lines in the
- * whole triangulation.
+ * Number of active lines in the whole triangulation.
*/
unsigned int n_active_lines;
/**
- * Array holding the number of active
- * lines on each level.
+ * Array holding the number of active lines on each level.
*/
std::vector<unsigned int> n_active_lines_level;
/**
- * Constructor. Set values to zero
- * by default.
+ * Constructor. Set values to zero by default.
*/
NumberCache ();
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
*/
template <class Archive>
void serialize (Archive &ar,
/**
- * Cache class used to store the number of used and active elements
- * (lines or quads etc) within the levels of a triangulation. This
- * specialization stores the numbers of quads. Due to the inheritance
- * from the base class NumberCache<1>, the numbers of lines
- * are also within this class.
+ * Cache class used to store the number of used and active elements (lines
+ * or quads etc) within the levels of a triangulation. This specialization
+ * stores the numbers of quads. Due to the inheritance from the base class
+ * NumberCache<1>, the numbers of lines are also within this class.
*
- * In the old days, whenever one wanted to access one of these
- * numbers, one had to perform a loop over all lines, e.g., and count
- * the elements until we hit the end iterator. This is time consuming
- * and since access to the number of lines etc is a rather frequent
- * operation, this was not an optimal solution.
+ * In the old days, whenever one wanted to access one of these numbers,
+ * one had to perform a loop over all lines, e.g., and count the elements
+ * until we hit the end iterator. This is time consuming and since access
+ * to the number of lines etc is a rather frequent operation, this was not
+ * an optimal solution.
*
* @author Wolfgang Bangerth, 1999
*/
struct NumberCache<2> : public NumberCache<1>
{
/**
- * Number of used quads in the whole
- * triangulation.
+ * Number of used quads in the whole triangulation.
*/
unsigned int n_quads;
/**
- * Array holding the number of used
- * quads on each level.
+ * Array holding the number of used quads on each level.
*/
std::vector<unsigned int> n_quads_level;
/**
- * Number of active quads in the
- * whole triangulation.
+ * Number of active quads in the whole triangulation.
*/
unsigned int n_active_quads;
/**
- * Array holding the number of active
- * quads on each level.
+ * Array holding the number of active quads on each level.
*/
std::vector<unsigned int> n_active_quads_level;
/**
- * Constructor. Set values to zero
- * by default.
+ * Constructor. Set values to zero by default.
*/
NumberCache ();
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
*/
template <class Archive>
void serialize (Archive &ar,
/**
- * Cache class used to store the number of used and active elements
- * (lines or quads etc) within the levels of a triangulation. This
- * specialization stores the numbers of hexes. Due to the inheritance
- * from the base class NumberCache<2>, the numbers of lines
- * and quads are also within this class.
+ * Cache class used to store the number of used and active elements (lines
+ * or quads etc) within the levels of a triangulation. This specialization
+ * stores the numbers of hexes. Due to the inheritance from the base class
+ * NumberCache<2>, the numbers of lines and quads are also within this
+ * class.
*
- * In the old days, whenever one wanted to access one of these
- * numbers, one had to perform a loop over all lines, e.g., and count
- * the elements until we hit the end . This is time consuming
- * and since access to the number of lines etc is a rather frequent
- * operation, this was not an optimal solution.
+ * In the old days, whenever one wanted to access one of these numbers,
+ * one had to perform a loop over all lines, e.g., and count the elements
+ * until we hit the end . This is time consuming and since access to the
+ * number of lines etc is a rather frequent operation, this was not an
+ * optimal solution.
*
* @author Wolfgang Bangerth, 1999
*/
struct NumberCache<3> : public NumberCache<2>
{
/**
- * Number of used hexes in the whole
- * triangulation.
+ * Number of used hexes in the whole triangulation.
*/
unsigned int n_hexes;
/**
- * Array holding the number of used
- * hexes on each level.
+ * Array holding the number of used hexes on each level.
*/
std::vector<unsigned int> n_hexes_level;
/**
- * Number of active hexes in the
- * whole triangulation.
+ * Number of active hexes in the whole triangulation.
*/
unsigned int n_active_hexes;
/**
- * Array holding the number of active
- * hexes on each level.
+ * Array holding the number of active hexes on each level.
*/
std::vector<unsigned int> n_active_hexes_level;
/**
- * Constructor. Set values to zero
- * by default.
+ * Constructor. Set values to zero by default.
*/
NumberCache ();
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
*/
template <class Archive>
void serialize (Archive &ar,
/**
- * Triangulations denote a hierarchy of levels of elements which together
- * form a @p dim -dimensional manifold in @p spacedim spatial dimensions
- * (if spacedim is not specified it takes the default value @p spacedim=dim).
- *
- * Thus, for example, an object of type @p Triangulation<1,1> (or simply
- * @p Triangulation<1> since @p spacedim==dim by default) is used to represent
- * and handle the usual one-dimensional triangulation used in the finite
- * element method (so, segments on a straight line). On the other hand,
- * objects such as @p Triangulation<1,2> or @p Triangulation<2,3> (that
- * are associated with curves in 2D or surfaces in 3D)
- * are the ones one wants to use in the boundary element method.
- *
- * This class is written to be as independent of the dimension as possible
- * (thus the complex construction of the dealii::internal::Triangulation::TriaLevel
- * classes) to allow code-sharing, to allow reducing the need to mirror
- * changes in the code for one dimension to the code for other
- * dimensions. Nonetheless, some of the functions are dependent of the
- * dimension and there only exist specialized versions for distinct
- * dimensions.
- *
- * This class satisfies the requirements outlined in
- * @ref GlossMeshAsAContainer "Meshes as containers".
- *
- *
- * <h3>Structure and iterators</h3>
- *
- * The actual data structure of a Triangulation object is rather complex
- * and quite inconvenient if one attempted to operate on it directly, since
- * data is spread over quite a lot of arrays and other places. However,
- * there are ways powerful enough to work on these data structures
- * without knowing their exact relations. This is done through the
- * concept of iterators (see the STL documentation and TriaIterator).
- * In order to make things as easy and dimension independent as possible,
- * use of class local typedefs is made, see below.
- *
- * The Triangulation class provides iterator which enable looping over all
- * cells without knowing the exact representation used to
- * describe them. Their names are typedefs imported from the Iterators
- * class (thus making them local types to this class) and are as follows:
- *
- * <ul>
- * <li> <tt>cell_iterator</tt>: loop over all cells used in the Triangulation
- * <li> <tt>active_cell_iterator</tt>: loop over all active cells
- * </ul>
- *
- * For <tt>dim==1</tt>, these iterators are mapped as follows:
+ * Triangulations denote a hierarchy of levels of elements which together form
+ * a @p dim -dimensional manifold in @p spacedim spatial dimensions (if
+ * spacedim is not specified it takes the default value @p spacedim=dim).
+ *
+ * Thus, for example, an object of type @p Triangulation<1,1> (or simply @p
+ * Triangulation<1> since @p spacedim==dim by default) is used to represent
+ * and handle the usual one-dimensional triangulation used in the finite
+ * element method (so, segments on a straight line). On the other hand,
+ * objects such as @p Triangulation<1,2> or @p Triangulation<2,3> (that are
+ * associated with curves in 2D or surfaces in 3D) are the ones one wants to
+ * use in the boundary element method.
+ *
+ * This class is written to be as independent of the dimension as possible
+ * (thus the complex construction of the
+ * dealii::internal::Triangulation::TriaLevel classes) to allow code-sharing,
+ * to allow reducing the need to mirror changes in the code for one dimension
+ * to the code for other dimensions. Nonetheless, some of the functions are
+ * dependent of the dimension and there only exist specialized versions for
+ * distinct dimensions.
+ *
+ * This class satisfies the requirements outlined in @ref
+ * GlossMeshAsAContainer "Meshes as containers".
+ *
+ *
+ * <h3>Structure and iterators</h3>
+ *
+ * The actual data structure of a Triangulation object is rather complex and
+ * quite inconvenient if one attempted to operate on it directly, since data
+ * is spread over quite a lot of arrays and other places. However, there are
+ * ways powerful enough to work on these data structures without knowing their
+ * exact relations. This is done through the concept of iterators (see the STL
+ * documentation and TriaIterator). In order to make things as easy and
+ * dimension independent as possible, use of class local typedefs is made, see
+ * below.
+ *
+ * The Triangulation class provides iterator which enable looping over all
+ * cells without knowing the exact representation used to describe them. Their
+ * names are typedefs imported from the Iterators class (thus making them
+ * local types to this class) and are as follows:
+ *
+ * <ul>
+ * <li> <tt>cell_iterator</tt>: loop over all cells used in the Triangulation
+ * <li> <tt>active_cell_iterator</tt>: loop over all active cells
+ * </ul>
+ *
+ * For <tt>dim==1</tt>, these iterators are mapped as follows:
* @code
* typedef line_iterator cell_iterator;
* typedef active_line_iterator active_cell_iterator;
* @endcode
- * while for @p dim==2 we have the additional face iterator:
+ * while for @p dim==2 we have the additional face iterator:
* @code
* typedef quad_iterator cell_iterator;
* typedef active_quad_iterator active_cell_iterator;
* typedef active_line_iterator active_face_iterator;
* @endcode
*
- * By using the cell iterators, you can write code independent of
- * the spatial dimension. The same applies for substructure iterators,
- * where a substructure is defined as a face of a cell. The face of a
- * cell is a vertex in 1D and a line in 2D; however, vertices are
- * handled in a different way and therefore lines have no faces.
- *
- * The Triangulation class offers functions like begin_active() which gives
- * you an iterator to the first active cell. There are quite a lot of functions
- * returning iterators. Take a look at the class doc to get an overview.
- *
- * Usage of these iterators works mostly like with the STL iterators. Some
- * examples taken from the Triangulation source code follow (notice that in the last
- * two examples the template parameter @p spacedim has been omitted, so it takes
- * the default value <code>dim</code>).
- * <ul>
- * <li> <em>Counting the number of cells on a specific level</em>
+ * By using the cell iterators, you can write code independent of the spatial
+ * dimension. The same applies for substructure iterators, where a
+ * substructure is defined as a face of a cell. The face of a cell is a vertex
+ * in 1D and a line in 2D; however, vertices are handled in a different way
+ * and therefore lines have no faces.
+ *
+ * The Triangulation class offers functions like begin_active() which gives
+ * you an iterator to the first active cell. There are quite a lot of
+ * functions returning iterators. Take a look at the class doc to get an
+ * overview.
+ *
+ * Usage of these iterators works mostly like with the STL iterators. Some
+ * examples taken from the Triangulation source code follow (notice that in
+ * the last two examples the template parameter @p spacedim has been omitted,
+ * so it takes the default value <code>dim</code>).
+ * <ul>
+ * <li> <em>Counting the number of cells on a specific level</em>
* @code
* template <int dim, int spacedim>
* int Triangulation<dim, spacedim>::n_cells (const int level) const {
* return n;
* };
* @endcode
- * Another way which uses the STL @p distance function would be to write
+ * Another way which uses the STL @p distance function would be to write
* @code
* template <int dim>
* int Triangulation<dim>::n_cells (const int level) const {
* };
* @endcode
*
- * <li> <em>Refining all cells of a triangulation</em>
+ * <li> <em>Refining all cells of a triangulation</em>
* @code
* template <int dim>
* void Triangulation<dim>::refine_global () {
* execute_coarsening_and_refinement ();
* };
* @endcode
- * </ul>
+ * </ul>
*
*
- * <h3>Usage</h3>
+ * <h3>Usage</h3>
*
- * Usage of a Triangulation is mainly done through the use of iterators.
- * An example probably shows best how to use it:
+ * Usage of a Triangulation is mainly done through the use of iterators. An
+ * example probably shows best how to use it:
* @code
* void main () {
* Triangulation<2> tria;
* @endcode
*
*
- * <h3>Creating a triangulation</h3>
- *
- * There are several possibilities to create a triangulation:
- * <ul>
- * <li> The most common domains, such as hypercubes (i.e. lines, squares,
- * cubes, etc), hyper-balls (circles, balls, ...) and some other, more
- * weird domains such as the L-shape region and higher dimensional
- * generalizations and others, are provided by the GridGenerator
- * class which takes a triangulation and fills it by a division
- * of the required domain.
- *
- * <li> Reading in a triangulation: By using an object of the GridIn
- * class, you can read in fairly general triangulations. See there for
- * more information. The mentioned class uses the interface described
- * directly below to transfer the data into the triangulation.
- *
- * <li> Explicitly creating a triangulation: you can create a triangulation
- * by providing a list of vertices and a list of cells. Each such cell
- * consists of a vector storing the indices of the vertices of this cell
- * in the vertex list. To see how this works, you can take a look at the
- * GridIn<dim>::read_* functions. The appropriate function to be
- * called is create_triangulation().
- *
- * Creating the hierarchical information needed for this
- * library from cells storing only vertex information can be
- * quite a complex task. For example in 2D, we have to create
- * lines between vertices (but only once, though there are two
- * cells which link these two vertices) and we have to create
- * neighborhood information. Grids being read in should
- * therefore not be too large, reading refined grids would be
- * inefficient (although there is technically no problem in
- * reading grids with several 10.000 or 100.000 cells; the
- * library can handle this without much problems). Apart from
- * the performance aspect, refined grids do not lend too well
- * to multigrid algorithms, since solving on the coarsest level
- * is expensive. It is wiser in any case to read in a grid as
- * coarse as possible and then do the needed refinement steps.
- *
- * It is your duty to guarantee that cells have the correct orientation.
- * To guarantee this, in the input vector keeping the cell list, the
- * vertex indices for each cell have to be in a defined order, see the
- * documentation of GeometryInfo<dim>. In one dimension, the first vertex
- * index must refer to that vertex with the lower coordinate value. In 2D
- * and 3D, the corresponding conditions are not easy to verify and no
- * full attempt to do so is made.
- * If you violate this condition, you may end up with matrix entries
- * having the wrong sign (clockwise vertex numbering, which results in
- * a negative area element) of with wrong matrix elements (twisted
- * quadrilaterals, i.e. two vertices interchanged; this results in
- * a wrong area element).
- *
- * There are more subtle conditions which must be imposed upon
- * the vertex numbering within cells. They do not only hold for
- * the data read from an UCD or any other input file, but also
- * for the data passed to create_triangulation().
- * See the documentation for the GridIn class
- * for more details on this, and above all to the
- * GridReordering class that explains many of the
- * problems and an algorithm to reorder cells such that they
- * satisfy the conditions outlined above.
- *
- * <li> Copying a triangulation: when computing on time dependent meshes
- * or when using adaptive refinement, you will often want to create a
- * new triangulation to be the same as another one. This is facilitated
- * by the @p copy_triangulation function.
- *
- * It is guaranteed that vertex, line or cell numbers in the two
- * triangulations are the same and that two iterators walking on the
- * two triangulations visit matching cells if they are incremented in
- * parallel. It may be conceivable to implement a clean-up in the copy
- * operation, which eliminates holes of unused memory, re-joins
- * scattered data and so on. In principle this would be a useful
- * operation but guaranteeing some parallelism in the two triangulations
- * seems more important since usually data will have to be transferred
- * between the grids.
- * </ul>
- *
- * Finally, there is a special function for folks who like bad grids:
- * distort_random(). It moves all the vertices in the
- * grid a bit around by a random value, leaving behind a distorted mesh.
- * Note that you should apply this function to the final mesh, since
- * refinement smoothes the mesh a bit.
- *
- * The function will make sure that vertices on restricted faces (hanging
- * nodes) will end up in the correct place, i.e. in the middle of the two
- * other vertices of the mother line, and the analogue in higher space
- * dimensions (vertices on the boundary are not corrected, so don't distort
- * boundary vertices in more than two space dimension, i.e. in dimensions
- * where boundary vertices can be hanging nodes). Applying the algorithm
- * has another drawback related to the
- * placement of cells, however: the children of a cell will not occupy the
- * same region of the domain as the mother cell does. While this is the
- * usual behavior with cells at the boundary, here you may get into trouble
- * when using multigrid algorithms or when transferring solutions from coarse
- * to fine grids and back. In general, the use of this function is only safe
- * if you only use the most refined level of the triangulation for
- * computations.
- *
- *
- *
- * <h3>Refinement and coarsening of a triangulation</h3>
- *
- * Refinement of a triangulation may be done through several ways. The most
- * low-level way is directly through iterators: let @p i be an iterator to
- * an active cell (i.e. the cell pointed to has no children), then the
- * function call <tt>i->set_refine_flag()</tt> marks the respective cell for
- * refinement. Marking non-active cells results in an error.
- *
- * After all the cells you wanted to mark for refinement, call
- * execute_coarsening_and_refinement() to actually perform
- * the refinement. This function itself first calls the
- * @p prepare_coarsening_and_refinement function to regularize the resulting
- * triangulation: since a face between two adjacent cells may only
- * be subdivided once (i.e. the levels of two adjacent cells may
- * differ by one at most; it is not possible to have a cell refined
- * twice while the neighboring one is not refined), some additional
- * cells are flagged for refinement to smooth the grid. This
- * enlarges the number of resulting cells but makes the grid more
- * regular, thus leading to better approximation properties and,
- * above all, making the handling of data structures and algorithms
- * much much easier. To be honest, this is mostly an algorithmic
- * step than one needed by the finite element method.
- *
- * To coarsen a grid, the same way as above is possible by using
- * <tt>i->set_coarsen_flag</tt> and calling execute_coarsening_and_refinement().
- *
- * The reason for first coarsening, then refining is that the
- * refinement usually adds some additional cells to keep the triangulation
- * regular and thus satisfies all refinement requests, while the coarsening
- * does not delete cells not requested for; therefore the refinement will
- * often revert some effects of coarsening while the opposite is not true.
- * The stated order of coarsening before refinement will thus normally
- * lead to a result closer to the intended one.
- *
- * Marking cells for refinement 'by hand' through iterators is one way to
- * produce a new grid, especially if you know what kind of grid you are
- * looking for, e.g. if you want to have a grid successively refined
- * towards the boundary or always at the center (see the example programs,
- * they do exactly these things). There are more advanced functions,
- * however, which are more suitable for automatic generation of hierarchical
- * grids in the context of a posteriori error estimation and adaptive finite
- * elements. These functions can be found in the GridRefinement class.
- *
- *
- * <h3>Smoothing of a triangulation</h3>
- *
- * Some degradation of approximation properties has been observed
- * for grids which are too unstructured. Therefore,
- * prepare_coarsening_and_refinement() which is automatically called
- * by execute_coarsening_and_refinement() can do some
- * smoothing of the triangulation. Note that mesh smoothing is only
- * done for two or more space dimensions, no smoothing is available
- * at present for one spatial dimension. In the following, let
- * <tt>execute_*</tt> stand for execute_coarsening_and_refinement().
- *
- * For the purpose of smoothing, the
- * Triangulation constructor takes an argument specifying whether a
- * smoothing step shall be performed on the grid each time <tt>execute_*</tt>
- * is called. The default is that such a step not be done, since this results
- * in additional cells being produced, which may not be necessary in all
- * cases. If switched on, calling <tt>execute_*</tt> results in
- * flagging additional cells for refinement to avoid
- * vertices as the ones mentioned. The algorithms for both regularization
- * and smoothing of triangulations are described below in the section on
- * technical issues. The reason why this parameter must be given to the
- * constructor rather than to <tt>execute_*</tt> is that it would result
- * in algorithmic problems if you called <tt>execute_*</tt> once without
- * and once with smoothing, since then in some refinement steps would need
- * to be refined twice.
- *
- * The parameter taken by the constructor is an integer which may be
- * composed bitwise by the constants defined in the enum
- * #MeshSmoothing (see there for the possibilities).
- *
- * @note While it is possible to pass all of the flags in #MeshSmoothing to
- * objects of type parallel::distributed::Triangulation, it is not always
- * possible to honor all of these smoothing options if they would require
- * knowledge of refinement/coarsening flags on cells not locally owned by
- * this processor. As a consequence, for some of these flags, the ultimate
- * number of cells of the parallel triangulation may depend on the number of
- * processors into which it is partitioned.
- *
- *
- * <h3>Material and boundary information</h3>
- *
- * Each cell, face or edge stores information denoting the
- * material or the part of the boundary that an object
- * belongs to. The material of a cell may be used
- * during matrix generation in order to implement different
- * coefficients in different parts of the domain. It is not used by
- * functions of the grid and dof handling libraries.
- *
- * This material_id may be set upon construction of a
- * triangulation (through the CellData data structure), or later
- * through use of cell iterators. For a typical use of this
- * functionality, see the step-28 tutorial
- * program. The functions of the GridGenerator namespace typically
- * set the material ID of all cells to zero. When reading a
- * triangulation, the material id must be specified in the input
- * file (UCD format) or is otherwise set to zero. Material IDs are
- * inherited by child cells from their parent upon mesh refinement.
- *
- * Boundary indicators on lower dimensional objects (these have no
- * material id) indicate the number of a boundary component. These
- * are used for two purposes: First, they specify a boundary
- * curve. When a cell is refined, a function can be used to place
- * new vertices on this curve. See the section on boundary
- * approximation below. Furthermore, the weak formulation of the
- * partial differential equation may have different boundary
- * conditions on different parts of the boundary. The boundary
- * indicator can be used in creating the matrix or the right hand
- * side vector to indicate these different parts of the model (this
- * use is like the material id of cells).
-
- * Boundary indicators may be in the range from zero to
- * numbers::internal_face_boundary_id-1. The value
- * numbers::internal_face_boundary_id is reserved to denote interior lines (in 2D)
- * and interior lines and quads (in 3D), which do not have a
- * boundary indicator. This way, a program can easily
- * determine, whether such an object is at the boundary or not.
- * Material indicators may be in the range from zero to numbers::invalid_material_id-1.
- *
- * Lines in two dimensions and quads in three dimensions inherit their
- * boundary indicator to their children upon refinement. You should therefore
- * make sure that if you have different boundary parts, the different parts
- * are separated by a vertex (in 2D) or a line (in 3D) such that each boundary
- * line or quad has a unique boundary indicator.
- *
- * By default (unless otherwise specified during creation of a
- * triangulation), all parts of the boundary have boundary indicator
- * zero. As a historical wart, this isn't true for 1d meshes, however: For
- * these, leftmost vertices have boundary indicator zero while rightmost
- * vertices have boundary indicator one. In either case, the boundary
- * indicator of a face can be changed using a call of the kind
- * <code>cell-@>face(1)-@>set_boundary_indicator(42);</code>.
- *
- * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
- *
- *
- * <h3>History of a triangulation</h3>
- *
- * It is possible to reconstruct a grid from its refinement history, which
- * can be stored and loaded through the @p save_refine_flags and
- * @p load_refine_flags functions. Normally, the code will look like this:
+ * <h3>Creating a triangulation</h3>
+ *
+ * There are several possibilities to create a triangulation:
+ * <ul>
+ * <li> The most common domains, such as hypercubes (i.e. lines, squares,
+ * cubes, etc), hyper-balls (circles, balls, ...) and some other, more weird
+ * domains such as the L-shape region and higher dimensional generalizations
+ * and others, are provided by the GridGenerator class which takes a
+ * triangulation and fills it by a division of the required domain.
+ *
+ * <li> Reading in a triangulation: By using an object of the GridIn class,
+ * you can read in fairly general triangulations. See there for more
+ * information. The mentioned class uses the interface described directly
+ * below to transfer the data into the triangulation.
+ *
+ * <li> Explicitly creating a triangulation: you can create a triangulation by
+ * providing a list of vertices and a list of cells. Each such cell consists
+ * of a vector storing the indices of the vertices of this cell in the vertex
+ * list. To see how this works, you can take a look at the GridIn<dim>::read_*
+ * functions. The appropriate function to be called is create_triangulation().
+ *
+ * Creating the hierarchical information needed for this library from cells
+ * storing only vertex information can be quite a complex task. For example
+ * in 2D, we have to create lines between vertices (but only once, though
+ * there are two cells which link these two vertices) and we have to create
+ * neighborhood information. Grids being read in should therefore not be too
+ * large, reading refined grids would be inefficient (although there is
+ * technically no problem in reading grids with several 10.000 or 100.000
+ * cells; the library can handle this without much problems). Apart from the
+ * performance aspect, refined grids do not lend too well to multigrid
+ * algorithms, since solving on the coarsest level is expensive. It is wiser
+ * in any case to read in a grid as coarse as possible and then do the needed
+ * refinement steps.
+ *
+ * It is your duty to guarantee that cells have the correct orientation. To
+ * guarantee this, in the input vector keeping the cell list, the vertex
+ * indices for each cell have to be in a defined order, see the documentation
+ * of GeometryInfo<dim>. In one dimension, the first vertex index must refer
+ * to that vertex with the lower coordinate value. In 2D and 3D, the
+ * corresponding conditions are not easy to verify and no full attempt to do
+ * so is made. If you violate this condition, you may end up with matrix
+ * entries having the wrong sign (clockwise vertex numbering, which results in
+ * a negative area element) of with wrong matrix elements (twisted
+ * quadrilaterals, i.e. two vertices interchanged; this results in a wrong
+ * area element).
+ *
+ * There are more subtle conditions which must be imposed upon the vertex
+ * numbering within cells. They do not only hold for the data read from an UCD
+ * or any other input file, but also for the data passed to
+ * create_triangulation(). See the documentation for the GridIn class for more
+ * details on this, and above all to the GridReordering class that explains
+ * many of the problems and an algorithm to reorder cells such that they
+ * satisfy the conditions outlined above.
+ *
+ * <li> Copying a triangulation: when computing on time dependent meshes or
+ * when using adaptive refinement, you will often want to create a new
+ * triangulation to be the same as another one. This is facilitated by the @p
+ * copy_triangulation function.
+ *
+ * It is guaranteed that vertex, line or cell numbers in the two
+ * triangulations are the same and that two iterators walking on the two
+ * triangulations visit matching cells if they are incremented in parallel. It
+ * may be conceivable to implement a clean-up in the copy operation, which
+ * eliminates holes of unused memory, re-joins scattered data and so on. In
+ * principle this would be a useful operation but guaranteeing some
+ * parallelism in the two triangulations seems more important since usually
+ * data will have to be transferred between the grids.
+ * </ul>
+ *
+ * Finally, there is a special function for folks who like bad grids:
+ * distort_random(). It moves all the vertices in the grid a bit around by a
+ * random value, leaving behind a distorted mesh. Note that you should apply
+ * this function to the final mesh, since refinement smoothes the mesh a bit.
+ *
+ * The function will make sure that vertices on restricted faces (hanging
+ * nodes) will end up in the correct place, i.e. in the middle of the two
+ * other vertices of the mother line, and the analogue in higher space
+ * dimensions (vertices on the boundary are not corrected, so don't distort
+ * boundary vertices in more than two space dimension, i.e. in dimensions
+ * where boundary vertices can be hanging nodes). Applying the algorithm has
+ * another drawback related to the placement of cells, however: the children
+ * of a cell will not occupy the same region of the domain as the mother cell
+ * does. While this is the usual behavior with cells at the boundary, here you
+ * may get into trouble when using multigrid algorithms or when transferring
+ * solutions from coarse to fine grids and back. In general, the use of this
+ * function is only safe if you only use the most refined level of the
+ * triangulation for computations.
+ *
+ *
+ *
+ * <h3>Refinement and coarsening of a triangulation</h3>
+ *
+ * Refinement of a triangulation may be done through several ways. The most
+ * low-level way is directly through iterators: let @p i be an iterator to an
+ * active cell (i.e. the cell pointed to has no children), then the function
+ * call <tt>i->set_refine_flag()</tt> marks the respective cell for
+ * refinement. Marking non-active cells results in an error.
+ *
+ * After all the cells you wanted to mark for refinement, call
+ * execute_coarsening_and_refinement() to actually perform the refinement.
+ * This function itself first calls the @p prepare_coarsening_and_refinement
+ * function to regularize the resulting triangulation: since a face between
+ * two adjacent cells may only be subdivided once (i.e. the levels of two
+ * adjacent cells may differ by one at most; it is not possible to have a cell
+ * refined twice while the neighboring one is not refined), some additional
+ * cells are flagged for refinement to smooth the grid. This enlarges the
+ * number of resulting cells but makes the grid more regular, thus leading to
+ * better approximation properties and, above all, making the handling of data
+ * structures and algorithms much much easier. To be honest, this is mostly an
+ * algorithmic step than one needed by the finite element method.
+ *
+ * To coarsen a grid, the same way as above is possible by using
+ * <tt>i->set_coarsen_flag</tt> and calling
+ * execute_coarsening_and_refinement().
+ *
+ * The reason for first coarsening, then refining is that the refinement
+ * usually adds some additional cells to keep the triangulation regular and
+ * thus satisfies all refinement requests, while the coarsening does not
+ * delete cells not requested for; therefore the refinement will often revert
+ * some effects of coarsening while the opposite is not true. The stated order
+ * of coarsening before refinement will thus normally lead to a result closer
+ * to the intended one.
+ *
+ * Marking cells for refinement 'by hand' through iterators is one way to
+ * produce a new grid, especially if you know what kind of grid you are
+ * looking for, e.g. if you want to have a grid successively refined towards
+ * the boundary or always at the center (see the example programs, they do
+ * exactly these things). There are more advanced functions, however, which
+ * are more suitable for automatic generation of hierarchical grids in the
+ * context of a posteriori error estimation and adaptive finite elements.
+ * These functions can be found in the GridRefinement class.
+ *
+ *
+ * <h3>Smoothing of a triangulation</h3>
+ *
+ * Some degradation of approximation properties has been observed for grids
+ * which are too unstructured. Therefore, prepare_coarsening_and_refinement()
+ * which is automatically called by execute_coarsening_and_refinement() can do
+ * some smoothing of the triangulation. Note that mesh smoothing is only done
+ * for two or more space dimensions, no smoothing is available at present for
+ * one spatial dimension. In the following, let <tt>execute_*</tt> stand for
+ * execute_coarsening_and_refinement().
+ *
+ * For the purpose of smoothing, the Triangulation constructor takes an
+ * argument specifying whether a smoothing step shall be performed on the grid
+ * each time <tt>execute_*</tt> is called. The default is that such a step not
+ * be done, since this results in additional cells being produced, which may
+ * not be necessary in all cases. If switched on, calling <tt>execute_*</tt>
+ * results in flagging additional cells for refinement to avoid vertices as
+ * the ones mentioned. The algorithms for both regularization and smoothing of
+ * triangulations are described below in the section on technical issues. The
+ * reason why this parameter must be given to the constructor rather than to
+ * <tt>execute_*</tt> is that it would result in algorithmic problems if you
+ * called <tt>execute_*</tt> once without and once with smoothing, since then
+ * in some refinement steps would need to be refined twice.
+ *
+ * The parameter taken by the constructor is an integer which may be composed
+ * bitwise by the constants defined in the enum #MeshSmoothing (see there for
+ * the possibilities).
+ *
+ * @note While it is possible to pass all of the flags in #MeshSmoothing to
+ * objects of type parallel::distributed::Triangulation, it is not always
+ * possible to honor all of these smoothing options if they would require
+ * knowledge of refinement/coarsening flags on cells not locally owned by this
+ * processor. As a consequence, for some of these flags, the ultimate number
+ * of cells of the parallel triangulation may depend on the number of
+ * processors into which it is partitioned.
+ *
+ *
+ * <h3>Material and boundary information</h3>
+ *
+ * Each cell, face or edge stores information denoting the material or the
+ * part of the boundary that an object belongs to. The material of a cell may
+ * be used during matrix generation in order to implement different
+ * coefficients in different parts of the domain. It is not used by functions
+ * of the grid and dof handling libraries.
+ *
+ * This material_id may be set upon construction of a triangulation (through
+ * the CellData data structure), or later through use of cell iterators. For a
+ * typical use of this functionality, see the step-28 tutorial program. The
+ * functions of the GridGenerator namespace typically set the material ID of
+ * all cells to zero. When reading a triangulation, the material id must be
+ * specified in the input file (UCD format) or is otherwise set to zero.
+ * Material IDs are inherited by child cells from their parent upon mesh
+ * refinement.
+ *
+ * Boundary indicators on lower dimensional objects (these have no material
+ * id) indicate the number of a boundary component. These are used for two
+ * purposes: First, they specify a boundary curve. When a cell is refined, a
+ * function can be used to place new vertices on this curve. See the section
+ * on boundary approximation below. Furthermore, the weak formulation of the
+ * partial differential equation may have different boundary conditions on
+ * different parts of the boundary. The boundary indicator can be used in
+ * creating the matrix or the right hand side vector to indicate these
+ * different parts of the model (this use is like the material id of cells).
+ * Boundary indicators may be in the range from zero to
+ * numbers::internal_face_boundary_id-1. The value
+ * numbers::internal_face_boundary_id is reserved to denote interior lines (in
+ * 2D) and interior lines and quads (in 3D), which do not have a boundary
+ * indicator. This way, a program can easily determine, whether such an object
+ * is at the boundary or not. Material indicators may be in the range from
+ * zero to numbers::invalid_material_id-1.
+ *
+ * Lines in two dimensions and quads in three dimensions inherit their
+ * boundary indicator to their children upon refinement. You should therefore
+ * make sure that if you have different boundary parts, the different parts
+ * are separated by a vertex (in 2D) or a line (in 3D) such that each boundary
+ * line or quad has a unique boundary indicator.
+ *
+ * By default (unless otherwise specified during creation of a triangulation),
+ * all parts of the boundary have boundary indicator zero. As a historical
+ * wart, this isn't true for 1d meshes, however: For these, leftmost vertices
+ * have boundary indicator zero while rightmost vertices have boundary
+ * indicator one. In either case, the boundary indicator of a face can be
+ * changed using a call of the kind
+ * <code>cell-@>face(1)-@>set_boundary_indicator(42);</code>.
+ *
+ * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
+ *
+ *
+ * <h3>History of a triangulation</h3>
+ *
+ * It is possible to reconstruct a grid from its refinement history, which can
+ * be stored and loaded through the @p save_refine_flags and @p
+ * load_refine_flags functions. Normally, the code will look like this:
* @code
* // open output file
* ofstream history("mesh.history");
* };
* @endcode
*
- * If you want to re-create the grid from the stored information, you write:
+ * If you want to re-create the grid from the stored information, you write:
* @code
* // open input file
* ifstream history("mesh.history");
* };
* @endcode
*
- * The same scheme is employed for coarsening and the coarsening flags.
- *
- * You may write other information to the output file between different sets
- * of refinement information, as long as you read it upon re-creation of the
- * grid. You should make sure that the other information in the new
- * triangulation which is to be created from the saved flags, matches that of
- * the old triangulation, for example the smoothing level; if not, the
- * cells actually created from the flags may be other ones, since smoothing
- * adds additional cells, but their number may be depending on the smoothing
- * level.
- *
- * There actually are two sets of <tt>save_*_flags</tt> and <tt>load_*_flags</tt> functions.
- * One takes a stream as argument and reads/writes the information from/to the
- * stream, thus enabling storing flags to files. The other set takes an
- * argument of type <tt>vector<bool></tt>. This enables the user to temporarily store
- * some flags, e.g. if another function needs them, and restore them
- * afterwards.
- *
- *
- * <h3>User flags and data</h3>
- *
- * A triangulation offers one bit per line, quad, etc for user flags.
- * This field can be
- * accessed as all other data using iterators. Normally, this user flag is
- * used if an algorithm walks over all cells and needs information whether
- * another cell, e.g. a neighbor, has already been processed.
- * See @ref GlossUserFlags "the glossary for more information".
- *
- * There is another set of user data, which can be either an
- * <tt>unsigned int</tt> or a <tt>void *</tt>, for
- * each line, quad, etc. You can access these through
- * the functions listed under <tt>User data</tt> in
- * the accessor classes.
- * Again, see @ref GlossUserData "the glossary for more information".
- *
- * The value of these user indices or pointers is @p NULL by default. Note that
- * the pointers are not inherited to children upon
- * refinement. Still, after a remeshing they are available on all
- * cells, where they were set on the previous mesh.
- *
- * The usual warning about the missing type safety of @p void pointers are
- * obviously in place here; responsibility for correctness of types etc
- * lies entirely with the user of the pointer.
- *
- * @note User pointers and user indices are stored in the same
- * place. In order to avoid unwanted conversions, Triangulation
- * checks which one of them is in use and does not allow access to
- * the other one, until clear_user_data() has been called.
- *
- *
- * <h3>Boundary approximation</h3>
- *
- * You can specify a boundary function for each boundary
- * component. If a new vertex is created on a side or face at the
- * boundary, this function is used to compute where it will be
- * placed. The boundary indicator of the face will be used to
- * determine the proper component. See Boundary for the
- * details. Usage with the Triangulation object is then like this
- * (let @p Ball be a class derived from Boundary<tt><2></tt>):
+ * The same scheme is employed for coarsening and the coarsening flags.
+ *
+ * You may write other information to the output file between different sets
+ * of refinement information, as long as you read it upon re-creation of the
+ * grid. You should make sure that the other information in the new
+ * triangulation which is to be created from the saved flags, matches that of
+ * the old triangulation, for example the smoothing level; if not, the cells
+ * actually created from the flags may be other ones, since smoothing adds
+ * additional cells, but their number may be depending on the smoothing level.
+ *
+ * There actually are two sets of <tt>save_*_flags</tt> and
+ * <tt>load_*_flags</tt> functions. One takes a stream as argument and
+ * reads/writes the information from/to the stream, thus enabling storing
+ * flags to files. The other set takes an argument of type
+ * <tt>vector<bool></tt>. This enables the user to temporarily store some
+ * flags, e.g. if another function needs them, and restore them afterwards.
+ *
+ *
+ * <h3>User flags and data</h3>
+ *
+ * A triangulation offers one bit per line, quad, etc for user flags. This
+ * field can be accessed as all other data using iterators. Normally, this
+ * user flag is used if an algorithm walks over all cells and needs
+ * information whether another cell, e.g. a neighbor, has already been
+ * processed. See @ref GlossUserFlags "the glossary for more information".
+ *
+ * There is another set of user data, which can be either an <tt>unsigned
+ * int</tt> or a <tt>void *</tt>, for each line, quad, etc. You can access
+ * these through the functions listed under <tt>User data</tt> in the accessor
+ * classes. Again, see @ref GlossUserData "the glossary for more information".
+ *
+ * The value of these user indices or pointers is @p NULL by default. Note
+ * that the pointers are not inherited to children upon refinement. Still,
+ * after a remeshing they are available on all cells, where they were set on
+ * the previous mesh.
+ *
+ * The usual warning about the missing type safety of @p void pointers are
+ * obviously in place here; responsibility for correctness of types etc lies
+ * entirely with the user of the pointer.
+ *
+ * @note User pointers and user indices are stored in the same place. In order
+ * to avoid unwanted conversions, Triangulation checks which one of them is in
+ * use and does not allow access to the other one, until clear_user_data() has
+ * been called.
+ *
+ *
+ * <h3>Boundary approximation</h3>
+ *
+ * You can specify a boundary function for each boundary component. If a new
+ * vertex is created on a side or face at the boundary, this function is used
+ * to compute where it will be placed. The boundary indicator of the face will
+ * be used to determine the proper component. See Boundary for the details.
+ * Usage with the Triangulation object is then like this (let @p Ball be a
+ * class derived from Boundary<tt><2></tt>):
*
* @code
* void main () {
* };
* @endcode
*
- * You should take note of one caveat: if you have concave
- * boundaries, you must make sure that a new boundary vertex does
- * not lie too much inside the cell which is to be refined. The
- * reason is that the center vertex is placed at the point which is
- * the arithmetic mean of the vertices of the original cell.
- * Therefore if your new boundary vertex is too near the center of
- * the old quadrilateral or hexahedron, the distance to the midpoint
- * vertex will become too small, thus generating distorted
- * cells. This issue is discussed extensively in
- * @ref GlossDistorted "distorted cells".
- *
- *
- * <h3>Getting notice when a triangulation changes</h3>
- *
- * There are cases where one object would like to know whenever a triangulation
- * is being refined, copied, or modified in a number of other ways. This
- * could of course be achieved if, in your user code, you tell every
- * such object whenever you are about to refine the triangulation, but this
- * will get tedious and is error prone. The Triangulation class implements
- * a more elegant way to achieve this: signals.
- *
- * In essence, a signal is an object (a member of the Triangulation class)
- * that another object can connect to. A connection is in essence that
- * the connecting object passes a function object taking a certain number
- * and kind of arguments. Whenever the owner of the signal wants to
- * indicate a certain kind of event, it 'triggers' the signal, which in
- * turn means that all connections of the signal are triggered: in other
- * word, the function objects are executed and can take the action that
- * is necessary.
- *
- * As a simple example, the following code will print something to the
- * output every time the triangulation has just been refined:
+ * You should take note of one caveat: if you have concave boundaries, you
+ * must make sure that a new boundary vertex does not lie too much inside the
+ * cell which is to be refined. The reason is that the center vertex is placed
+ * at the point which is the arithmetic mean of the vertices of the original
+ * cell. Therefore if your new boundary vertex is too near the center of the
+ * old quadrilateral or hexahedron, the distance to the midpoint vertex will
+ * become too small, thus generating distorted cells. This issue is discussed
+ * extensively in @ref GlossDistorted "distorted cells".
+ *
+ *
+ * <h3>Getting notice when a triangulation changes</h3>
+ *
+ * There are cases where one object would like to know whenever a
+ * triangulation is being refined, copied, or modified in a number of other
+ * ways. This could of course be achieved if, in your user code, you tell
+ * every such object whenever you are about to refine the triangulation, but
+ * this will get tedious and is error prone. The Triangulation class
+ * implements a more elegant way to achieve this: signals.
+ *
+ * In essence, a signal is an object (a member of the Triangulation class)
+ * that another object can connect to. A connection is in essence that the
+ * connecting object passes a function object taking a certain number and kind
+ * of arguments. Whenever the owner of the signal wants to indicate a certain
+ * kind of event, it 'triggers' the signal, which in turn means that all
+ * connections of the signal are triggered: in other word, the function
+ * objects are executed and can take the action that is necessary.
+ *
+ * As a simple example, the following code will print something to the output
+ * every time the triangulation has just been refined:
* @code
* void f() {
* std::cout << "Triangulation has been refined." << std::endl;
* triangulation.signals.post_refinement.connect (&f);
* triangulation.refine_global (2);
* @endcode
- * This code will produce output twice, once for each refinement cycle.
- *
- * A more interesting application would be the following, akin to what
- * the FEValues class does. This class stores a pointer to a triangulation
- * and also an iterator to the cell last handled (so that it can compare
- * the current cell with the previous one and, for example, decide that
- * there is no need to re-compute the Jacobian matrix if the new cell
- * is a simple translation of the previous one). However, whenever the
- * triangulation is modified, the iterator to the previously handled
- * cell needs to be invalidated since it now no longer points to any
- * useful cell (or, at the very least, points to something that may not
- * necessarily resemble the cells previously handled). The code would
- * look something like this (the real code has some more error checking
- * and has to handle the case that subsequent cells might actually belong to
- * different triangulation, but that is of no concern to us here):
+ * This code will produce output twice, once for each refinement cycle.
+ *
+ * A more interesting application would be the following, akin to what the
+ * FEValues class does. This class stores a pointer to a triangulation and
+ * also an iterator to the cell last handled (so that it can compare the
+ * current cell with the previous one and, for example, decide that there is
+ * no need to re-compute the Jacobian matrix if the new cell is a simple
+ * translation of the previous one). However, whenever the triangulation is
+ * modified, the iterator to the previously handled cell needs to be
+ * invalidated since it now no longer points to any useful cell (or, at the
+ * very least, points to something that may not necessarily resemble the cells
+ * previously handled). The code would look something like this (the real code
+ * has some more error checking and has to handle the case that subsequent
+ * cells might actually belong to different triangulation, but that is of no
+ * concern to us here):
* @code
* template <int dim>
* class FEValues {
* previous_cell = Triangulation<dim>::active_cell_iterator();
* }
* @endcode
- * Here, whenever the triangulation is refined, it triggers the post-refinement
- * signal which calls the function object attached to it. This function object
- * is the member function <code>FEValues<dim>::invalidate_previous_cell</code>
- * where we have bound the single argument (the <code>this</code> pointer of
- * a member function that otherwise takes no arguments) to the <code>this</code>
- * pointer of the FEValues object. Note how here there is no need for the code
- * that owns the triangulation and the FEValues object to inform the latter if
- * the former is refined. (In practice, the function would want to connect to
- * some of the other signals that the triangulation offers as well, in particular
- * to creation and deletion signals.)
- *
- * The Triangulation class has a variety of signals that indicate different
- * actions by which the triangulation can modify itself and potentially
- * require follow-up action elsewhere:
- * - creation: This signal is triggered whenever the
- * Triangulation::create_triangulation or Triangulation::copy_triangulation
- * is called. This signal is also triggered when loading a
- * triangulation from an archive via Triangulation::load.
- * - pre-refinement: This signal is triggered at the beginning
- * of execution of the Triangulation::execute_coarsening_and_refinement
- * function (which is itself called by other functions such as
- * Triangulation::refine_global). At the time this signal is triggered,
- * the triangulation is still unchanged.
- * - post-refinement: This signal is triggered at the end
- * of execution of the Triangulation::execute_coarsening_and_refinement
- * function when the triangulation has reached its final state
- * - copy: This signal is triggered whenever the triangulation owning
- * the signal is copied by another triangulation using
- * Triangulation::copy_triangulation (i.e. it is triggered on the <i>old</i>
- * triangulation, but the new one is passed as a argument).
- * - clear: This signal is triggered whenever the Triangulation::clear
- * function is called. This signal is also triggered when loading a
- * triangulation from an archive via Triangulation::load as the previous
- * content of the triangulation is first destroyed.
- * - any_change: This is a catch-all signal that is triggered whenever the
- * create, post_refinement, or clear signals are triggered. In effect, it
- * can be used to indicate to an object connected to the signal that the
- * triangulation has been changed, whatever the exact cause of the change.
- *
- *
- * <h3>Serializing (loading or storing) triangulations</h3>
- *
- * Like many other classes in deal.II, the Triangulation class can stream
- * its contents to an archive using BOOST's serialization facilities. The
- * data so stored can later be retrieved again from the archive to restore
- * the contents of this object. This facility is frequently used to save the
- * state of a program to disk for possible later resurrection, often in the
- * context of checkpoint/restart strategies for long running computations or
- * on computers that aren't very reliable (e.g. on very large clusters where
- * individual nodes occasionally fail and then bring down an entire MPI
- * job).
- *
- * For technical reasons, writing and restoring a Triangulation object is
- * not-trivial. The primary reason is that unlike many other objects,
- * triangulations rely on many other objects to which they store pointers or
- * with which they interace; for example, triangulations store pointers to
- * objects describing boundaries and manifolds, and they have signals that
- * store pointers to other objects so they can be notified of changes in the
- * triangulation (see the section on signals in this introduction). As
- * objects that are re-loaded at a later time do not usually end up at the
- * same location in memory as they were when they were saved, dealing with
- * pointers to other objects is difficult.
- *
- * For these reasons, saving a triangulation to an archive does not store
- * all information, but only certain parts. More specifically, the
- * information that is stored is everything that defines the mesh such as
- * vertex locations, vertex indices, how vertices are connected to cells,
- * boundary indicators, subdomain ids, material ids, etc. On the other hand,
- * the following information is not stored:
- * - signals
- * - pointers to boundary objects previously set using
- * Triangulation::set_boundary
- * On the other hand, since these are objects that are usually set in
- * user code, they can typically easily be set again in that part of your
- * code in which you re-load triangulations.
- *
- * In a sense, this approach to serialization means that re-loading a
- * triangulation is more akin to calling the
- * Triangulation::create_triangulation function and filling it with some
- * additional content, as that function also does not touch the signals and
- * boundary objects that belong to this triangulation. In keeping with this
- * analogy, the Triangulation::load function also triggers the same kinds of
- * signal as Triangulation::create_triangulation.
- *
- *
- * <h3>Technical details</h3>
- *
- * <h4>Algorithms for mesh regularization and smoothing upon refinement</h4>
- *
- * We chose an inductive point of view: since upon creation of the
- * triangulation all cells are on the same level, all regularity assumptions
- * regarding the maximum difference in level of cells sharing a common face,
- * edge or vertex hold. Since we use the regularization and smoothing in
- * each step of the mesh history, when coming to the point of refining it
- * further the assumptions also hold.
- *
- * The regularization and smoothing is done in the
- * @p prepare_coarsening_and_refinement function, which is called by
- * @p execute_coarsening_and_refinement at the very beginning. It
- * decides which additional cells to flag for refinement by looking
- * at the old grid and the refinement flags for each cell.
- *
- * <ul>
- * <li> <em>Regularization:</em> The algorithm walks over all cells checking
- * whether the present cell is flagged for refinement and a neighbor of the
- * present cell is refined once less than the present one. If so, flag the
- * neighbor for refinement. Because of the induction above, there may be no
- * neighbor with level two less than the present one.
- *
- * The neighbor thus flagged for refinement may induce more cells which need
- * to be refined. However, such cells which need additional refinement always
- * are on one level lower than the present one, so we can get away with only
- * one sweep over all cells if we do the loop in the reverse way, starting
- * with those on the highest level. This way, we may flag additional cells
- * on lower levels, but if these induce more refinement needed, this is
- * performed later on when we visit them in out backward running loop.
- *
- * <li> <em>Smoothing:</em>
- * <ul>
- * <li> @p limit_level_difference_at_vertices:
- * First a list is set up which stores for each vertex
- * the highest level one of the adjacent cells belongs to. Now, since we did
- * smoothing in the previous refinement steps also, each cell may only have
- * vertices with levels at most one greater than the level of the present
- * cell.
- *
- * However, if we store the level plus one for cells marked for refinement,
- * we may end up with cells which have vertices of level two greater than
- * the cells level. We need to refine this cell also, and need thus also
- * update the levels of its vertices. This itself may lead to cells needing
- * refinement, but these are on lower levels, as above, which is why we
- * may do all kinds of additional flagging in one loop only.
- *
- * <li> @p eliminate_unrefined_islands:
- * For each cell we count the number of neighbors which are refined or
- * flagged for refinement. If this exceeds the number of neighbors
- * which are not refined and not flagged for refinement, then the current
- * cell is flagged for
- * refinement. Since this may lead to cells on the same level which also
- * will need refinement, we will need additional loops of regularization
- * and smoothing over all cells until nothing changes any more.
- *
- * <li> <tt>eliminate_refined_*_islands</tt>:
- * This one does much the same as the above one, but for coarsening. If
- * a cell is flagged for refinement or if all of its children are active
- * and if the number of neighbors which are either active and not flagged
- * for refinement, or not active but all children flagged for coarsening
- * equals the total number of neighbors, then this cell's children
- * are flagged for coarsening or (if this cell was flagged for refinement)
- * the refine flag is cleared.
- *
- * For a description of the distinction between the two versions of the
- * flag see above in the section about mesh smoothing in the general part
- * of this classes description.
- *
- * The same applies as above: several loops may be necessary.
- * </ul>
- * </ul>
- *
- * Regularization and smoothing are a bit complementary in that we check
- * whether we need to set additional refinement flags when being on a cell
- * flagged for refinement (regularization) or on a cell not flagged for
- * refinement. This makes readable programming easier.
- *
- * All the described algorithms apply only for more than one space dimension,
- * since for one dimension no restrictions apply. It may be necessary to
- * apply some smoothing for multigrid algorithms, but this has to be decided
- * upon later.
- *
- *
- * <h3>Warning</h3>
- *
- * It seems impossible to preserve @p constness of a triangulation through
- * iterator usage. Thus, if you declare pointers to a @p const triangulation
- * object, you should be well aware that you might involuntarily alter the
- * data stored in the triangulation.
+ * Here, whenever the triangulation is refined, it triggers the post-
+ * refinement signal which calls the function object attached to it. This
+ * function object is the member function
+ * <code>FEValues<dim>::invalidate_previous_cell</code> where we have bound
+ * the single argument (the <code>this</code> pointer of a member function
+ * that otherwise takes no arguments) to the <code>this</code> pointer of the
+ * FEValues object. Note how here there is no need for the code that owns the
+ * triangulation and the FEValues object to inform the latter if the former is
+ * refined. (In practice, the function would want to connect to some of the
+ * other signals that the triangulation offers as well, in particular to
+ * creation and deletion signals.)
+ *
+ * The Triangulation class has a variety of signals that indicate different
+ * actions by which the triangulation can modify itself and potentially
+ * require follow-up action elsewhere: - creation: This signal is triggered
+ * whenever the Triangulation::create_triangulation or
+ * Triangulation::copy_triangulation is called. This signal is also triggered
+ * when loading a triangulation from an archive via Triangulation::load. -
+ * pre-refinement: This signal is triggered at the beginning of execution of
+ * the Triangulation::execute_coarsening_and_refinement function (which is
+ * itself called by other functions such as Triangulation::refine_global). At
+ * the time this signal is triggered, the triangulation is still unchanged. -
+ * post-refinement: This signal is triggered at the end of execution of the
+ * Triangulation::execute_coarsening_and_refinement function when the
+ * triangulation has reached its final state - copy: This signal is triggered
+ * whenever the triangulation owning the signal is copied by another
+ * triangulation using Triangulation::copy_triangulation (i.e. it is triggered
+ * on the <i>old</i> triangulation, but the new one is passed as a argument).
+ * - clear: This signal is triggered whenever the Triangulation::clear
+ * function is called. This signal is also triggered when loading a
+ * triangulation from an archive via Triangulation::load as the previous
+ * content of the triangulation is first destroyed. - any_change: This is a
+ * catch-all signal that is triggered whenever the create, post_refinement, or
+ * clear signals are triggered. In effect, it can be used to indicate to an
+ * object connected to the signal that the triangulation has been changed,
+ * whatever the exact cause of the change.
+ *
+ *
+ * <h3>Serializing (loading or storing) triangulations</h3>
+ *
+ * Like many other classes in deal.II, the Triangulation class can stream its
+ * contents to an archive using BOOST's serialization facilities. The data so
+ * stored can later be retrieved again from the archive to restore the
+ * contents of this object. This facility is frequently used to save the state
+ * of a program to disk for possible later resurrection, often in the context
+ * of checkpoint/restart strategies for long running computations or on
+ * computers that aren't very reliable (e.g. on very large clusters where
+ * individual nodes occasionally fail and then bring down an entire MPI job).
+ *
+ * For technical reasons, writing and restoring a Triangulation object is not-
+ * trivial. The primary reason is that unlike many other objects,
+ * triangulations rely on many other objects to which they store pointers or
+ * with which they interace; for example, triangulations store pointers to
+ * objects describing boundaries and manifolds, and they have signals that
+ * store pointers to other objects so they can be notified of changes in the
+ * triangulation (see the section on signals in this introduction). As objects
+ * that are re-loaded at a later time do not usually end up at the same
+ * location in memory as they were when they were saved, dealing with pointers
+ * to other objects is difficult.
+ *
+ * For these reasons, saving a triangulation to an archive does not store all
+ * information, but only certain parts. More specifically, the information
+ * that is stored is everything that defines the mesh such as vertex
+ * locations, vertex indices, how vertices are connected to cells, boundary
+ * indicators, subdomain ids, material ids, etc. On the other hand, the
+ * following information is not stored: - signals - pointers to boundary
+ * objects previously set using Triangulation::set_boundary On the other hand,
+ * since these are objects that are usually set in user code, they can
+ * typically easily be set again in that part of your code in which you re-
+ * load triangulations.
+ *
+ * In a sense, this approach to serialization means that re-loading a
+ * triangulation is more akin to calling the
+ * Triangulation::create_triangulation function and filling it with some
+ * additional content, as that function also does not touch the signals and
+ * boundary objects that belong to this triangulation. In keeping with this
+ * analogy, the Triangulation::load function also triggers the same kinds of
+ * signal as Triangulation::create_triangulation.
+ *
+ *
+ * <h3>Technical details</h3>
+ *
+ * <h4>Algorithms for mesh regularization and smoothing upon refinement</h4>
+ *
+ * We chose an inductive point of view: since upon creation of the
+ * triangulation all cells are on the same level, all regularity assumptions
+ * regarding the maximum difference in level of cells sharing a common face,
+ * edge or vertex hold. Since we use the regularization and smoothing in each
+ * step of the mesh history, when coming to the point of refining it further
+ * the assumptions also hold.
+ *
+ * The regularization and smoothing is done in the @p
+ * prepare_coarsening_and_refinement function, which is called by @p
+ * execute_coarsening_and_refinement at the very beginning. It decides which
+ * additional cells to flag for refinement by looking at the old grid and the
+ * refinement flags for each cell.
+ *
+ * <ul>
+ * <li> <em>Regularization:</em> The algorithm walks over all cells checking
+ * whether the present cell is flagged for refinement and a neighbor of the
+ * present cell is refined once less than the present one. If so, flag the
+ * neighbor for refinement. Because of the induction above, there may be no
+ * neighbor with level two less than the present one.
+ *
+ * The neighbor thus flagged for refinement may induce more cells which need
+ * to be refined. However, such cells which need additional refinement always
+ * are on one level lower than the present one, so we can get away with only
+ * one sweep over all cells if we do the loop in the reverse way, starting
+ * with those on the highest level. This way, we may flag additional cells on
+ * lower levels, but if these induce more refinement needed, this is performed
+ * later on when we visit them in out backward running loop.
+ *
+ * <li> <em>Smoothing:</em>
+ * <ul>
+ * <li> @p limit_level_difference_at_vertices: First a list is set up which
+ * stores for each vertex the highest level one of the adjacent cells belongs
+ * to. Now, since we did smoothing in the previous refinement steps also, each
+ * cell may only have vertices with levels at most one greater than the level
+ * of the present cell.
+ *
+ * However, if we store the level plus one for cells marked for refinement, we
+ * may end up with cells which have vertices of level two greater than the
+ * cells level. We need to refine this cell also, and need thus also update
+ * the levels of its vertices. This itself may lead to cells needing
+ * refinement, but these are on lower levels, as above, which is why we may do
+ * all kinds of additional flagging in one loop only.
+ *
+ * <li> @p eliminate_unrefined_islands: For each cell we count the number of
+ * neighbors which are refined or flagged for refinement. If this exceeds the
+ * number of neighbors which are not refined and not flagged for refinement,
+ * then the current cell is flagged for refinement. Since this may lead to
+ * cells on the same level which also will need refinement, we will need
+ * additional loops of regularization and smoothing over all cells until
+ * nothing changes any more.
+ *
+ * <li> <tt>eliminate_refined_*_islands</tt>: This one does much the same as
+ * the above one, but for coarsening. If a cell is flagged for refinement or
+ * if all of its children are active and if the number of neighbors which are
+ * either active and not flagged for refinement, or not active but all
+ * children flagged for coarsening equals the total number of neighbors, then
+ * this cell's children are flagged for coarsening or (if this cell was
+ * flagged for refinement) the refine flag is cleared.
+ *
+ * For a description of the distinction between the two versions of the flag
+ * see above in the section about mesh smoothing in the general part of this
+ * classes description.
+ *
+ * The same applies as above: several loops may be necessary.
+ * </ul>
+ * </ul>
+ *
+ * Regularization and smoothing are a bit complementary in that we check
+ * whether we need to set additional refinement flags when being on a cell
+ * flagged for refinement (regularization) or on a cell not flagged for
+ * refinement. This makes readable programming easier.
+ *
+ * All the described algorithms apply only for more than one space dimension,
+ * since for one dimension no restrictions apply. It may be necessary to apply
+ * some smoothing for multigrid algorithms, but this has to be decided upon
+ * later.
+ *
+ *
+ * <h3>Warning</h3>
+ *
+ * It seems impossible to preserve @p constness of a triangulation through
+ * iterator usage. Thus, if you declare pointers to a @p const triangulation
+ * object, you should be well aware that you might involuntarily alter the
+ * data stored in the triangulation.
*
* @ingroup grid aniso
* @author Wolfgang Bangerth, 1998; Ralf Hartmann, 2005
private:
/**
- * An internal typedef to make
- * the definition of the iterator
- * classes simpler.
+ * An internal typedef to make the definition of the iterator classes
+ * simpler.
*/
typedef dealii::internal::Triangulation::Iterators<dim, spacedim> IteratorSelector;
public:
/**
- * Default manifold object. This is used
- * for those objects for which no
- * boundary description has been explicitly
- * set using set_manifold().
+ * Default manifold object. This is used for those objects for which no
+ * boundary description has been explicitly set using set_manifold().
*/
static const StraightBoundary<dim,spacedim> straight_boundary;
/**
- * Declare some symbolic names
- * for mesh smoothing
- * algorithms. The meaning of
- * these flags is documented in
- * the Triangulation class.
+ * Declare some symbolic names for mesh smoothing algorithms. The meaning of
+ * these flags is documented in the Triangulation class.
*/
enum MeshSmoothing
{
/**
- * No mesh smoothing at all, except that meshes have to remain one-irregular.
+ * No mesh smoothing at all, except that meshes have to remain one-
+ * irregular.
*/
none = 0x0,
/**
- * It can be shown, that degradation of approximation occurs if the
- * triangulation contains vertices which are member of cells with levels
- * differing by more than one. One such example is the following:
+ * It can be shown, that degradation of approximation occurs if the
+ * triangulation contains vertices which are member of cells with levels
+ * differing by more than one. One such example is the following:
*
- * @image html limit_level_difference_at_vertices.png ""
+ * @image html limit_level_difference_at_vertices.png ""
*
- * It would seem that in two space dimensions, the maximum jump in levels
- * between cells sharing a common vertex is two (as in the example
- * above). However, this is not true if more than four cells meet at a
- * vertex. It is not uncommon that a coarse (initial) mesh contains
- * vertices at which six or even eight cells meet, when small features of
- * the domain have to be resolved even on the coarsest mesh. In that case,
- * the maximum difference in levels is three or four, respectively. The
- * problem gets even worse in three space dimensions.
+ * It would seem that in two space dimensions, the maximum jump in levels
+ * between cells sharing a common vertex is two (as in the example above).
+ * However, this is not true if more than four cells meet at a vertex. It
+ * is not uncommon that a coarse (initial) mesh contains vertices at which
+ * six or even eight cells meet, when small features of the domain have to
+ * be resolved even on the coarsest mesh. In that case, the maximum
+ * difference in levels is three or four, respectively. The problem gets
+ * even worse in three space dimensions.
*
- * Looking at an interpolation of the second derivative of the finite
- * element solution (assuming bilinear finite elements), one sees that the
- * numerical solution is almost totally wrong, compared with the true
- * second derivative. Indeed, on regular meshes, there exist sharp
- * estimations that the H<sup>2</sup>-error is only of order one, so we should not be
- * surprised; however, the numerical solution may show a value for the
- * second derivative which may be a factor of ten away from the true
- * value. These problems are located on the small cell adjacent to the
- * center vertex, where cells of non-subsequent levels meet, as well as on
- * the upper and right neighbor of this cell (but with a less degree of
- * deviation from the true value).
+ * Looking at an interpolation of the second derivative of the finite
+ * element solution (assuming bilinear finite elements), one sees that the
+ * numerical solution is almost totally wrong, compared with the true
+ * second derivative. Indeed, on regular meshes, there exist sharp
+ * estimations that the H<sup>2</sup>-error is only of order one, so we
+ * should not be surprised; however, the numerical solution may show a
+ * value for the second derivative which may be a factor of ten away from
+ * the true value. These problems are located on the small cell adjacent
+ * to the center vertex, where cells of non-subsequent levels meet, as
+ * well as on the upper and right neighbor of this cell (but with a less
+ * degree of deviation from the true value).
*
- * If the smoothing indicator given to the constructor contains the bit for
- * #limit_level_difference_at_vertices, situations as the above one are
- * eliminated by also marking the lower left cell for refinement.
+ * If the smoothing indicator given to the constructor contains the bit
+ * for #limit_level_difference_at_vertices, situations as the above one
+ * are eliminated by also marking the lower left cell for refinement.
*
- * In case of anisotropic refinement, the level of a cell is not linked to
- * the refinement of a cell as directly as in case of isotropic
- * refinement. Furthermore, a cell can be strongly refined in one
- * direction and not or at least much less refined in another. Therefore,
- * it is very difficult to decide, which cases should be excluded from the
- * refinement process. As a consequence, when using anisotropic
- * refinement, the #limit_level_difference_at_vertices flag must not be
- * set. On the other hand, the implementation of multigrid methods in
- * deal.II requires that this bit be set.
+ * In case of anisotropic refinement, the level of a cell is not linked to
+ * the refinement of a cell as directly as in case of isotropic
+ * refinement. Furthermore, a cell can be strongly refined in one
+ * direction and not or at least much less refined in another. Therefore,
+ * it is very difficult to decide, which cases should be excluded from the
+ * refinement process. As a consequence, when using anisotropic
+ * refinement, the #limit_level_difference_at_vertices flag must not be
+ * set. On the other hand, the implementation of multigrid methods in
+ * deal.II requires that this bit be set.
*/
limit_level_difference_at_vertices = 0x1,
/**
- * Single cells which are not refined and are surrounded by cells which are
- * refined usually also lead to a sharp decline in approximation properties
- * locally. The reason is that the nodes on the faces between unrefined and
- * refined cells are not real degrees of freedom but carry constraints. The
- * patch without additional degrees of freedom is thus significantly larger
- * then the unrefined cell itself. If in the parameter passed to the
- * constructor the bit for #eliminate_unrefined_islands is set, all cells
- * which are not flagged for refinement but which are surrounded by more
- * refined cells than unrefined cells are flagged for refinement. Cells
- * which are not yet refined but flagged for that are accounted for the
- * number of refined neighbors. Cells on the boundary are not accounted for
- * at all. An unrefined island is, by this definition
- * also a cell which (in 2D) is surrounded by three refined cells and one
- * unrefined one, or one surrounded by two refined cells, one unrefined one
- * and is at the boundary on one side. It is thus not a true island, as the
- * name of the flag may indicate. However, no better name came to mind to
- * the author by now.
- */
+ * Single cells which are not refined and are surrounded by cells which
+ * are refined usually also lead to a sharp decline in approximation
+ * properties locally. The reason is that the nodes on the faces between
+ * unrefined and refined cells are not real degrees of freedom but carry
+ * constraints. The patch without additional degrees of freedom is thus
+ * significantly larger then the unrefined cell itself. If in the
+ * parameter passed to the constructor the bit for
+ * #eliminate_unrefined_islands is set, all cells which are not flagged
+ * for refinement but which are surrounded by more refined cells than
+ * unrefined cells are flagged for refinement. Cells which are not yet
+ * refined but flagged for that are accounted for the number of refined
+ * neighbors. Cells on the boundary are not accounted for at all. An
+ * unrefined island is, by this definition also a cell which (in 2D) is
+ * surrounded by three refined cells and one unrefined one, or one
+ * surrounded by two refined cells, one unrefined one and is at the
+ * boundary on one side. It is thus not a true island, as the name of the
+ * flag may indicate. However, no better name came to mind to the author
+ * by now.
+ */
eliminate_unrefined_islands = 0x2,
/**
- * A triangulation of patch level 1 consists of patches, i.e. of
- * cells that are refined once. This flag ensures that a mesh of
- * patch level 1 is still of patch level 1 after coarsening and
- * refinement. It is, however, the user's responsibility to ensure
- * that the mesh is of patch level 1 before calling
- * Triangulation::execute_coarsening_and_refinement() the first time. The easiest
- * way to achieve this is by calling global_refine(1) straight
- * after creation of the triangulation. It follows that if at
- * least one of the children of a cell is or will be refined than
- * all children need to be refined. If the #patch_level_1 flag
- * is set, than the flags #eliminate_unrefined_islands,
- * #eliminate_refined_inner_islands and
- * #eliminate_refined_boundary_islands will be ignored as they will
- * be fulfilled automatically.
+ * A triangulation of patch level 1 consists of patches, i.e. of cells
+ * that are refined once. This flag ensures that a mesh of patch level 1
+ * is still of patch level 1 after coarsening and refinement. It is,
+ * however, the user's responsibility to ensure that the mesh is of patch
+ * level 1 before calling
+ * Triangulation::execute_coarsening_and_refinement() the first time. The
+ * easiest way to achieve this is by calling global_refine(1) straight
+ * after creation of the triangulation. It follows that if at least one
+ * of the children of a cell is or will be refined than all children need
+ * to be refined. If the #patch_level_1 flag is set, than the flags
+ * #eliminate_unrefined_islands, #eliminate_refined_inner_islands and
+ * #eliminate_refined_boundary_islands will be ignored as they will be
+ * fulfilled automatically.
*/
patch_level_1 = 0x4,
/**
- * Each coarse grid cell is refined at least once, i.e. the
- * triangulation might have active cells on level 1 but not on
- * level 0. This flag ensures that a mesh which has
- * coarsest_level_1 has still coarsest_level_1 after coarsening
- * and refinement. It is, however, the user's responsibility to
- * ensure that the mesh has coarsest_level_1 before calling
- * execute_coarsening_and_refinement the first time. The easiest
- * way to achieve this is by calling global_refine(1) straight
- * after creation of the triangulation. It follows that active
- * cells on level 1 may not be coarsenend.
+ * Each coarse grid cell is refined at least once, i.e. the triangulation
+ * might have active cells on level 1 but not on level 0. This flag
+ * ensures that a mesh which has coarsest_level_1 has still
+ * coarsest_level_1 after coarsening and refinement. It is, however, the
+ * user's responsibility to ensure that the mesh has coarsest_level_1
+ * before calling execute_coarsening_and_refinement the first time. The
+ * easiest way to achieve this is by calling global_refine(1) straight
+ * after creation of the triangulation. It follows that active cells on
+ * level 1 may not be coarsenend.
*
- * The main use of this flag is to ensure that each cell has at least one
- * neighbor in each coordinate direction (i.e. each cell has at least a
- * left or right, and at least an upper or lower neighbor in 2d). This is
- * a necessary precondition for some algorihms that compute finite
- * differences between cells. The DerivativeApproximation class is one of
- * these algorithms that require that a triangulation is coarsest_level_1
- * unless all cells already have at least one neighbor in each coordinate
- * direction on the coarsest level.
+ * The main use of this flag is to ensure that each cell has at least one
+ * neighbor in each coordinate direction (i.e. each cell has at least a
+ * left or right, and at least an upper or lower neighbor in 2d). This is
+ * a necessary precondition for some algorihms that compute finite
+ * differences between cells. The DerivativeApproximation class is one of
+ * these algorithms that require that a triangulation is coarsest_level_1
+ * unless all cells already have at least one neighbor in each coordinate
+ * direction on the coarsest level.
*/
coarsest_level_1 = 0x8,
/**
- * This flag is not included in @p maximum_smoothing. The flag is
- * concerned with the following case: consider the case that an
- * unrefined and a refined cell share a common face and that one
- * of the children of the refined cell along the common face is
- * flagged for further refinement. In that case, the resulting
- * mesh would have more than one hanging node along one or more of
- * the edges of the triangulation, a situation that is not
- * allowed. Consequently, in order to perform the refinement, the
- * coarser of the two original cells is also going to be refined.
+ * This flag is not included in @p maximum_smoothing. The flag is
+ * concerned with the following case: consider the case that an unrefined
+ * and a refined cell share a common face and that one of the children of
+ * the refined cell along the common face is flagged for further
+ * refinement. In that case, the resulting mesh would have more than one
+ * hanging node along one or more of the edges of the triangulation, a
+ * situation that is not allowed. Consequently, in order to perform the
+ * refinement, the coarser of the two original cells is also going to be
+ * refined.
*
- * However, in many cases it is sufficient to refine the coarser
- * of the two original cells in an anisotropic way to avoid the
- * case of multiple hanging vertices on a single edge. Doing only
- * the minimal anisotropic refinement can save cells and degrees
- * of freedom. By specifying this flag, the library can produce
- * these anisotropic refinements.
+ * However, in many cases it is sufficient to refine the coarser of the
+ * two original cells in an anisotropic way to avoid the case of multiple
+ * hanging vertices on a single edge. Doing only the minimal anisotropic
+ * refinement can save cells and degrees of freedom. By specifying this
+ * flag, the library can produce these anisotropic refinements.
*
- * The flag is not included by default since it may lead to
- * anisotropically refined meshes even though no cell has ever
- * been refined anisotropically explicitly by a user command. This
- * surprising fact may lead to programs that do the wrong thing
- * since they are not written for the additional cases that can
- * happen with anisotropic meshes, see the discussion in the
- * introduction to step-30.
+ * The flag is not included by default since it may lead to
+ * anisotropically refined meshes even though no cell has ever been
+ * refined anisotropically explicitly by a user command. This surprising
+ * fact may lead to programs that do the wrong thing since they are not
+ * written for the additional cases that can happen with anisotropic
+ * meshes, see the discussion in the introduction to step-30.
*/
allow_anisotropic_smoothing = 0x10,
/**
- * This algorithm seeks for isolated cells which are refined or flagged
- * for refinement. This definition is unlike that for
- * #eliminate_unrefined_islands, which would mean that an island is
- * defined as a cell which
- * is refined but more of its neighbors are not refined than are refined.
- * For example, in 2D, a cell's refinement would be reverted if at most
- * one of its neighbors is also refined (or refined but flagged for
- * coarsening).
+ * This algorithm seeks for isolated cells which are refined or flagged
+ * for refinement. This definition is unlike that for
+ * #eliminate_unrefined_islands, which would mean that an island is
+ * defined as a cell which is refined but more of its neighbors are not
+ * refined than are refined. For example, in 2D, a cell's refinement would
+ * be reverted if at most one of its neighbors is also refined (or refined
+ * but flagged for coarsening).
*
- * The reason for the change in definition of an island is, that this
- * option would be a bit dangerous, since if you consider a
- * chain of refined cells (e.g. along a kink in the solution), the cells
- * at the two ends would be coarsened, after which the next outermost cells
- * would need to be coarsened. Therefore, only one loop of flagging cells
- * like this could be done to avoid eating up the whole chain of refined
- * cells (`chain reaction'...).
+ * The reason for the change in definition of an island is, that this
+ * option would be a bit dangerous, since if you consider a chain of
+ * refined cells (e.g. along a kink in the solution), the cells at the two
+ * ends would be coarsened, after which the next outermost cells would
+ * need to be coarsened. Therefore, only one loop of flagging cells like
+ * this could be done to avoid eating up the whole chain of refined cells
+ * (`chain reaction'...).
*
- * This algorithm also takes into account cells which are not actually
- * refined but are flagged for refinement. If necessary, it takes away the
- * refinement flag.
+ * This algorithm also takes into account cells which are not actually
+ * refined but are flagged for refinement. If necessary, it takes away the
+ * refinement flag.
*
- * Actually there are two versions of this flag,
- * #eliminate_refined_inner_islands and #eliminate_refined_boundary_islands.
- * There first eliminates islands defined by the definition above which are
- * in the interior of the domain, while the second eliminates only those
- * islands if the cell is at the boundary. The reason for this split of
- * flags is that one often wants to eliminate such islands in the interior
- * while those at the boundary may well be wanted, for example if one
- * refines the mesh according to a criterion associated with a boundary
- * integral or if one has rough boundary data.
+ * Actually there are two versions of this flag,
+ * #eliminate_refined_inner_islands and
+ * #eliminate_refined_boundary_islands. There first eliminates islands
+ * defined by the definition above which are in the interior of the
+ * domain, while the second eliminates only those islands if the cell is
+ * at the boundary. The reason for this split of flags is that one often
+ * wants to eliminate such islands in the interior while those at the
+ * boundary may well be wanted, for example if one refines the mesh
+ * according to a criterion associated with a boundary integral or if one
+ * has rough boundary data.
*/
eliminate_refined_inner_islands = 0x100,
/**
*/
eliminate_refined_boundary_islands = 0x200,
/**
- * This flag prevents the occurrence of unrefined islands. In more detail:
- * It prohibits the coarsening of a cell if 'most of the neighbors' will
- * be refined after the step.
+ * This flag prevents the occurrence of unrefined islands. In more detail:
+ * It prohibits the coarsening of a cell if 'most of the neighbors' will
+ * be refined after the step.
*/
do_not_produce_unrefined_islands = 0x400,
/**
- * This flag sums up all smoothing algorithms which may be performed upon
- * refinement by flagging some more cells for refinement.
+ * This flag sums up all smoothing algorithms which may be performed upon
+ * refinement by flagging some more cells for refinement.
*/
smoothing_on_refinement = (limit_level_difference_at_vertices |
eliminate_unrefined_islands),
/**
- * This flag sums up all smoothing algorithms which may be performed upon
- * coarsening by flagging some more cells for coarsening.
+ * This flag sums up all smoothing algorithms which may be performed upon
+ * coarsening by flagging some more cells for coarsening.
*/
smoothing_on_coarsening = (eliminate_refined_inner_islands |
eliminate_refined_boundary_islands |
do_not_produce_unrefined_islands),
/**
- * This flag includes all the above ones and therefore combines all
- * smoothing algorithms implemented with the exception of
- * anisotropic smoothening.
+ * This flag includes all the above ones and therefore combines all
+ * smoothing algorithms implemented with the exception of anisotropic
+ * smoothening.
*/
maximum_smoothing = 0xffff ^ allow_anisotropic_smoothing
};
/**
- * A typedef that is used to to identify cell iterators. The
- * concept of iterators is discussed at length in the
- * @ref Iterators "iterators documentation module".
+ * A typedef that is used to to identify cell iterators. The concept of
+ * iterators is discussed at length in the @ref Iterators "iterators
+ * documentation module".
*
- * The current typedef identifies cells in a triangulation. The
- * TriaIterator class works like a pointer that when you
- * dereference it yields an object of type CellAccessor.
- * CellAccessor is a class that identifies properties that
- * are specific to cells in a triangulation, but it is derived
- * (and consequently inherits) from TriaAccessor that describes
- * what you can ask of more general objects (lines, faces, as
- * well as cells) in a triangulation.
+ * The current typedef identifies cells in a triangulation. The TriaIterator
+ * class works like a pointer that when you dereference it yields an object
+ * of type CellAccessor. CellAccessor is a class that identifies properties
+ * that are specific to cells in a triangulation, but it is derived (and
+ * consequently inherits) from TriaAccessor that describes what you can ask
+ * of more general objects (lines, faces, as well as cells) in a
+ * triangulation.
*
* @ingroup Iterators
*/
typedef TriaIterator <CellAccessor<dim,spacedim> > cell_iterator;
/**
- * A typedef that is used to to identify
- * @ref GlossActive "active cell iterators". The
- * concept of iterators is discussed at length in the
- * @ref Iterators "iterators documentation module".
+ * A typedef that is used to to identify @ref GlossActive "active cell
+ * iterators". The concept of iterators is discussed at length in the @ref
+ * Iterators "iterators documentation module".
*
* The current typedef identifies active cells in a triangulation. The
- * TriaActiveIterator class works like a pointer to active objects that when you
- * dereference it yields an object of type CellAccessor.
- * CellAccessor is a class that identifies properties that
- * are specific to cells in a triangulation, but it is derived
- * (and consequently inherits) from TriaAccessor that describes
- * what you can ask of more general objects (lines, faces, as
- * well as cells) in a triangulation.
+ * TriaActiveIterator class works like a pointer to active objects that when
+ * you dereference it yields an object of type CellAccessor. CellAccessor is
+ * a class that identifies properties that are specific to cells in a
+ * triangulation, but it is derived (and consequently inherits) from
+ * TriaAccessor that describes what you can ask of more general objects
+ * (lines, faces, as well as cells) in a triangulation.
*
* @ingroup Iterators
*/
typedef typename IteratorSelector::active_hex_iterator active_hex_iterator;
/**
- * Base class for refinement listeners.
- * Other classes, which need to be
- * informed about refinements of the
- * Triangulation,
- * can be derived from
- * RefinementListener.
+ * Base class for refinement listeners. Other classes, which need to be
+ * informed about refinements of the Triangulation, can be derived from
+ * RefinementListener.
*
- * @note The use of this class has been
- * superseded by the signals mechanism.
- * See the general documentation of the
- * Triangulation class for more information.
+ * @note The use of this class has been superseded by the signals mechanism.
+ * See the general documentation of the Triangulation class for more
+ * information.
*
* @deprecated
*/
{
public:
/**
- * Destructor. Does nothing, but is
- * declared virtual because this
- * class also has virtual functions.
+ * Destructor. Does nothing, but is declared virtual because this class
+ * also has virtual functions.
*
- * @note The use of this class has been
- * superseded by the signals mechanism.
- * See the general documentation of the
- * Triangulation class for more information.
+ * @note The use of this class has been superseded by the signals
+ * mechanism. See the general documentation of the Triangulation class for
+ * more information.
*
* @deprecated
*/
virtual ~RefinementListener ();
/**
- * Before refinement is actually
- * performed, the triangulation class
- * calls this method on all objects
- * derived from this class and
- * registered with the triangulation.
+ * Before refinement is actually performed, the triangulation class calls
+ * this method on all objects derived from this class and registered with
+ * the triangulation.
*
- * @note The use of this class has been
- * superseded by the signals mechanism.
- * See the general documentation of the
- * Triangulation class for more information.
+ * @note The use of this class has been superseded by the signals
+ * mechanism. See the general documentation of the Triangulation class for
+ * more information.
*
* @deprecated
*/
pre_refinement_notification (const Triangulation<dim, spacedim> &tria);
/**
- * After refinement is actually
- * performed, the triangulation class
- * calls this method on all objects
- * derived from this class and
- * registered with the triangulation.
+ * After refinement is actually performed, the triangulation class calls
+ * this method on all objects derived from this class and registered with
+ * the triangulation.
*
- * @note The use of this class has been
- * superseded by the signals mechanism.
- * See the general documentation of the
- * Triangulation class for more information.
+ * @note The use of this class has been superseded by the signals
+ * mechanism. See the general documentation of the Triangulation class for
+ * more information.
*
* @deprecated
*/
post_refinement_notification (const Triangulation<dim, spacedim> &tria);
/**
- * At the end of a call to
- * copy_triangulation() the
- * Triangulation class calls this
- * method on all objects derived from
- * this class and registered with the
- * original Triangulation @p old_tria
- * so that they might subscribe to the
- * copied one @p new_tria as well, if
- * that is desired. By default this
- * method does nothing, a different
- * behavior has to be implemented in
- * derived classes.
+ * At the end of a call to copy_triangulation() the Triangulation class
+ * calls this method on all objects derived from this class and registered
+ * with the original Triangulation @p old_tria so that they might
+ * subscribe to the copied one @p new_tria as well, if that is desired. By
+ * default this method does nothing, a different behavior has to be
+ * implemented in derived classes.
*
- * @note The use of this class has been
- * superseded by the signals mechanism.
- * See the general documentation of the
- * Triangulation class for more information.
+ * @note The use of this class has been superseded by the signals
+ * mechanism. See the general documentation of the Triangulation class for
+ * more information.
*
* @deprecated
*/
const Triangulation<dim, spacedim> &new_tria);
/**
- * At the end of a call to
- * create_triangulation() the
- * Triangulation class calls this
- * method on all objects derived from
- * this class and registered with the
- * current Triangulation object. By
- * default this method does nothing,
- * a different behavior has to be
- * implemented in derived classes.
+ * At the end of a call to create_triangulation() the Triangulation class
+ * calls this method on all objects derived from this class and registered
+ * with the current Triangulation object. By default this method does
+ * nothing, a different behavior has to be implemented in derived classes.
*
- * @note The use of this class has been
- * superseded by the signals mechanism.
- * See the general documentation of the
- * Triangulation class for more information.
+ * @note The use of this class has been superseded by the signals
+ * mechanism. See the general documentation of the Triangulation class for
+ * more information.
*
* @deprecated
*/
};
/**
- * A structure that is used as an
- * exception object by the
- * create_triangulation() function to
- * indicate which cells among the coarse
- * mesh cells are inverted or severely
- * distorted (see the entry on
- * @ref GlossDistorted "distorted cells"
- * in the glossary).
- *
- * Objects of this kind are
- * thrown by the
- * create_triangulation() and
- * execute_coarsening_and_refinement()
- * functions, and they can be
- * caught in user code if this
- * condition is to be
- * ignored. Note, however, that
- * such exceptions are only
- * produced if the necessity for
- * this check was indicated when
- * calling the constructor of the
- * Triangulation class.
- *
- * A cell is called
- * <i>deformed</i> if the
- * determinant of the Jacobian of
- * the mapping from reference
- * cell to real cell is negative
- * at least at one vertex. This
- * computation is done using the
- * GeometryInfo::jacobian_determinants_at_vertices
- * function.
+ * A structure that is used as an exception object by the
+ * create_triangulation() function to indicate which cells among the coarse
+ * mesh cells are inverted or severely distorted (see the entry on @ref
+ * GlossDistorted "distorted cells" in the glossary).
+ *
+ * Objects of this kind are thrown by the create_triangulation() and
+ * execute_coarsening_and_refinement() functions, and they can be caught in
+ * user code if this condition is to be ignored. Note, however, that such
+ * exceptions are only produced if the necessity for this check was
+ * indicated when calling the constructor of the Triangulation class.
+ *
+ * A cell is called <i>deformed</i> if the determinant of the Jacobian of
+ * the mapping from reference cell to real cell is negative at least at one
+ * vertex. This computation is done using the
+ * GeometryInfo::jacobian_determinants_at_vertices function.
*/
struct DistortedCellList : public dealii::ExceptionBase
{
/**
- * Destructor. Empty, but needed
- * for the sake of exception
- * specification, since the base
- * class has this exception
- * specification and the
- * automatically generated
- * destructor would have a
- * different one due to member
- * objects.
+ * Destructor. Empty, but needed for the sake of exception specification,
+ * since the base class has this exception specification and the
+ * automatically generated destructor would have a different one due to
+ * member objects.
*/
virtual ~DistortedCellList () throw();
/**
- * A list of those cells
- * among the coarse mesh
- * cells that are deformed or
- * whose children are
- * deformed.
+ * A list of those cells among the coarse mesh cells that are deformed or
+ * whose children are deformed.
*/
std::list<typename Triangulation<dim,spacedim>::cell_iterator>
distorted_cells;
/**
- * Make the dimension available
- * in function templates.
+ * Make the dimension available in function templates.
*/
static const unsigned int dimension = dim;
/**
- * Make the space-dimension available
- * in function templates.
+ * Make the space-dimension available in function templates.
*/
static const unsigned int space_dimension = spacedim;
/**
- * Create an empty
- * triangulation. Do not create
- * any cells.
+ * Create an empty triangulation. Do not create any cells.
*
- * @param smooth_grid Determines
- * the level of smoothness of the
- * mesh size function that should
- * be enforced upon mesh
- * refinement.
+ * @param smooth_grid Determines the level of smoothness of the mesh size
+ * function that should be enforced upon mesh refinement.
*
- * @param
- * check_for_distorted_cells
- * Determines whether the
- * triangulation should check
- * whether any of the cells that
- * are created by
- * create_triangulation() or
- * execute_coarsening_and_refinement()
- * are distorted (see
- * @ref GlossDistorted "distorted cells").
- * If set, these two
- * functions may throw an
- * exception if they encounter
- * distorted cells.
+ * @param check_for_distorted_cells Determines whether the triangulation
+ * should check whether any of the cells that are created by
+ * create_triangulation() or execute_coarsening_and_refinement() are
+ * distorted (see @ref GlossDistorted "distorted cells"). If set, these two
+ * functions may throw an exception if they encounter distorted cells.
*/
Triangulation (const MeshSmoothing smooth_grid = none,
const bool check_for_distorted_cells = false);
/**
- * Copy constructor.
- *
- * You should really use the @p
- * copy_triangulation function,
- * so we declare this function
- * but let it throw an internal
- * error. The reason for this is
- * that we may want to use
- * triangulation objects in
- * collections. However, C++
- * containers require that the
- * objects stored in them are
- * copyable, so we need to
- * provide a copy
- * constructor. On the other
- * hand, copying triangulations
- * is so expensive that we do
- * not want such objects copied
- * by accident, for example in
- * compiler-generated temporary
- * objects. By defining a copy
- * constructor but throwing an
- * error, we satisfy the formal
- * requirements of containers,
- * but at the same time disallow
- * actual copies. Finally,
- * through the exception, one
- * easily finds the places where
- * code has to be changed to
- * avoid copies.
+ * Copy constructor.
+ *
+ * You should really use the @p copy_triangulation function, so we declare
+ * this function but let it throw an internal error. The reason for this is
+ * that we may want to use triangulation objects in collections. However,
+ * C++ containers require that the objects stored in them are copyable, so
+ * we need to provide a copy constructor. On the other hand, copying
+ * triangulations is so expensive that we do not want such objects copied by
+ * accident, for example in compiler-generated temporary objects. By
+ * defining a copy constructor but throwing an error, we satisfy the formal
+ * requirements of containers, but at the same time disallow actual copies.
+ * Finally, through the exception, one easily finds the places where code
+ * has to be changed to avoid copies.
*/
Triangulation (const Triangulation<dim, spacedim> &t);
/**
- * Delete the object and all levels of
- * the hierarchy.
+ * Delete the object and all levels of the hierarchy.
*/
virtual ~Triangulation ();
/**
- * Reset this triangulation into a
- * virgin state by deleting all data.
+ * Reset this triangulation into a virgin state by deleting all data.
*
- * Note that this operation is only
- * allowed if no subscriptions to this
- * object exist any more, such as
- * DoFHandler objects using it.
+ * Note that this operation is only allowed if no subscriptions to this
+ * object exist any more, such as DoFHandler objects using it.
*/
virtual void clear ();
/**
- * Sets the mesh smoothing to @p
- * mesh_smoothing. This overrides
- * the MeshSmoothing given to the
- * constructor. It is allowed to
- * call this function only if
- * the triangulation is empty.
+ * Sets the mesh smoothing to @p mesh_smoothing. This overrides the
+ * MeshSmoothing given to the constructor. It is allowed to call this
+ * function only if the triangulation is empty.
*/
virtual void set_mesh_smoothing (const MeshSmoothing mesh_smoothing);
/**
- * If @p dim==spacedim, assign a boundary object to a certain part
- * of the boundary of a the triangulation. If a face with boundary
- * number @p number is refined, this object is used to find the
- * location of new vertices on the boundary (see the results section
- * of step-49 for a more in-depth discussion of this, with
- * examples). It is also used for non-linear (i.e.: non-Q1)
- * transformations of cells to the unit cell in shape function
- * calculations.
- *
- * If @p dim!=spacedim the boundary object is in fact the exact
- * manifold that the triangulation is approximating (for example a
- * circle approximated by a polygon triangulation). As above, the
- * refinement is made in such a way that the new points are located
- * on the exact manifold.
- *
- * Numbers of boundary objects correspond to material numbers of
- * faces at the boundary, for instance the material id in a UCD
- * input file. They are not necessarily consecutive but must be in
- * the range 0-(types::boundary_id-1). Material IDs on boundaries
- * are also called boundary indicators and are accessed with
- * accessor functions of that name.
+ * If @p dim==spacedim, assign a boundary object to a certain part of the
+ * boundary of a the triangulation. If a face with boundary number @p number
+ * is refined, this object is used to find the location of new vertices on
+ * the boundary (see the results section of step-49 for a more in-depth
+ * discussion of this, with examples). It is also used for non-linear
+ * (i.e.: non-Q1) transformations of cells to the unit cell in shape
+ * function calculations.
+ *
+ * If @p dim!=spacedim the boundary object is in fact the exact manifold
+ * that the triangulation is approximating (for example a circle
+ * approximated by a polygon triangulation). As above, the refinement is
+ * made in such a way that the new points are located on the exact manifold.
+ *
+ * Numbers of boundary objects correspond to material numbers of faces at
+ * the boundary, for instance the material id in a UCD input file. They are
+ * not necessarily consecutive but must be in the range
+ * 0-(types::boundary_id-1). Material IDs on boundaries are also called
+ * boundary indicators and are accessed with accessor functions of that
+ * name.
*
* The @p boundary_object is not copied and MUST persist until the
* triangulation is destroyed. This is also true for triangulations
* generated from this one by @p copy_triangulation.
*
- * It is possible to remove or replace the boundary object during
- * the lifetime of a non-empty triangulation. Usually, this is done
- * before the first refinement and is dangerous afterwards. Removal
- * of a boundary object is done by <tt>set_boundary(number)</tt>,
- * i.e. the function of same name but only one argument. This
- * operation then replaces the boundary object given before by a
- * straight boundary approximation.
+ * It is possible to remove or replace the boundary object during the
+ * lifetime of a non-empty triangulation. Usually, this is done before the
+ * first refinement and is dangerous afterwards. Removal of a boundary
+ * object is done by <tt>set_boundary(number)</tt>, i.e. the function of
+ * same name but only one argument. This operation then replaces the
+ * boundary object given before by a straight boundary approximation.
*
* @ingroup boundary
*
/**
- * Reset those parts of the boundary with the given number to use a
- * straight boundary approximation. This is the default state of a
- * triangulation, and undoes assignment of a different boundary
- * object by the function of same name and two arguments.
+ * Reset those parts of the boundary with the given number to use a straight
+ * boundary approximation. This is the default state of a triangulation, and
+ * undoes assignment of a different boundary object by the function of same
+ * name and two arguments.
*
* @ingroup boundary
*
void set_boundary (const types::manifold_id number);
/**
- * Assign a manifold object to a certain part of the the
- * triangulation. If an object with manfifold number @p number is
- * refined, this object is used to find the location of new vertices
- * (see the results section of step-49 for a more in-depth
- * discussion of this, with examples). It is also used for
- * non-linear (i.e.: non-Q1) transformations of cells to the unit
- * cell in shape function calculations.
+ * Assign a manifold object to a certain part of the the triangulation. If
+ * an object with manfifold number @p number is refined, this object is used
+ * to find the location of new vertices (see the results section of step-49
+ * for a more in-depth discussion of this, with examples). It is also used
+ * for non-linear (i.e.: non-Q1) transformations of cells to the unit cell
+ * in shape function calculations.
*
* The @p manifold_object is not copied and MUST persist until the
* triangulation is destroyed. This is also true for triangulations
* generated from this one by @p copy_triangulation.
*
- * It is possible to remove or replace the boundary object during
- * the lifetime of a non-empty triangulation. Usually, this is done
- * before the first refinement and is dangerous afterwards. Removal
- * of a manifold object is done by <tt>set_manifold(number)</tt>,
- * i.e. the function of same name but only one argument. This
- * operation then replaces the manifold object given before by a
- * straight manifold approximation.
+ * It is possible to remove or replace the boundary object during the
+ * lifetime of a non-empty triangulation. Usually, this is done before the
+ * first refinement and is dangerous afterwards. Removal of a manifold
+ * object is done by <tt>set_manifold(number)</tt>, i.e. the function of
+ * same name but only one argument. This operation then replaces the
+ * manifold object given before by a straight manifold approximation.
*
* @ingroup manifold
*
/**
- * Reset those parts of the triangulation with the given manifold_id
- * to use a FlatManifold object. This is the default state of a
- * triangulation, and undoes assignment of a different Manifold
- * object by the function of same name and two arguments.
+ * Reset those parts of the triangulation with the given manifold_id to use
+ * a FlatManifold object. This is the default state of a triangulation, and
+ * undoes assignment of a different Manifold object by the function of same
+ * name and two arguments.
*
* @ingroup manifold
*
const Manifold<dim,spacedim> &get_manifold (const types::manifold_id number) const;
/**
- * Returns a vector containing all boundary indicators assigned to
- * boundary faces of this Triangulation object. Note, that each
- * boundary indicator is reported only once. The size of the return
- * vector will represent the number of different indicators (which
- * is greater or equal one).
+ * Returns a vector containing all boundary indicators assigned to boundary
+ * faces of this Triangulation object. Note, that each boundary indicator is
+ * reported only once. The size of the return vector will represent the
+ * number of different indicators (which is greater or equal one).
*
* @ingroup boundary
*
std::vector<types::boundary_id> get_boundary_indicators() const;
/**
- * Returns a vector containing all manifold indicators assigned to
- * the objects of this Triangulation. Note, that each manifold
- * indicator is reported only once. The size of the return vector
- * will represent the number of different indicators (which is
- * greater or equal one).
+ * Returns a vector containing all manifold indicators assigned to the
+ * objects of this Triangulation. Note, that each manifold indicator is
+ * reported only once. The size of the return vector will represent the
+ * number of different indicators (which is greater or equal one).
*
* @ingroup manifold
*
std::vector<types::manifold_id> get_manifold_ids() const;
/**
- * Copy a triangulation. This operation is not cheap, so you should
- * be careful with using this. We do not implement this function as
- * a copy constructor, since it makes it easier to maintain
- * collections of triangulations if you can assign them values
- * later on.
+ * Copy a triangulation. This operation is not cheap, so you should be
+ * careful with using this. We do not implement this function as a copy
+ * constructor, since it makes it easier to maintain collections of
+ * triangulations if you can assign them values later on.
*
- * Keep in mind that this function also copies the pointer to the
- * boundary descriptor previously set by the @p set_boundary
- * function and to the Manifold object previously set by the
- * set_manifold() function. You must therefore also guarantee that
- * the boundary and manifold objects have a lifetime at least as
- * long as the copied triangulation.
+ * Keep in mind that this function also copies the pointer to the boundary
+ * descriptor previously set by the @p set_boundary function and to the
+ * Manifold object previously set by the set_manifold() function. You must
+ * therefore also guarantee that the boundary and manifold objects have a
+ * lifetime at least as long as the copied triangulation.
*
- * This triangulation must be empty beforehand.
+ * This triangulation must be empty beforehand.
*
- * The function is made @p virtual since some derived classes might
- * want to disable or extend the functionality of this function.
+ * The function is made @p virtual since some derived classes might want to
+ * disable or extend the functionality of this function.
*
- * @note Calling this function triggers the 'copy' signal on
- * old_tria, i.e. the triangulation being copied <i>from</i>. It
- * also triggers the 'create' signal of the current triangulation.
- * See the section on signals in the general documentation for more
- * information.
+ * @note Calling this function triggers the 'copy' signal on old_tria, i.e.
+ * the triangulation being copied <i>from</i>. It also triggers the
+ * 'create' signal of the current triangulation. See the section on signals
+ * in the general documentation for more information.
*
- * @note The list of connections to signals is not copied from the
- * old to the new triangulation since these connections were
- * established to monitor how the old triangulation changes, not
- * how any triangulation it may be copied to changes.
+ * @note The list of connections to signals is not copied from the old to
+ * the new triangulation since these connections were established to monitor
+ * how the old triangulation changes, not how any triangulation it may be
+ * copied to changes.
*/
virtual void copy_triangulation (const Triangulation<dim, spacedim> &old_tria);
/**
- * Create a triangulation from a list of vertices and a list of
- * cells, each of the latter being a list of <tt>1<<dim</tt> vertex
- * indices. The triangulation must be empty upon calling this
- * function and the cell list should be useful (connected domain,
- * etc.).
- *
- * Material data for the cells is given within the @p cells array,
- * while boundary information is given in the @p subcelldata field.
- *
- * The numbering of vertices within the @p cells array is subject to
- * some constraints; see the general class documentation for this.
- *
- * For conditions when this function can generate a valid
- * triangulation, see the documentation of this class, and the
- * GridIn and GridReordering class.
- *
- * If the <code>check_for_distorted_cells</code> flag was specified
- * upon creation of this object, at the very end of its operation,
- * the current function walks over all cells and verifies that none
- * of the cells is deformed (see the entry on @ref GlossDistorted
- * "distorted cells" in the glossary), where we call a cell deformed
- * if the determinant of the Jacobian of the mapping from reference
- * cell to real cell is negative at least at one of the vertices
- * (this computation is done using the
- * GeometryInfo::jacobian_determinants_at_vertices function). If
- * there are deformed cells, this function throws an exception of
- * kind DistortedCellList. Since this happens after all data
- * structures have been set up, you can catch and ignore this
- * exception if you know what you do -- for example, it may be that
- * the determinant is zero (indicating that you have collapsed edges
- * in a cell) but that this is ok because you didn't intend to
- * integrate on this cell anyway. On the other hand, deformed cells
- * are often a sign of a mesh that is too coarse to resolve the
- * geometry of the domain, and in this case ignoring the exception
- * is probably unwise.
+ * Create a triangulation from a list of vertices and a list of cells, each
+ * of the latter being a list of <tt>1<<dim</tt> vertex indices. The
+ * triangulation must be empty upon calling this function and the cell list
+ * should be useful (connected domain, etc.).
+ *
+ * Material data for the cells is given within the @p cells array, while
+ * boundary information is given in the @p subcelldata field.
+ *
+ * The numbering of vertices within the @p cells array is subject to some
+ * constraints; see the general class documentation for this.
+ *
+ * For conditions when this function can generate a valid triangulation, see
+ * the documentation of this class, and the GridIn and GridReordering class.
+ *
+ * If the <code>check_for_distorted_cells</code> flag was specified upon
+ * creation of this object, at the very end of its operation, the current
+ * function walks over all cells and verifies that none of the cells is
+ * deformed (see the entry on @ref GlossDistorted "distorted cells" in the
+ * glossary), where we call a cell deformed if the determinant of the
+ * Jacobian of the mapping from reference cell to real cell is negative at
+ * least at one of the vertices (this computation is done using the
+ * GeometryInfo::jacobian_determinants_at_vertices function). If there are
+ * deformed cells, this function throws an exception of kind
+ * DistortedCellList. Since this happens after all data structures have been
+ * set up, you can catch and ignore this exception if you know what you do
+ * -- for example, it may be that the determinant is zero (indicating that
+ * you have collapsed edges in a cell) but that this is ok because you
+ * didn't intend to integrate on this cell anyway. On the other hand,
+ * deformed cells are often a sign of a mesh that is too coarse to resolve
+ * the geometry of the domain, and in this case ignoring the exception is
+ * probably unwise.
*
* @note This function is used in step-14 .
*
- * @note This function triggers the create signal after doing its
- * work. See the section on signals in the general documentation of
- * this class.
+ * @note This function triggers the create signal after doing its work. See
+ * the section on signals in the general documentation of this class.
*
- * @note The check for distorted cells is only done if
- * dim==spacedim, as otherwise cells can legitimately be twisted if
- * the manifold they describe is twisted.
+ * @note The check for distorted cells is only done if dim==spacedim, as
+ * otherwise cells can legitimately be twisted if the manifold they describe
+ * is twisted.
*/
virtual void create_triangulation (const std::vector<Point<spacedim> > &vertices,
const std::vector<CellData<dim> > &cells,
const SubCellData &subcelldata);
/**
- * For backward compatibility, only. This function takes the cell
- * data in the ordering as requested by deal.II versions up to 5.2,
- * converts it to the new (lexicographic) ordering and calls
- * create_triangulation().
+ * For backward compatibility, only. This function takes the cell data in
+ * the ordering as requested by deal.II versions up to 5.2, converts it to
+ * the new (lexicographic) ordering and calls create_triangulation().
*
- * @note This function internally calls create_triangulation and
- * therefore can throw the same exception as the other function.
+ * @note This function internally calls create_triangulation and therefore
+ * can throw the same exception as the other function.
*/
virtual void create_triangulation_compatibility (
const std::vector<Point<spacedim> > &vertices,
const SubCellData &subcelldata);
/**
- * Revert or flip the direction_flags of a dim<spacedim
- * triangulation, see @ref GlossDirectionFlag .
+ * Revert or flip the direction_flags of a dim<spacedim triangulation, see
+ * @ref GlossDirectionFlag .
*
* This function throws an exception if dim equals spacedim.
- */
+ */
void flip_all_direction_flags();
/**
- * Distort the grid by randomly moving around all the vertices of
- * the grid. The direction of moving is random, while the length of
- * the shift vector has a value of @p factor times the minimal
- * length of the active lines adjacent to this vertex. Note that @p
- * factor should obviously be well below <tt>0.5</tt>.
+ * Distort the grid by randomly moving around all the vertices of the grid.
+ * The direction of moving is random, while the length of the shift vector
+ * has a value of @p factor times the minimal length of the active lines
+ * adjacent to this vertex. Note that @p factor should obviously be well
+ * below <tt>0.5</tt>.
*
- * If @p keep_boundary is set to @p true (which is the default),
- * then boundary vertices are not moved.
+ * If @p keep_boundary is set to @p true (which is the default), then
+ * boundary vertices are not moved.
*
* @deprecated Use GridTools::distort_random instead.
*/
*/
/**
- * Flag all active cells for refinement. This will refine all
- * cells of all levels which are not already refined (i.e. only
- * cells are refined which do not yet have children). The cells are
- * only flagged, not refined, thus you have the chance to save the
- * refinement flags.
+ * Flag all active cells for refinement. This will refine all cells of all
+ * levels which are not already refined (i.e. only cells are refined which
+ * do not yet have children). The cells are only flagged, not refined, thus
+ * you have the chance to save the refinement flags.
*/
void set_all_refine_flags ();
* Refine all cells @p times times, by alternatingly calling
* set_all_refine_flags and execute_coarsening_and_refinement.
*
- * The latter function may throw an exception if it creates cells
- * that are distorted (see its documentation for an
- * explanation). This exception will be propagated through this
- * function if that happens, and you may not get the actual number
- * of refinement steps in that case.
+ * The latter function may throw an exception if it creates cells that are
+ * distorted (see its documentation for an explanation). This exception will
+ * be propagated through this function if that happens, and you may not get
+ * the actual number of refinement steps in that case.
*
- * @note This function triggers the pre- and post-refinement signals
- * before and after doing each individual refinement cycle
- * (i.e. more than once if times > 1) . See the section on signals
- * in the general documentation of this class.
+ * @note This function triggers the pre- and post-refinement signals before
+ * and after doing each individual refinement cycle (i.e. more than once if
+ * times > 1) . See the section on signals in the general documentation of
+ * this class.
*/
void refine_global (const unsigned int times = 1);
/**
* Execute both refinement and coarsening of the triangulation.
*
- * The function resets all refinement and coarsening flags to
- * false. It uses the user flags for internal purposes. They will
- * therefore be overwritten by undefined content.
+ * The function resets all refinement and coarsening flags to false. It uses
+ * the user flags for internal purposes. They will therefore be overwritten
+ * by undefined content.
*
- * To allow user programs to fix up these cells if that is desired,
- * this function after completing all other work may throw an
- * exception of type DistortedCellList that contains a list of those
- * cells that have been refined and have at least one child that is
- * distorted. The function does not create such an exception if no
- * cells have created distorted children. Note that for the check
- * for distorted cells to happen, the
- * <code>check_for_distorted_cells</code> flag has to be specified
- * upon creation of a triangulation object.
+ * To allow user programs to fix up these cells if that is desired, this
+ * function after completing all other work may throw an exception of type
+ * DistortedCellList that contains a list of those cells that have been
+ * refined and have at least one child that is distorted. The function does
+ * not create such an exception if no cells have created distorted children.
+ * Note that for the check for distorted cells to happen, the
+ * <code>check_for_distorted_cells</code> flag has to be specified upon
+ * creation of a triangulation object.
*
* See the general docs for more information.
*
- * @note This function triggers the pre- and post-refinement signals
- * before and after doing its work. See the section on signals in
- * the general documentation of this class.
+ * @note This function triggers the pre- and post-refinement signals before
+ * and after doing its work. See the section on signals in the general
+ * documentation of this class.
*
- * @note If the boundary description is sufficiently irregular, it
- * can happen that some of the children produced by mesh refinement
- * are distorted (see the extensive discussion on @ref
- * GlossDistorted "distorted cells").
+ * @note If the boundary description is sufficiently irregular, it can
+ * happen that some of the children produced by mesh refinement are
+ * distorted (see the extensive discussion on @ref GlossDistorted "distorted
+ * cells").
*
- * @note This function is <tt>virtual</tt> to allow derived classes
- * to insert hooks, such as saving refinement flags and the like
- * (see e.g. the PersistentTriangulation class).
+ * @note This function is <tt>virtual</tt> to allow derived classes to
+ * insert hooks, such as saving refinement flags and the like (see e.g. the
+ * PersistentTriangulation class).
*/
virtual void execute_coarsening_and_refinement ();
* Do both preparation for refinement and coarsening as well as mesh
* smoothing.
*
- * Regarding the refinement process it fixes the closure of the
- * refinement in <tt>dim>=2</tt> (make sure that no two cells are
- * adjacent with a refinement level differing with more than one),
- * etc. It performs some mesh smoothing if the according flag was
- * given to the constructor of this class. The function returns
- * whether additional cells have been flagged for refinement.
+ * Regarding the refinement process it fixes the closure of the refinement
+ * in <tt>dim>=2</tt> (make sure that no two cells are adjacent with a
+ * refinement level differing with more than one), etc. It performs some
+ * mesh smoothing if the according flag was given to the constructor of this
+ * class. The function returns whether additional cells have been flagged
+ * for refinement.
*
- * See the general doc of this class for more information on
- * smoothing upon refinement.
+ * See the general doc of this class for more information on smoothing upon
+ * refinement.
*
* Regarding the coarsening part, flagging and deflagging cells in
* preparation of the actual coarsening step are done. This includes
- * deleting coarsen flags from cells which may not be deleted
- * (e.g. because one neighbor is more refined than the cell), doing
- * some smoothing, etc.
+ * deleting coarsen flags from cells which may not be deleted (e.g. because
+ * one neighbor is more refined than the cell), doing some smoothing, etc.
*
- * The effect is that only those cells are flagged for coarsening
- * which will actually be coarsened. This includes the fact that all
- * flagged cells belong to parent cells of which all children are
- * flagged.
+ * The effect is that only those cells are flagged for coarsening which will
+ * actually be coarsened. This includes the fact that all flagged cells
+ * belong to parent cells of which all children are flagged.
*
- * The function returns whether some cells' flagging has been
- * changed in the process.
+ * The function returns whether some cells' flagging has been changed in the
+ * process.
*
- * This function uses the user flags, so store them if you still
- * need them afterwards.
+ * This function uses the user flags, so store them if you still need them
+ * afterwards.
*/
bool prepare_coarsening_and_refinement ();
*/
/**
- * Add a RefinementListener. Adding listeners to the Triangulation
- * allows other classes to be informed when the Triangulation is
- * refined.
+ * Add a RefinementListener. Adding listeners to the Triangulation allows
+ * other classes to be informed when the Triangulation is refined.
*
* @note The use of this function has been superseded by the signals
- * mechanism. See the general documentation of the Triangulation
- * class for more information.
+ * mechanism. See the general documentation of the Triangulation class for
+ * more information.
*
* @deprecated
*/
void add_refinement_listener (RefinementListener &listener) const DEAL_II_DEPRECATED;
/**
- * Remove a RefinementListener. When some class needs no longer to
- * be informed about refinements, the listener should be removed
- * from the Triangulation.
+ * Remove a RefinementListener. When some class needs no longer to be
+ * informed about refinements, the listener should be removed from the
+ * Triangulation.
*
* @note The use of this function has been superseded by the signals
- * mechanism. See the general documentation of the Triangulation
- * class for more information.
+ * mechanism. See the general documentation of the Triangulation class for
+ * more information.
*
* @deprecated
*/
/**
* A structure that has boost::signal objects for a number of actions that a
* triangulation can do to itself. See the general documentation of the
- * Triangulation class for more information and for documentation of
- * the semantics of the member functions.
+ * Triangulation class for more information and for documentation of the
+ * semantics of the member functions.
*
- * For documentation on signals, see http://www.boost.org/doc/libs/release/libs/signals2 .
- **/
+ * For documentation on signals, see
+ * http://www.boost.org/doc/libs/release/libs/signals2 .
+ */
struct Signals
{
boost::signals2::signal<void ()> create;
*/
/**
- * Save the addresses of the cells which are flagged for refinement
- * to @p out. For usage, read the general documentation for this
- * class.
+ * Save the addresses of the cells which are flagged for refinement to @p
+ * out. For usage, read the general documentation for this class.
*/
void save_refine_flags (std::ostream &out) const;
/**
- * Same as above, but store the flags to a bitvector rather than to
- * a file.
+ * Same as above, but store the flags to a bitvector rather than to a file.
*/
void save_refine_flags (std::vector<bool> &v) const;
/**
- * Read the information stored by @p save_refine_flags.
+ * Read the information stored by @p save_refine_flags.
*/
void load_refine_flags (std::istream &in);
/**
- * Read the information stored by @p save_refine_flags.
+ * Read the information stored by @p save_refine_flags.
*/
void load_refine_flags (const std::vector<bool> &v);
void save_coarsen_flags (std::ostream &out) const;
/**
- * Same as above, but store the flags to a bitvector rather than to
- * a file.
+ * Same as above, but store the flags to a bitvector rather than to a file.
*/
void save_coarsen_flags (std::vector<bool> &v) const;
void load_coarsen_flags (const std::vector<bool> &v);
/**
- * Return whether this triangulation has ever undergone anisotropic
- * (as opposed to only isotropic) refinement.
+ * Return whether this triangulation has ever undergone anisotropic (as
+ * opposed to only isotropic) refinement.
*/
bool get_anisotropic_refinement_flag() const;
*/
/**
- * Clear all user flags. See also @ref GlossUserFlags .
+ * Clear all user flags. See also @ref GlossUserFlags .
*/
void clear_user_flags ();
/**
- * Save all user flags. See the general documentation for this
- * class and the documentation for the @p save_refine_flags for
- * more details. See also @ref GlossUserFlags .
+ * Save all user flags. See the general documentation for this class and the
+ * documentation for the @p save_refine_flags for more details. See also
+ * @ref GlossUserFlags .
*/
void save_user_flags (std::ostream &out) const;
/**
- * Same as above, but store the flags to a bitvector rather than to
- * a file. The output vector is resized if necessary. See also
- * @ref GlossUserFlags .
+ * Same as above, but store the flags to a bitvector rather than to a file.
+ * The output vector is resized if necessary. See also @ref GlossUserFlags
+ * .
*/
void save_user_flags (std::vector<bool> &v) const;
/**
- * Read the information stored by @p save_user_flags. See also
- * @ref GlossUserFlags .
+ * Read the information stored by @p save_user_flags. See also @ref
+ * GlossUserFlags .
*/
void load_user_flags (std::istream &in);
/**
- * Read the information stored by @p save_user_flags. See also
- * @ref GlossUserFlags .
+ * Read the information stored by @p save_user_flags. See also @ref
+ * GlossUserFlags .
*/
void load_user_flags (const std::vector<bool> &v);
/**
- * Clear all user flags on lines. See also @ref GlossUserFlags .
+ * Clear all user flags on lines. See also @ref GlossUserFlags .
*/
void clear_user_flags_line ();
void save_user_flags_line (std::ostream &out) const;
/**
- * Same as above, but store the flags to a bitvector rather than to
- * a file. The output vector is resized if necessary. See also
- * @ref GlossUserFlags .
+ * Same as above, but store the flags to a bitvector rather than to a file.
+ * The output vector is resized if necessary. See also @ref GlossUserFlags
+ * .
*/
void save_user_flags_line (std::vector<bool> &v) const;
/**
- * Load the user flags located on lines. See also @ref
- * GlossUserFlags .
+ * Load the user flags located on lines. See also @ref GlossUserFlags .
*/
void load_user_flags_line (std::istream &in);
/**
- * Load the user flags located on lines. See also @ref
- * GlossUserFlags .
+ * Load the user flags located on lines. See also @ref GlossUserFlags .
*/
void load_user_flags_line (const std::vector<bool> &v);
/**
- * Clear all user flags on quads. See also @ref GlossUserFlags .
+ * Clear all user flags on quads. See also @ref GlossUserFlags .
*/
void clear_user_flags_quad ();
void save_user_flags_quad (std::ostream &out) const;
/**
- * Same as above, but store the flags to a bitvector rather than to
- * a file. The output vector is resized if necessary. See also
- * @ref GlossUserFlags .
+ * Same as above, but store the flags to a bitvector rather than to a file.
+ * The output vector is resized if necessary. See also @ref GlossUserFlags
+ * .
*/
void save_user_flags_quad (std::vector<bool> &v) const;
/**
- * Load the user flags located on quads. See also @ref
- * GlossUserFlags .
+ * Load the user flags located on quads. See also @ref GlossUserFlags .
*/
void load_user_flags_quad (std::istream &in);
/**
- * Load the user flags located on quads. See also @ref
- * GlossUserFlags .
+ * Load the user flags located on quads. See also @ref GlossUserFlags .
*/
void load_user_flags_quad (const std::vector<bool> &v);
void save_user_flags_hex (std::ostream &out) const;
/**
- * Same as above, but store the flags to a bitvector rather than to
- * a file. The output vector is resized if necessary. See also
- * @ref GlossUserFlags .
+ * Same as above, but store the flags to a bitvector rather than to a file.
+ * The output vector is resized if necessary. See also @ref GlossUserFlags
+ * .
*/
void save_user_flags_hex (std::vector<bool> &v) const;
/**
- * Load the user flags located on hexs. See also @ref
- * GlossUserFlags .
+ * Load the user flags located on hexs. See also @ref GlossUserFlags .
*/
void load_user_flags_hex (std::istream &in);
/**
- * Load the user flags located on hexs. See also @ref
- * GlossUserFlags .
+ * Load the user flags located on hexs. See also @ref GlossUserFlags .
*/
void load_user_flags_hex (const std::vector<bool> &v);
/**
- * Clear all user pointers and indices and allow the use of both for
- * next access. See also @ref GlossUserData .
+ * Clear all user pointers and indices and allow the use of both for next
+ * access. See also @ref GlossUserData .
*/
void clear_user_data ();
/**
* @deprecated User clear_user_data() instead.
*
- * Clear all user pointers. See also @ref GlossUserData .
+ * Clear all user pointers. See also @ref GlossUserData .
*/
void clear_user_pointers () DEAL_II_DEPRECATED;
/**
- * Save all user indices. The output vector is resized if necessary.
- * See also @ref GlossUserData .
+ * Save all user indices. The output vector is resized if necessary. See
+ * also @ref GlossUserData .
*/
void save_user_indices (std::vector<unsigned int> &v) const;
/**
- * Read the information stored by save_user_indices(). See also
- * @ref GlossUserData .
+ * Read the information stored by save_user_indices(). See also @ref
+ * GlossUserData .
*/
void load_user_indices (const std::vector<unsigned int> &v);
/**
- * Save all user pointers. The output vector is resized if
- * necessary. See also @ref GlossUserData .
+ * Save all user pointers. The output vector is resized if necessary. See
+ * also @ref GlossUserData .
*/
void save_user_pointers (std::vector<void *> &v) const;
/**
- * Read the information stored by save_user_pointers(). See also
- * @ref GlossUserData .
+ * Read the information stored by save_user_pointers(). See also @ref
+ * GlossUserData .
*/
void load_user_pointers (const std::vector<void *> &v);
void save_user_indices_line (std::vector<unsigned int> &v) const;
/**
- * Load the user indices located on lines. See also @ref
- * GlossUserData .
+ * Load the user indices located on lines. See also @ref GlossUserData .
*/
void load_user_indices_line (const std::vector<unsigned int> &v);
void save_user_indices_quad (std::vector<unsigned int> &v) const;
/**
- * Load the user indices located on quads. See also @ref
- * GlossUserData .
+ * Load the user indices located on quads. See also @ref GlossUserData .
*/
void load_user_indices_quad (const std::vector<unsigned int> &v);
void save_user_indices_hex (std::vector<unsigned int> &v) const;
/**
- * Load the user indices located on hexs. See also @ref
- * GlossUserData .
+ * Load the user indices located on hexs. See also @ref GlossUserData .
*/
void load_user_indices_hex (const std::vector<unsigned int> &v);
/**
void save_user_pointers_line (std::vector<void *> &v) const;
/**
- * Load the user pointers located on lines. See also @ref
- * GlossUserData .
+ * Load the user pointers located on lines. See also @ref GlossUserData .
*/
void load_user_pointers_line (const std::vector<void *> &v);
void save_user_pointers_quad (std::vector<void *> &v) const;
/**
- * Load the user pointers located on quads. See also @ref
- * GlossUserData .
+ * Load the user pointers located on quads. See also @ref GlossUserData .
*/
void load_user_pointers_quad (const std::vector<void *> &v);
void save_user_pointers_hex (std::vector<void *> &v) const;
/**
- * Load the user pointers located on hexs. See also @ref
- * GlossUserData .
+ * Load the user pointers located on hexs. See also @ref GlossUserData .
*/
void load_user_pointers_hex (const std::vector<void *> &v);
*/
/**
- * Iterator to the first used cell on level @p level.
+ * Iterator to the first used cell on level @p level.
*/
cell_iterator begin (const unsigned int level = 0) const;
/**
- * Iterator to the first active cell on level @p level. If the
- * given level does not contain any active cells (i.e., all cells
- * on this level are further refined, then this function returns
- * <code>end_active(level)</code> so that loops of the kind
+ * Iterator to the first active cell on level @p level. If the given level
+ * does not contain any active cells (i.e., all cells on this level are
+ * further refined, then this function returns
+ * <code>end_active(level)</code> so that loops of the kind
* @code
* for (cell=tria.begin_active(level); cell!=tria.end_active(level); ++cell)
* ...
* @endcode
- * have zero iterations, as may be expected if there are no active
- * cells on this level.
+ * have zero iterations, as may be expected if there are no active cells on
+ * this level.
*/
active_cell_iterator begin_active(const unsigned int level = 0) const;
/**
- * Iterator past the end; this iterator serves for comparisons of
- * iterators with past-the-end or before-the-beginning states.
+ * Iterator past the end; this iterator serves for comparisons of iterators
+ * with past-the-end or before-the-beginning states.
*/
cell_iterator end () const;
/**
- * Return an iterator which is the first iterator not on level. If
- * @p level is the last level, then this returns <tt>end()</tt>.
+ * Return an iterator which is the first iterator not on level. If @p level
+ * is the last level, then this returns <tt>end()</tt>.
*/
cell_iterator end (const unsigned int level) const;
/**
- * Return an active iterator which is the first active iterator not
- * on the given level. If @p level is the last level, then this
- * returns <tt>end()</tt>.
+ * Return an active iterator which is the first active iterator not on the
+ * given level. If @p level is the last level, then this returns
+ * <tt>end()</tt>.
*/
active_cell_iterator end_active (const unsigned int level) const;
/**
- * Return an iterator pointing to the last used cell.
+ * Return an iterator pointing to the last used cell.
*/
cell_iterator last () const;
/**
- * Return an iterator pointing to the last active cell.
+ * Return an iterator pointing to the last active cell.
*/
active_cell_iterator last_active () const;
/**
- * @name Cell iterator functions returning ranges of iterators
+ * @name Cell iterator functions returning ranges of iterators
*/
/**
- * Return an iterator range that contains all cells (active or not)
- * that make up this triangulation. Such a range is useful to
- * initialize range-based for loops as supported by C++11. See the
- * example in the documentation of active_cell_iterators().
+ * Return an iterator range that contains all cells (active or not) that
+ * make up this triangulation. Such a range is useful to initialize range-
+ * based for loops as supported by C++11. See the example in the
+ * documentation of active_cell_iterators().
*
* @return The half open range <code>[this->begin(), this->end())</code>
*
IteratorRange<cell_iterator> cell_iterators () const;
/**
- * Return an iterator range that contains all active cells
- * that make up this triangulation. Such a range is useful to
- * initialize range-based for loops as supported by C++11,
- * see also @ref CPP11 "C++11 standard".
+ * Return an iterator range that contains all active cells that make up this
+ * triangulation. Such a range is useful to initialize range-based for loops
+ * as supported by C++11, see also @ref CPP11 "C++11 standard".
*
- * Range-based for loops are useful in that they require much less
- * code than traditional loops (see
- * <a href="http://en.wikipedia.org/wiki/C%2B%2B11#Range-based_for_loop">here</a>
- * for a discussion of how they work). An example is that without
- * range-based for loops, one often writes code such as the following
- * (assuming for a moment that our goal is setting the user flag
- * on every active cell):
+ * Range-based for loops are useful in that they require much less code than
+ * traditional loops (see <a href="http://en.wikipedia.org/wiki/C%2B%2B11
+ * #Range-based_for_loop">here</a> for a discussion of how they work). An
+ * example is that without range-based for loops, one often writes code such
+ * as the following (assuming for a moment that our goal is setting the user
+ * flag on every active cell):
* @code
* Triangulation<dim> triangulation;
* ...
* for (; cell!=endc; ++cell)
* cell->set_user_flag();
* @endcode
- * Using C++11's range-based for loops, this is now entirely
- * equivalent to the following:
+ * Using C++11's range-based for loops, this is now entirely equivalent to
+ * the following:
* @code
* Triangulation<dim> triangulation;
* ...
* @endcode
* To use this feature, you need a compiler that supports C++11.
*
- * @return The half open range <code>[this->begin_active(), this->end())</code>
+ * @return The half open range <code>[this->begin_active(),
+ * this->end())</code>
*
* @ingroup CPP11
*/
IteratorRange<active_cell_iterator> active_cell_iterators () const;
/**
- * Return an iterator range that contains all cells (active or not)
- * that make up the given level of this triangulation. Such a range is useful to
- * initialize range-based for loops as supported by C++11. See the
- * example in the documentation of active_cell_iterators().
+ * Return an iterator range that contains all cells (active or not) that
+ * make up the given level of this triangulation. Such a range is useful to
+ * initialize range-based for loops as supported by C++11. See the example
+ * in the documentation of active_cell_iterators().
*
* @param[in] level A given level in the refinement hierarchy of this
- * triangulation.
- * @return The half open range <code>[this->begin(level), this->end(level))</code>
+ * triangulation. @return The half open range <code>[this->begin(level),
+ * this->end(level))</code>
*
* @pre level must be less than this->n_levels().
*
IteratorRange<cell_iterator> cell_iterators_on_level (const unsigned int level) const;
/**
- * Return an iterator range that contains all active cells
- * that make up the given level of this triangulation. Such a range is useful to
- * initialize range-based for loops as supported by C++11. See the
- * example in the documentation of active_cell_iterators().
+ * Return an iterator range that contains all active cells that make up the
+ * given level of this triangulation. Such a range is useful to initialize
+ * range-based for loops as supported by C++11. See the example in the
+ * documentation of active_cell_iterators().
*
* @param[in] level A given level in the refinement hierarchy of this
- * triangulation.
- * @return The half open range <code>[this->begin_active(level), this->end(level))</code>
+ * triangulation. @return The half open range
+ * <code>[this->begin_active(level), this->end(level))</code>
*
* @pre level must be less than this->n_levels().
*
*/
/**
- * Iterator to the first used face.
+ * Iterator to the first used face.
*/
face_iterator begin_face () const;
/**
- * Iterator to the first active face.
+ * Iterator to the first active face.
*/
active_face_iterator begin_active_face() const;
/**
- * Iterator past the end; this iterator serves for comparisons of
- * iterators with past-the-end or before-the-beginning states.
+ * Iterator past the end; this iterator serves for comparisons of iterators
+ * with past-the-end or before-the-beginning states.
*/
face_iterator end_face () const;
*/
/**
- * In the following, most functions are provided in two versions,
- * with and without an argument describing the level. The versions
- * with this argument are only applicable for objects describing the
- * cells of the present triangulation. For example: in 2D
- * <tt>n_lines(level)</tt> cannot be called, only
- * <tt>n_lines()</tt>, as lines are faces in 2D and therefore have
- * no level.
+ * In the following, most functions are provided in two versions, with and
+ * without an argument describing the level. The versions with this argument
+ * are only applicable for objects describing the cells of the present
+ * triangulation. For example: in 2D <tt>n_lines(level)</tt> cannot be
+ * called, only <tt>n_lines()</tt>, as lines are faces in 2D and therefore
+ * have no level.
*/
/**
- * Return the total number of used lines,
- * active or not.
+ * Return the total number of used lines, active or not.
*/
unsigned int n_lines () const;
/**
- * Return the total number of used lines,
- * active or not on level @p level.
+ * Return the total number of used lines, active or not on level @p level.
*/
unsigned int n_lines (const unsigned int level) const;
unsigned int n_active_lines () const;
/**
- * Return the total number of active lines,
- * on level @p level.
+ * Return the total number of active lines, on level @p level.
*/
unsigned int n_active_lines (const unsigned int level) const;
/**
- * Return the total number of used quads,
- * active or not.
+ * Return the total number of used quads, active or not.
*/
unsigned int n_quads () const;
/**
- * Return the total number of used quads,
- * active or not on level @p level.
+ * Return the total number of used quads, active or not on level @p level.
*/
unsigned int n_quads (const unsigned int level) const;
/**
- * Return the total number of active quads,
- * active or not.
+ * Return the total number of active quads, active or not.
*/
unsigned int n_active_quads () const;
/**
- * Return the total number of active quads,
- * active or not on level @p level.
+ * Return the total number of active quads, active or not on level @p level.
*/
unsigned int n_active_quads (const unsigned int level) const;
/**
- * Return the total number of used
- * hexahedra, active or not.
+ * Return the total number of used hexahedra, active or not.
*/
unsigned int n_hexs() const;
/**
- * Return the total number of used
- * hexahedra, active or not on level @p
- * level.
+ * Return the total number of used hexahedra, active or not on level @p
+ * level.
*/
unsigned int n_hexs(const unsigned int level) const;
/**
- * Return the total number of active
- * hexahedra, active or not.
+ * Return the total number of active hexahedra, active or not.
*/
unsigned int n_active_hexs() const;
/**
- * Return the total number of active
- * hexahedra, active or not on level @p
- * level.
+ * Return the total number of active hexahedra, active or not on level @p
+ * level.
*/
unsigned int n_active_hexs(const unsigned int level) const;
/**
- * Return the total number of used cells,
- * active or not. Maps to
- * <tt>n_lines()</tt> in one space
- * dimension and so on.
+ * Return the total number of used cells, active or not. Maps to
+ * <tt>n_lines()</tt> in one space dimension and so on.
*/
unsigned int n_cells () const;
/**
- * Return the total number of used cells,
- * active or not, on level @p level.
- * Maps to <tt>n_lines(level)</tt> in
- * one space dimension and so on.
+ * Return the total number of used cells, active or not, on level @p level.
+ * Maps to <tt>n_lines(level)</tt> in one space dimension and so on.
*/
unsigned int n_cells (const unsigned int level) const;
/**
- * Return the total number of active cells.
- * Maps to <tt>n_active_lines()</tt> in
- * one space dimension and so on.
+ * Return the total number of active cells. Maps to
+ * <tt>n_active_lines()</tt> in one space dimension and so on.
*/
unsigned int n_active_cells () const;
/**
- * Return the total number of active cells on
- * level @p level. Maps to
- * <tt>n_active_lines(level)</tt> in one
- * space dimension and so on.
+ * Return the total number of active cells on level @p level. Maps to
+ * <tt>n_active_lines(level)</tt> in one space dimension and so on.
*/
unsigned int n_active_cells (const unsigned int level) const;
/**
- * Return the total number of used faces,
- * active or not. In 2D, the result
- * equals n_lines(), while in 3D it
- * equals n_quads(). Since there are no
- * face objects in 1d, the function
- * returns zero in 1d.
+ * Return the total number of used faces, active or not. In 2D, the result
+ * equals n_lines(), while in 3D it equals n_quads(). Since there are no
+ * face objects in 1d, the function returns zero in 1d.
*/
unsigned int n_faces () const;
/**
- * Return the total number of active faces,
- * active or not. In 2D, the result
- * equals n_active_lines(), while in 3D
- * it equals n_active_quads(). Since
- * there are no face objects in 1d, the
- * function returns zero in 1d.
+ * Return the total number of active faces, active or not. In 2D, the
+ * result equals n_active_lines(), while in 3D it equals n_active_quads().
+ * Since there are no face objects in 1d, the function returns zero in 1d.
*/
unsigned int n_active_faces () const;
/**
* Return the number of levels in this triangulation.
*
- * @note Internally, triangulations store data in levels, and there
- * may be more levels in this data structure than one may think --
- * for example, imagine a triangulation that we just got by
- * coarsening the highest level so that it was completely
- * depopulated. That level is not removed, since it will most likely
- * be repopulated soon by the next refinement process. As a consequence,
- * if you happened to run through raw cell iterators (which you can't
- * do as a user of this class, but can internally), then the number
- * of objects in the levels hierarchy is larger than the level of the most
- * refined cell plus one. On the other hand, since this is rarely what a
- * user of this class cares about, the function really just returns the
- * level of the most refined active cell plus one. (The plus one is
- * because in a coarse, unrefined mesh, all cells have level zero --
- * making the number of levels equal to one.)
+ * @note Internally, triangulations store data in levels, and there may be
+ * more levels in this data structure than one may think -- for example,
+ * imagine a triangulation that we just got by coarsening the highest level
+ * so that it was completely depopulated. That level is not removed, since
+ * it will most likely be repopulated soon by the next refinement process.
+ * As a consequence, if you happened to run through raw cell iterators
+ * (which you can't do as a user of this class, but can internally), then
+ * the number of objects in the levels hierarchy is larger than the level of
+ * the most refined cell plus one. On the other hand, since this is rarely
+ * what a user of this class cares about, the function really just returns
+ * the level of the most refined active cell plus one. (The plus one is
+ * because in a coarse, unrefined mesh, all cells have level zero -- making
+ * the number of levels equal to one.)
*/
unsigned int n_levels () const;
/**
- * Return the number of levels in use. This function is equivalent
- * to n_levels() for a serial Triangulation, but gives the maximum
- * of n_levels() over all processors for a
- * parallel::distributed::Triangulation and therefore can be larger
- * than n_levels().
+ * Return the number of levels in use. This function is equivalent to
+ * n_levels() for a serial Triangulation, but gives the maximum of
+ * n_levels() over all processors for a parallel::distributed::Triangulation
+ * and therefore can be larger than n_levels().
*/
virtual
unsigned int n_global_levels () const;
/**
* Return true if the triangulation has hanging nodes.
*
- * The function is made virtual since the result can be interpreted in different
- * ways, depending on whether the triangulation lives only on a single processor,
- * or may be distributed as done in the parallel::distributed::Triangulation
- * class (see there for a description of what the function is supposed to do in the
- * parallel context).
+ * The function is made virtual since the result can be interpreted in
+ * different ways, depending on whether the triangulation lives only on a
+ * single processor, or may be distributed as done in the
+ * parallel::distributed::Triangulation class (see there for a description
+ * of what the function is supposed to do in the parallel context).
*/
virtual
bool has_hanging_nodes() const;
/**
- * Return the total number of
- * vertices. Some of them may
- * not be used, which usually
- * happens upon coarsening of a
- * triangulation when some
- * vertices are discarded, but we
- * do not want to renumber the
- * remaining ones, leading to
- * holes in the numbers of used
- * vertices. You can get the
- * number of used vertices using
- * @p n_used_vertices function.
+ * Return the total number of vertices. Some of them may not be used, which
+ * usually happens upon coarsening of a triangulation when some vertices are
+ * discarded, but we do not want to renumber the remaining ones, leading to
+ * holes in the numbers of used vertices. You can get the number of used
+ * vertices using @p n_used_vertices function.
*/
unsigned int n_vertices () const;
/**
* Return a constant reference to all the vertices present in this
- * triangulation. Note that not necessarily all vertices in this
- * array are actually used; for example, if you coarsen a mesh, then
- * some vertices are deleted, but their positions in this array are
- * unchanged as the indices of vertices are only allocated once. You
- * can find out about which vertices are actually used by the
- * function get_used_vertices().
+ * triangulation. Note that not necessarily all vertices in this array are
+ * actually used; for example, if you coarsen a mesh, then some vertices are
+ * deleted, but their positions in this array are unchanged as the indices
+ * of vertices are only allocated once. You can find out about which
+ * vertices are actually used by the function get_used_vertices().
*/
const std::vector<Point<spacedim> > &
get_vertices () const;
/**
- * Return the number of vertices that are presently in use,
- * i.e. belong to at least one used element.
+ * Return the number of vertices that are presently in use, i.e. belong to
+ * at least one used element.
*/
unsigned int n_used_vertices () const;
bool vertex_used (const unsigned int index) const;
/**
- * Return a constant reference to the array of @p bools indicating
- * whether an entry in the vertex array is used or not.
+ * Return a constant reference to the array of @p bools indicating whether
+ * an entry in the vertex array is used or not.
*/
const std::vector<bool> &
get_used_vertices () const;
/**
- * Return the maximum number of cells meeting at a common
- * vertex. Since this number is an invariant under refinement, only
- * the cells on the coarsest level are considered. The operation is
- * thus reasonably fast. The invariance is only true for
- * sufficiently many cells in the coarsest triangulation (e.g. for a
- * single cell one would be returned), so a minimum of four is
- * returned in two dimensions, 8 in three dimensions, etc, which is
- * how many cells meet if the triangulation is refined.
+ * Return the maximum number of cells meeting at a common vertex. Since this
+ * number is an invariant under refinement, only the cells on the coarsest
+ * level are considered. The operation is thus reasonably fast. The
+ * invariance is only true for sufficiently many cells in the coarsest
+ * triangulation (e.g. for a single cell one would be returned), so a
+ * minimum of four is returned in two dimensions, 8 in three dimensions,
+ * etc, which is how many cells meet if the triangulation is refined.
*
* In one space dimension, two is returned.
*/
unsigned int max_adjacent_cells () const;
/**
- * This function always returns @p invalid_subdomain_id but is there
- * for compatibility with the derived @p
- * parallel::distributed::Triangulation class. For distributed
- * parallel triangulations this function returns the subdomain id of
- * those cells that are owned by the current processor.
+ * This function always returns @p invalid_subdomain_id but is there for
+ * compatibility with the derived @p parallel::distributed::Triangulation
+ * class. For distributed parallel triangulations this function returns the
+ * subdomain id of those cells that are owned by the current processor.
*/
virtual types::subdomain_id locally_owned_subdomain () const;
/**
* Total number of lines, used or unused.
*
- * @note This function really
- * exports internal information
- * about the triangulation. It
- * shouldn't be used in
- * applications. The function is
- * only part of the public
- * interface of this class
- * because it is used in some of
- * the other classes that build
- * very closely on it (in
- * particular, the DoFHandler
- * class).
+ * @note This function really exports internal information about the
+ * triangulation. It shouldn't be used in applications. The function is only
+ * part of the public interface of this class because it is used in some of
+ * the other classes that build very closely on it (in particular, the
+ * DoFHandler class).
*/
unsigned int n_raw_lines () const;
/**
- * Number of lines, used or
- * unused, on the given level.
+ * Number of lines, used or unused, on the given level.
*
- * @note This function really
- * exports internal information
- * about the triangulation. It
- * shouldn't be used in
- * applications. The function is
- * only part of the public
- * interface of this class
- * because it is used in some of
- * the other classes that build
- * very closely on it (in
- * particular, the DoFHandler
- * class).
+ * @note This function really exports internal information about the
+ * triangulation. It shouldn't be used in applications. The function is only
+ * part of the public interface of this class because it is used in some of
+ * the other classes that build very closely on it (in particular, the
+ * DoFHandler class).
*/
unsigned int n_raw_lines (const unsigned int level) const;
/**
- * Total number of quads, used or
- * unused.
+ * Total number of quads, used or unused.
*
- * @note This function really
- * exports internal information
- * about the triangulation. It
- * shouldn't be used in
- * applications. The function is
- * only part of the public
- * interface of this class
- * because it is used in some of
- * the other classes that build
- * very closely on it (in
- * particular, the DoFHandler
- * class).
+ * @note This function really exports internal information about the
+ * triangulation. It shouldn't be used in applications. The function is only
+ * part of the public interface of this class because it is used in some of
+ * the other classes that build very closely on it (in particular, the
+ * DoFHandler class).
*/
unsigned int n_raw_quads () const;
/**
- * Number of quads, used or
- * unused, on the given level.
+ * Number of quads, used or unused, on the given level.
*
- * @note This function really
- * exports internal information
- * about the triangulation. It
- * shouldn't be used in
- * applications. The function is
- * only part of the public
- * interface of this class
- * because it is used in some of
- * the other classes that build
- * very closely on it (in
- * particular, the DoFHandler
- * class).
+ * @note This function really exports internal information about the
+ * triangulation. It shouldn't be used in applications. The function is only
+ * part of the public interface of this class because it is used in some of
+ * the other classes that build very closely on it (in particular, the
+ * DoFHandler class).
*/
unsigned int n_raw_quads (const unsigned int level) const;
/**
- * Total number of hexs, used or
- * unused.
+ * Total number of hexs, used or unused.
*
- * @note This function really
- * exports internal information
- * about the triangulation. It
- * shouldn't be used in
- * applications. The function is
- * only part of the public
- * interface of this class
- * because it is used in some of
- * the other classes that build
- * very closely on it (in
- * particular, the DoFHandler
- * class).
+ * @note This function really exports internal information about the
+ * triangulation. It shouldn't be used in applications. The function is only
+ * part of the public interface of this class because it is used in some of
+ * the other classes that build very closely on it (in particular, the
+ * DoFHandler class).
*/
unsigned int n_raw_hexs () const;
/**
- * Number of hexs, used or
- * unused, on the given level.
+ * Number of hexs, used or unused, on the given level.
*
- * @note This function really
- * exports internal information
- * about the triangulation. It
- * shouldn't be used in
- * applications. The function is
- * only part of the public
- * interface of this class
- * because it is used in some of
- * the other classes that build
- * very closely on it (in
- * particular, the DoFHandler
- * class).
+ * @note This function really exports internal information about the
+ * triangulation. It shouldn't be used in applications. The function is only
+ * part of the public interface of this class because it is used in some of
+ * the other classes that build very closely on it (in particular, the
+ * DoFHandler class).
*/
unsigned int n_raw_hexs (const unsigned int level) const;
/**
- * Number of cells, used or
- * unused, on the given level.
+ * Number of cells, used or unused, on the given level.
*
- * @note This function really
- * exports internal information
- * about the triangulation. It
- * shouldn't be used in
- * applications. The function is
- * only part of the public
- * interface of this class
- * because it is used in some of
- * the other classes that build
- * very closely on it (in
- * particular, the DoFHandler
- * class).
+ * @note This function really exports internal information about the
+ * triangulation. It shouldn't be used in applications. The function is only
+ * part of the public interface of this class because it is used in some of
+ * the other classes that build very closely on it (in particular, the
+ * DoFHandler class).
*/
unsigned int n_raw_cells (const unsigned int level) const;
/**
- * Return the total number of faces,
- * used or not. In 2d, the result
- * equals n_raw_lines(), while in 3d it
- * equals n_raw_quads().
- *
- * @note This function really
- * exports internal information
- * about the triangulation. It
- * shouldn't be used in
- * applications. The function is
- * only part of the public
- * interface of this class
- * because it is used in some of
- * the other classes that build
- * very closely on it (in
- * particular, the DoFHandler
- * class).
+ * Return the total number of faces, used or not. In 2d, the result equals
+ * n_raw_lines(), while in 3d it equals n_raw_quads().
+ *
+ * @note This function really exports internal information about the
+ * triangulation. It shouldn't be used in applications. The function is only
+ * part of the public interface of this class because it is used in some of
+ * the other classes that build very closely on it (in particular, the
+ * DoFHandler class).
*/
unsigned int n_raw_faces () const;
*/
/**
- * Determine an estimate for the memory consumption (in bytes) of
- * this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*
- * This function is made virtual, since a triangulation object might
- * be accessed through a pointer to this base class, even if the
- * actual object is a derived class.
+ * This function is made virtual, since a triangulation object might be
+ * accessed through a pointer to this base class, even if the actual object
+ * is a derived class.
*/
virtual std::size_t memory_consumption () const;
* Write the data of this object to a stream for the purpose of
* serialization.
*
- * @note This function does not save <i>all</i> member variables of
- * the current triangulation. Rather, only certain kinds of
- * information are stored. For more information see the general
- * documentation of this class.
+ * @note This function does not save <i>all</i> member variables of the
+ * current triangulation. Rather, only certain kinds of information are
+ * stored. For more information see the general documentation of this class.
*/
template <class Archive>
void save (Archive &ar,
* Read the data of this object from a stream for the purpose of
* serialization. Throw away the previous content.
*
- * @note This function does not reset <i>all</i> member variables of
- * the current triangulation to the ones of the triangulation that
- * was previously stored to an archive. Rather, only certain kinds
- * of information are loaded. For more information see the general
+ * @note This function does not reset <i>all</i> member variables of the
+ * current triangulation to the ones of the triangulation that was
+ * previously stored to an archive. Rather, only certain kinds of
+ * information are loaded. For more information see the general
* documentation of this class.
*
* @note This function calls the Triangulation::clear() function and
- * consequently triggers the "clear" signal. After loading all data
- * from the archive, it then triggers the "create" signal. For more
- * information on signals, see the general documentation of this
- * class.
+ * consequently triggers the "clear" signal. After loading all data from the
+ * archive, it then triggers the "create" signal. For more information on
+ * signals, see the general documentation of this class.
*/
template <class Archive>
void load (Archive &ar,
*/
/**
- * Exception @ingroup Exceptions
+ * Exception @ingroup Exceptions
*/
DeclException1 (ExcInvalidLevel,
int,
protected:
/**
- * Do some smoothing in the process of refining the
- * triangulation. See the general doc of this class for more
- * information about this.
+ * Do some smoothing in the process of refining the triangulation. See the
+ * general doc of this class for more information about this.
*/
MeshSmoothing smooth_grid;
/**
- * Write a bool vector to the given stream, writing a pre- and a
- * postfix magic number. The vector is written in an almost binary
- * format, i.e. the bool flags are packed but the data is written
- * as ASCII text.
+ * Write a bool vector to the given stream, writing a pre- and a postfix
+ * magic number. The vector is written in an almost binary format, i.e. the
+ * bool flags are packed but the data is written as ASCII text.
*
- * The flags are stored in a binary format: for each @p true, a @p
- * 1 bit is stored, a @p 0 bit otherwise. The bits are stored as
- * <tt>unsigned char</tt>, thus avoiding endianess. They are
- * written to @p out in plain text, thus amounting to 3.6 bits in
- * the output per bits in the input on the average. Other
- * information (magic numbers and number of elements of the input
- * vector) is stored as plain text as well. The format should
- * therefore be interplatform compatible.
+ * The flags are stored in a binary format: for each @p true, a @p 1 bit is
+ * stored, a @p 0 bit otherwise. The bits are stored as <tt>unsigned
+ * char</tt>, thus avoiding endianess. They are written to @p out in plain
+ * text, thus amounting to 3.6 bits in the output per bits in the input on
+ * the average. Other information (magic numbers and number of elements of
+ * the input vector) is stored as plain text as well. The format should
+ * therefore be interplatform compatible.
*/
static void write_bool_vector (const unsigned int magic_number1,
const std::vector<bool> &v,
std::ostream &out);
/**
- * Re-read a vector of bools previously written by @p
- * write_bool_vector and compare with the magic numbers.
+ * Re-read a vector of bools previously written by @p write_bool_vector and
+ * compare with the magic numbers.
*/
static void read_bool_vector (const unsigned int magic_number1,
std::vector<bool> &v,
*/
/**
- * Declare a number of iterator types for raw iterators, i.e.,
- * iterators that also iterate over holes in the list of cells left
- * by cells that have been coarsened away in previous mesh
- * refinement cycles.
+ * Declare a number of iterator types for raw iterators, i.e., iterators
+ * that also iterate over holes in the list of cells left by cells that have
+ * been coarsened away in previous mesh refinement cycles.
*
- * Since users should never have to access these internal properties
- * of how we store data, these iterator types are made private.
+ * Since users should never have to access these internal properties of how
+ * we store data, these iterator types are made private.
*/
typedef TriaRawIterator <CellAccessor<dim,spacedim> > raw_cell_iterator;
typedef TriaRawIterator <TriaAccessor<dim-1, dim, spacedim> > raw_face_iterator;
typedef typename IteratorSelector::raw_hex_iterator raw_hex_iterator;
/**
- * Iterator to the first cell, used or not, on level @p level. If a
- * level has no cells, a past-the-end iterator is returned.
+ * Iterator to the first cell, used or not, on level @p level. If a level
+ * has no cells, a past-the-end iterator is returned.
*/
raw_cell_iterator begin_raw (const unsigned int level = 0) const;
/**
- * Return a raw iterator which is the first iterator not on
- * level. If @p level is the last level, then this returns
- * <tt>end()</tt>.
+ * Return a raw iterator which is the first iterator not on level. If @p
+ * level is the last level, then this returns <tt>end()</tt>.
*/
raw_cell_iterator end_raw (const unsigned int level) const;
*/
/**
- * Iterator to the first line, used or not, on level @p level. If a
- * level has no lines, a past-the-end iterator is returned. If
- * lines are no cells, i.e. for @p dim>1 no @p level argument must
- * be given. The same applies for all the other functions above,
- * of course.
+ * Iterator to the first line, used or not, on level @p level. If a level
+ * has no lines, a past-the-end iterator is returned. If lines are no
+ * cells, i.e. for @p dim>1 no @p level argument must be given. The same
+ * applies for all the other functions above, of course.
*/
raw_line_iterator
begin_raw_line (const unsigned int level = 0) const;
/**
- * Iterator to the first used line on level @p level.
+ * Iterator to the first used line on level @p level.
*/
line_iterator
begin_line (const unsigned int level = 0) const;
/**
- * Iterator to the first active line on level @p level.
+ * Iterator to the first active line on level @p level.
*/
active_line_iterator
begin_active_line(const unsigned int level = 0) const;
/**
- * Iterator past the end; this iterator serves for comparisons of
- * iterators with past-the-end or before-the-beginning states.
+ * Iterator past the end; this iterator serves for comparisons of iterators
+ * with past-the-end or before-the-beginning states.
*/
line_iterator end_line () const;
*/
/**
- * Iterator to the first quad, used or not, on the given level. If
- * a level has no quads, a past-the-end iterator is returned. If
- * quads are no cells, i.e. for $dim>2$ no level argument must be
- * given.
-
+ * Iterator to the first quad, used or not, on the given level. If a level
+ * has no quads, a past-the-end iterator is returned. If quads are no
+ * cells, i.e. for $dim>2$ no level argument must be given.
*/
raw_quad_iterator
begin_raw_quad (const unsigned int level = 0) const;
/**
- * Iterator to the first used quad on level @p level.
+ * Iterator to the first used quad on level @p level.
*/
quad_iterator
begin_quad (const unsigned int level = 0) const;
/**
- * Iterator to the first active quad on level @p level.
+ * Iterator to the first active quad on level @p level.
*/
active_quad_iterator
begin_active_quad (const unsigned int level = 0) const;
/**
- * Iterator past the end; this iterator serves for comparisons of
- * iterators with past-the-end or before-the-beginning states.
+ * Iterator past the end; this iterator serves for comparisons of iterators
+ * with past-the-end or before-the-beginning states.
*/
quad_iterator
end_quad () const;
*/
/**
- * Iterator to the first hex, used or not, on level @p level. If a
- * level has no hexs, a past-the-end iterator is returned.
+ * Iterator to the first hex, used or not, on level @p level. If a level has
+ * no hexs, a past-the-end iterator is returned.
*/
raw_hex_iterator
begin_raw_hex (const unsigned int level = 0) const;
/**
- * Iterator to the first used hex on level @p level.
+ * Iterator to the first used hex on level @p level.
*/
hex_iterator
begin_hex (const unsigned int level = 0) const;
/**
- * Iterator to the first active hex on level @p level.
+ * Iterator to the first active hex on level @p level.
*/
active_hex_iterator
begin_active_hex (const unsigned int level = 0) const;
/**
- * Iterator past the end; this iterator serves for comparisons of
- * iterators with past-the-end or before-the-beginning states.
+ * Iterator past the end; this iterator serves for comparisons of iterators
+ * with past-the-end or before-the-beginning states.
*/
hex_iterator
end_hex () const;
/**
- * The (public) function clear() will only work when the
- * triangulation is not subscribed to by other users. The
- * clear_despite_subscriptions() function now allows the
- * triangulation being cleared even when there are subscriptions.
+ * The (public) function clear() will only work when the triangulation is
+ * not subscribed to by other users. The clear_despite_subscriptions()
+ * function now allows the triangulation being cleared even when there are
+ * subscriptions.
*
- * Make sure, you know what you do, when calling this function, as
- * its use is reasonable in very rare cases, only. For example, when
- * the subscriptions were for the initially empty Triangulation and
- * the Triangulation object wants to release its memory before
- * throwing an assertion due to input errors (e.g. in the
- * create_triangulation() function).
+ * Make sure, you know what you do, when calling this function, as its use
+ * is reasonable in very rare cases, only. For example, when the
+ * subscriptions were for the initially empty Triangulation and the
+ * Triangulation object wants to release its memory before throwing an
+ * assertion due to input errors (e.g. in the create_triangulation()
+ * function).
*/
void clear_despite_subscriptions ();
/**
- * Refine all cells on all levels which were previously flagged for
- * refinement.
+ * Refine all cells on all levels which were previously flagged for
+ * refinement.
*
- * Note, that this function uses the <tt>line->user_flags</tt> for
- * <tt>dim=2,3</tt> and the <tt>quad->user_flags</tt> for
- * <tt>dim=3</tt>.
+ * Note, that this function uses the <tt>line->user_flags</tt> for
+ * <tt>dim=2,3</tt> and the <tt>quad->user_flags</tt> for <tt>dim=3</tt>.
*
- * The function returns a list of cells that have produced children
- * that satisfy the criteria of @ref GlossDistorted "distorted
- * cells" if the <code>check_for_distorted_cells</code> flag was
- * specified upon creation of this object, at
+ * The function returns a list of cells that have produced children that
+ * satisfy the criteria of @ref GlossDistorted "distorted cells" if the
+ * <code>check_for_distorted_cells</code> flag was specified upon creation
+ * of this object, at
*/
DistortedCellList execute_refinement ();
/**
- * Coarsen all cells which were flagged for coarsening, or rather:
- * delete all children of those cells of which all child cells are
- * flagged for coarsening and several other constraints hold (see
- * the general doc of this class).
+ * Coarsen all cells which were flagged for coarsening, or rather: delete
+ * all children of those cells of which all child cells are flagged for
+ * coarsening and several other constraints hold (see the general doc of
+ * this class).
*/
void execute_coarsening ();
/**
- * Make sure that either all or none of the children of a cell are
- * tagged for coarsening.
+ * Make sure that either all or none of the children of a cell are tagged
+ * for coarsening.
*/
void fix_coarsen_flags ();
/**
- * Array of pointers pointing to the objects storing the cell data
- * on the different levels.
+ * Array of pointers pointing to the objects storing the cell data on the
+ * different levels.
*/
std::vector<dealii::internal::Triangulation::TriaLevel<dim>*> levels;
/**
- * Pointer to the faces of the triangulation. In 1d this contains
- * nothing, in 2D it contains data concerning lines and in 3D quads
- * and lines. All of these have no level and are therefore treated
- * separately.
+ * Pointer to the faces of the triangulation. In 1d this contains nothing,
+ * in 2D it contains data concerning lines and in 3D quads and lines. All
+ * of these have no level and are therefore treated separately.
*/
dealii::internal::Triangulation::TriaFaces<dim> *faces;
/**
- * Array of the vertices of this triangulation.
+ * Array of the vertices of this triangulation.
*/
std::vector<Point<spacedim> > vertices;
/**
- * Array storing a bit-pattern which vertices are used.
+ * Array storing a bit-pattern which vertices are used.
*/
std::vector<bool> vertices_used;
/**
- * Collection of manifold objects. We store only objects, which are
- * not of type FlatManifold.
+ * Collection of manifold objects. We store only objects, which are not of
+ * type FlatManifold.
*/
std::map<types::manifold_id, SmartPointer<const Manifold<dim,spacedim> , Triangulation<dim, spacedim> > > manifold;
/**
- * A flag that determines whether we are to check for distorted
- * cells upon creation and refinement of a mesh.
+ * A flag that determines whether we are to check for distorted cells upon
+ * creation and refinement of a mesh.
*/
const bool check_for_distorted_cells;
/**
- * Cache to hold the numbers of lines, quads, hexes, etc. These
- * numbers are set at the end of the refinement and coarsening
- * functions and enable faster access later on. In the old days,
- * whenever one wanted to access one of these numbers, one had to
- * perform a loop over all lines, e.g., and count the elements until
- * we hit the end iterator. This is time consuming and since access
- * to the number of lines etc is a rather frequent operation, this
- * was not an optimal solution.
+ * Cache to hold the numbers of lines, quads, hexes, etc. These numbers are
+ * set at the end of the refinement and coarsening functions and enable
+ * faster access later on. In the old days, whenever one wanted to access
+ * one of these numbers, one had to perform a loop over all lines, e.g., and
+ * count the elements until we hit the end iterator. This is time consuming
+ * and since access to the number of lines etc is a rather frequent
+ * operation, this was not an optimal solution.
*/
dealii::internal::Triangulation::NumberCache<dim> number_cache;
/**
- * A map that relates the number of a boundary vertex to the
- * boundary indicator. This field is only used in 1d. We have this
- * field because we store boundary indicator information with faces
- * in 2d and higher where we have space in the structures that store
- * data for faces, but in 1d there is no such space for faces.
+ * A map that relates the number of a boundary vertex to the boundary
+ * indicator. This field is only used in 1d. We have this field because we
+ * store boundary indicator information with faces in 2d and higher where we
+ * have space in the structures that store data for faces, but in 1d there
+ * is no such space for faces.
*
- * The field is declared as a pointer for a rather mundane reason:
- * all other fields of this class that can be modified by the
- * TriaAccessor hierarchy are pointers, and so these accessor
- * classes store a const pointer to the triangulation. We could no
- * longer do so for TriaAccessor<0,1,spacedim> if this field (that
- * can be modified by TriaAccessor::set_boundary_indicator) were not
- * a pointer.
+ * The field is declared as a pointer for a rather mundane reason: all other
+ * fields of this class that can be modified by the TriaAccessor hierarchy
+ * are pointers, and so these accessor classes store a const pointer to the
+ * triangulation. We could no longer do so for TriaAccessor<0,1,spacedim> if
+ * this field (that can be modified by TriaAccessor::set_boundary_indicator)
+ * were not a pointer.
*/
std::map<unsigned int, types::boundary_id> *vertex_to_boundary_id_map_1d;
/**
- * A map that relates the number of a boundary vertex to the
- * manifold indicator. This field is only used in 1d. We have this
- * field because we store manifold indicator information with faces
- * in 2d and higher where we have space in the structures that store
- * data for faces, but in 1d there is no such space for faces.
+ * A map that relates the number of a boundary vertex to the manifold
+ * indicator. This field is only used in 1d. We have this field because we
+ * store manifold indicator information with faces in 2d and higher where we
+ * have space in the structures that store data for faces, but in 1d there
+ * is no such space for faces.
*
* @note Manifold objects are pretty useless for points since they are
* neither refined nor are their interiors mapped. We nevertheless allow
* storing manifold ids for points to be consistent in dimension-independent
* programs.
*
- * The field is declared as a pointer for a rather mundane reason:
- * all other fields of this class that can be modified by the
- * TriaAccessor hierarchy are pointers, and so these accessor
- * classes store a const pointer to the triangulation. We could no
- * longer do so for TriaAccessor<0,1,spacedim> if this field (that
- * can be modified by TriaAccessor::set_boundary_indicator) were not
- * a pointer.
+ * The field is declared as a pointer for a rather mundane reason: all other
+ * fields of this class that can be modified by the TriaAccessor hierarchy
+ * are pointers, and so these accessor classes store a const pointer to the
+ * triangulation. We could no longer do so for TriaAccessor<0,1,spacedim> if
+ * this field (that can be modified by TriaAccessor::set_boundary_indicator)
+ * were not a pointer.
*/
std::map<unsigned int, types::manifold_id> *vertex_to_manifold_id_map_1d;
/**
- * A map that correlates each refinement listener that has been
- * added through the outdated RefinementListener interface via
- * add_refinement_listener(), with the new-style boost::signal
- * connections for each of the member function. We need to keep this
- * list around so that we can later terminate the connection again
- * when someone calls remove_refinement_listener().
+ * A map that correlates each refinement listener that has been added
+ * through the outdated RefinementListener interface via
+ * add_refinement_listener(), with the new-style boost::signal connections
+ * for each of the member function. We need to keep this list around so that
+ * we can later terminate the connection again when someone calls
+ * remove_refinement_listener().
*
- * The data type is a multimap since, although this would be weird,
- * the same object may add itself multiple times as a listener.
+ * The data type is a multimap since, although this would be weird, the same
+ * object may add itself multiple times as a listener.
*/
mutable
std::multimap<const RefinementListener *, std::vector<boost::signals2::connection> >
struct Implementation;
/**
- * Implementation of a type with
- * which to store the level of an
- * accessor object. We only need
- * it for the case that
- * <tt>structdim ==
- * dim</tt>. Otherwise, an empty
- * object is sufficient.
+ * Implementation of a type with which to store the level of an accessor
+ * object. We only need it for the case that <tt>structdim == dim</tt>.
+ * Otherwise, an empty object is sufficient.
*/
template <int structdim, int dim> struct PresentLevelType
{
{}
/**
- * Dummy
- * constructor. Only
- * level zero is allowed.
+ * Dummy constructor. Only level zero is allowed.
*/
type (const int level)
{
}
/**
- * Dummy conversion
- * operator. Returns
- * level zero.
+ * Dummy conversion operator. Returns level zero.
*/
operator int () const
{
/**
- * Implementation of a type with
- * which to store the level of an
- * accessor object. We only need
- * it for the case that
- * <tt>structdim ==
- * dim</tt>. Otherwise, an empty
- * object is sufficient.
+ * Implementation of a type with which to store the level of an accessor
+ * object. We only need it for the case that <tt>structdim == dim</tt>.
+ * Otherwise, an empty object is sufficient.
*/
template <int dim> struct PresentLevelType<dim,dim>
{
*/
DeclException0 (ExcCellNotUsed);
/**
- * The cell is not an @ref
- * GlossActive "active" cell, but
- * it already has children. Some
- * operations, like setting
- * refinement flags or accessing
- * degrees of freedom are only
- * possible on active cells.
+ * The cell is not an @ref GlossActive "active" cell, but it already has
+ * children. Some operations, like setting refinement flags or accessing
+ * degrees of freedom are only possible on active cells.
*
* @ingroup Exceptions
*/
DeclException0 (ExcCellNotActive);
/**
- * Trying to access the children of
- * a cell which is in fact active.
+ * Trying to access the children of a cell which is in fact active.
*
* @ingroup Exceptions
*/
DeclException0 (ExcCellHasNoChildren);
/**
- * Trying to access the parent of
- * a cell which is in the coarsest
- * level of the triangulation.
+ * Trying to access the parent of a cell which is in the coarsest level of
+ * the triangulation.
*
* @ingroup Exceptions
*/
*/
DeclException0 (ExcNeighborIsNotCoarser);
/**
- * You are trying to access the
- * level of a face, but faces have
- * no inherent level. The level of
- * a face can only be determined by
- * the level of an adjacent face,
- * which in turn implies that a
- * face can have several levels.
+ * You are trying to access the level of a face, but faces have no inherent
+ * level. The level of a face can only be determined by the level of an
+ * adjacent face, which in turn implies that a face can have several levels.
*
* @ingroup Exceptions
*/
/**
- * A base class for the accessor classes used by TriaRawIterator and
- * derived classes.
+ * A base class for the accessor classes used by TriaRawIterator and derived
+ * classes.
*
- * This class offers only the basic functionality required by the
- * iterators (stores the necessary data members, offers comparison
- * operators and the like), but has no functionality to actually
- * dereference data. This is done in the derived classes.
+ * This class offers only the basic functionality required by the iterators
+ * (stores the necessary data members, offers comparison operators and the
+ * like), but has no functionality to actually dereference data. This is done
+ * in the derived classes.
*
- * In the implementation, the behavior of this class differs between
- * the cases where <tt>structdim==dim</tt> (cells of a mesh) and
- * <tt>structdim<dim</tt> (faces and edges). For the latter,
- * #present_level is always equal to zero and the constructors may not
- * receive a positive value there. For cells, any level is
- * possible, but only those within the range of the levels of the
- * Triangulation are reasonable. Furthermore, the function objects()
- * returns either the container with all cells on the same level or
- * the container with all objects of this dimension (<tt>structdim<dim</tt>).
+ * In the implementation, the behavior of this class differs between the cases
+ * where <tt>structdim==dim</tt> (cells of a mesh) and
+ * <tt>structdim<dim</tt> (faces and edges). For the latter, #present_level
+ * is always equal to zero and the constructors may not receive a positive
+ * value there. For cells, any level is possible, but only those within the
+ * range of the levels of the Triangulation are reasonable. Furthermore, the
+ * function objects() returns either the container with all cells on the same
+ * level or the container with all objects of this dimension
+ * (<tt>structdim<dim</tt>).
*
- * Some internals of this class are discussed in @ref IteratorAccessorInternals .
+ * Some internals of this class are discussed in @ref
+ * IteratorAccessorInternals .
*
* @ingroup grid
* @ingroup Accessors
{
public:
/**
- * Dimension of the space the
- * object represented by this
- * accessor lives in. For
- * example, if this accessor
- * represents a quad that is
- * part of a two-dimensional
- * surface in four-dimensional
- * space, then this value is
- * four.
+ * Dimension of the space the object represented by this accessor lives in.
+ * For example, if this accessor represents a quad that is part of a two-
+ * dimensional surface in four-dimensional space, then this value is four.
*/
static const unsigned int space_dimension = spacedim;
/**
- * Dimensionality of the object
- * that the thing represented by
- * this accessopr is part of. For
- * example, if this accessor
- * represents a line that is part
- * of a hexahedron, then this
- * value will be three.
+ * Dimensionality of the object that the thing represented by this accessopr
+ * is part of. For example, if this accessor represents a line that is part
+ * of a hexahedron, then this value will be three.
*/
static const unsigned int dimension = dim;
/**
- * Dimensionality of the current
- * object represented by this
- * accessor. For example, if it
- * is line (irrespective of
- * whether it is part of a quad
- * or hex, and what dimension we
- * are in), then this value
- * equals 1.
+ * Dimensionality of the current object represented by this accessor. For
+ * example, if it is line (irrespective of whether it is part of a quad or
+ * hex, and what dimension we are in), then this value equals 1.
*/
static const unsigned int structure_dimension = structdim;
protected:
/**
- * Declare the data type that
- * this accessor class expects to
- * get passed from the iterator
- * classes. Since the pure
- * triangulation iterators need
- * no additional data, this data
- * type is @p void.
+ * Declare the data type that this accessor class expects to get passed from
+ * the iterator classes. Since the pure triangulation iterators need no
+ * additional data, this data type is @p void.
*/
typedef void AccessorData;
/**
- * Constructor. Protected, thus
- * only callable from friend
- * classes.
+ * Constructor. Protected, thus only callable from friend classes.
*/
TriaAccessorBase (const Triangulation<dim,spacedim> *parent = 0,
const int level = -1,
const AccessorData * = 0);
/**
- * Copy constructor. Creates an
- * object with exactly the same data.
+ * Copy constructor. Creates an object with exactly the same data.
*/
TriaAccessorBase (const TriaAccessorBase &);
/**
- * Copy operator. Since this is
- * only called from iterators,
- * do not return anything, since
- * the iterator will return
- * itself.
+ * Copy operator. Since this is only called from iterators, do not return
+ * anything, since the iterator will return itself.
*
- * This method is protected,
- * since it is only to be called
- * from the iterator class.
+ * This method is protected, since it is only to be called from the iterator
+ * class.
*/
void copy_from (const TriaAccessorBase &);
/**
- * Copy operator. Creates an
- * object with exactly the same data.
+ * Copy operator. Creates an object with exactly the same data.
*/
TriaAccessorBase &operator = (const TriaAccessorBase &);
/**
- * Ordering of accessors. If #structure_dimension is less than
- * #dimension, we simply compare the index of such an object. If
- * #structure_dimension equals #dimension, we compare the level()
- * first, and the index() only if levels are equal.
+ * Ordering of accessors. If #structure_dimension is less than #dimension,
+ * we simply compare the index of such an object. If #structure_dimension
+ * equals #dimension, we compare the level() first, and the index() only if
+ * levels are equal.
*/
bool operator < (const TriaAccessorBase &other) const;
protected:
/**
- * Copy operator. This is normally
- * used in a context like
- * <tt>iterator a,b; *a=*b;</tt>. Since
- * the meaning is to copy the object
- * pointed to by @p b to the object
- * pointed to by @p a and since
- * accessors are not real but
- * virtual objects, this operation
- * is not useful for iterators on
- * triangulations. We declare this
- * function here private, thus it may
- * not be used from outside.
- * Furthermore it is not implemented
- * and will give a linker error if
- * used anyway.
+ * Copy operator. This is normally used in a context like <tt>iterator a,b;
+ * *a=*b;</tt>. Since the meaning is to copy the object pointed to by @p b
+ * to the object pointed to by @p a and since accessors are not real but
+ * virtual objects, this operation is not useful for iterators on
+ * triangulations. We declare this function here private, thus it may not be
+ * used from outside. Furthermore it is not implemented and will give a
+ * linker error if used anyway.
*/
void operator = (const TriaAccessorBase *);
/**
- * Compare for equality.
+ * Compare for equality.
*/
bool operator == (const TriaAccessorBase &) const;
* @{
*/
/**
- * This operator advances the
- * iterator to the next element.
+ * This operator advances the iterator to the next element.
*
- * For @p dim=1 only:
- * The next element is next on
- * this level if there are
- * more. If the present element
- * is the last on this level,
- * the first on the next level
- * is accessed.
+ * For @p dim=1 only: The next element is next on this level if there are
+ * more. If the present element is the last on this level, the first on the
+ * next level is accessed.
*/
void operator ++ ();
/**
- * This operator moves the
- * iterator to the previous
- * element.
+ * This operator moves the iterator to the previous element.
*
- * For @p dim=1 only:
- * The previous element is
- * previous on this level if
- * <tt>index>0</tt>. If the present
- * element is the first on this
- * level, the last on the
- * previous level is accessed.
+ * For @p dim=1 only: The previous element is previous on this level if
+ * <tt>index>0</tt>. If the present element is the first on this level, the
+ * last on the previous level is accessed.
*/
void operator -- ();
/**
*/
/**
- * Access to the other objects of
- * a Triangulation with same
- * dimension.
+ * Access to the other objects of a Triangulation with same dimension.
*/
dealii::internal::Triangulation::TriaObjects<dealii::internal::Triangulation::TriaObject<structdim> > &
objects () const;
public:
/**
- * Data type to be used for passing
- * parameters from iterators to the
- * accessor classes in a unified
- * way, no matter what the type of
- * number of these parameters is.
+ * Data type to be used for passing parameters from iterators to the
+ * accessor classes in a unified way, no matter what the type of number of
+ * these parameters is.
*/
typedef void *LocalData;
*
* @note Within a Triangulation object, cells are uniquely identified by a
* pair <code>(level, index)</code> where the former is the cell's
- * refinement level and the latter is the index of the cell within
- * this refinement level (the former being what this function
- * returns). Consequently, there may be multiple cells on different
- * refinement levels but with the same index within their level.
- * Contrary to this, if the current object corresponds to a face or
- * edge, then the object is uniquely identified solely by its index
- * as faces and edges do not have a refinement level. For these objects,
- * the current function always returns zero as the level.
+ * refinement level and the latter is the index of the cell within this
+ * refinement level (the former being what this function returns).
+ * Consequently, there may be multiple cells on different refinement levels
+ * but with the same index within their level. Contrary to this, if the
+ * current object corresponds to a face or edge, then the object is uniquely
+ * identified solely by its index as faces and edges do not have a
+ * refinement level. For these objects, the current function always returns
+ * zero as the level.
*/
int level () const;
/**
- * Return the index of the
- * element presently pointed to
- * on the present level.
+ * Return the index of the element presently pointed to on the present
+ * level.
*
- * Within a Triangulation object, cells are uniquely identified by a
- * pair <code>(level, index)</code> where the former is the cell's
- * refinement level and the latter is the index of the cell within
- * this refinement level (the latter being what this function
- * returns). Consequently, there may be multiple cells on different
- * refinement levels but with the same index within their level.
- * Contrary to this, if the current object corresponds to a face or
- * edge, then the object is uniquely identified solely by its index
- * as faces and edges do not have a refinement level.
- *
- * @note The indices objects returned by this function are not a
- * contiguous set of numbers on each level: going from cell to cell,
- * some of the indices in a level may be unused.
+ * Within a Triangulation object, cells are uniquely identified by a pair
+ * <code>(level, index)</code> where the former is the cell's refinement
+ * level and the latter is the index of the cell within this refinement
+ * level (the latter being what this function returns). Consequently, there
+ * may be multiple cells on different refinement levels but with the same
+ * index within their level. Contrary to this, if the current object
+ * corresponds to a face or edge, then the object is uniquely identified
+ * solely by its index as faces and edges do not have a refinement level.
+ *
+ * @note The indices objects returned by this function are not a contiguous
+ * set of numbers on each level: going from cell to cell, some of the
+ * indices in a level may be unused.
*
* @note If the triangulation is actually of type
- * parallel::distributed::Triangulation then the indices are
- * relatively only to that part of the distributed triangulation
- * that is stored on the current processor. In other words, cells
- * living in the partitions of the triangulation stored on different
- * processors may have the same index even if they refer to the same
- * cell, and the may have different indices even if they do refer to
- * the same cell (e.g., if a cell is owned by one processor but is a
- * ghost cell on another).
+ * parallel::distributed::Triangulation then the indices are relatively only
+ * to that part of the distributed triangulation that is stored on the
+ * current processor. In other words, cells living in the partitions of the
+ * triangulation stored on different processors may have the same index even
+ * if they refer to the same cell, and the may have different indices even
+ * if they do refer to the same cell (e.g., if a cell is owned by one
+ * processor but is a ghost cell on another).
*/
int index () const;
/**
- * Return the state of the
- * iterator. For the different
- * states an accessor can be in,
- * refer to the
- * TriaRawIterator
- * documentation.
+ * Return the state of the iterator. For the different states an accessor
+ * can be in, refer to the TriaRawIterator documentation.
*/
IteratorState::IteratorStates state () const;
/**
- * Return a pointer to the
- * triangulation which the object
- * pointed to by this class
- * belongs to.
+ * Return a pointer to the triangulation which the object pointed to by this
+ * class belongs to.
*/
const Triangulation<dim,spacedim> &get_triangulation () const;
*/
protected:
/**
- * The level if this is a cell
- * (<tt>structdim==dim</tt>). Else,
- * contains zero.
+ * The level if this is a cell (<tt>structdim==dim</tt>). Else, contains
+ * zero.
*/
typename dealii::internal::TriaAccessor::PresentLevelType<structdim,dim>::type present_level;
/**
- * Used to store the index of
- * the element presently pointed
- * to on the level presentl
- * used.
+ * Used to store the index of the element presently pointed to on the level
+ * presentl used.
*/
int present_index;
/**
- * Pointer to the triangulation
- * which we act on.
+ * Pointer to the triangulation which we act on.
*/
const Triangulation<dim,spacedim> *tria;
/**
- * A class that represents accessor objects to iterators that don't
- * make sense such as quad iterators in on 1d meshes. This class can
- * not be used to create objects (it will in fact throw an exception
- * if this should ever be attempted but it sometimes allows code to be
- * written in a simpler way in a dimension independent way. For
- * example, it allows to write code that works on quad iterators that
- * is dimension independent because quad iterators (with the current
- * class) exist and are syntactically correct. You can not expect,
- * however, to ever generate one of these iterators, meaning you need
- * to expect to wrap the code block in which you use quad iterators
- * into something like <code>if (dim@>1)</code> -- which makes eminent
- * sense anyway.
+ * A class that represents accessor objects to iterators that don't make sense
+ * such as quad iterators in on 1d meshes. This class can not be used to
+ * create objects (it will in fact throw an exception if this should ever be
+ * attempted but it sometimes allows code to be written in a simpler way in a
+ * dimension independent way. For example, it allows to write code that works
+ * on quad iterators that is dimension independent because quad iterators
+ * (with the current class) exist and are syntactically correct. You can not
+ * expect, however, to ever generate one of these iterators, meaning you need
+ * to expect to wrap the code block in which you use quad iterators into
+ * something like <code>if (dim@>1)</code> -- which makes eminent sense
+ * anyway.
*
- * This class provides the minimal interface necessary for Accessor
- * classes to interact with Iterator classes. However, this is only
- * for syntactic correctness, none of the functions do anything but
- * generate errors.
+ * This class provides the minimal interface necessary for Accessor classes to
+ * interact with Iterator classes. However, this is only for syntactic
+ * correctness, none of the functions do anything but generate errors.
*
* @ingroup Accessors
* @author Wolfgang Bangerth, 2008
{
public:
/**
- * Propagate typedef from
- * base class to this class.
+ * Propagate typedef from base class to this class.
*/
typedef typename TriaAccessorBase<structdim,dim,spacedim>::AccessorData AccessorData;
/**
- * Constructor. This class is
- * used for iterators that make
- * sense in a given dimension,
- * for example quads for 1d
- * meshes. Consequently, while
- * the creation of such objects
- * is syntactically valid, they
- * make no semantic sense, and we
- * generate an exception when
- * such an object is actually
+ * Constructor. This class is used for iterators that make sense in a given
+ * dimension, for example quads for 1d meshes. Consequently, while the
+ * creation of such objects is syntactically valid, they make no semantic
+ * sense, and we generate an exception when such an object is actually
* generated.
*/
InvalidAccessor (const Triangulation<dim,spacedim> *parent = 0,
const AccessorData *local_data = 0);
/**
- * Copy constructor. This class
- * is used for iterators that
- * make sense in a given
- * dimension, for example quads
- * for 1d meshes. Consequently,
- * while the creation of such
- * objects is syntactically
- * valid, they make no semantic
- * sense, and we generate an
- * exception when such an object
- * is actually generated.
+ * Copy constructor. This class is used for iterators that make sense in a
+ * given dimension, for example quads for 1d meshes. Consequently, while the
+ * creation of such objects is syntactically valid, they make no semantic
+ * sense, and we generate an exception when such an object is actually
+ * generated.
*/
InvalidAccessor (const InvalidAccessor &);
/**
- * Conversion from other
- * accessors to the current
- * invalid one. This of course
- * also leads to a run-time
- * error.
+ * Conversion from other accessors to the current invalid one. This of
+ * course also leads to a run-time error.
*/
template <typename OtherAccessor>
InvalidAccessor (const OtherAccessor &);
bool operator != (const InvalidAccessor &) const;
/**
- * Dummy operators to make things
- * compile. Does nothing.
+ * Dummy operators to make things compile. Does nothing.
*/
void operator ++ () const;
void operator -- () const;
/**
- * Dummy function representing
- * whether the accessor points to
- * a used or an unused object.
+ * Dummy function representing whether the accessor points to a used or an
+ * unused object.
*/
bool used () const;
/**
- * Dummy function representing
- * whether the accessor points to
- * an object that has children.
+ * Dummy function representing whether the accessor points to an object that
+ * has children.
*/
bool has_children () const;
};
/**
- * A class that provides access to objects in a triangulation such as
- * its vertices, sub-objects, children, geometric information, etc.
- * This class represents objects of dimension <code>structdim</code>
- * (i.e. 1 for lines, 2 for quads, 3 for hexes) in a triangulation of
- * dimensionality <code>dim</code> (i.e. 1 for a triangulation of
- * lines, 2 for a triangulation of quads, and 3 for a triangulation of
- * hexes) that is embedded in a space of dimensionality
- * <code>spacedim</code> (for <code>spacedim==dim</code> the
- * triangulation represents a domain in $R^{dim}$, for
- * <code>spacedim@>dim</code> the triangulation is of a manifold
- * embedded in a higher dimensional space).
+ * A class that provides access to objects in a triangulation such as its
+ * vertices, sub-objects, children, geometric information, etc. This class
+ * represents objects of dimension <code>structdim</code> (i.e. 1 for lines, 2
+ * for quads, 3 for hexes) in a triangulation of dimensionality
+ * <code>dim</code> (i.e. 1 for a triangulation of lines, 2 for a
+ * triangulation of quads, and 3 for a triangulation of hexes) that is
+ * embedded in a space of dimensionality <code>spacedim</code> (for
+ * <code>spacedim==dim</code> the triangulation represents a domain in
+ * $R^{dim}$, for <code>spacedim@>dim</code> the triangulation is of a
+ * manifold embedded in a higher dimensional space).
*
* @ingroup Accessors
* @author Wolfgang Bangerth and others, 1998, 2000, 2008
{
public:
/**
- * Propagate typedef from
- * base class to this class.
+ * Propagate typedef from base class to this class.
*/
typedef
typename TriaAccessorBase<structdim,dim,spacedim>::AccessorData
AccessorData;
/**
- * Constructor.
+ * Constructor.
*/
TriaAccessor (const Triangulation<dim,spacedim> *parent = 0,
const int level = -1,
const AccessorData *local_data = 0);
/**
- * Conversion constructor. This
- * constructor exists to make certain
- * constructs simpler to write in
- * dimension independent code. For
- * example, it allows assigning a face
- * iterator to a line iterator, an
- * operation that is useful in 2d but
- * doesn't make any sense in 3d. The
- * constructor here exists for the
- * purpose of making the code conform to
- * C++ but it will unconditionally abort;
- * in other words, assigning a face
- * iterator to a line iterator is better
- * put into an if-statement that checks
- * that the dimension is two, and assign
- * to a quad iterator in 3d (an operator
- * that, without this constructor would
- * be illegal if we happen to compile for
+ * Conversion constructor. This constructor exists to make certain
+ * constructs simpler to write in dimension independent code. For example,
+ * it allows assigning a face iterator to a line iterator, an operation that
+ * is useful in 2d but doesn't make any sense in 3d. The constructor here
+ * exists for the purpose of making the code conform to C++ but it will
+ * unconditionally abort; in other words, assigning a face iterator to a
+ * line iterator is better put into an if-statement that checks that the
+ * dimension is two, and assign to a quad iterator in 3d (an operator that,
+ * without this constructor would be illegal if we happen to compile for
* 2d).
*/
template <int structdim2, int dim2, int spacedim2>
TriaAccessor (const InvalidAccessor<structdim2,dim2,spacedim2> &);
/**
- * Another conversion operator
- * between objects that don't
- * make sense, just like the
- * previous one.
+ * Another conversion operator between objects that don't make sense, just
+ * like the previous one.
*/
template <int structdim2, int dim2, int spacedim2>
TriaAccessor (const TriaAccessor<structdim2,dim2,spacedim2> &);
/**
- * Test for the element being
- * used or not. The return
- * value is @p true for all
- * iterators that are either
- * normal iterators or active
- * iterators, only raw iterators
- * can return @p false. Since
- * raw iterators are only used
- * in the interiors of the
- * library, you will not usually
- * need this function.
+ * Test for the element being used or not. The return value is @p true for
+ * all iterators that are either normal iterators or active iterators, only
+ * raw iterators can return @p false. Since raw iterators are only used in
+ * the interiors of the library, you will not usually need this function.
*/
bool used () const;
/**
- * @name Accessing sub-objects
+ * @name Accessing sub-objects
*/
/**
* @{
*/
/**
- * Return the global index of i-th
- * vertex of the current object. The
- * convention regarding the numbering of
- * vertices is laid down in the
- * documentation of the GeometryInfo
- * class.
+ * Return the global index of i-th vertex of the current object. The
+ * convention regarding the numbering of vertices is laid down in the
+ * documentation of the GeometryInfo class.
*
- * Note that the returned value is only
- * the index of the geometrical
- * vertex. It has nothing to do with
- * possible degrees of freedom
- * associated with it. For this, see the
- * @p DoFAccessor::vertex_dof_index
- * functions.
+ * Note that the returned value is only the index of the geometrical vertex.
+ * It has nothing to do with possible degrees of freedom associated with it.
+ * For this, see the @p DoFAccessor::vertex_dof_index functions.
*
- * @note Despite the name, the index returned here is only
- * global in the sense that it is specific to a particular
- * Triangulation object or, in the case the triangulation is
- * actually of type parallel::distributed::Triangulation,
- * specific to that part of the distributed triangulation stored
- * on the current processor.
+ * @note Despite the name, the index returned here is only global in the
+ * sense that it is specific to a particular Triangulation object or, in the
+ * case the triangulation is actually of type
+ * parallel::distributed::Triangulation, specific to that part of the
+ * distributed triangulation stored on the current processor.
*/
unsigned int vertex_index (const unsigned int i) const;
/**
- * Return a reference to the
- * @p ith vertex. The reference is not const, i.e., it is possible
- * to call this function on the left hand side of an assignment,
- * thereby moving the vertex of a cell within the triangulation. Of
- * course, doing so requires that you ensure that the new location
- * of the vertex remains useful -- for example, avoiding inverted
- * or otherwise distorted (see also @ref GlossDistorted "this glossary entry").
- *
- * @note When a cell is refined, its children inherit the position
- * of the vertex positions of those vertices they share with the mother
- * cell (plus the locations of the new vertices on edges, faces, and
- * cell interiors that are created for the new child cells). If the
- * vertex of a cell is moved, this implies that its children will also
- * use these new locations. On the other hand, imagine a 2d situation
- * where you have one cell that is refined (with four children) and then
- * you move the central vertex connecting all four children. If you
- * coarsen these four children again to the mother cell, then the
- * location of the moved vertex is lost and if, in a later step, you
- * refine the mother cell again, the then again new vertex will be
- * placed again at the same position as the first time around -- i.e.,
- * not at the location you had previously moved it to.
- *
- * @note The behavior described above is relevant if
- * you have a parallel::distributed::Triangulation object. There,
- * refining a mesh always involves a re-partitioning. In other words,
- * vertices of locally owned cells (see
- * @ref GlossLocallyOwnedCell "this glossary entry")
- * that you may have moved to a different location on one processor
- * may be moved to a different processor upon mesh refinement (even
- * if these particular cells were not refined) which will re-create
- * their position based on the position of the coarse cells they
- * previously had, not based on the position these vertices had on
- * the processor that previously owned them. In other words, in
- * parallel computations, you will probably have to move nodes
- * explicitly after every mesh refinement because vertex positions
- * may or may not be preserved across the re-partitioning that
- * accompanies mesh refinement.
+ * Return a reference to the @p ith vertex. The reference is not const,
+ * i.e., it is possible to call this function on the left hand side of an
+ * assignment, thereby moving the vertex of a cell within the triangulation.
+ * Of course, doing so requires that you ensure that the new location of the
+ * vertex remains useful -- for example, avoiding inverted or otherwise
+ * distorted (see also @ref GlossDistorted "this glossary entry").
+ *
+ * @note When a cell is refined, its children inherit the position of the
+ * vertex positions of those vertices they share with the mother cell (plus
+ * the locations of the new vertices on edges, faces, and cell interiors
+ * that are created for the new child cells). If the vertex of a cell is
+ * moved, this implies that its children will also use these new locations.
+ * On the other hand, imagine a 2d situation where you have one cell that is
+ * refined (with four children) and then you move the central vertex
+ * connecting all four children. If you coarsen these four children again to
+ * the mother cell, then the location of the moved vertex is lost and if, in
+ * a later step, you refine the mother cell again, the then again new vertex
+ * will be placed again at the same position as the first time around --
+ * i.e., not at the location you had previously moved it to.
+ *
+ * @note The behavior described above is relevant if you have a
+ * parallel::distributed::Triangulation object. There, refining a mesh
+ * always involves a re-partitioning. In other words, vertices of locally
+ * owned cells (see @ref GlossLocallyOwnedCell "this glossary entry") that
+ * you may have moved to a different location on one processor may be moved
+ * to a different processor upon mesh refinement (even if these particular
+ * cells were not refined) which will re-create their position based on the
+ * position of the coarse cells they previously had, not based on the
+ * position these vertices had on the processor that previously owned them.
+ * In other words, in parallel computations, you will probably have to move
+ * nodes explicitly after every mesh refinement because vertex positions may
+ * or may not be preserved across the re-partitioning that accompanies mesh
+ * refinement.
*/
Point<spacedim> &vertex (const unsigned int i) const;
/**
- * Pointer to the @p ith line
- * bounding this object.
+ * Pointer to the @p ith line bounding this object.
*/
typename dealii::internal::Triangulation::Iterators<dim,spacedim>::line_iterator
line (const unsigned int i) const;
/**
- * Line index of the @p ith
- * line bounding this object.
+ * Line index of the @p ith line bounding this object.
*
- * Implemented only for
- * <tt>structdim>1</tt>,
- * otherwise an exception
+ * Implemented only for <tt>structdim>1</tt>, otherwise an exception
* generated.
*/
unsigned int line_index (const unsigned int i) const;
/**
- * Pointer to the @p ith quad
- * bounding this object.
+ * Pointer to the @p ith quad bounding this object.
*/
typename dealii::internal::Triangulation::Iterators<dim,spacedim>::quad_iterator
quad (const unsigned int i) const;
/**
- * Quad index of the @p ith
- * quad bounding this object.
+ * Quad index of the @p ith quad bounding this object.
*
- * Implemented only for
- * <tt>structdim>2</tt>,
- * otherwise an exception
+ * Implemented only for <tt>structdim>2</tt>, otherwise an exception
* generated.
*/
unsigned int quad_index (const unsigned int i) const;
*/
/**
- * @name Orientation of sub-objects
+ * @name Orientation of sub-objects
*/
/**
* @{
*/
/**
- * Return whether the face with
- * index @p face has its normal
- * pointing in the standard
- * direction (@p true) or
- * whether it is the opposite
- * (@p false). Which is the
- * standard direction is
- * documented with the
- * GeometryInfo class. In
- * 1d and 2d, this is always
- * @p true, but in 3d it may be
- * different, see the respective
- * discussion in the
- * documentation of the
+ * Return whether the face with index @p face has its normal pointing in the
+ * standard direction (@p true) or whether it is the opposite (@p false).
+ * Which is the standard direction is documented with the GeometryInfo
+ * class. In 1d and 2d, this is always @p true, but in 3d it may be
+ * different, see the respective discussion in the documentation of the
* GeometryInfo class.
*
- * This function is really only
- * for internal use in the
- * library unless you absolutely
- * know what this is all about.
+ * This function is really only for internal use in the library unless you
+ * absolutely know what this is all about.
*/
bool face_orientation (const unsigned int face) const;
/**
- * Return whether the face with index @p
- * face is rotated by 180 degrees (@p true)
- * or or not (@p false). In 1d and 2d, this
- * is always @p false, but in 3d it may be
- * different, see the respective discussion
- * in the documentation of the
- * GeometryInfo class.
+ * Return whether the face with index @p face is rotated by 180 degrees (@p
+ * true) or or not (@p false). In 1d and 2d, this is always @p false, but in
+ * 3d it may be different, see the respective discussion in the
+ * documentation of the GeometryInfo class.
*
- * This function is really only
- * for internal use in the
- * library unless you absolutely
- * know what this is all about.
+ * This function is really only for internal use in the library unless you
+ * absolutely know what this is all about.
*/
bool face_flip (const unsigned int face) const;
/**
- * Return whether the face with index @p
- * face is rotated by 90 degrees (@p true)
- * or or not (@p false). In 1d and 2d, this
- * is always @p false, but in 3d it may be
- * different, see the respective discussion
- * in the documentation of the
- * GeometryInfo class.
+ * Return whether the face with index @p face is rotated by 90 degrees (@p
+ * true) or or not (@p false). In 1d and 2d, this is always @p false, but in
+ * 3d it may be different, see the respective discussion in the
+ * documentation of the GeometryInfo class.
*
- * This function is really only
- * for internal use in the
- * library unless you absolutely
- * know what this is all about.
+ * This function is really only for internal use in the library unless you
+ * absolutely know what this is all about.
*/
bool face_rotation (const unsigned int face) const;
/**
- * Return whether the line with index @p
- * line is oriented in standard
- * direction. @p true indicates, that the
- * line is oriented from vertex 0 to vertex
- * 1, whereas it is the other way around
- * otherwise. In 1d and 2d, this is always
- * @p true, but in 3d it may be different,
- * see the respective discussion in the
- * documentation of the
- * GeometryInfo classe.
+ * Return whether the line with index @p line is oriented in standard
+ * direction. @p true indicates, that the line is oriented from vertex 0 to
+ * vertex 1, whereas it is the other way around otherwise. In 1d and 2d,
+ * this is always @p true, but in 3d it may be different, see the respective
+ * discussion in the documentation of the GeometryInfo classe.
*
- * This function is really only
- * for internal use in the
- * library unless you absolutely
- * know what this is all about.
+ * This function is really only for internal use in the library unless you
+ * absolutely know what this is all about.
*/
bool line_orientation (const unsigned int line) const;
/**
*/
/**
- * @name Accessing children
+ * @name Accessing children
*/
/**
* @{
*/
/**
- * Test whether the object has
- * children.
+ * Test whether the object has children.
*/
bool has_children () const;
/**
- * Return the number of immediate
- * children of this object. The
- * number of children of an
- * unrefined cell is zero.
+ * Return the number of immediate children of this object. The number of
+ * children of an unrefined cell is zero.
*/
unsigned int n_children() const;
/**
- * Compute and return the number
- * of active descendants of this
- * objects. For example, if all
- * of the eight children of a hex
- * are further refined
- * isotropically exactly once,
- * the returned number will be
- * 64, not 80.
- *
- * If the present cell is not
- * refined, one is returned.
- *
- * If one considers a triangulation as a
- * forest where the root of each tree are
- * the coarse mesh cells and nodes have
- * descendents (the children of a cell),
- * then this function returns the number
- * of terminal nodes in the sub-tree
- * originating from the current object;
- * consequently, if the current object is
- * not further refined, the answer is
- * one.
+ * Compute and return the number of active descendants of this objects. For
+ * example, if all of the eight children of a hex are further refined
+ * isotropically exactly once, the returned number will be 64, not 80.
+ *
+ * If the present cell is not refined, one is returned.
+ *
+ * If one considers a triangulation as a forest where the root of each tree
+ * are the coarse mesh cells and nodes have descendents (the children of a
+ * cell), then this function returns the number of terminal nodes in the
+ * sub-tree originating from the current object; consequently, if the
+ * current object is not further refined, the answer is one.
*/
unsigned int number_of_children () const;
/**
- * Return the number of times
- * that this object is
- * refined. Note that not all its
- * children are refined that
- * often (which is why we prepend
- * @p max_), the returned number
- * is rather the maximum number
- * of refinement in any branch of
- * children of this object.
- *
- * For example, if this object is
- * refined, and one of its children is
- * refined exactly one more time, then
- * <tt>max_refinement_depth</tt> should
+ * Return the number of times that this object is refined. Note that not all
+ * its children are refined that often (which is why we prepend @p max_),
+ * the returned number is rather the maximum number of refinement in any
+ * branch of children of this object.
+ *
+ * For example, if this object is refined, and one of its children is
+ * refined exactly one more time, then <tt>max_refinement_depth</tt> should
* return 2.
*
- * If this object is not refined (i.e. it
- * is active), then the return value is
- * zero.
+ * If this object is not refined (i.e. it is active), then the return value
+ * is zero.
*/
unsigned int max_refinement_depth () const;
/**
- * Return an iterator to the @p ith
- * child.
+ * Return an iterator to the @p ith child.
*/
TriaIterator<TriaAccessor<structdim,dim,spacedim> >
child (const unsigned int i) const;
/**
- * Return an iterator to that object
- * that is identical to the ith child
- * for isotropic refinement. If the
- * current object is refined
- * isotropically, then the returned
- * object is the ith child. If the
- * current object is refined
- * anisotropically, the returned child
- * may in fact be a grandchild of the
- * object, or may not exist at all (in
- * which case an exception is
- * generated).
+ * Return an iterator to that object that is identical to the ith child for
+ * isotropic refinement. If the current object is refined isotropically,
+ * then the returned object is the ith child. If the current object is
+ * refined anisotropically, the returned child may in fact be a grandchild
+ * of the object, or may not exist at all (in which case an exception is
+ * generated).
*/
TriaIterator<TriaAccessor<structdim,dim,spacedim> >
isotropic_child (const unsigned int i) const;
/**
- * Return the RefinementCase
- * of this cell.
+ * Return the RefinementCase of this cell.
*/
RefinementCase<structdim> refinement_case () const;
/**
- * Index of the @p ith child.
- * The level of the child is one
- * higher than that of the
- * present cell, if the children
- * of a cell are accessed. The
- * children of faces have no level.
- * If the child does not exist, -1
- * is returned.
+ * Index of the @p ith child. The level of the child is one higher than that
+ * of the present cell, if the children of a cell are accessed. The children
+ * of faces have no level. If the child does not exist, -1 is returned.
*/
int child_index (const unsigned int i) const;
/**
- * Index of the @p ith isotropic child.
- * See the isotropic_child() function
- * for a definition of this concept. If
- * the child does not exist, -1 is
- * returned.
+ * Index of the @p ith isotropic child. See the isotropic_child() function
+ * for a definition of this concept. If the child does not exist, -1 is
+ * returned.
*/
int isotropic_child_index (const unsigned int i) const;
/**
*/
/**
- * @name Dealing with boundary indicators
+ * @name Dealing with boundary indicators
*/
/**
* @{
*/
/**
- * Boundary indicator of this
- * object.
+ * Boundary indicator of this object.
*
- * If the return value is the special
- * value numbers::internal_face_boundary_id,
- * then this object is in the
- * interior of the domain.
+ * If the return value is the special value
+ * numbers::internal_face_boundary_id, then this object is in the interior
+ * of the domain.
*
* @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
*/
types::boundary_id boundary_indicator () const;
/**
- * Set the boundary indicator.
- * The same applies as for the
- * <tt>boundary_indicator()</tt>
- * function.
- *
- * Note that it only sets the
- * boundary object of the current
- * object itself, not the
- * indicators of the ones that
- * bound it. For example, in 3d,
- * if this function is called on
- * a face, then the boundary
- * indicator of the 4 edges that
- * bound the face remain
- * unchanged. If you want to set
- * the boundary indicators of
- * face and edges at the same
- * time, use the
- * set_all_boundary_indicators()
- * function. You can see the result of not using the correct function in the
- * results section of step-49.
- *
- * @warning You should never set the
- * boundary indicator of an interior face
- * (a face not at the boundary of the
- * domain), or set set the boundary
- * indicator of an exterior face to
- * numbers::internal_face_boundary_id
- * (this value is reserved for another
- * purpose). Algorithms may not work or
- * produce very confusing results if
- * boundary cells have a boundary
- * indicator of numbers::internal_face_boundary_id
- * or if interior cells have boundary
- * indicators other than numbers::internal_face_boundary_id.
- * Unfortunately, the current object
- * has no means of finding out whether it
- * really is at the boundary of the
- * domain and so cannot determine whether
- * the value you are trying to set makes
- * sense under the current circumstances.
+ * Set the boundary indicator. The same applies as for the
+ * <tt>boundary_indicator()</tt> function.
+ *
+ * Note that it only sets the boundary object of the current object itself,
+ * not the indicators of the ones that bound it. For example, in 3d, if this
+ * function is called on a face, then the boundary indicator of the 4 edges
+ * that bound the face remain unchanged. If you want to set the boundary
+ * indicators of face and edges at the same time, use the
+ * set_all_boundary_indicators() function. You can see the result of not
+ * using the correct function in the results section of step-49.
+ *
+ * @warning You should never set the boundary indicator of an interior face
+ * (a face not at the boundary of the domain), or set set the boundary
+ * indicator of an exterior face to numbers::internal_face_boundary_id (this
+ * value is reserved for another purpose). Algorithms may not work or
+ * produce very confusing results if boundary cells have a boundary
+ * indicator of numbers::internal_face_boundary_id or if interior cells have
+ * boundary indicators other than numbers::internal_face_boundary_id.
+ * Unfortunately, the current object has no means of finding out whether it
+ * really is at the boundary of the domain and so cannot determine whether
+ * the value you are trying to set makes sense under the current
+ * circumstances.
*
* @ingroup boundary
*
void set_boundary_indicator (const types::boundary_id) const;
/**
- * Do as set_boundary_indicator()
- * but also set the boundary
- * indicators of the objects that
- * bound the current object. For
- * example, in 3d, if
- * set_boundary_indicator() is
- * called on a face, then the
- * boundary indicator of the 4
- * edges that bound the face
- * remain unchanged. In contrast, if you call the current function,
- * the boundary indicators
- * of face and edges are all set to the given value.
- *
- * This function is useful if you set boundary indicators of faces
- * in 3d (in 2d, the function does the same as set_boundary_indicator())
- * and you do so because you want a curved boundary object to
- * represent the part of the boundary that corresponds to the
- * current face. In that case, the Triangulation class needs to figure
- * out where to put new vertices upon mesh refinement, and higher order
- * Mapping objects also need to figure out where new interpolation points
- * for a curved boundary approximation should be. In either case, the
- * two classes first determine where interpolation points on the edges
- * of a boundary face should be, asking the boundary object, before
- * asking the boundary object for the interpolation points corresponding
- * to the interior of the boundary face. For this to work properly, it is
- * not sufficient to have set the boundary indicator for the face alone,
- * but you also need to set the boundary indicators of the edges that
- * bound the face. This function does all of this at once. You can see
- * the result of not using the correct function in the
- * results section of step-49.
+ * Do as set_boundary_indicator() but also set the boundary indicators of
+ * the objects that bound the current object. For example, in 3d, if
+ * set_boundary_indicator() is called on a face, then the boundary indicator
+ * of the 4 edges that bound the face remain unchanged. In contrast, if you
+ * call the current function, the boundary indicators of face and edges are
+ * all set to the given value.
+ *
+ * This function is useful if you set boundary indicators of faces in 3d (in
+ * 2d, the function does the same as set_boundary_indicator()) and you do so
+ * because you want a curved boundary object to represent the part of the
+ * boundary that corresponds to the current face. In that case, the
+ * Triangulation class needs to figure out where to put new vertices upon
+ * mesh refinement, and higher order Mapping objects also need to figure out
+ * where new interpolation points for a curved boundary approximation should
+ * be. In either case, the two classes first determine where interpolation
+ * points on the edges of a boundary face should be, asking the boundary
+ * object, before asking the boundary object for the interpolation points
+ * corresponding to the interior of the boundary face. For this to work
+ * properly, it is not sufficient to have set the boundary indicator for the
+ * face alone, but you also need to set the boundary indicators of the edges
+ * that bound the face. This function does all of this at once. You can see
+ * the result of not using the correct function in the results section of
+ * step-49.
*
* @ingroup boundary
*
void set_all_boundary_indicators (const types::boundary_id) const;
/**
- * Return whether this object is at the
- * boundary. Obviously, the use of this
- * function is only possible for
- * <tt>dim@>structdim</tt>; however, for
- * <tt>dim==structdim</tt>, an object is a
- * cell and the CellAccessor class offers
- * another possibility to determine
- * whether a cell is at the boundary or
- * not.
+ * Return whether this object is at the boundary. Obviously, the use of this
+ * function is only possible for <tt>dim@>structdim</tt>; however, for
+ * <tt>dim==structdim</tt>, an object is a cell and the CellAccessor class
+ * offers another possibility to determine whether a cell is at the boundary
+ * or not.
*/
bool at_boundary () const;
/**
- * Return a constant reference to the manifold object used for this
- * object. This function exists for backward compatibility and calls
- * get_manifold() internally.
+ * Return a constant reference to the manifold object used for this object.
+ * This function exists for backward compatibility and calls get_manifold()
+ * internally.
*/
const Boundary<dim,spacedim> &get_boundary () const;
/**
* Return a constant reference to the manifold object used for this object.
*
- * As explained in
- * @ref boundary "Boundary and manifold description for triangulations",
- * the process involved in finding the appropriate manifold description
- * involves querying both the manifold or boundary indicators. See there
- * for more information.
+ * As explained in @ref boundary "Boundary and manifold description for
+ * triangulations", the process involved in finding the appropriate manifold
+ * description involves querying both the manifold or boundary indicators.
+ * See there for more information.
*/
const Manifold<dim,spacedim> &get_manifold () const;
*/
/**
- * @name Dealing with manifold indicators
+ * @name Dealing with manifold indicators
*/
/**
* @{
*/
/**
- * Return the manifold indicator of this
- * object.
+ * Return the manifold indicator of this object.
*
- * If the return value is the special value
- * numbers::flat_manifold_id, then this object is associated with a
- * standard Cartesian Manifold Description.
+ * If the return value is the special value numbers::flat_manifold_id, then
+ * this object is associated with a standard Cartesian Manifold Description.
*
* @see @ref GlossManifoldIndicator "Glossary entry on manifold indicators"
*/
* Set the manifold indicator. The same applies as for the
* <tt>manifold_id()</tt> function.
*
- * Note that it only sets the manifold object of the current object
- * itself, not the indicators of the ones that bound it, nor of its
- * children. For example, in 3d, if this function is called on a
- * face, then the manifold indicator of the 4 edges that bound the
- * face remain unchanged. If you want to set the manifold indicators
- * of face, edges and all children at the same time, use the
- * set_all_manifold_ids() function.
+ * Note that it only sets the manifold object of the current object itself,
+ * not the indicators of the ones that bound it, nor of its children. For
+ * example, in 3d, if this function is called on a face, then the manifold
+ * indicator of the 4 edges that bound the face remain unchanged. If you
+ * want to set the manifold indicators of face, edges and all children at
+ * the same time, use the set_all_manifold_ids() function.
*
*
* @ingroup manifold
void set_manifold_id (const types::manifold_id) const;
/**
- * Do as set_manifold_id()
- * but also set the manifold
- * indicators of the objects that
- * bound the current object. For
- * example, in 3d, if
- * set_manifold_id() is
- * called on a face, then the
- * manifold indicator of the 4
- * edges that bound the face
- * remain unchanged. On the other
- * hand, the manifold indicators
- * of face and edges are all set
- * at the same time using the
- * current function.
+ * Do as set_manifold_id() but also set the manifold indicators of the
+ * objects that bound the current object. For example, in 3d, if
+ * set_manifold_id() is called on a face, then the manifold indicator of the
+ * 4 edges that bound the face remain unchanged. On the other hand, the
+ * manifold indicators of face and edges are all set at the same time using
+ * the current function.
*
* @ingroup manifold
*
* @{
*/
/**
- * Read the user flag.
- * See @ref GlossUserFlags for more information.
+ * Read the user flag. See @ref GlossUserFlags for more information.
*/
bool user_flag_set () const;
/**
- * Set the user flag.
- * See @ref GlossUserFlags for more information.
+ * Set the user flag. See @ref GlossUserFlags for more information.
*/
void set_user_flag () const;
/**
- * Clear the user flag.
- * See @ref GlossUserFlags for more information.
+ * Clear the user flag. See @ref GlossUserFlags for more information.
*/
void clear_user_flag () const;
/**
- * Set the user flag for this
- * and all descendants.
- * See @ref GlossUserFlags for more information.
+ * Set the user flag for this and all descendants. See @ref GlossUserFlags
+ * for more information.
*/
void recursively_set_user_flag () const;
/**
- * Clear the user flag for this
- * and all descendants.
- * See @ref GlossUserFlags for more information.
+ * Clear the user flag for this and all descendants. See @ref GlossUserFlags
+ * for more information.
*/
void recursively_clear_user_flag () const;
/**
- * Reset the user data to zero,
- * independent if pointer or index.
- * See @ref GlossUserData for more information.
+ * Reset the user data to zero, independent if pointer or index. See @ref
+ * GlossUserData for more information.
*/
void clear_user_data () const;
/**
- * Set the user pointer
- * to @p p.
+ * Set the user pointer to @p p.
+ *
+ * @note User pointers and user indices are mutually exclusive. Therefore,
+ * you can only use one of them, unless you call
+ * Triangulation::clear_user_data() in between.
*
- * @note User pointers and user
- * indices are mutually
- * exclusive. Therefore, you can
- * only use one of them, unless
- * you call
- * Triangulation::clear_user_data()
- * in between.
- *
- * See @ref GlossUserData for more information.
+ * See @ref GlossUserData for more information.
*/
void set_user_pointer (void *p) const;
/**
- * Reset the user pointer
- * to a @p NULL pointer.
- * See @ref GlossUserData for more information.
+ * Reset the user pointer to a @p NULL pointer. See @ref GlossUserData for
+ * more information.
*/
void clear_user_pointer () const;
/**
- * Access the value of the user
- * pointer. It is in the
- * responsibility of the user to
- * make sure that the pointer
- * points to something
- * useful. You should use the new
- * style cast operator to
- * maintain a minimum of
- * typesafety, e.g.
- *
- * @note User pointers and user
- * indices are mutually
- * exclusive. Therefore, you can
- * only use one of them, unless
- * you call
- * Triangulation::clear_user_data()
- * in between.
- * <tt>A *a=static_cast<A*>(cell->user_pointer());</tt>.
- *
- * See @ref GlossUserData for more information.
+ * Access the value of the user pointer. It is in the responsibility of the
+ * user to make sure that the pointer points to something useful. You should
+ * use the new style cast operator to maintain a minimum of typesafety, e.g.
+ *
+ * @note User pointers and user indices are mutually exclusive. Therefore,
+ * you can only use one of them, unless you call
+ * Triangulation::clear_user_data() in between. <tt>A
+ * *a=static_cast<A*>(cell->user_pointer());</tt>.
+ *
+ * See @ref GlossUserData for more information.
*/
void *user_pointer () const;
/**
- * Set the user pointer of this
- * object and all its children to
- * the given value. This is
- * useful for example if all
- * cells of a certain subdomain,
- * or all faces of a certain part
- * of the boundary should have
- * user pointers pointing to
- * objects describing this part
- * of the domain or boundary.
- *
- * Note that the user pointer is
- * not inherited under mesh
- * refinement, so after mesh
- * refinement there might be
- * cells or faces that don't have
- * user pointers pointing to the
- * describing object. In this
- * case, simply loop over all the
- * elements of the coarsest level
- * that has this information, and
- * use this function to
- * recursively set the user
- * pointer of all finer levels of
- * the triangulation.
+ * Set the user pointer of this object and all its children to the given
+ * value. This is useful for example if all cells of a certain subdomain, or
+ * all faces of a certain part of the boundary should have user pointers
+ * pointing to objects describing this part of the domain or boundary.
*
- * @note User pointers and user
- * indices are mutually
- * exclusive. Therefore, you can
- * only use one of them, unless
- * you call
- * Triangulation::clear_user_data()
- * in between.
- *
- * See @ref GlossUserData for more information.
+ * Note that the user pointer is not inherited under mesh refinement, so
+ * after mesh refinement there might be cells or faces that don't have user
+ * pointers pointing to the describing object. In this case, simply loop
+ * over all the elements of the coarsest level that has this information,
+ * and use this function to recursively set the user pointer of all finer
+ * levels of the triangulation.
+ *
+ * @note User pointers and user indices are mutually exclusive. Therefore,
+ * you can only use one of them, unless you call
+ * Triangulation::clear_user_data() in between.
+ *
+ * See @ref GlossUserData for more information.
*/
void recursively_set_user_pointer (void *p) const;
/**
- * Clear the user pointer of this
- * object and all of its
- * descendants. The same holds as
- * said for the
- * recursively_set_user_pointer()
- * function.
- * See @ref GlossUserData for more information.
+ * Clear the user pointer of this object and all of its descendants. The
+ * same holds as said for the recursively_set_user_pointer() function. See
+ * @ref GlossUserData for more information.
*/
void recursively_clear_user_pointer () const;
/**
- * Set the user index
- * to @p p.
+ * Set the user index to @p p.
*
- * @note User pointers and user
- * indices are mutually
- * exclusive. Therefore, you can
- * only use one of them, unless
- * you call
- * Triangulation::clear_user_data()
- * in between.
- * See @ref GlossUserData for more information.
+ * @note User pointers and user indices are mutually exclusive. Therefore,
+ * you can only use one of them, unless you call
+ * Triangulation::clear_user_data() in between. See @ref GlossUserData for
+ * more information.
*/
void set_user_index (const unsigned int p) const;
/**
- * Reset the user index to 0.
- * See @ref GlossUserData for more information.
+ * Reset the user index to 0. See @ref GlossUserData for more information.
*/
void clear_user_index () const;
/**
- * Access the value of the user
- * index.
+ * Access the value of the user index.
+ *
+ * @note User pointers and user indices are mutually exclusive. Therefore,
+ * you can only use one of them, unless you call
+ * Triangulation::clear_user_data() in between.
*
- * @note User pointers and user
- * indices are mutually
- * exclusive. Therefore, you can
- * only use one of them, unless
- * you call
- * Triangulation::clear_user_data()
- * in between.
- *
- * See @ref GlossUserData for more information.
+ * See @ref GlossUserData for more information.
*/
unsigned int user_index () const;
/**
- * Set the user index of this
- * object and all its children.
- *
- * Note that the user index is
- * not inherited under mesh
- * refinement, so after mesh
- * refinement there might be
- * cells or faces that don't have
- * the expected user indices. In
- * this case, simply loop over
- * all the elements of the
- * coarsest level that has this
- * information, and use this
- * function to recursively set
- * the user index of all finer
- * levels of the triangulation.
+ * Set the user index of this object and all its children.
+ *
+ * Note that the user index is not inherited under mesh refinement, so after
+ * mesh refinement there might be cells or faces that don't have the
+ * expected user indices. In this case, simply loop over all the elements of
+ * the coarsest level that has this information, and use this function to
+ * recursively set the user index of all finer levels of the triangulation.
*
- * @note User pointers and user
- * indices are mutually
- * exclusive. Therefore, you can
- * only use one of them, unless
- * you call
- * Triangulation::clear_user_data()
- * in between.
- *
- * See @ref GlossUserData for more information.
+ * @note User pointers and user indices are mutually exclusive. Therefore,
+ * you can only use one of them, unless you call
+ * Triangulation::clear_user_data() in between.
+ *
+ * See @ref GlossUserData for more information.
*/
void recursively_set_user_index (const unsigned int p) const;
/**
- * Clear the user index of this
- * object and all of its
- * descendants. The same holds as
- * said for the
- * recursively_set_user_index()
- * function.
- *
- * See @ref GlossUserData for more information.
+ * Clear the user index of this object and all of its descendants. The same
+ * holds as said for the recursively_set_user_index() function.
+ *
+ * See @ref GlossUserData for more information.
*/
void recursively_clear_user_index () const;
/**
/**
* Diameter of the object.
*
- * The diameter of an object is computed
- * to be the largest diagonal. This is
- * not necessarily the true diameter for
- * objects that may use higher order
- * mappings, but completely sufficient
- * for most computations.
+ * The diameter of an object is computed to be the largest diagonal. This is
+ * not necessarily the true diameter for objects that may use higher order
+ * mappings, but completely sufficient for most computations.
*/
double diameter () const;
/**
- * Length of an object in the direction
- * of the given axis, specified in the
- * local coordinate system. See the
- * documentation of GeometryInfo for the
- * meaning and enumeration of the local
- * axes.
+ * Length of an object in the direction of the given axis, specified in the
+ * local coordinate system. See the documentation of GeometryInfo for the
+ * meaning and enumeration of the local axes.
*
- * Note that the "length" of an object
- * can be interpreted in a variety of
- * ways. Here, we choose it as the
- * maximal length of any of the edges of
- * the object that are parallel to the
- * chosen axis on the reference cell.
+ * Note that the "length" of an object can be interpreted in a variety of
+ * ways. Here, we choose it as the maximal length of any of the edges of the
+ * object that are parallel to the chosen axis on the reference cell.
*/
double extent_in_direction (const unsigned int axis) const;
/**
- * Returns the minimal distance between
- * any two vertices.
+ * Returns the minimal distance between any two vertices.
*/
double minimum_vertex_distance () const;
/**
- * Returns a point belonging to the Manifold<dim,spacedim> where
- * this object lives, given its parametric coordinates on the
- * reference #structdim cell. This function queries the underlying
- * manifold object, and can be used to obtain the exact geometrical
- * location of arbitrary points on this object.
+ * Returns a point belonging to the Manifold<dim,spacedim> where this object
+ * lives, given its parametric coordinates on the reference #structdim cell.
+ * This function queries the underlying manifold object, and can be used to
+ * obtain the exact geometrical location of arbitrary points on this object.
*
- * Notice that the argument @p coordinates are the coordinates on
- * the <emph>reference cell</emph>, given in reference
- * coordinates. In other words, the argument provides a weighting
- * between the different vertices. For example, for lines, calling
- * this function with argument Point<1>(.5), is equivalent to asking
- * the line for its center.
+ * Notice that the argument @p coordinates are the coordinates on the
+ * <emph>reference cell</emph>, given in reference coordinates. In other
+ * words, the argument provides a weighting between the different vertices.
+ * For example, for lines, calling this function with argument Point<1>(.5),
+ * is equivalent to asking the line for its center.
*/
Point<spacedim> intermediate_point(const Point<structdim> &coordinates) const;
/**
- * Center of the object. The center of an object is defined to be
- * the average of the locations of the vertices. If required, the
- * user may ask this function to return the average of the point
- * according to the underlyinging Manifold object, by setting to
- * true the optional parameter @p respect_manifold.
- *
- * When the geometry of a TriaAccessor is not flat, or when part of
- * the bounding objects of this TriaAccessor are not flat, the
- * result given by the TriaAccessor::center() function may not be
- * accurate enough, even when parameter @p respect_manifold is set
- * to true. If you find this to be case, than you can further refine
- * the computation of the center by setting to true the second
- * additional parameter @p use_laplace_transformation, which will
- * force this function to compute the location of the center by
- * solving a linear elasticity problem with Dirichlet boundary
- * conditions set to the location of the bounding vertices and the
- * centers of the bounding lines and quads.
+ * Center of the object. The center of an object is defined to be the
+ * average of the locations of the vertices. If required, the user may ask
+ * this function to return the average of the point according to the
+ * underlyinging Manifold object, by setting to true the optional parameter
+ * @p respect_manifold.
+ *
+ * When the geometry of a TriaAccessor is not flat, or when part of the
+ * bounding objects of this TriaAccessor are not flat, the result given by
+ * the TriaAccessor::center() function may not be accurate enough, even when
+ * parameter @p respect_manifold is set to true. If you find this to be
+ * case, than you can further refine the computation of the center by
+ * setting to true the second additional parameter @p
+ * use_laplace_transformation, which will force this function to compute the
+ * location of the center by solving a linear elasticity problem with
+ * Dirichlet boundary conditions set to the location of the bounding
+ * vertices and the centers of the bounding lines and quads.
*/
Point<spacedim> center (const bool respect_manifold=false,
const bool use_laplace_transformation=false) const;
Point<spacedim> barycenter () const;
/**
- * Compute the dim-dimensional measure of the object. For a
- * dim-dimensional cell in dim-dimensional space, this equals its
- * volume. On the other hand, for a 2d cell in 3d space, or if the
- * current object pointed to is a 2d face of a 3d cell in 3d space,
- * then the function computes the area the object occupies. For a
- * one-dimensional object, return its length.
- *
- * The function only computes the measure of cells, faces or edges
- * assumed to be represented by (bi-/tri-)linear mappings. In other
- * words, it only takes into account the locations of the vertices
- * that bound the current object but not how the interior of the
- * object may actually be mapped. In most simple cases, this is
- * exactly what you want. However, for objects that are not
- * "straight", e.g. 2d cells embedded in 3d space as part of a
- * triangulation of a curved domain, two-dimensional faces of 3d
- * cells that are not just parallelograms, or for faces that are at
- * the boundary of a domain that is not just bounded by straight
- * line segments or planes, this function only computes the
- * dim-dimensional measure of a (bi-/tri-)linear interpolation of
- * the "real" object as defined by the manifold or boundary object
- * describing the real geometry of the object in question. If you
- * want to consider the "real" geometry, you will need to compute
- * the measure by integrating a function equal to one over the
- * object, which after applying quadrature equals the summing the
- * JxW values returned by the FEValues or FEFaceValues object you
- * will want to use for the integral.
+ * Compute the dim-dimensional measure of the object. For a dim-dimensional
+ * cell in dim-dimensional space, this equals its volume. On the other hand,
+ * for a 2d cell in 3d space, or if the current object pointed to is a 2d
+ * face of a 3d cell in 3d space, then the function computes the area the
+ * object occupies. For a one-dimensional object, return its length.
+ *
+ * The function only computes the measure of cells, faces or edges assumed
+ * to be represented by (bi-/tri-)linear mappings. In other words, it only
+ * takes into account the locations of the vertices that bound the current
+ * object but not how the interior of the object may actually be mapped. In
+ * most simple cases, this is exactly what you want. However, for objects
+ * that are not "straight", e.g. 2d cells embedded in 3d space as part of a
+ * triangulation of a curved domain, two-dimensional faces of 3d cells that
+ * are not just parallelograms, or for faces that are at the boundary of a
+ * domain that is not just bounded by straight line segments or planes, this
+ * function only computes the dim-dimensional measure of a (bi-/tri-)linear
+ * interpolation of the "real" object as defined by the manifold or boundary
+ * object describing the real geometry of the object in question. If you
+ * want to consider the "real" geometry, you will need to compute the
+ * measure by integrating a function equal to one over the object, which
+ * after applying quadrature equals the summing the JxW values returned by
+ * the FEValues or FEFaceValues object you will want to use for the
+ * integral.
*/
double measure () const;
/**
- * Return true if the current object is a
- * translation of the given argument.
- *
- * @note For the purpose of a
- * triangulation, cells, faces, etc are
- * only characterized by their
- * vertices. The current function
- * therefore only compares the locations
- * of vertices. For many practical
- * applications, however, it is not only
- * the vertices that determine whether
- * one cell is a translation of another,
- * but also how the cell is mapped from
- * the reference cell to its location in
- * real space. For example, if we are
- * using higher order mappings, then not
- * only do the vertices have to be
- * translations of each other, but also
- * the points along edges. In these
- * questions, therefore, it would be
- * appropriate to ask the mapping, not
- * the current function, whether two
- * objects are translations of each
- * other.
+ * Return true if the current object is a translation of the given argument.
+ *
+ * @note For the purpose of a triangulation, cells, faces, etc are only
+ * characterized by their vertices. The current function therefore only
+ * compares the locations of vertices. For many practical applications,
+ * however, it is not only the vertices that determine whether one cell is a
+ * translation of another, but also how the cell is mapped from the
+ * reference cell to its location in real space. For example, if we are
+ * using higher order mappings, then not only do the vertices have to be
+ * translations of each other, but also the points along edges. In these
+ * questions, therefore, it would be appropriate to ask the mapping, not the
+ * current function, whether two objects are translations of each other.
*/
bool
is_translation_of (const TriaIterator<TriaAccessor<structdim,dim,spacedim> > &o) const;
private:
/**
- * Copy the data of the given
- * object into the internal data
- * structures of a
- * triangulation.
+ * Copy the data of the given object into the internal data structures of a
+ * triangulation.
*/
void set (const dealii::internal::Triangulation::TriaObject<structdim> &o) const;
/**
- * Set the flag indicating, what
- * <code>line_orientation()</code> will
+ * Set the flag indicating, what <code>line_orientation()</code> will
* return.
*
- * It is only possible to set the
- * line_orientation of faces in 3d
- * (i.e. <code>structdim==2 &&
- * dim==3</code>).
+ * It is only possible to set the line_orientation of faces in 3d (i.e.
+ * <code>structdim==2 && dim==3</code>).
*/
void set_line_orientation (const unsigned int line,
const bool orientation) const;
/**
- * Set whether the quad with
- * index @p face has its normal
- * pointing in the standard
- * direction (@p true) or
- * whether it is the opposite
- * (@p false). Which is the
- * standard direction is
- * documented with the
- * GeometryInfo class.
+ * Set whether the quad with index @p face has its normal pointing in the
+ * standard direction (@p true) or whether it is the opposite (@p false).
+ * Which is the standard direction is documented with the GeometryInfo
+ * class.
*
- * This function is only for
- * internal use in the
- * library. Setting this flag to
- * any other value than the one
- * that the triangulation has
- * already set is bound to bring
- * you desaster.
+ * This function is only for internal use in the library. Setting this flag
+ * to any other value than the one that the triangulation has already set is
+ * bound to bring you desaster.
*/
void set_face_orientation (const unsigned int face,
const bool orientation) const;
/**
- * Set the flag indicating, what
- * <code>face_flip()</code> will
- * return.
+ * Set the flag indicating, what <code>face_flip()</code> will return.
*
- * It is only possible to set the
- * face_orientation of cells in 3d
- * (i.e. <code>structdim==3 &&
- * dim==3</code>).
+ * It is only possible to set the face_orientation of cells in 3d (i.e.
+ * <code>structdim==3 && dim==3</code>).
*/
void set_face_flip (const unsigned int face,
const bool flip) const;
/**
- * Set the flag indicating, what
- * <code>face_rotation()</code> will
- * return.
+ * Set the flag indicating, what <code>face_rotation()</code> will return.
*
- * It is only possible to set the
- * face_orientation of cells in 3d
- * (i.e. <code>structdim==3 &&
- * dim==3</code>).
+ * It is only possible to set the face_orientation of cells in 3d (i.e.
+ * <code>structdim==3 && dim==3</code>).
*/
void set_face_rotation (const unsigned int face,
const bool rotation) const;
/**
- * Set the @p used flag. Only
- * for internal use in the
- * library.
+ * Set the @p used flag. Only for internal use in the library.
*/
void set_used_flag () const;
/**
- * Clear the @p used flag. Only
- * for internal use in the
- * library.
+ * Clear the @p used flag. Only for internal use in the library.
*/
void clear_used_flag () const;
/**
- * Set the @p RefinementCase<dim> this
- * TriaObject is refined with.
- * Not defined for
- * <tt>structdim=1</tt> as lines
- * are always refined resulting
- * in 2 children lines (isotropic
- * refinement).
+ * Set the @p RefinementCase<dim> this TriaObject is refined with. Not
+ * defined for <tt>structdim=1</tt> as lines are always refined resulting in
+ * 2 children lines (isotropic refinement).
*
- * You should know quite exactly
- * what you are doing if you
- * touch this function. It is
- * exclusively for internal use
- * in the library.
+ * You should know quite exactly what you are doing if you touch this
+ * function. It is exclusively for internal use in the library.
*/
void set_refinement_case (const RefinementCase<structdim> &ref_case) const;
/**
- * Clear the RefinementCase<dim> of
- * this TriaObject, i.e. reset it
- * to RefinementCase<dim>::no_refinement.
+ * Clear the RefinementCase<dim> of this TriaObject, i.e. reset it to
+ * RefinementCase<dim>::no_refinement.
*
- * You should know quite exactly
- * what you are doing if you
- * touch this function. It is
- * exclusively for internal use
- * in the library.
+ * You should know quite exactly what you are doing if you touch this
+ * function. It is exclusively for internal use in the library.
*/
void clear_refinement_case () const;
/**
- * Set the index of the ith
- * child. Since the children
- * come at least in pairs, we
- * need to store the index of
- * only every second child,
- * i.e. of the even numbered
- * children. Make sure, that the
- * index of child i=0 is set
- * first. Calling this function
- * for odd numbered children is
- * not allowed.
+ * Set the index of the ith child. Since the children come at least in
+ * pairs, we need to store the index of only every second child, i.e. of the
+ * even numbered children. Make sure, that the index of child i=0 is set
+ * first. Calling this function for odd numbered children is not allowed.
*/
void set_children (const unsigned int i, const int index) const;
/**
- * Clear the child field,
- * i.e. set it to a value which
- * indicates that this cell has
- * no children.
+ * Clear the child field, i.e. set it to a value which indicates that this
+ * cell has no children.
*/
void clear_children () const;
private:
/**
- * Copy operator. This is normally used
- * in a context like <tt>iterator a,b;
- * *a=*b;</tt>. Presumably, the intent
- * here is to copy the object pointed to
- * by @p b to the object pointed to by
- * @p a. However, the result of
- * dereferencing an iterator is not an
- * object but an accessor; consequently,
- * this operation is not useful for
- * iterators on triangulations. We
- * declare this function here private,
- * thus it may not be used from outside.
- * Furthermore it is not implemented and
- * will give a linker error if used
- * anyway.
+ * Copy operator. This is normally used in a context like <tt>iterator a,b;
+ * *a=*b;</tt>. Presumably, the intent here is to copy the object pointed to
+ * by @p b to the object pointed to by @p a. However, the result of
+ * dereferencing an iterator is not an object but an accessor; consequently,
+ * this operation is not useful for iterators on triangulations. We declare
+ * this function here private, thus it may not be used from outside.
+ * Furthermore it is not implemented and will give a linker error if used
+ * anyway.
*/
void operator = (const TriaAccessor &);
/**
- * Closure class to stop induction of classes. Should never be called
- * and thus produces an error when created.
+ * Closure class to stop induction of classes. Should never be called and thus
+ * produces an error when created.
*
* @ingroup grid
*/
{
private:
/**
- * Constructor. Made private to
- * make sure that this class
- * can't be used.
+ * Constructor. Made private to make sure that this class can't be used.
*/
TriaAccessor ();
};
/**
- * A class that represents an access to a face in 1d -- i.e. to a
- * point. This is not a full fledged access from which you can build
- * an iterator: for example, you can't iterate from one such point to
- * the next. Point also don't have children, and they don't have
- * neighbors.
+ * A class that represents an access to a face in 1d -- i.e. to a point. This
+ * is not a full fledged access from which you can build an iterator: for
+ * example, you can't iterate from one such point to the next. Point also
+ * don't have children, and they don't have neighbors.
*
* @author Wolfgang Bangerth, 2010
*/
{
public:
/**
- * Dimension of the space the
- * object represented by this
- * accessor lives in. For
- * example, if this accessor
- * represents a quad that is
- * part of a two-dimensional
- * surface in four-dimensional
- * space, then this value is
- * four.
+ * Dimension of the space the object represented by this accessor lives in.
+ * For example, if this accessor represents a quad that is part of a two-
+ * dimensional surface in four-dimensional space, then this value is four.
*/
static const unsigned int space_dimension = spacedim;
/**
- * Dimensionality of the object
- * that the thing represented by
- * this accessopr is part of. For
- * example, if this accessor
- * represents a line that is part
- * of a hexahedron, then this
- * value will be three.
+ * Dimensionality of the object that the thing represented by this accessopr
+ * is part of. For example, if this accessor represents a line that is part
+ * of a hexahedron, then this value will be three.
*/
static const unsigned int dimension = 1;
/**
- * Dimensionality of the current
- * object represented by this
- * accessor. For example, if it
- * is line (irrespective of
- * whether it is part of a quad
- * or hex, and what dimension we
- * are in), then this value
- * equals 1.
+ * Dimensionality of the current object represented by this accessor. For
+ * example, if it is line (irrespective of whether it is part of a quad or
+ * hex, and what dimension we are in), then this value equals 1.
*/
static const unsigned int structure_dimension = 0;
typedef void AccessorData;
/**
- * Whether the vertex represented
- * here is at the left end of the
- * domain, the right end, or in
- * the interior.
+ * Whether the vertex represented here is at the left end of the domain, the
+ * right end, or in the interior.
*/
enum VertexKind
{
/**
* Constructor.
*
- * Since there is no mapping from
- * vertices to cells, an accessor
- * object for a point has no way
- * to figure out whether it is at
- * the boundary of the domain or
- * not. Consequently, the second
- * argument must be passed by the
- * object that generates this
- * accessor -- e.g. a 1d cell
- * that can figure out whether
- * its left or right vertex are
- * at the boundary.
- *
- * The third argument is the
- * global index of the vertex we
- * point to.
+ * Since there is no mapping from vertices to cells, an accessor object for
+ * a point has no way to figure out whether it is at the boundary of the
+ * domain or not. Consequently, the second argument must be passed by the
+ * object that generates this accessor -- e.g. a 1d cell that can figure out
+ * whether its left or right vertex are at the boundary.
+ *
+ * The third argument is the global index of the vertex we point to.
*/
TriaAccessor (const Triangulation<1,spacedim> *tria,
const VertexKind vertex_kind,
const unsigned int vertex_index);
/**
- * Constructor. This constructor
- * exists in order to maintain
- * interface compatibility with
- * the other accessor
- * classes. However, it doesn't
- * do anything useful here and so
- * may not actually be called.
+ * Constructor. This constructor exists in order to maintain interface
+ * compatibility with the other accessor classes. However, it doesn't do
+ * anything useful here and so may not actually be called.
*/
TriaAccessor (const Triangulation<1,spacedim> *tria = 0,
const int = 0,
const AccessorData * = 0);
/**
- * Constructor. Should never be
- * called and thus produces an
- * error.
+ * Constructor. Should never be called and thus produces an error.
*/
template <int structdim2, int dim2, int spacedim2>
TriaAccessor (const TriaAccessor<structdim2,dim2,spacedim2> &);
/**
- * Constructor. Should never be
- * called and thus produces an
- * error.
+ * Constructor. Should never be called and thus produces an error.
*/
template <int structdim2, int dim2, int spacedim2>
TriaAccessor (const InvalidAccessor<structdim2,dim2,spacedim2> &);
/**
- * Copy operator. Since this is
- * only called from iterators,
- * do not return anything, since
- * the iterator will return
- * itself.
+ * Copy operator. Since this is only called from iterators, do not return
+ * anything, since the iterator will return itself.
*
- * This method is protected,
- * since it is only to be called
- * from the iterator class.
+ * This method is protected, since it is only to be called from the iterator
+ * class.
*/
void copy_from (const TriaAccessor &);
/**
- * Return the state of the
- * iterator. Since an iterator
- * to points can not be
- * incremented or decremented,
- * its state remains constant,
- * and in particular equal to
- * IteratorState::valid.
+ * Return the state of the iterator. Since an iterator to points can not be
+ * incremented or decremented, its state remains constant, and in particular
+ * equal to IteratorState::valid.
*/
static IteratorState::IteratorStates state ();
/**
- * Level of this object. Vertices
- * have no level, so this
- * function always returns zero.
+ * Level of this object. Vertices have no level, so this function always
+ * returns zero.
*/
static int level ();
/**
- * Index of this object. Returns
- * the global index of the vertex
- * this object points to.
+ * Index of this object. Returns the global index of the vertex this object
+ * points to.
*/
int index () const;
* @{
*/
/**
- * This operator advances the
- * iterator to the next
- * element. For points, this
- * operation is not defined, so
- * you can't iterate over point
- * iterators.
+ * This operator advances the iterator to the next element. For points, this
+ * operation is not defined, so you can't iterate over point iterators.
*/
void operator ++ () const;
/**
- * This operator moves the
- * iterator to the previous
- * element. For points, this
- * operation is not defined, so
- * you can't iterate over point
- * iterators.
+ * This operator moves the iterator to the previous element. For points,
+ * this operation is not defined, so you can't iterate over point iterators.
*/
void operator -- () const;
/**
- * Compare for equality.
+ * Compare for equality.
*/
bool operator == (const TriaAccessor &) const;
*/
/**
- * @name Accessing sub-objects
+ * @name Accessing sub-objects
*/
/**
* @{
*/
/**
- * Return the global index of
- * i-th vertex of the current
- * object. If i is zero, this
- * returns the index of the
- * current point to which this
- * object refers. Otherwise, it
- * throws an exception.
+ * Return the global index of i-th vertex of the current object. If i is
+ * zero, this returns the index of the current point to which this object
+ * refers. Otherwise, it throws an exception.
*
- * Note that the returned value is only
- * the index of the geometrical
- * vertex. It has nothing to do with
- * possible degrees of freedom
- * associated with it. For this, see the
- * @p DoFAccessor::vertex_dof_index
- * functions.
+ * Note that the returned value is only the index of the geometrical vertex.
+ * It has nothing to do with possible degrees of freedom associated with it.
+ * For this, see the @p DoFAccessor::vertex_dof_index functions.
*
- * @note Despite the name, the index returned here is only
- * global in the sense that it is specific to a particular
- * Triangulation object or, in the case the triangulation is
- * actually of type parallel::distributed::Triangulation,
- * specific to that part of the distributed triangulation stored
- * on the current processor.
+ * @note Despite the name, the index returned here is only global in the
+ * sense that it is specific to a particular Triangulation object or, in the
+ * case the triangulation is actually of type
+ * parallel::distributed::Triangulation, specific to that part of the
+ * distributed triangulation stored on the current processor.
*/
unsigned int vertex_index (const unsigned int i = 0) const;
/**
- * Return a reference to the
- * @p ith vertex. If i is zero, this
- * returns a reference to the
- * current point to which this
- * object refers. Otherwise, it
- * throws an exception.
+ * Return a reference to the @p ith vertex. If i is zero, this returns a
+ * reference to the current point to which this object refers. Otherwise, it
+ * throws an exception.
*/
Point<spacedim> &vertex (const unsigned int i = 0) const;
/**
- * Return the center of this object,
- * which of course co-incides with the
- * location of the vertex this object
- * refers to.
+ * Return the center of this object, which of course co-incides with the
+ * location of the vertex this object refers to.
*/
Point<spacedim> center () const;
/**
- * Pointer to the @p ith line
- * bounding this object. Will
- * point to an invalid object.
+ * Pointer to the @p ith line bounding this object. Will point to an invalid
+ * object.
*/
typename dealii::internal::Triangulation::Iterators<1,spacedim>::line_iterator
static line (const unsigned int);
/**
- * Line index of the @p ith
- * line bounding this object.
+ * Line index of the @p ith line bounding this object.
*
- * Implemented only for
- * <tt>structdim>1</tt>,
- * otherwise an exception
+ * Implemented only for <tt>structdim>1</tt>, otherwise an exception
* generated.
*/
static unsigned int line_index (const unsigned int i);
/**
- * Pointer to the @p ith quad
- * bounding this object.
+ * Pointer to the @p ith quad bounding this object.
*/
static
typename dealii::internal::Triangulation::Iterators<1,spacedim>::quad_iterator
quad (const unsigned int i);
/**
- * Quad index of the @p ith
- * quad bounding this object.
+ * Quad index of the @p ith quad bounding this object.
*
- * Implemented only for
- * <tt>structdim>2</tt>,
- * otherwise an exception
+ * Implemented only for <tt>structdim>2</tt>, otherwise an exception
* generated.
*/
static unsigned int quad_index (const unsigned int i);
/**
- * Return whether this point is
- * at the boundary of the
- * one-dimensional triangulation
- * we deal with here.
+ * Return whether this point is at the boundary of the one-dimensional
+ * triangulation we deal with here.
*/
bool at_boundary () const;
types::boundary_id boundary_indicator () const;
/**
- * Return the manifold indicator of this
- * object.
+ * Return the manifold indicator of this object.
*
* @see @ref GlossManifoldIndicator "Glossary entry on manifold indicators"
*/
/**
- * @name Orientation of sub-objects
+ * @name Orientation of sub-objects
*/
/**
* @{
*/
/**
- * @name Accessing children
+ * @name Accessing children
*/
/**
* @{
*/
/**
- * Test whether the object has
- * children. Always false.
+ * Test whether the object has children. Always false.
*/
static bool has_children ();
/**
- * Return the number of immediate
- * children of this object.This
- * is always zero in dimension 0.
+ * Return the number of immediate children of this object.This is always
+ * zero in dimension 0.
*/
static unsigned int n_children();
/**
- * Compute and return the number
- * of active descendants of this
- * objects. Always zero.
+ * Compute and return the number of active descendants of this objects.
+ * Always zero.
*/
static unsigned int number_of_children ();
/**
- * Return the number of times
- * that this object is
- * refined. Always 0.
+ * Return the number of times that this object is refined. Always 0.
*/
static unsigned int max_refinement_depth ();
*/
/**
- * @name Dealing with boundary indicators
+ * @name Dealing with boundary indicators
*/
/**
* @{
*/
/**
- * Set the boundary indicator.
- * The same applies as for the
- * <tt>boundary_indicator()</tt>
- * function.
- *
- * @warning You should never set the
- * boundary indicator of an interior face
- * (a face not at the boundary of the
- * domain), or set set the boundary
- * indicator of an exterior face to
- * numbers::internal_face_boundary_id
- * (this value is reserved for another
- * purpose). Algorithms may not work or
- * produce very confusing results if
- * boundary cells have a boundary
- * indicator of numbers::internal_face_boundary_id
- * or if interior cells have boundary
- * indicators other than numbers::internal_face_boundary_id.
- * Unfortunately, the current object
- * has no means of finding out whether it
- * really is at the boundary of the
- * domain and so cannot determine whether
- * the value you are trying to set makes
- * sense under the current circumstances.
+ * Set the boundary indicator. The same applies as for the
+ * <tt>boundary_indicator()</tt> function.
+ *
+ * @warning You should never set the boundary indicator of an interior face
+ * (a face not at the boundary of the domain), or set set the boundary
+ * indicator of an exterior face to numbers::internal_face_boundary_id (this
+ * value is reserved for another purpose). Algorithms may not work or
+ * produce very confusing results if boundary cells have a boundary
+ * indicator of numbers::internal_face_boundary_id or if interior cells have
+ * boundary indicators other than numbers::internal_face_boundary_id.
+ * Unfortunately, the current object has no means of finding out whether it
+ * really is at the boundary of the domain and so cannot determine whether
+ * the value you are trying to set makes sense under the current
+ * circumstances.
*
* @ingroup boundary
*
set_manifold_id (const types::manifold_id);
/**
- * Set the boundary indicator of this object and all of its
- * lower-dimensional sub-objects. Since this object only represents a
- * single vertex, there are no lower-dimensional obejct and this function is
+ * Set the boundary indicator of this object and all of its lower-
+ * dimensional sub-objects. Since this object only represents a single
+ * vertex, there are no lower-dimensional obejct and this function is
* equivalent to calling set_boundary_indicator with the same argument.
*
* @ingroup boundary
set_all_boundary_indicators (const types::boundary_id);
/**
- * Set the manifold indicator of this object and all of its
- * lower-dimensional sub-objects. Since this object only represents a
- * single vertex, there are no lower-dimensional obejct and this function is
+ * Set the manifold indicator of this object and all of its lower-
+ * dimensional sub-objects. Since this object only represents a single
+ * vertex, there are no lower-dimensional obejct and this function is
* equivalent to calling set_manifold_indicator with the same argument.
*
* @ingroup manifold
*/
/**
- * Return whether the vertex
- * pointed to here is used.
+ * Return whether the vertex pointed to here is used.
*/
bool used () const;
protected:
/**
- * Pointer to the triangulation
- * we operate on.
+ * Pointer to the triangulation we operate on.
*/
const Triangulation<1,spacedim> *tria;
/**
- * Whether this is a left end,
- * right end, or interior
- * vertex. This information is
- * provided by the cell at the
- * time of creation.
+ * Whether this is a left end, right end, or interior vertex. This
+ * information is provided by the cell at the time of creation.
*/
VertexKind vertex_kind;
/**
- * The global vertex index of the
- * vertex this object corresponds
- * to.
+ * The global vertex index of the vertex this object corresponds to.
*/
unsigned int global_vertex_index;
};
/**
- * This class allows access to a cell: a line in one dimension, a quad
- * in two dimension, etc.
+ * This class allows access to a cell: a line in one dimension, a quad in two
+ * dimension, etc.
*
* The following refers to any dimension:
*
- * This class allows access to a <tt>cell</tt>, which is a line in 1D
- * and a quad in 2D. Cells have more functionality than lines or quads
- * by themselves, for example they can be flagged for refinement, they
- * have neighbors, they have the possibility to check whether they are
- * at the boundary etc. This class offers access to all this data.
+ * This class allows access to a <tt>cell</tt>, which is a line in 1D and a
+ * quad in 2D. Cells have more functionality than lines or quads by
+ * themselves, for example they can be flagged for refinement, they have
+ * neighbors, they have the possibility to check whether they are at the
+ * boundary etc. This class offers access to all this data.
*
* @ingroup grid
* @ingroup Accessors
{
public:
/**
- * Propagate the AccessorData type
- * into the present class.
+ * Propagate the AccessorData type into the present class.
*/
typedef typename TriaAccessor<dim,dim,spacedim>::AccessorData AccessorData;
/**
- * Define the type of the
- * container this is part of.
+ * Define the type of the container this is part of.
*/
typedef Triangulation<dim, spacedim> Container;
/**
- * @name Constructors
+ * @name Constructors
*/
/**
* @{
*/
/**
- * Constructor.
+ * Constructor.
*/
CellAccessor (const Triangulation<dim,spacedim> *parent = 0,
const int level = -1,
CellAccessor (const TriaAccessor<dim,dim,spacedim> &cell_accessor);
/**
- * Conversion constructor. This
- * constructor exists to make certain
- * constructs simpler to write in
- * dimension independent code. For
- * example, it allows assigning a face
- * iterator to a line iterator, an
- * operation that is useful in 2d but
- * doesn't make any sense in 3d. The
- * constructor here exists for the
- * purpose of making the code conform to
- * C++ but it will unconditionally abort;
- * in other words, assigning a face
- * iterator to a line iterator is better
- * put into an if-statement that checks
- * that the dimension is two, and assign
- * to a quad iterator in 3d (an operator
- * that, without this constructor would
- * be illegal if we happen to compile for
+ * Conversion constructor. This constructor exists to make certain
+ * constructs simpler to write in dimension independent code. For example,
+ * it allows assigning a face iterator to a line iterator, an operation that
+ * is useful in 2d but doesn't make any sense in 3d. The constructor here
+ * exists for the purpose of making the code conform to C++ but it will
+ * unconditionally abort; in other words, assigning a face iterator to a
+ * line iterator is better put into an if-statement that checks that the
+ * dimension is two, and assign to a quad iterator in 3d (an operator that,
+ * without this constructor would be illegal if we happen to compile for
* 2d).
*/
template <int structdim2, int dim2, int spacedim2>
CellAccessor (const InvalidAccessor<structdim2,dim2,spacedim2> &);
/**
- * Another conversion operator
- * between objects that don't
- * make sense, just like the
- * previous one.
+ * Another conversion operator between objects that don't make sense, just
+ * like the previous one.
*/
template <int structdim2, int dim2, int spacedim2>
CellAccessor (const TriaAccessor<structdim2,dim2,spacedim2> &);
*/
/**
- * @name Accessing sub-objects and neighbors
+ * @name Accessing sub-objects and neighbors
*/
/**
* @{
*/
/**
- * Return a pointer to the
- * @p ith child. Overloaded
- * version which returns a more
- * reasonable iterator class.
+ * Return a pointer to the @p ith child. Overloaded version which returns a
+ * more reasonable iterator class.
*/
TriaIterator<CellAccessor<dim, spacedim> >
child (const unsigned int i) const;
/**
- * Return an iterator to the
- * @p ith face of this cell.
+ * Return an iterator to the @p ith face of this cell.
*/
TriaIterator<TriaAccessor<dim-1,dim,spacedim> >
face (const unsigned int i) const;
/**
- * Return the (global) index of the
- * @p ith face of this cell.
+ * Return the (global) index of the @p ith face of this cell.
*
- * @note Despite the name, the index returned here is only
- * global in the sense that it is specific to a particular
- * Triangulation object or, in the case the triangulation is
- * actually of type parallel::distributed::Triangulation,
- * specific to that part of the distributed triangulation stored
- * on the current processor.
+ * @note Despite the name, the index returned here is only global in the
+ * sense that it is specific to a particular Triangulation object or, in the
+ * case the triangulation is actually of type
+ * parallel::distributed::Triangulation, specific to that part of the
+ * distributed triangulation stored on the current processor.
*/
unsigned int
face_index (const unsigned int i) const;
/**
- * Return an iterator to that
- * cell that neighbors the
- * present cell on the given face
- * and subface number.
- *
- * To succeed, the present cell
- * must not be further refined,
- * and the neighbor on the given
- * face must be further refined
- * exactly once; the returned
- * cell is then a child of that
- * neighbor.
- *
- * The function may not be called
- * in 1d, since there we have no
- * subfaces. The implementation
- * of this function is rather
- * straightforward in 2d, by
- * first determining which face
- * of the neighbor cell the
- * present cell is bordering on
- * (this is what the
- * @p neighbor_of_neighbor
- * function does), and then
- * asking
- * @p GeometryInfo::child_cell_on_subface
- * for the index of the
- * child.
- *
- * However, the situation is more
- * complicated in 3d, since there faces may
- * have more than one orientation, and we
- * have to use @p face_orientation, @p
- * face_flip and @p face_rotation for both
- * this and the neighbor cell to figure out
- * which cell we want to have.
- *
- * This can lead to surprising
- * results: if we are sitting on
- * a cell and are asking for a
- * cell behind subface
- * <tt>sf</tt>, then this means
- * that we are considering the
- * subface for the face in the
- * natural direction for the
- * present cell. However, if the
- * face as seen from this cell
- * has
- * <tt>face_orientation()==false</tt>,
- * then the child of the face
- * that separates the present
- * cell from the neighboring
- * cell's child is not
- * necessarily the @p sf-th child
- * of the face of this cell. This
- * is so because the @p
- * subface_no on a cell corresponds to the
- * subface with respect to the
- * intrinsic ordering of the
- * present cell, whereas children
- * of face iterators are computed
- * with respect to the intrinsic
- * ordering of faces; these two
- * orderings are only identical
- * if the face orientation is @p
- * true, and reversed otherwise.
- *
- * Similarly, effects of
- * <tt>face_flip()==true</tt> and
- * <tt>face_rotation()==true()</tt>, both
- * of which indicate a non-standard face
- * have to be considered.
- *
- * Fortunately, this is only very rarely of
- * concern, since usually one simply wishes
- * to loop over all finer neighbors at a
- * given face of an active cell. Only in
- * the process of refinement of a
- * Triangulation we want to set neighbor
- * information for both our child cells and
- * the neighbor's children. Since we can
- * respect orientation of faces from our
- * current cell in that case, we do NOT
- * respect face_orientation, face_flip and
- * face_rotation of the present cell within
- * this function, i.e. the returned
- * neighbor's child is behind subface @p
- * subface concerning the intrinsic
+ * Return an iterator to that cell that neighbors the present cell on the
+ * given face and subface number.
+ *
+ * To succeed, the present cell must not be further refined, and the
+ * neighbor on the given face must be further refined exactly once; the
+ * returned cell is then a child of that neighbor.
+ *
+ * The function may not be called in 1d, since there we have no subfaces.
+ * The implementation of this function is rather straightforward in 2d, by
+ * first determining which face of the neighbor cell the present cell is
+ * bordering on (this is what the @p neighbor_of_neighbor function does),
+ * and then asking @p GeometryInfo::child_cell_on_subface for the index of
+ * the child.
+ *
+ * However, the situation is more complicated in 3d, since there faces may
+ * have more than one orientation, and we have to use @p face_orientation,
+ * @p face_flip and @p face_rotation for both this and the neighbor cell to
+ * figure out which cell we want to have.
+ *
+ * This can lead to surprising results: if we are sitting on a cell and are
+ * asking for a cell behind subface <tt>sf</tt>, then this means that we are
+ * considering the subface for the face in the natural direction for the
+ * present cell. However, if the face as seen from this cell has
+ * <tt>face_orientation()==false</tt>, then the child of the face that
+ * separates the present cell from the neighboring cell's child is not
+ * necessarily the @p sf-th child of the face of this cell. This is so
+ * because the @p subface_no on a cell corresponds to the subface with
+ * respect to the intrinsic ordering of the present cell, whereas children
+ * of face iterators are computed with respect to the intrinsic ordering of
+ * faces; these two orderings are only identical if the face orientation is
+ * @p true, and reversed otherwise.
+ *
+ * Similarly, effects of <tt>face_flip()==true</tt> and
+ * <tt>face_rotation()==true()</tt>, both of which indicate a non-standard
+ * face have to be considered.
+ *
+ * Fortunately, this is only very rarely of concern, since usually one
+ * simply wishes to loop over all finer neighbors at a given face of an
+ * active cell. Only in the process of refinement of a Triangulation we want
+ * to set neighbor information for both our child cells and the neighbor's
+ * children. Since we can respect orientation of faces from our current cell
+ * in that case, we do NOT respect face_orientation, face_flip and
+ * face_rotation of the present cell within this function, i.e. the returned
+ * neighbor's child is behind subface @p subface concerning the intrinsic
* ordering of the given face.
*/
TriaIterator<CellAccessor<dim, spacedim> >
const unsigned int subface_no) const;
/**
- * Return a pointer to the
- * @p ith neighbor. If the
- * neighbor does not exist, an
- * invalid iterator is returned.
+ * Return a pointer to the @p ith neighbor. If the neighbor does not exist,
+ * an invalid iterator is returned.
*
- * <b>Note</b> (cf. TriaLevel<0>):
- * The neighbor of a cell has at most the
- * same level as this cell, i.e. it may
- * or may not be refined.
+ * <b>Note</b> (cf. TriaLevel<0>): The neighbor of a cell has at most the
+ * same level as this cell, i.e. it may or may not be refined.
*/
TriaIterator<CellAccessor<dim, spacedim> >
neighbor (const unsigned int i) const;
/**
- * Return the index of the
- * @p ith neighbor. If the
- * neighbor does not exist, its
- * index is -1.
+ * Return the index of the @p ith neighbor. If the neighbor does not exist,
+ * its index is -1.
*/
int neighbor_index (const unsigned int i) const;
/**
- * Return the level of the
- * @p ith neighbor. If the
- * neighbor does not exist, its
- * level is -1.
+ * Return the level of the @p ith neighbor. If the neighbor does not exist,
+ * its level is -1.
*/
int neighbor_level (const unsigned int i) const;
/**
- * Return the how-many'th
- * neighbor this cell is of
- * <tt>cell->neighbor(neighbor)</tt>,
- * i.e. return the @p face_no
- * such that
- * <tt>cell->neighbor(neighbor)->neighbor(face_no)==cell</tt>. This
- * function is the right one if
- * you want to know how to get
- * back from a neighbor to the
- * present cell.
- *
- * Note that this operation is
- * only useful if the neighbor is
- * not coarser than the present
- * cell. If the neighbor is
- * coarser this function throws
- * an exception. Use the @p
- * neighbor_of_coarser_neighbor
- * function in that case.
+ * Return the how-many'th neighbor this cell is of
+ * <tt>cell->neighbor(neighbor)</tt>, i.e. return the @p face_no such that
+ * <tt>cell->neighbor(neighbor)->neighbor(face_no)==cell</tt>. This function
+ * is the right one if you want to know how to get back from a neighbor to
+ * the present cell.
+ *
+ * Note that this operation is only useful if the neighbor is not coarser
+ * than the present cell. If the neighbor is coarser this function throws an
+ * exception. Use the @p neighbor_of_coarser_neighbor function in that case.
*/
unsigned int neighbor_of_neighbor (const unsigned int neighbor) const;
/**
- * Return, whether the neighbor
- * is coarser then the present
- * cell. This is important in
- * case of ansiotropic
- * refinement where this
- * information does not depend on
- * the levels of the cells.
- *
- * Note, that in an anisotropic
- * setting, a cell can only be
- * coarser than another one at a
- * given face, not on a general
- * basis. The face of the finer
- * cell is contained in the
- * corresponding face of the
- * coarser cell, the finer face
- * is either a child or a
- * grandchild of the coarser
- * face.
+ * Return, whether the neighbor is coarser then the present cell. This is
+ * important in case of ansiotropic refinement where this information does
+ * not depend on the levels of the cells.
+ *
+ * Note, that in an anisotropic setting, a cell can only be coarser than
+ * another one at a given face, not on a general basis. The face of the
+ * finer cell is contained in the corresponding face of the coarser cell,
+ * the finer face is either a child or a grandchild of the coarser face.
*/
bool neighbor_is_coarser (const unsigned int neighbor) const;
/**
- * This function is a generalization of the
- * @p neighbor_of_neighbor function for the
- * case of a coarser neighbor. It returns a
- * pair of numbers, face_no and subface_no,
- * with the following property, if the
- * neighbor is not refined:
- * <tt>cell->neighbor(neighbor)->neighbor_child_on_subface(face_no,subface_no)==cell</tt>.
- * In 3D, a coarser neighbor can still be
- * refined. In that case subface_no denotes the child index of the neighbors face that relates to our face:
- * <tt>cell->neighbor(neighbor)->face(face_no)->child(subface_no)==cell->face(neighbor)</tt>.
- * This case in 3d and how it can happen
- * is discussed in the introduction of the
- * step-30 tutorial program.
+ * This function is a generalization of the @p neighbor_of_neighbor function
+ * for the case of a coarser neighbor. It returns a pair of numbers, face_no
+ * and subface_no, with the following property, if the neighbor is not
+ * refined: <tt>cell->neighbor(neighbor)->neighbor_child_on_subface(face_no,
+ * subface_no)==cell</tt>. In 3D, a coarser neighbor can still be refined.
+ * In that case subface_no denotes the child index of the neighbors face
+ * that relates to our face: <tt>cell->neighbor(neighbor)->face(face_no)->ch
+ * ild(subface_no)==cell->face(neighbor)</tt>. This case in 3d and how it
+ * can happen is discussed in the introduction of the step-30 tutorial
+ * program.
*
- * This function is impossible
- * for <tt>dim==1</tt>.
+ * This function is impossible for <tt>dim==1</tt>.
*/
std::pair<unsigned int, unsigned int>
neighbor_of_coarser_neighbor (const unsigned int neighbor) const;
/**
- * This function is a generalization of the
- * @p neighbor_of_neighbor and the @p
- * neighbor_of_coarser_neighbor
- * functions. It checks whether the
- * neighbor is coarser or not and calls the
- * respective function. In both cases, only
+ * This function is a generalization of the @p neighbor_of_neighbor and the
+ * @p neighbor_of_coarser_neighbor functions. It checks whether the neighbor
+ * is coarser or not and calls the respective function. In both cases, only
* the face_no is returned.
*/
unsigned int neighbor_face_no (const unsigned int neighbor) const;
*/
/**
- * @name Dealing with boundary indicators
+ * @name Dealing with boundary indicators
*/
/**
* @{
*/
/**
- * Return whether the @p ith
- * vertex or face (depending on
- * the dimension) is part of the
- * boundary. This is true, if
- * the @p ith neighbor does not
- * exist.
+ * Return whether the @p ith vertex or face (depending on the dimension) is
+ * part of the boundary. This is true, if the @p ith neighbor does not
+ * exist.
*/
bool at_boundary (const unsigned int i) const;
/**
- * Return whether the cell is at
- * the boundary. Being at the
- * boundary is defined by one
- * face being on the
- * boundary. Note that this does
- * not catch cases where only one
- * vertex of a quad or of a hex
- * is at the boundary, or where
- * only one line of a hex is at
- * the boundary while the
- * interiors of all faces are in
- * the interior of the
- * domain. For the latter case,
- * the @p has_boundary_lines
- * function is the right one to
- * ask.
+ * Return whether the cell is at the boundary. Being at the boundary is
+ * defined by one face being on the boundary. Note that this does not catch
+ * cases where only one vertex of a quad or of a hex is at the boundary, or
+ * where only one line of a hex is at the boundary while the interiors of
+ * all faces are in the interior of the domain. For the latter case, the @p
+ * has_boundary_lines function is the right one to ask.
*/
bool at_boundary () const;
/**
- * This is a slight variation to
- * the @p at_boundary function:
- * for 1 and 2 dimensions,
- * it is equivalent, for three
- * dimensions it returns
- * whether at least one of the 12
- * lines of the hexahedron is at
- * a boundary. This, of course,
- * includes the case where a
- * whole face is at the boundary,
- * but also some other cases.
+ * This is a slight variation to the @p at_boundary function: for 1 and 2
+ * dimensions, it is equivalent, for three dimensions it returns whether at
+ * least one of the 12 lines of the hexahedron is at a boundary. This, of
+ * course, includes the case where a whole face is at the boundary, but also
+ * some other cases.
*/
bool has_boundary_lines () const;
/**
*/
/**
- * @name Dealing with refinement indicators
+ * @name Dealing with refinement indicators
*/
/**
* @{
RefinementCase<dim> refine_flag_set () const;
/**
- * Flag the cell pointed to for
- * refinement. This function is
- * only allowed for active
- * cells. Keeping the default value for @p ref_case will mark this cell for
- * isotropic refinement.
+ * Flag the cell pointed to for refinement. This function is only allowed
+ * for active cells. Keeping the default value for @p ref_case will mark
+ * this cell for isotropic refinement.
*/
void set_refine_flag (const RefinementCase<dim> ref_case = RefinementCase<dim>::isotropic_refinement) const;
/**
- * Clear the refinement flag.
+ * Clear the refinement flag.
*/
void clear_refine_flag () const;
/**
- * Modify the refinement flag of the cell
- * to ensure (at least) the given
- * refinement case @p face_refinement_case at
- * face <tt>face_no</tt>, taking into
- * account orientation, flip and rotation
- * of the face. Return, whether the
- * refinement flag had to be
- * modified. This function is only allowed
- * for active cells.
+ * Modify the refinement flag of the cell to ensure (at least) the given
+ * refinement case @p face_refinement_case at face <tt>face_no</tt>, taking
+ * into account orientation, flip and rotation of the face. Return, whether
+ * the refinement flag had to be modified. This function is only allowed for
+ * active cells.
*/
bool flag_for_face_refinement (const unsigned int face_no,
const RefinementCase<dim-1> &face_refinement_case=RefinementCase<dim-1>::isotropic_refinement) const;
/**
- * Modify the refinement flag of the cell
- * to ensure that line <tt>face_no</tt>
- * will be refined. Return, whether the
- * refinement flag had to be
- * modified. This function is only allowed
- * for active cells.
+ * Modify the refinement flag of the cell to ensure that line
+ * <tt>face_no</tt> will be refined. Return, whether the refinement flag had
+ * to be modified. This function is only allowed for active cells.
*/
bool flag_for_line_refinement (const unsigned int line_no) const;
/**
- * Return the SubfaceCase of face
- * <tt>face_no</tt>. Note that this is not
- * identical to asking
- * <tt>cell->face(face_no)->refinement_case()</tt>
- * since the latter returns a RefinementCase<dim-1>
- * and thus only considers one
- * (anisotropic) refinement, whereas this
- * function considers the complete
- * refinement situation including possible
- * refinement of the face's children. This
- * function may only be called for active
- * cells in 2d and 3d.
+ * Return the SubfaceCase of face <tt>face_no</tt>. Note that this is not
+ * identical to asking <tt>cell->face(face_no)->refinement_case()</tt> since
+ * the latter returns a RefinementCase<dim-1> and thus only considers one
+ * (anisotropic) refinement, whereas this function considers the complete
+ * refinement situation including possible refinement of the face's
+ * children. This function may only be called for active cells in 2d and 3d.
*/
dealii::internal::SubfaceCase<dim> subface_case(const unsigned int face_no) const;
/**
- * Return whether the coarsen flag
- * is set or not.
+ * Return whether the coarsen flag is set or not.
*/
bool coarsen_flag_set () const;
/**
- * Flag the cell pointed to for
- * coarsening. This function is
- * only allowed for active
- * cells.
+ * Flag the cell pointed to for coarsening. This function is only allowed
+ * for active cells.
*/
void set_coarsen_flag () const;
/**
- * Clear the coarsen flag.
+ * Clear the coarsen flag.
*/
void clear_coarsen_flag () const;
/**
*/
/**
- * @name Dealing with material indicators
+ * @name Dealing with material indicators
*/
/**
* @{
*/
/**
- * Return the material id of this
- * cell.
+ * Return the material id of this cell.
*
- * For a typical use of this
- * function, see the @ref step_28
- * "step-28" tutorial program.
+ * For a typical use of this function, see the @ref step_28 "step-28"
+ * tutorial program.
*
- * See the @ref GlossMaterialId
- * "glossary" for more
- * information.
+ * See the @ref GlossMaterialId "glossary" for more information.
*/
types::material_id material_id () const;
/**
- * Set the material id of this
- * cell.
+ * Set the material id of this cell.
*
- * For a typical use of this
- * function, see the @ref step_28
- * "step-28" tutorial program.
+ * For a typical use of this function, see the @ref step_28 "step-28"
+ * tutorial program.
*
- * See the @ref GlossMaterialId
- * "glossary" for more
- * information.
+ * See the @ref GlossMaterialId "glossary" for more information.
*/
void set_material_id (const types::material_id new_material_id) const;
/**
- * Set the material id of this
- * cell and all its children (and
- * grand-children, and so on) to
- * the given value.
+ * Set the material id of this cell and all its children (and grand-
+ * children, and so on) to the given value.
*
- * See the @ref GlossMaterialId
- * "glossary" for more
- * information.
+ * See the @ref GlossMaterialId "glossary" for more information.
*/
void recursively_set_material_id (const types::material_id new_material_id) const;
/**
*/
/**
- * @name Dealing with subdomain indicators
+ * @name Dealing with subdomain indicators
*/
/**
* @{
*/
/**
- * Return the subdomain id of
- * this cell.
+ * Return the subdomain id of this cell.
*
- * See the @ref GlossSubdomainId
- * "glossary" for more
- * information.
+ * See the @ref GlossSubdomainId "glossary" for more information.
*
- * @note The subdomain of a cell is a property only defined
- * for active cells, i.e., cells that are not further
- * refined. Consequently, you can only call this function if
- * the cell it refers to has no children. For multigrid
- * methods in parallel, it is also important to know which
+ * @note The subdomain of a cell is a property only defined for active
+ * cells, i.e., cells that are not further refined. Consequently, you can
+ * only call this function if the cell it refers to has no children. For
+ * multigrid methods in parallel, it is also important to know which
* processor owns non-active cells, and for this you can call
* level_subdomain_id().
*/
types::subdomain_id subdomain_id () const;
/**
- * Set the subdomain id of this
- * cell.
+ * Set the subdomain id of this cell.
*
- * See the @ref GlossSubdomainId
- * "glossary" for more
- * information. This function
- * should not be called if you
- * use a
- * parallel::distributed::Triangulation
- * object.
+ * See the @ref GlossSubdomainId "glossary" for more information. This
+ * function should not be called if you use a
+ * parallel::distributed::Triangulation object.
*
- * @note The subdomain of a cell is a property only defined
- * for active cells, i.e., cells that are not further
- * refined. Consequently, you can only call this function if
- * the cell it refers to has no children. For multigrid
- * methods in parallel, it is also important to know which
+ * @note The subdomain of a cell is a property only defined for active
+ * cells, i.e., cells that are not further refined. Consequently, you can
+ * only call this function if the cell it refers to has no children. For
+ * multigrid methods in parallel, it is also important to know which
* processor owns non-active cells, and for this you can call
* level_subdomain_id().
*/
void set_subdomain_id (const types::subdomain_id new_subdomain_id) const;
/**
- * Get the level subdomain id of this cell. This is used for parallel multigrid.
+ * Get the level subdomain id of this cell. This is used for parallel
+ * multigrid.
*/
types::subdomain_id level_subdomain_id () const;
/**
- * Set the level subdomain id of this cell. This is used for parallel multigrid.
+ * Set the level subdomain id of this cell. This is used for parallel
+ * multigrid.
*/
void set_level_subdomain_id (const types::subdomain_id new_level_subdomain_id) const;
* Set the subdomain id of this cell (if it is active) or all its terminal
* children (and grand-children, and so on, as long as they have no children
* of their own) to the given value. Since the subdomain id is a concept
- * that is only defined for cells that are active (i.e., have no children
- * of their own), this function only sets the subdomain ids for all
- * children and grand children of this cell that are actually active,
- * skipping intermediate child cells.
- *
- * See the @ref GlossSubdomainId
- * "glossary" for more
- * information. This function
- * should not be called if you
- * use a
- * parallel::distributed::Triangulation
- * object since there the subdomain id is implicitly defined by which
- * processor you're on.
+ * that is only defined for cells that are active (i.e., have no children of
+ * their own), this function only sets the subdomain ids for all children
+ * and grand children of this cell that are actually active, skipping
+ * intermediate child cells.
+ *
+ * See the @ref GlossSubdomainId "glossary" for more information. This
+ * function should not be called if you use a
+ * parallel::distributed::Triangulation object since there the subdomain id
+ * is implicitly defined by which processor you're on.
*/
void recursively_set_subdomain_id (const types::subdomain_id new_subdomain_id) const;
/**
*/
/**
- * @name Dealing with codim 1 cell orientation
+ * @name Dealing with codim 1 cell orientation
*/
/**
* @{
*/
/**
- * Return the orientation of
- * this cell.
+ * Return the orientation of this cell.
*
- * For the meaning of this flag, see
- * @ref GlossDirectionFlag .
+ * For the meaning of this flag, see @ref GlossDirectionFlag .
*/
bool direction_flag () const;
/**
- * Index of the parent of this cell within the level of the triangulation
- * to which the parent cell belongs. The level of the parent is of course
- * one lower than that of the present cell. If the parent does not exist
- * (i.e., if the object is at the coarsest level of the mesh hierarchy), an
- * exception is generated.
+ * Index of the parent of this cell within the level of the triangulation to
+ * which the parent cell belongs. The level of the parent is of course one
+ * lower than that of the present cell. If the parent does not exist (i.e.,
+ * if the object is at the coarsest level of the mesh hierarchy), an
+ * exception is generated.
*/
int parent_index () const;
/**
- * Return an iterator to the
- * parent. If the
- * parent does not exist (i.e., if the object is at the coarsest level of
- * the mesh hierarchy), an exception is generated.
+ * Return an iterator to the parent. If the parent does not exist (i.e., if
+ * the object is at the coarsest level of the mesh hierarchy), an exception
+ * is generated.
*/
TriaIterator<CellAccessor<dim,spacedim> >
parent () const;
*/
/**
- * @name Other functions
+ * @name Other functions
*/
/**
* @{
*/
/**
- * Test whether the cell has children
- * (this is the criterion for activity
- * of a cell).
+ * Test whether the cell has children (this is the criterion for activity of
+ * a cell).
*
- * See the @ref GlossActive "glossary"
- * for more information.
+ * See the @ref GlossActive "glossary" for more information.
*/
bool active () const;
/**
- * Return whether this cell is owned by the current processor
- * or is owned by another processor. The function always returns
- * true if applied to an object of type dealii::Triangulation,
- * but may yield false if the triangulation is of type
- * parallel::distributed::Triangulation.
+ * Return whether this cell is owned by the current processor or is owned by
+ * another processor. The function always returns true if applied to an
+ * object of type dealii::Triangulation, but may yield false if the
+ * triangulation is of type parallel::distributed::Triangulation.
*
- * See the @ref GlossGhostCell
- * "glossary" and the @ref
- * distributed module for more
- * information.
+ * See the @ref GlossGhostCell "glossary" and the @ref distributed module
+ * for more information.
*
* @post The returned value is equal to <code>!is_ghost() &&
* !is_artificial()</code>.
*
- * @note Whether a cell is a ghost cell, artificial, or is
- * locally owned or is a property that only pertains to cells
- * that are active. Consequently,
- * you can only call this function if the cell it refers to has
- * no children.
+ * @note Whether a cell is a ghost cell, artificial, or is locally owned or
+ * is a property that only pertains to cells that are active. Consequently,
+ * you can only call this function if the cell it refers to has no children.
*/
bool is_locally_owned () const;
bool is_locally_owned_on_level () const;
/**
- * Return whether this cell
- * exists in the global mesh but
- * (i) is owned by another
- * processor, i.e. has a
- * subdomain_id different from
- * the one the current processor
- * owns and (ii) is adjacent to a
- * cell owned by the current
- * processor.
- *
- * This function only makes sense
- * if the triangulation used is
- * of kind
- * parallel::distributed::Triangulation. In
- * all other cases, the returned
+ * Return whether this cell exists in the global mesh but (i) is owned by
+ * another processor, i.e. has a subdomain_id different from the one the
+ * current processor owns and (ii) is adjacent to a cell owned by the
+ * current processor.
+ *
+ * This function only makes sense if the triangulation used is of kind
+ * parallel::distributed::Triangulation. In all other cases, the returned
* value is always false.
*
- * See the @ref GlossGhostCell
- * "glossary" and the @ref
- * distributed module for more
- * information.
+ * See the @ref GlossGhostCell "glossary" and the @ref distributed module
+ * for more information.
*
- * @post The returned value is equal to
- * <code>!is_locally_owned() &&
+ * @post The returned value is equal to <code>!is_locally_owned() &&
* !is_artificial()</code>.
*
- * @note Whether a cell is a ghost cell, artificial, or is
- * locally owned or is a property that only pertains to cells
- * that are active. Consequently,
- * you can only call this function if the cell it refers to has
- * no children.
+ * @note Whether a cell is a ghost cell, artificial, or is locally owned or
+ * is a property that only pertains to cells that are active. Consequently,
+ * you can only call this function if the cell it refers to has no children.
*/
bool is_ghost () const;
/**
- * Return whether this cell is
- * artificial, i.e. it isn't one
- * of the cells owned by the
- * current processor, and it also
- * doesn't border on one. As a
- * consequence, it exists in the
- * mesh to ensure that each
- * processor has all coarse mesh
- * cells and that the 2:1 ratio
- * of neighboring cells is
- * maintained, but it is not one
- * of the cells we should work on
- * on the current processor. In
- * particular, there is no
- * guarantee that this cell
- * isn't, in fact, further
- * refined on one of the other
- * processors.
- *
- * This function only makes sense
- * if the triangulation used is
- * of kind
- * parallel::distributed::Triangulation. In
- * all other cases, the returned
+ * Return whether this cell is artificial, i.e. it isn't one of the cells
+ * owned by the current processor, and it also doesn't border on one. As a
+ * consequence, it exists in the mesh to ensure that each processor has all
+ * coarse mesh cells and that the 2:1 ratio of neighboring cells is
+ * maintained, but it is not one of the cells we should work on on the
+ * current processor. In particular, there is no guarantee that this cell
+ * isn't, in fact, further refined on one of the other processors.
+ *
+ * This function only makes sense if the triangulation used is of kind
+ * parallel::distributed::Triangulation. In all other cases, the returned
* value is always false.
*
- * See the @ref
- * GlossArtificialCell "glossary"
- * and the @ref distributed
+ * See the @ref GlossArtificialCell "glossary" and the @ref distributed
* module for more information.
*
- * @post The returned value is equal to
- * <code>!is_ghost() &&
+ * @post The returned value is equal to <code>!is_ghost() &&
* !is_locally_owned()</code>.
*
- * @note Whether a cell is a ghost cell, artificial, or is
- * locally owned is a property that only pertains to cells
- * that are active. Consequently,
- * you can only call this function if the cell it refers to has
- * no children.
+ * @note Whether a cell is a ghost cell, artificial, or is locally owned is
+ * a property that only pertains to cells that are active. Consequently, you
+ * can only call this function if the cell it refers to has no children.
*/
bool is_artificial () const;
/**
- * Test whether the point @p p
- * is inside this cell. Points on
- * the boundary are counted as
- * being inside the cell.
+ * Test whether the point @p p is inside this cell. Points on the boundary
+ * are counted as being inside the cell.
*
- * Note that this function
- * assumes that the mapping
- * between unit cell and real
- * cell is (bi-, tri-)linear,
- * i.e. that faces in 2d and
- * edges in 3d are straight
- * lines. If you have higher
- * order transformations, results
- * may be different as to whether
- * a point is in- or outside the
- * cell in real space.
+ * Note that this function assumes that the mapping between unit cell and
+ * real cell is (bi-, tri-)linear, i.e. that faces in 2d and edges in 3d are
+ * straight lines. If you have higher order transformations, results may be
+ * different as to whether a point is in- or outside the cell in real space.
*
- * In case of codim>0, the point is first projected
- * to the manifold where the cell is embedded and
- * then check if this projection is inside the cell.
+ * In case of codim>0, the point is first projected to the manifold where
+ * the cell is embedded and then check if this projection is inside the
+ * cell.
*/
bool point_inside (const Point<spacedim> &p) const;
/**
- * Set the neighbor @p i of
- * this cell to the cell pointed
- * to by @p pointer.
+ * Set the neighbor @p i of this cell to the cell pointed to by @p pointer.
*
- * This function shouldn't really be
- * public (but needs to for various
- * reasons in order not to make a long
- * list of functions friends): it
- * modifies internal data structures and
- * may leave things. Do not use it from
- * application codes.
+ * This function shouldn't really be public (but needs to for various
+ * reasons in order not to make a long list of functions friends): it
+ * modifies internal data structures and may leave things. Do not use it
+ * from application codes.
*/
void set_neighbor (const unsigned int i,
const TriaIterator<CellAccessor<dim, spacedim> > &pointer) const;
protected:
/**
- * This function assumes that the
- * neighbor is not coarser than
- * the current cell. In this case
- * it returns the
- * neighbor_of_neighbor() value.
- * If, however, the neighbor is
- * coarser this function returns
- * an
+ * This function assumes that the neighbor is not coarser than the current
+ * cell. In this case it returns the neighbor_of_neighbor() value. If,
+ * however, the neighbor is coarser this function returns an
* <code>invalid_unsigned_int</code>.
*
- * This function is not for
- * public use. Use the function
- * neighbor_of_neighbor() instead
- * which throws an exception if
- * called for a coarser
- * neighbor. If neighbor is
- * indeed coarser (you get to
- * know this by e.g. the
- * neighbor_is_coarser()
- * function) then the
- * neighbor_of_coarser_neighbor()
- * function should be call. If
- * you'd like to know only the
- * <code>face_no</code> which is
- * required to get back from the
- * neighbor to the present cell
- * then simply use the
- * neighbor_face_no() function
- * which can be used for coarser
- * as well as noncoarser
- * neighbors.
+ * This function is not for public use. Use the function
+ * neighbor_of_neighbor() instead which throws an exception if called for a
+ * coarser neighbor. If neighbor is indeed coarser (you get to know this by
+ * e.g. the neighbor_is_coarser() function) then the
+ * neighbor_of_coarser_neighbor() function should be call. If you'd like to
+ * know only the <code>face_no</code> which is required to get back from the
+ * neighbor to the present cell then simply use the neighbor_face_no()
+ * function which can be used for coarser as well as noncoarser neighbors.
*/
unsigned int neighbor_of_neighbor_internal (const unsigned int neighbor) const;
/**
- As for any codim>0 we can use a similar code
- and c++ does not allow partial templates.
- we use this auxiliary function that is then
- called from point_inside.
- */
+ * As for any codim>0 we can use a similar code and c++ does not allow
+ * partial templates. we use this auxiliary function that is then called
+ * from point_inside.
+ */
template<int dim_,int spacedim_ >
bool point_inside_codim(const Point<spacedim_> &p) const;
void set_parent (const unsigned int parent_index);
/**
- * Set the orientation of this
- * cell.
+ * Set the orientation of this cell.
*
- * For the meaning of this flag, see
- * @ref GlossDirectionFlag .
+ * For the meaning of this flag, see @ref GlossDirectionFlag .
*/
void set_direction_flag (const bool new_direction_flag) const;
/**
- * Copy operator. This is
- * normally used in a context
- * like <tt>iterator a,b;
- * *a=*b;</tt>. Since the meaning is
- * to copy the object pointed to
- * by @p b to the object
- * pointed to by @p a and since
- * accessors are not real but
- * virtual objects, this
- * operation is not useful for
- * iterators on
- * triangulations. We declare
- * this function here private,
- * thus it may not be used from
- * outside. Furthermore it is
- * not implemented and will give
- * a linker error if used
- * anyway.
+ * Copy operator. This is normally used in a context like <tt>iterator a,b;
+ * *a=*b;</tt>. Since the meaning is to copy the object pointed to by @p b
+ * to the object pointed to by @p a and since accessors are not real but
+ * virtual objects, this operation is not useful for iterators on
+ * triangulations. We declare this function here private, thus it may not be
+ * used from outside. Furthermore it is not implemented and will give a
+ * linker error if used anyway.
*/
void operator = (const CellAccessor<dim, spacedim> &);
namespace TriaAccessorBase
{
/**
- * Out of a face object, get the
- * sub-objects of dimensionality
- * given by the last argument.
+ * Out of a face object, get the sub-objects of dimensionality given by
+ * the last argument.
*/
template <int dim>
inline
}
/**
- * This function should never be
- * used, but we need it for the
- * template instantiation of TriaAccessorBase<dim,dim,spacedim>::objects() const
+ * This function should never be used, but we need it for the template
+ * instantiation of TriaAccessorBase<dim,dim,spacedim>::objects() const
*/
template <int dim>
inline
}
/**
- * Copy the above functions for
- * cell objects.
+ * Copy the above functions for cell objects.
*/
template <int structdim, int dim>
inline
struct Implementation
{
/**
- * Implementation of the function
- * of some name in the mother
- * class.
+ * Implementation of the function of some name in the mother class.
*/
template <int dim, int spacedim>
static
/**
- * Implementation of the function
- * of some name in the mother
- * class.
+ * Implementation of the function of some name in the mother class.
*/
template <int structdim, int dim, int spacedim>
static
/**
- * Implementation of the function
- * of some name in the mother
- * class.
+ * Implementation of the function of some name in the mother class.
*/
template <int structdim, int dim, int spacedim>
static
/**
- * Implementation of the function
- * of some name in the mother
- * class.
+ * Implementation of the function of some name in the mother class.
*/
template <int structdim, int dim, int spacedim>
static
}
/**
- * Implementation of the function
- * of some name in the mother
- * class.
+ * Implementation of the function of some name in the mother class.
*/
template <int dim, int spacedim>
static
/**
- * Implementation of the function
- * of some name in the mother
- * class.
+ * Implementation of the function of some name in the mother class.
*/
template <int structdim, int dim, int spacedim>
static
/**
- * Implementation of the function
- * of some name in the mother
- * class.
+ * Implementation of the function of some name in the mother class.
*/
template <int structdim, int dim, int spacedim>
static
/**
- * Implementation of the function
- * of some name in the mother
- * class.
+ * Implementation of the function of some name in the mother class.
*/
template <int structdim, int dim, int spacedim>
static
}
/**
- * Implementation of the function
- * of some name in the mother
- * class.
+ * Implementation of the function of some name in the mother class.
*/
template <int dim, int spacedim>
static
/**
- * Implementation of the function of same
- * name in the enclosing class.
+ * Implementation of the function of same name in the enclosing class.
*/
template <int dim, int spacedim>
static
/**
- * This class is used to represent a boundary to a triangulation.
- * When a triangulation creates a new vertex on the boundary of the
- * domain, it determines the new vertex' coordinates through the
- * following code (here in two dimensions):
+ * This class is used to represent a boundary to a triangulation. When a
+ * triangulation creates a new vertex on the boundary of the domain, it
+ * determines the new vertex' coordinates through the following code (here in
+ * two dimensions):
* @code
* ...
* Point<2> new_vertex = boundary.get_new_point_on_line (line);
* ...
* @endcode
- * @p line denotes the line at the boundary that shall be refined
- * and for which we seek the common point of the two child lines.
+ * @p line denotes the line at the boundary that shall be refined and for
+ * which we seek the common point of the two child lines.
*
- * In 3D, a new vertex may be placed on the middle of a line or on
- * the middle of a side. Respectively, the library calls
+ * In 3D, a new vertex may be placed on the middle of a line or on the middle
+ * of a side. Respectively, the library calls
* @code
* ...
* Point<3> new_line_vertices[4]
* boundary.get_new_point_on_line (face->line(3)) };
* ...
* @endcode
- * to get the four midpoints of the lines bounding the quad at the
- * boundary, and after that
+ * to get the four midpoints of the lines bounding the quad at the boundary,
+ * and after that
* @code
* ...
* Point<3> new_quad_vertex = boundary.get_new_point_on_quad (face);
* ...
* @endcode
- * to get the midpoint of the face. It is guaranteed that this order
- * (first lines, then faces) holds, so you can use information from
- * the children of the four lines of a face, since these already exist
- * at the time the midpoint of the face is to be computed.
+ * to get the midpoint of the face. It is guaranteed that this order (first
+ * lines, then faces) holds, so you can use information from the children of
+ * the four lines of a face, since these already exist at the time the
+ * midpoint of the face is to be computed.
*
- * Since iterators are passed to the functions, you may use information
- * about boundary indicators and the like, as well as all other information
- * provided by these objects.
+ * Since iterators are passed to the functions, you may use information about
+ * boundary indicators and the like, as well as all other information provided
+ * by these objects.
*
- * There are specializations, StraightBoundary, which places
- * the new point right into the middle of the given points, and
- * HyperBallBoundary creating a hyperball with given radius
- * around a given center point.
+ * There are specializations, StraightBoundary, which places the new point
+ * right into the middle of the given points, and HyperBallBoundary creating a
+ * hyperball with given radius around a given center point.
*
* @ingroup boundary
- * @author Wolfgang Bangerth, 1999, 2001, 2009, Ralf Hartmann, 2001, 2008, Luca Heltai, 2014
+ * @author Wolfgang Bangerth, 1999, 2001, 2009, Ralf Hartmann, 2001, 2008,
+ * Luca Heltai, 2014
*/
template <int dim, int spacedim=dim>
class Boundary : public FlatManifold<dim, spacedim>
* have a kink at the vertices itself).
*
* @note Implementations of this function should be able to assume that the
- * point p lies within or close to the face described by the first
- * argument. In turn, callers of this function should ensure that this is in
- * fact the case.
+ * point p lies within or close to the face described by the first argument.
+ * In turn, callers of this function should ensure that this is in fact the
+ * case.
*/
virtual
Tensor<1,spacedim>
/**
* Compute the normal vectors to the boundary at each vertex of the given
- * face. It is not required that the normal vectors be normed
- * somehow. Neither is it required that the normals actually point outward.
+ * face. It is not required that the normal vectors be normed somehow.
+ * Neither is it required that the normals actually point outward.
*
* This function is needed to compute data for C1 mappings. The default
* implementation is to throw an error, so you need not overload this
/**
- * Specialization of Boundary<dim,spacedim>, which places the new point
- * right into the middle of the given points. The middle is defined
- * as the arithmetic mean of the points.
+ * Specialization of Boundary<dim,spacedim>, which places the new point right
+ * into the middle of the given points. The middle is defined as the
+ * arithmetic mean of the points.
*
- * This class does not really describe a boundary in the usual
- * sense. By placing new points in the middle of old ones, it rather
- * assumes that the boundary of the domain is given by the
- * polygon/polyhedron defined by the boundary of the initial coarse
- * triangulation.
+ * This class does not really describe a boundary in the usual sense. By
+ * placing new points in the middle of old ones, it rather assumes that the
+ * boundary of the domain is given by the polygon/polyhedron defined by the
+ * boundary of the initial coarse triangulation.
*
- * @ingroup boundary
+ * @ingroup boundary
*
- * @author Wolfgang Bangerth, 1998, 2001, Ralf Hartmann, 2001
+ * @author Wolfgang Bangerth, 1998, 2001, Ralf Hartmann, 2001
*/
template <int dim, int spacedim=dim>
class StraightBoundary : public Boundary<dim,spacedim>
DEAL_II_NAMESPACE_OPEN
/**
- * Boundary object for the hull of a cylinder. In three dimensions,
- * points are projected on a circular tube along the <tt>x-</tt>,
- * <tt>y-</tt> or <tt>z</tt>-axis (when using the first constructor of
- * this class), or an arbitrarily oriented cylinder described by the
- * direction of its axis and a point located on the axis. The radius
- * of the tube can be given independently. Similar to
- * HyperBallBoundary, new points are projected by dividing the
- * straight line between the old two points and adjusting the radius
- * from the axis.
+ * Boundary object for the hull of a cylinder. In three dimensions, points
+ * are projected on a circular tube along the <tt>x-</tt>, <tt>y-</tt> or
+ * <tt>z</tt>-axis (when using the first constructor of this class), or an
+ * arbitrarily oriented cylinder described by the direction of its axis and a
+ * point located on the axis. The radius of the tube can be given
+ * independently. Similar to HyperBallBoundary, new points are projected by
+ * dividing the straight line between the old two points and adjusting the
+ * radius from the axis.
*
- * This class was developed to be used in conjunction with the
- * @p cylinder function of GridGenerator. It should be used for
- * the hull of the cylinder only (boundary indicator 0). Its use is
- * discussed in detail in the results section of step-49.
+ * This class was developed to be used in conjunction with the @p cylinder
+ * function of GridGenerator. It should be used for the hull of the cylinder
+ * only (boundary indicator 0). Its use is discussed in detail in the results
+ * section of step-49.
*
- * This class is derived from StraightBoundary rather than from
- * Boundary, which would seem natural, since this way we can use the
+ * This class is derived from StraightBoundary rather than from Boundary,
+ * which would seem natural, since this way we can use the
* StraightBoundary::in_between() function.
*
* @ingroup boundary
const unsigned int axis = 0);
/**
- * Constructor. If constructed
- * with this constructor, the
- * boundary described is a
- * cylinder with an axis that
- * points in direction #direction
- * and goes through the given
- * #point_on_axis. The direction
- * may be arbitrarily scaled, and
- * the given point may be any
- * point on the axis.
+ * Constructor. If constructed with this constructor, the boundary described
+ * is a cylinder with an axis that points in direction #direction and goes
+ * through the given #point_on_axis. The direction may be arbitrarily
+ * scaled, and the given point may be any point on the axis.
*/
CylinderBoundary (const double radius,
const Point<spacedim> &direction,
const Point<spacedim> &point_on_axis);
/**
- * Refer to the general documentation of
- * this class and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*/
virtual Point<spacedim>
get_new_point_on_line (const typename Triangulation<dim,spacedim>::line_iterator &line) const;
/**
- * Refer to the general documentation of
- * this class and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*/
virtual Point<spacedim>
get_new_point_on_quad (const typename Triangulation<dim,spacedim>::quad_iterator &quad) const;
/**
- * Refer to the general
- * documentation of this class
- * and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*
- * Calls
- * @p get_intermediate_points_between_points.
+ * Calls @p get_intermediate_points_between_points.
*/
virtual void
get_intermediate_points_on_line (const typename Triangulation<dim,spacedim>::line_iterator &line,
std::vector<Point<spacedim> > &points) const;
/**
- * Refer to the general
- * documentation of this class
- * and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*
- * Only implemented for <tt>dim=3</tt>
- * and for <tt>points.size()==1</tt>.
+ * Only implemented for <tt>dim=3</tt> and for <tt>points.size()==1</tt>.
*/
virtual void
get_intermediate_points_on_quad (const typename Triangulation<dim,spacedim>::quad_iterator &quad,
std::vector<Point<spacedim> > &points) const;
/**
- * Compute the normals to the
- * boundary at the vertices of
- * the given face.
+ * Compute the normals to the boundary at the vertices of the given face.
*
- * Refer to the general
- * documentation of this class
- * and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*/
virtual void
get_normals_at_vertices (const typename Triangulation<dim,spacedim>::face_iterator &face,
double get_radius () const;
/**
- * Exception. Thrown by the
- * @p get_radius if the
- * @p compute_radius_automatically,
- * see below, flag is set true.
+ * Exception. Thrown by the @p get_radius if the @p
+ * compute_radius_automatically, see below, flag is set true.
*/
DeclException0 (ExcRadiusNotSet);
private:
/**
- * Called by
- * @p get_intermediate_points_on_line
- * and by
- * @p get_intermediate_points_on_quad.
+ * Called by @p get_intermediate_points_on_line and by @p
+ * get_intermediate_points_on_quad.
*
- * Refer to the general
- * documentation of
- * @p get_intermediate_points_on_line
- * in the documentation of the
- * base class.
+ * Refer to the general documentation of @p get_intermediate_points_on_line
+ * in the documentation of the base class.
*/
void get_intermediate_points_between_points (const Point<spacedim> &p0, const Point<spacedim> &p1,
std::vector<Point<spacedim> > &points) const;
/**
- * Given a number for the axis,
- * return a vector that denotes
- * this direction.
+ * Given a number for the axis, return a vector that denotes this direction.
*/
static Point<spacedim> get_axis_vector (const unsigned int axis);
};
/**
- * Boundary object for the hull of a (truncated) cone with two
- * different radii at the two ends. If one radius is chosen to be 0
- * the object describes the boundary of a cone. In three dimensions,
- * points are projected on an arbitrarily oriented (truncated) cone
- * described by the two endpoints and the corresponding radii. Similar
- * to HyperBallBoundary, new points are projected by dividing the
- * straight line between the old two points and adjusting the radius
- * from the axis.
+ * Boundary object for the hull of a (truncated) cone with two different radii
+ * at the two ends. If one radius is chosen to be 0 the object describes the
+ * boundary of a cone. In three dimensions, points are projected on an
+ * arbitrarily oriented (truncated) cone described by the two endpoints and
+ * the corresponding radii. Similar to HyperBallBoundary, new points are
+ * projected by dividing the straight line between the old two points and
+ * adjusting the radius from the axis.
*
- * This class is derived from StraightBoundary rather than from
- * Boundary, which would seem natural, since this way we can use the
+ * This class is derived from StraightBoundary rather than from Boundary,
+ * which would seem natural, since this way we can use the
* StraightBoundary::in_between() function.
*
* As an example of use, consider the following code snippet:
* triangulation.set_boundary (0, boundary);
* triangulation.refine_global (2);
* @endcode
- * This will produce the following meshes after the two
- * refinements we perform, in 2d and 3d, respectively:
+ * This will produce the following meshes after the two refinements we
+ * perform, in 2d and 3d, respectively:
*
- * @image html cone_2d.png
- * @image html cone_3d.png
+ * @image html cone_2d.png @image html cone_3d.png
*
* @author Markus Bürg, 2009
*/
{
public:
/**
- * Constructor. Here the boundary
- * object is constructed. The
- * points <tt>x_0</tt> and
- * <tt>x_1</tt> describe the
- * starting and ending points of
- * the axis of the (truncated)
- * cone. <tt>radius_0</tt>
- * denotes the radius
- * corresponding to <tt>x_0</tt>
- * and <tt>radius_1</tt> the one
- * corresponding to <tt>x_1</tt>.
+ * Constructor. Here the boundary object is constructed. The points
+ * <tt>x_0</tt> and <tt>x_1</tt> describe the starting and ending points of
+ * the axis of the (truncated) cone. <tt>radius_0</tt> denotes the radius
+ * corresponding to <tt>x_0</tt> and <tt>radius_1</tt> the one corresponding
+ * to <tt>x_1</tt>.
*/
ConeBoundary (const double radius_0,
const double radius_1,
const Point<dim> x_1);
/**
- * Return the radius of the
- * (truncated) cone at given point
- * <tt>x</tt> on the axis.
+ * Return the radius of the (truncated) cone at given point <tt>x</tt> on
+ * the axis.
*/
double get_radius (const Point<dim> x) const;
/**
- * Refer to the general
- * documentation of this class
- * and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*/
virtual
Point<dim>
get_new_point_on_line (const typename Triangulation<dim>::line_iterator &line) const;
/**
- * Refer to the general
- * documentation of this class
- * and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*/
virtual
Point<dim>
get_new_point_on_quad (const typename Triangulation<dim>::quad_iterator &quad) const;
/**
- * Refer to the general
- * documentation of this class
- * and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*
- * Calls @p
- * get_intermediate_points_between_points.
+ * Calls @p get_intermediate_points_between_points.
*/
virtual
void
std::vector<Point<dim> > &points) const;
/**
- * Refer to the general
- * documentation of this class
- * and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*
- * Only implemented for
- * <tt>dim=3</tt> and for
- * <tt>points.size()==1</tt>.
+ * Only implemented for <tt>dim=3</tt> and for <tt>points.size()==1</tt>.
*/
virtual
void
std::vector<Point<dim> > &points) const;
/**
- * Compute the normals to the
- * boundary at the vertices of
- * the given face.
+ * Compute the normals to the boundary at the vertices of the given face.
*
- * Refer to the general
- * documentation of this class
- * and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*/
virtual
void
protected:
/**
- * First radius of the (truncated)
- * cone.
+ * First radius of the (truncated) cone.
*/
const double radius_0;
/**
- * Second radius of the (truncated)
- * cone.
+ * Second radius of the (truncated) cone.
*/
const double radius_1;
private:
/**
- * Called by @p
- * get_intermediate_points_on_line
- * and by @p
+ * Called by @p get_intermediate_points_on_line and by @p
* get_intermediate_points_on_quad.
*
- * Refer to the general
- * documentation of @p
- * get_intermediate_points_on_line
- * in the documentation of the
- * base class.
+ * Refer to the general documentation of @p get_intermediate_points_on_line
+ * in the documentation of the base class.
*/
void
get_intermediate_points_between_points (const Point<dim> &p0,
/**
- * Specialization of Boundary<dim>, which places the new point on
- * the boundary of a ball in arbitrary dimension. It works by projecting
- * the point in the middle of the old points onto the ball. The middle is
- * defined as the arithmetic mean of the points.
+ * Specialization of Boundary<dim>, which places the new point on the boundary
+ * of a ball in arbitrary dimension. It works by projecting the point in the
+ * middle of the old points onto the ball. The middle is defined as the
+ * arithmetic mean of the points.
*
- * The center of the ball and its radius may be given upon construction of
- * an object of this type. They default to the origin and a radius of 1.0.
+ * The center of the ball and its radius may be given upon construction of an
+ * object of this type. They default to the origin and a radius of 1.0.
*
- * This class is derived from StraightBoundary rather than from
- * Boundary, which would seem natural, since this way we can use the
- * StraightBoundary::in_between() function.
+ * This class is derived from StraightBoundary rather than from Boundary,
+ * which would seem natural, since this way we can use the
+ * StraightBoundary::in_between() function.
*
- * @ingroup boundary
+ * @ingroup boundary
*
- * @author Wolfgang Bangerth, 1998, Ralf Hartmann, 2001
+ * @author Wolfgang Bangerth, 1998, Ralf Hartmann, 2001
*/
template <int dim, int spacedim=dim>
class HyperBallBoundary : public StraightBoundary<dim,spacedim>
const double radius = 1.0);
/**
- * Refer to the general documentation of
- * this class and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*/
virtual
Point<spacedim>
get_new_point_on_line (const typename Triangulation<dim,spacedim>::line_iterator &line) const;
/**
- * Refer to the general documentation of
- * this class and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*/
virtual
Point<spacedim>
get_new_point_on_quad (const typename Triangulation<dim,spacedim>::quad_iterator &quad) const;
/**
- * Refer to the general
- * documentation of this class
- * and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*
- * Calls
- * @p get_intermediate_points_between_points.
+ * Calls @p get_intermediate_points_between_points.
*/
virtual
void
std::vector<Point<spacedim> > &points) const;
/**
- * Refer to the general
- * documentation of this class
- * and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*
- * Only implemented for <tt>dim=3</tt>
- * and for <tt>points.size()==1</tt>.
+ * Only implemented for <tt>dim=3</tt> and for <tt>points.size()==1</tt>.
*/
virtual
void
std::vector<Point<spacedim> > &points) const;
/**
- * Implementation of the function
- * declared in the base class.
+ * Implementation of the function declared in the base class.
*
- * Refer to the general
- * documentation of this class
- * and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*/
virtual
Tensor<1,spacedim>
const Point<spacedim> &p) const;
/**
- * Compute the normals to the
- * boundary at the vertices of
- * the given face.
+ * Compute the normals to the boundary at the vertices of the given face.
*
- * Refer to the general
- * documentation of this class
- * and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*/
virtual
void
get_radius () const;
/**
- * Exception. Thrown by the
- * @p get_radius if the
- * @p compute_radius_automatically,
- * see below, flag is set true.
+ * Exception. Thrown by the @p get_radius if the @p
+ * compute_radius_automatically, see below, flag is set true.
*/
DeclException0 (ExcRadiusNotSet);
const double radius;
/**
- * This flag is @p false for
- * this class and for all derived
- * classes that set the radius by
- * the constructor. For example
- * this flag is @p false for the
- * HalfHyperBallBoundary
- * class but it is @p true for
- * the HyperShellBoundary
- * class, for example. The
- * latter class doesn't get its
- * radii by the constructor but
- * need to compute the radii
- * automatically each time one of
- * the virtual functions is
- * called.
+ * This flag is @p false for this class and for all derived classes that set
+ * the radius by the constructor. For example this flag is @p false for the
+ * HalfHyperBallBoundary class but it is @p true for the HyperShellBoundary
+ * class, for example. The latter class doesn't get its radii by the
+ * constructor but need to compute the radii automatically each time one of
+ * the virtual functions is called.
*/
bool compute_radius_automatically;
private:
/**
- * Called by
- * @p get_intermediate_points_on_line
- * and by
- * @p get_intermediate_points_on_quad.
+ * Called by @p get_intermediate_points_on_line and by @p
+ * get_intermediate_points_on_quad.
*
- * Refer to the general
- * documentation of
- * @p get_intermediate_points_on_line
- * in the documentation of the
- * base class.
+ * Refer to the general documentation of @p get_intermediate_points_on_line
+ * in the documentation of the base class.
*/
void get_intermediate_points_between_points (const Point<spacedim> &p0, const Point<spacedim> &p1,
std::vector<Point<spacedim> > &points) const;
/**
- * Variant of HyperBallBoundary which denotes a half hyper ball
- * where the first coordinate is restricted to the range $x>=0$ (or
- * $x>=center(0)$). In two dimensions, this equals the right half
- * circle, in three space dimensions it is a half ball. This class
- * might be useful for computations with rotational symmetry, where
- * one dimension is the radius from the axis of rotation.
+ * Variant of HyperBallBoundary which denotes a half hyper ball where the
+ * first coordinate is restricted to the range $x>=0$ (or $x>=center(0)$). In
+ * two dimensions, this equals the right half circle, in three space
+ * dimensions it is a half ball. This class might be useful for computations
+ * with rotational symmetry, where one dimension is the radius from the axis
+ * of rotation.
*
* @ingroup boundary
*
const double radius = 1.0);
/**
- * Check if on the line <tt>x==0</tt>,
- * otherwise pass to the base
- * class.
+ * Check if on the line <tt>x==0</tt>, otherwise pass to the base class.
*/
virtual Point<dim>
get_new_point_on_line (const typename Triangulation<dim>::line_iterator &line) const;
/**
- * Check if on the line <tt>x==0</tt>,
- * otherwise pass to the base
- * class.
+ * Check if on the line <tt>x==0</tt>, otherwise pass to the base class.
*/
virtual Point<dim>
get_new_point_on_quad (const typename Triangulation<dim>::quad_iterator &quad) const;
/**
- * Refer to the general
- * documentation of this class
- * and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*
- * Calls
- * @p get_intermediate_points_between_points.
+ * Calls @p get_intermediate_points_between_points.
*/
virtual void
get_intermediate_points_on_line (const typename Triangulation<dim>::line_iterator &line,
std::vector<Point<dim> > &points) const;
/**
- * Refer to the general
- * documentation of this class
- * and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*
- * Only implemented for <tt>dim=3</tt>
- * and for <tt>points.size()==1</tt>.
+ * Only implemented for <tt>dim=3</tt> and for <tt>points.size()==1</tt>.
*/
virtual void
get_intermediate_points_on_quad (const typename Triangulation<dim>::quad_iterator &quad,
std::vector<Point<dim> > &points) const;
/**
- * Compute the normals to the
- * boundary at the vertices of
- * the given face.
+ * Compute the normals to the boundary at the vertices of the given face.
*
- * Refer to the general
- * documentation of this class
- * and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*/
virtual void
get_normals_at_vertices (const typename Triangulation<dim>::face_iterator &face,
/**
- * Class describing the boundaries of a hyper shell. Only the center
- * of the two spheres needs to be given, the radii of inner and outer
- * sphere are computed automatically upon calling one of the virtual
- * functions.
+ * Class describing the boundaries of a hyper shell. Only the center of the
+ * two spheres needs to be given, the radii of inner and outer sphere are
+ * computed automatically upon calling one of the virtual functions.
*
* @ingroup boundary
*
{
public:
/**
- * Constructor. The center of the
- * spheres defaults to the
- * origin.
+ * Constructor. The center of the spheres defaults to the origin.
*
- * Calls the constructor of its
- * base @p HyperBallBoundary
- * class with a dummy radius as
- * argument. This radius will be
- * ignored
+ * Calls the constructor of its base @p HyperBallBoundary class with a dummy
+ * radius as argument. This radius will be ignored
*/
HyperShellBoundary (const Point<dim> ¢er = Point<dim>());
};
/**
- * Variant of HyperShellBoundary which denotes a half hyper shell
- * where the first coordinate is restricted to the range $x>=0$ (or
- * $x>=center(0)$). In two dimensions, this equals the right half arc,
- * in three space dimensions it is a half shell. This class might be
- * useful for computations with rotational symmetry, where one
- * dimension is the radius from the axis of rotation.
+ * Variant of HyperShellBoundary which denotes a half hyper shell where the
+ * first coordinate is restricted to the range $x>=0$ (or $x>=center(0)$). In
+ * two dimensions, this equals the right half arc, in three space dimensions
+ * it is a half shell. This class might be useful for computations with
+ * rotational symmetry, where one dimension is the radius from the axis of
+ * rotation.
*
* @ingroup boundary
*
{
public:
/**
- * Constructor. The center of the
- * spheres defaults to the
- * origin.
+ * Constructor. The center of the spheres defaults to the origin.
*
- * If the radii are not specified, the
- * class tries to infer them from the
- * location of points on the
- * boundary. This works in 2d, but not in
- * 3d. As a consequence, in 3d these
- * radii must be given.
+ * If the radii are not specified, the class tries to infer them from the
+ * location of points on the boundary. This works in 2d, but not in 3d. As a
+ * consequence, in 3d these radii must be given.
*/
HalfHyperShellBoundary (const Point<dim> ¢er = Point<dim>(),
const double inner_radius = -1,
get_new_point_on_quad (const typename Triangulation<dim>::quad_iterator &quad) const;
/**
- * Refer to the general
- * documentation of this class
- * and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*
- * Calls
- * @p get_intermediate_points_between_points.
+ * Calls @p get_intermediate_points_between_points.
*/
virtual void
get_intermediate_points_on_line (const typename Triangulation<dim>::line_iterator &line,
std::vector<Point<dim> > &points) const;
/**
- * Refer to the general
- * documentation of this class
- * and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*
- * Only implemented for <tt>dim=3</tt>
- * and for <tt>points.size()==1</tt>.
+ * Only implemented for <tt>dim=3</tt> and for <tt>points.size()==1</tt>.
*/
virtual void
get_intermediate_points_on_quad (const typename Triangulation<dim>::quad_iterator &quad,
std::vector<Point<dim> > &points) const;
/**
- * Compute the normals to the
- * boundary at the vertices of
- * the given face.
+ * Compute the normals to the boundary at the vertices of the given face.
*
- * Refer to the general
- * documentation of this class
- * and the documentation of the
- * base class.
+ * Refer to the general documentation of this class and the documentation of
+ * the base class.
*/
virtual void
get_normals_at_vertices (const typename Triangulation<dim>::face_iterator &face,
* $y$-axis while the plane of the torus is the $x$-$z$ plane. A torus of this
* kind can be generated by GridGenerator::torus.
*
- * This class is only implemented for
- * <tt>dim=2</tt>,<tt>spacedim=3</tt>, that is, just the surface.
+ * This class is only implemented for <tt>dim=2</tt>,<tt>spacedim=3</tt>, that
+ * is, just the surface.
*/
template <int dim, int spacedim>
class TorusBoundary : public Boundary<dim,spacedim>
{
public:
/**
- * Constructor.<tt>R</tt> has to be
- * greater than <tt>r</tt>.
+ * Constructor.<tt>R</tt> has to be greater than <tt>r</tt>.
*/
TorusBoundary (const double R, const double r);
std::vector< Point< spacedim > > &points ) const ;
/**
- * Get the normal from cartesian
- * coordinates. This normal does not have
- * unit length.
+ * Get the normal from cartesian coordinates. This normal does not have unit
+ * length.
*/
virtual void get_normals_at_vertices (
const typename Triangulation< dim, spacedim >::face_iterator &face,
private:
//Handy functions
/**
- * Function that corrects the value and
- * sign of angle, that is, given
- * <tt>angle=tan(abs(y/x))</tt>; if <tt>
- * (y > 0) && (x < 0) </tt> then
- * <tt>correct_angle = Pi - angle</tt>,
- * etc.
+ * Function that corrects the value and sign of angle, that is, given
+ * <tt>angle=tan(abs(y/x))</tt>; if <tt> (y > 0) && (x < 0) </tt> then
+ * <tt>correct_angle = Pi - angle</tt>, etc.
*/
double get_correct_angle(const double angle,const double x,const double y) const;
/**
- * Get the cartesian coordinates of the
- * Torus, i.e., from <tt>(theta,phi)</tt>
- * to <tt>(x,y,z)</tt>.
+ * Get the cartesian coordinates of the Torus, i.e., from
+ * <tt>(theta,phi)</tt> to <tt>(x,y,z)</tt>.
*/
Point<spacedim> get_real_coord(const Point<dim> &surfP) const ;
/**
- * Get the surface coordinates of the
- * Torus, i.e., from <tt>(x,y,z)</tt> to
+ * Get the surface coordinates of the Torus, i.e., from <tt>(x,y,z)</tt> to
* <tt>(theta,phi)</tt>.
*/
Point<dim> get_surf_coord(const Point<spacedim> &p) const ;
/**
- * Get the normal from surface
- * coordinates. This normal does not have
- * unit length.
+ * Get the normal from surface coordinates. This normal does not have unit
+ * length.
*/
Point<spacedim> get_surf_norm_from_sp(const Point<dim> &surfP) const ;
/**
- * Get the normal from cartesian
- * coordinates. This normal does not have
- * unit length.
+ * Get the normal from cartesian coordinates. This normal does not have unit
+ * length.
*/
Point<spacedim> get_surf_norm(const Point<spacedim> &p) const ;
namespace Triangulation
{
/**
- * General template for information belonging to the faces of a triangulation. These classes
- * are similar to the TriaLevel classes. As cells are organised in a hierarchical
- * structure of levels, each triangulation consists of several such TriaLevels. However the
- * faces of a triangulation, lower dimensional objects like lines in 2D or lines and quads
- * in 3D, do not have to be based on such a hierarchical structure. In fact we have to
- * organise them in only one object if we want to enable anisotropic refinement. Therefore
- * the TriaFaces classes store the information belonging to the faces of a
- * triangulation separately from the TriaLevel classes.
+ * General template for information belonging to the faces of a
+ * triangulation. These classes are similar to the TriaLevel classes. As
+ * cells are organised in a hierarchical structure of levels, each
+ * triangulation consists of several such TriaLevels. However the faces of
+ * a triangulation, lower dimensional objects like lines in 2D or lines
+ * and quads in 3D, do not have to be based on such a hierarchical
+ * structure. In fact we have to organise them in only one object if we
+ * want to enable anisotropic refinement. Therefore the TriaFaces classes
+ * store the information belonging to the faces of a triangulation
+ * separately from the TriaLevel classes.
*
- * This general template is only provided to enable a specialization below.
+ * This general template is only provided to enable a specialization
+ * below.
*
* @author Tobias Leicht, 2006
*/
{
private:
/**
- * Make the constructor private so no one can use
- * this general template. Only the specializations
- * should be used.
+ * Make the constructor private so no one can use this general template.
+ * Only the specializations should be used.
*/
TriaFaces();
};
/**
- * Faces only have a meaning in <tt>dim@>=1</tt>. In <tt>dim=1</tt> they are vertices,
- * which are handled differently, so only for <tt>dim@>=2</tt> the use of TriaFaces
- * is reasonable, for <tt>dim=1</tt> the class is empty.
+ * Faces only have a meaning in <tt>dim@>=1</tt>. In <tt>dim=1</tt> they
+ * are vertices, which are handled differently, so only for
+ * <tt>dim@>=2</tt> the use of TriaFaces is reasonable, for <tt>dim=1</tt>
+ * the class is empty.
*/
template<>
class TriaFaces<1>
public:
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
- * Of course this returns 0.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object. Of course this returns 0.
*/
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
*/
template <class Archive>
void serialize(Archive &ar,
{
public:
/**
- * The TriaObject containing the data of lines.
+ * The TriaObject containing the data of lines.
*/
TriaObjects<TriaObject<1> > lines;
public:
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
*/
template <class Archive>
void serialize(Archive &ar,
};
/**
- * In <tt>dim=3</tt> the cells are hexes, the faces accordingly are quads. In
- * addition to that we also have to enable the storage of lines.
+ * In <tt>dim=3</tt> the cells are hexes, the faces accordingly are quads.
+ * In addition to that we also have to enable the storage of lines.
*/
template<>
class TriaFaces<3>
{
public:
/**
- * The TriaObject containing the data of quads.
+ * The TriaObject containing the data of quads.
*/
TriaObjectsQuad3D quads;
/**
- * The TriaObject containing the data of lines.
+ * The TriaObject containing the data of lines.
*/
TriaObjects<TriaObject<1> > lines;
public:
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
*/
template <class Archive>
void serialize(Archive &ar,
/**
- * This class implements an iterator, analogous to those of the
- * standard template library (STL). It fulfills the requirements of a
- * bidirectional iterator. See the C++ documentation for further
- * details of iterator specification and usage.
+ * This class implements an iterator, analogous to those of the standard
+ * template library (STL). It fulfills the requirements of a bidirectional
+ * iterator. See the C++ documentation for further details of iterator
+ * specification and usage.
*
*
- * In addition to the STL
- * iterators an iterator of this class provides a <tt>-@></tt>
- * operator, i.e. you can write statements like
+ * In addition to the STL iterators an iterator of this class provides a
+ * <tt>-@></tt> operator, i.e. you can write statements like
* @code
* i->set_refine_flag ();
* @endcode
*
- * Iterators are used whenever a loop over all lines, quads, cells
- * etc. is to be performed. These loops can then be coded like this:
+ * Iterators are used whenever a loop over all lines, quads, cells etc. is to
+ * be performed. These loops can then be coded like this:
* @code
* cell_iterator i = tria.begin();
* cell_iterator end = tria.end();
* cell->set_refine_flag();
* @endcode
*
- * Note the usage of <tt>++i</tt> instead of <tt>i++</tt> since this
- * does not involve temporaries and copying. It is recommended to use
- * a fixed value <tt>end</tt> inside the loop instead of
- * <tt>tria.end()</tt>, since the creation and copying of these
- * iterators is rather expensive compared to normal pointers.
+ * Note the usage of <tt>++i</tt> instead of <tt>i++</tt> since this does not
+ * involve temporaries and copying. It is recommended to use a fixed value
+ * <tt>end</tt> inside the loop instead of <tt>tria.end()</tt>, since the
+ * creation and copying of these iterators is rather expensive compared to
+ * normal pointers.
*
- * The objects pointed to are accessors, derived from
- * TriaAccessorBase. Which kind of accessor is determined by the template
- * argument <em>Accessor</em>. These accessors are not so much data
- * structures as they are a collection of functions providing access
- * to the data stored in Tringulation or DoFHandler objects. Using
- * these accessors, the structure of these classes is hidden from the
- * application program.
+ * The objects pointed to are accessors, derived from TriaAccessorBase. Which
+ * kind of accessor is determined by the template argument <em>Accessor</em>.
+ * These accessors are not so much data structures as they are a collection of
+ * functions providing access to the data stored in Tringulation or DoFHandler
+ * objects. Using these accessors, the structure of these classes is hidden
+ * from the application program.
*
* <h3>Which iterator to use when</h3>
*
- * @attention Application programs will rarely use TriaRawIterator,
- * but rather one of the derived classes TriaIterator or
- * TriaActiveIterator.
+ * @attention Application programs will rarely use TriaRawIterator, but rather
+ * one of the derived classes TriaIterator or TriaActiveIterator.
*
* <ul>
- * <li> TriaRawIterator objects point to lines, cells, etc in the
- * lists whether they are used or not (in the vectors, also
- * <i>dead</i> objects are stored, since deletion in vectors is
- * expensive and we also do not want to destroy the ordering induced
- * by the numbering in the vectors). Therefore not all raw iterators
- * point to valid objects.
+ * <li> TriaRawIterator objects point to lines, cells, etc in the lists
+ * whether they are used or not (in the vectors, also <i>dead</i> objects are
+ * stored, since deletion in vectors is expensive and we also do not want to
+ * destroy the ordering induced by the numbering in the vectors). Therefore
+ * not all raw iterators point to valid objects.
*
- * <li> The derived class TriaIterator selects the valid cells, that
- * is, cells used somewhere in the triangulation hierarchy.
+ * <li> The derived class TriaIterator selects the valid cells, that is, cells
+ * used somewhere in the triangulation hierarchy.
*
* <li> TriaActiveIterator objects which only loop over active cells.
* </ul>
* <h3>Purpose</h3>
*
* Iterators are not much slower than operating directly on the data
- * structures, since they perform the loops that you had to handcode
- * yourself anyway. Most iterator and accessor functions are inlined.
+ * structures, since they perform the loops that you had to handcode yourself
+ * anyway. Most iterator and accessor functions are inlined.
*
* The main functionality of iterators, resides in the <tt>++</tt> and
- * <tt>--</tt> operators. These move the iterator forward or backward
- * just as if it were a pointer into an array. Here, this operation is
- * not so easy, since it may include skipping some elements and the
- * transition between the triangulation levels. This is completely
- * hidden from the user, though you can still create an iterator
- * pointing to an arbitrary element. Actually, the operation of
- * moving iterators back and forth is not done in the iterator
- * classes, but rather in the accessor classes. Since these are passed
- * as template arguments, you can write your own versions here to add
+ * <tt>--</tt> operators. These move the iterator forward or backward just as
+ * if it were a pointer into an array. Here, this operation is not so easy,
+ * since it may include skipping some elements and the transition between the
+ * triangulation levels. This is completely hidden from the user, though you
+ * can still create an iterator pointing to an arbitrary element. Actually,
+ * the operation of moving iterators back and forth is not done in the
+ * iterator classes, but rather in the accessor classes. Since these are
+ * passed as template arguments, you can write your own versions here to add
* more functionality.
*
- * Furthermore, the iterators described here satisfy the requirement of
- * input and bidirectional iterators as stated by the C++ standard and
- * the STL documentation. It is therefore possible to use the
- * functions from the algorithm section of the C++ standard,
- * e.g. <em>count_if</em> (see the documentation for Triangulation for
- * an example) and several others.
+ * Furthermore, the iterators described here satisfy the requirement of input
+ * and bidirectional iterators as stated by the C++ standard and the STL
+ * documentation. It is therefore possible to use the functions from the
+ * algorithm section of the C++ standard, e.g. <em>count_if</em> (see the
+ * documentation for Triangulation for an example) and several others.
*
* <h3>Implementation</h3>
*
- * The iterator class itself does not have much functionality. It only
- * becomes useful when assigned an Accessor (the second template
- * parameter), which really does the access to data. An Accessor
- * has to fulfil some requirements:
+ * The iterator class itself does not have much functionality. It only becomes
+ * useful when assigned an Accessor (the second template parameter), which
+ * really does the access to data. An Accessor has to fulfil some
+ * requirements:
*
* <ul>
* <li> It must have two members named <tt>present_level</tt> and
* <tt>present_index</tt> storing the address of the element in the
- * triangulation presently pointed to. These data have to be
- * accessible by all triangulation iterators listed above.
+ * triangulation presently pointed to. These data have to be accessible by all
+ * triangulation iterators listed above.
*
- * <li> It must have a constructor which takes a Triangulation* and
- * two unsigned integers, denoting the initial level and index, as
- * well as a data object depending on its type.
+ * <li> It must have a constructor which takes a Triangulation* and two
+ * unsigned integers, denoting the initial level and index, as well as a data
+ * object depending on its type.
*
- * <li> For the TriaIterator and the TriaActiveIterator class, it must
- * have a member function <tt>bool used()</tt>, for the latter a
- * member function <tt>bool active()</tt>.
+ * <li> For the TriaIterator and the TriaActiveIterator class, it must have a
+ * member function <tt>bool used()</tt>, for the latter a member function
+ * <tt>bool active()</tt>.
*
* <li> It must have void operators <tt>++</tt> and <tt>--</tt>.
*
- * <li> It must declare a local <tt>typedef AccessorData</tt> which
- * states the data type the accessor expects to get passed as fourth
- * constructor argument. By declaring a local data type, the
- * respective iterator class may type-safely enforce that data type to
- * be one of its own constructor argument types. If an accessor class
- * does not need additional data, this type shall be <tt>void</tt>.
+ * <li> It must declare a local <tt>typedef AccessorData</tt> which states the
+ * data type the accessor expects to get passed as fourth constructor
+ * argument. By declaring a local data type, the respective iterator class may
+ * type-safely enforce that data type to be one of its own constructor
+ * argument types. If an accessor class does not need additional data, this
+ * type shall be <tt>void</tt>.
* </ul>
*
* Then the iterator is able to do what it is supposed to. All of the
- * necessary functions are implemented in the <tt>Accessor</tt> base
- * class, but you may write your own version (non-virtual, since we
- * use templates) to add functionality.
+ * necessary functions are implemented in the <tt>Accessor</tt> base class,
+ * but you may write your own version (non-virtual, since we use templates) to
+ * add functionality.
*
- * The accessors provided by the library are distributed in three
- * groups, determined by whether they access the data of
- * Triangulation, DoFHandler or MGDoFHandler. They are derived from
- * TriaAccessor, DoFAccessor and MGDoFAccessor,
- * respectively. In each group, there is an accessor to cells, which
- * have more functionality.
+ * The accessors provided by the library are distributed in three groups,
+ * determined by whether they access the data of Triangulation, DoFHandler or
+ * MGDoFHandler. They are derived from TriaAccessor, DoFAccessor and
+ * MGDoFAccessor, respectively. In each group, there is an accessor to cells,
+ * which have more functionality.
*
- * @attention It seems impossible to preserve constness of a
- * triangulation through iterator usage. Thus, if you declare pointers
- * to a <tt>const</tt> triangulation object, you should be well aware
- * that you might involuntarily alter the data stored in the
- * triangulation.
+ * @attention It seems impossible to preserve constness of a triangulation
+ * through iterator usage. Thus, if you declare pointers to a <tt>const</tt>
+ * triangulation object, you should be well aware that you might involuntarily
+ * alter the data stored in the triangulation.
*
- * @note More information on valid and invalid iterators can be found
- * in the documentation of TriaAccessorBase, where the iterator states are
- * checked and implemented.
+ * @note More information on valid and invalid iterators can be found in the
+ * documentation of TriaAccessorBase, where the iterator states are checked
+ * and implemented.
*
*
* <h3>Past-the-end iterators</h3>
*
* There is a representation of past-the-end-pointers, denoted by special
- * values of the member variables @p present_level and @p present_index:
- * If <tt>present_level>=0</tt> and <tt>present_index>=0</tt>, then the object is valid
- * (there is no check whether the triangulation really has that
- * many levels or that many cells on the present level when we investigate
- * the state of an iterator; however, in many places where an iterator is
- * dereferenced we make this check);
- * if <tt>present_level==-1</tt> and <tt>present_index==-1</tt>, then the iterator points
- * past the end; in all other cases, the iterator is considered invalid.
- * You can check this by calling the <tt>state()</tt> function.
+ * values of the member variables @p present_level and @p present_index: If
+ * <tt>present_level>=0</tt> and <tt>present_index>=0</tt>, then the object is
+ * valid (there is no check whether the triangulation really has that many
+ * levels or that many cells on the present level when we investigate the
+ * state of an iterator; however, in many places where an iterator is
+ * dereferenced we make this check); if <tt>present_level==-1</tt> and
+ * <tt>present_index==-1</tt>, then the iterator points past the end; in all
+ * other cases, the iterator is considered invalid. You can check this by
+ * calling the <tt>state()</tt> function.
*
* An iterator is also invalid, if the pointer pointing to the Triangulation
* object is invalid or zero.
*
- * Finally, an iterator is invalid, if the element pointed to by
- * @p present_level and @p present_index is not used, i.e. if the @p used
- * flag is set to false.
+ * Finally, an iterator is invalid, if the element pointed to by @p
+ * present_level and @p present_index is not used, i.e. if the @p used flag is
+ * set to false.
*
- * The last two checks are not made in <tt>state()</tt> since both cases should only
- * occur upon unitialized construction through @p memcpy and the like (the
- * parent triangulation can only be set upon construction). If
- * an iterator is constructed empty through the empty constructor,
- * <tt>present_level==-2</tt> and <tt>present_index==-2</tt>. Thus, the iterator is
- * invalid anyway, regardless of the state of the triangulation pointer
- * and the state of the element pointed to.
+ * The last two checks are not made in <tt>state()</tt> since both cases
+ * should only occur upon unitialized construction through @p memcpy and the
+ * like (the parent triangulation can only be set upon construction). If an
+ * iterator is constructed empty through the empty constructor,
+ * <tt>present_level==-2</tt> and <tt>present_index==-2</tt>. Thus, the
+ * iterator is invalid anyway, regardless of the state of the triangulation
+ * pointer and the state of the element pointed to.
*
- * Past-the-end iterators may also be used to compare an iterator with the
- * <i>before-the-start</i> value, when running backwards. There is no
+ * Past-the-end iterators may also be used to compare an iterator with the <i
+ * >before-the-start</i> value, when running backwards. There is no
* distinction between the iterators pointing past the two ends of a vector.
*
* By defining only one value to be past-the-end and making all other values
- * invalid provides a second track of security: if we should have forgotten
- * a check in the library when an iterator is incremented or decremented,
- * we automatically convert the iterator from the allowed state "past-the-end"
- * to the disallowed state "invalid" which increases the chance that somehwen
+ * invalid provides a second track of security: if we should have forgotten a
+ * check in the library when an iterator is incremented or decremented, we
+ * automatically convert the iterator from the allowed state "past-the-end" to
+ * the disallowed state "invalid" which increases the chance that somehwen
* earlier than for past-the-end iterators an exception is raised.
*
* @ref Triangulation
{
public:
/**
- * Declare the type of the Accessor for
- * use in the outside world. This way other
- * functions can use the Accessor's type
- * without knowledge of how the exact
- * implementation actually is.
+ * Declare the type of the Accessor for use in the outside world. This way
+ * other functions can use the Accessor's type without knowledge of how the
+ * exact implementation actually is.
*/
typedef Accessor AccessorType;
/**
- * Empty constructor. Such an object
- * is not usable!
+ * Empty constructor. Such an object is not usable!
*/
TriaRawIterator ();
/**
- * Copy constructor.
+ * Copy constructor.
*/
TriaRawIterator (const TriaRawIterator &);
/**
- * Construct an iterator from the given
- * accessor; the given accessor needs not
- * be of the same type as the accessor of
- * this class is, but it needs to be
- * convertible.
+ * Construct an iterator from the given accessor; the given accessor needs
+ * not be of the same type as the accessor of this class is, but it needs to
+ * be convertible.
*
- * Through this constructor, it is also
- * possible to construct objects for
+ * Through this constructor, it is also possible to construct objects for
* derived iterators:
* @code
* DoFCellAccessor dof_accessor;
explicit TriaRawIterator (const Accessor &a);
/**
- * Constructor. Assumes that the
- * other accessor type is
- * convertible to the current
- * one.
+ * Constructor. Assumes that the other accessor type is convertible to the
+ * current one.
*/
template <typename OtherAccessor>
explicit TriaRawIterator (const OtherAccessor &a);
/**
- * Proper constructor, initialized
- * with the triangulation, the
- * level and index of the object
- * pointed to. The last parameter is
- * of a type declared by the accessor
- * class.
+ * Proper constructor, initialized with the triangulation, the level and
+ * index of the object pointed to. The last parameter is of a type declared
+ * by the accessor class.
*/
TriaRawIterator (const Triangulation<Accessor::dimension,Accessor::space_dimension> *parent,
const int level,
const typename AccessorType::AccessorData *local_data = 0);
/**
- * This is a conversion operator
- * (constructor) which takes another
- * iterator type and copies the data;
- * this conversion works, if there is
- * a conversion path from the
- * @p OtherAccessor class to the @p Accessor
- * class of this object. One such path
- * would be derived class to base class,
- * which for example may be used to get
- * a Triangulation::raw_cell_iterator from
- * a DoFHandler::raw_cell_iterator, since
- * the DoFAccessor class is derived from
- * the TriaAccessorBase class.
+ * This is a conversion operator (constructor) which takes another iterator
+ * type and copies the data; this conversion works, if there is a conversion
+ * path from the @p OtherAccessor class to the @p Accessor class of this
+ * object. One such path would be derived class to base class, which for
+ * example may be used to get a Triangulation::raw_cell_iterator from a
+ * DoFHandler::raw_cell_iterator, since the DoFAccessor class is derived
+ * from the TriaAccessorBase class.
*/
template <typename OtherAccessor>
TriaRawIterator (const TriaRawIterator<OtherAccessor> &i);
/**
- * Another conversion operator,
- * where we use the pointers to
- * the Triangulation from a
- * TriaAccessorBase object, while
- * the additional data is used
- * according to the actual type
- * of Accessor.
+ * Another conversion operator, where we use the pointers to the
+ * Triangulation from a TriaAccessorBase object, while the additional data
+ * is used according to the actual type of Accessor.
*/
TriaRawIterator (const TriaAccessorBase<Accessor::structure_dimension,Accessor::dimension,Accessor::space_dimension> &tria_accessor,
const typename Accessor::AccessorData *local_data);
/**
- * Conversion constructor. Same
- * as above with the difference
- * that it converts from
- * TriaIterator classes (not
- * TriaRawIterator).
+ * Conversion constructor. Same as above with the difference that it
+ * converts from TriaIterator classes (not TriaRawIterator).
*/
template <typename OtherAccessor>
TriaRawIterator (const TriaIterator<OtherAccessor> &i);
/**
- * Conversion constructor. Same
- * as above with the difference
- * that it converts from
- * TriaActiveIterator classes
- * (not TriaRawIterator).
+ * Conversion constructor. Same as above with the difference that it
+ * converts from TriaActiveIterator classes (not TriaRawIterator).
*/
template <typename OtherAccessor>
TriaRawIterator (const TriaActiveIterator<OtherAccessor> &i);
/**
- * @name Dereferencing
+ * @name Dereferencing
*/
/*@{*/
/**
- * Dereferencing operator, returns a
- * reference to an accessor.
- * Usage is thus like <tt>(*i).index ();</tt>
+ * Dereferencing operator, returns a reference to an accessor. Usage is thus
+ * like <tt>(*i).index ();</tt>
*
- * This function has to be specialized
- * explicitly for the different
- * @p Pointees, to allow an
- * <tt>iterator<1,TriangulationLevel<1>::LinesData></tt>
- * to point to <tt>tria->lines.cells[index]</tt> while
- * for one dimension higher it has
- * to point to <tt>tria->quads.cells[index]</tt>.
+ * This function has to be specialized explicitly for the different @p
+ * Pointees, to allow an
+ * <tt>iterator<1,TriangulationLevel<1>::LinesData></tt> to point to
+ * <tt>tria->lines.cells[index]</tt> while for one dimension higher it has
+ * to point to <tt>tria->quads.cells[index]</tt>.
*
- * You must not dereference invalid or
- * past the end iterators.
+ * You must not dereference invalid or past the end iterators.
*/
const Accessor &operator * () const;
/**
- * Dereferencing operator, non-@p const
- * version.
+ * Dereferencing operator, non-@p const version.
*/
Accessor &operator * ();
/**
- * Dereferencing operator, returns a
- * reference of the cell pointed to.
- * Usage is thus like <tt>i->index ();</tt>
+ * Dereferencing operator, returns a reference of the cell pointed to. Usage
+ * is thus like <tt>i->index ();</tt>
*
- * There is a @p const and a non-@p const
- * version.
+ * There is a @p const and a non-@p const version.
*/
const Accessor *operator -> () const;
/**
- * Dereferencing operator, non-@p const
- * version.
+ * Dereferencing operator, non-@p const version.
*/
Accessor *operator -> ();
/**
- * In order be able to assign
- * end-iterators for different
- * accessors to each other, we
- * need an access function which
- * returns the accessor
- * regardless of its state.
- *
- * @warning This function should
- * not be used in application
- * programs. It is only intended
- * for limited purposes inside
- * the library and it makes
- * debugging much harder.
- */
+ * In order be able to assign end-iterators for different accessors to each
+ * other, we need an access function which returns the accessor regardless
+ * of its state.
+ *
+ * @warning This function should not be used in application programs. It is
+ * only intended for limited purposes inside the library and it makes
+ * debugging much harder.
+ */
const Accessor &access_any () const;
/*@}*/
/**
- * Assignment operator.
+ * Assignment operator.
*/
TriaRawIterator &operator = (const TriaRawIterator &);
/**
- * Assignment operator.
+ * Assignment operator.
*/
// template <class OtherAccessor>
// TriaRawIterator & operator = (const TriaRawIterator<OtherAccessor>&);
/**
- * Assignment operator.
+ * Assignment operator.
*/
// template <class OtherAccessor>
// TriaRawIterator & operator = (const TriaIterator<OtherAccessor>&);
/**
- * Assignment operator.
+ * Assignment operator.
*/
// template <class OtherAccessor>
// TriaRawIterator & operator = (const TriaActiveIterator<OtherAccessor>&);
/**
- * Compare for equality.
+ * Compare for equality.
*/
bool operator == (const TriaRawIterator &) const;
/**
- * Compare for inequality.
+ * Compare for inequality.
*/
bool operator != (const TriaRawIterator &) const;
* The relation is defined as follows:
*
* For objects of <tt>Accessor::structure_dimension <
- * Accessor::dimension</tt>, we simply compare the index of such an
- * object. The ordering is lexicographic
- * according to the following hierarchy (in the sense, that the next
- * test is only applied if the previous was inconclusive):
+ * Accessor::dimension</tt>, we simply compare the index of such an object.
+ * The ordering is lexicographic according to the following hierarchy (in
+ * the sense, that the next test is only applied if the previous was
+ * inconclusive):
*
* <ol>
- * <li> The past-the-end iterator is always ordered last. Two
- * past-the-end iterators rank the same, thus false is returned in
- * that case.</li>
+ * <li> The past-the-end iterator is always ordered last. Two past-the-end
+ * iterators rank the same, thus false is returned in that case.</li>
*
* <li> The level of the cell.</li>
* <li> The index of a cell inside the level.</li>
* </ol>
*
- * @note The ordering is not consistent between different processor in
- * a parallel::distributed::Triangulation because we rely on index(),
- * which is likely not the same.
+ * @note The ordering is not consistent between different processor in a
+ * parallel::distributed::Triangulation because we rely on index(), which is
+ * likely not the same.
*/
bool operator < (const TriaRawIterator &) const;
/**@name Advancement of iterators*/
/*@{*/
/**
- * Prefix <tt>++</tt> operator: <tt>++iterator</tt>. This
- * operator advances the iterator to
- * the next element and returns
- * a reference to <tt>*this</tt>.
+ * Prefix <tt>++</tt> operator: <tt>++iterator</tt>. This operator advances
+ * the iterator to the next element and returns a reference to
+ * <tt>*this</tt>.
*/
TriaRawIterator &operator ++ ();
/**
- * Postfix <tt>++</tt> operator: <tt>iterator++</tt>. This
- * operator advances the iterator to
- * the next element, but
- * returns an iterator to the element
- * previously pointed to.
+ * Postfix <tt>++</tt> operator: <tt>iterator++</tt>. This operator advances
+ * the iterator to the next element, but returns an iterator to the element
+ * previously pointed to.
*
- * Since this operation
- * involves a temporary and a copy
- * operation and since an
- * @p iterator is quite a large
- * object for a pointer, use the
- * prefix operator <tt>++iterator</tt> whenever
- * possible, especially in the header
- * of for loops
- * (<tt>for (; iterator!=end; ++iterator)</tt>) since there
- * you normally never need the
- * returned value.
+ * Since this operation involves a temporary and a copy operation and since
+ * an @p iterator is quite a large object for a pointer, use the prefix
+ * operator <tt>++iterator</tt> whenever possible, especially in the header
+ * of for loops (<tt>for (; iterator!=end; ++iterator)</tt>) since there you
+ * normally never need the returned value.
*/
TriaRawIterator operator ++ (int);
/**
- * Prefix @p -- operator: @p --iterator. This
- * operator moves the iterator to
- * the previous element and returns
- * a reference to <tt>*this</tt>.
+ * Prefix @p -- operator: @p --iterator. This operator moves the iterator to
+ * the previous element and returns a reference to <tt>*this</tt>.
*/
TriaRawIterator &operator -- ();
/**
- * Postfix @p -- operator: @p iterator--. This
- * operator moves the iterator to
- * the previous element, but
- * returns an iterator to the element
- * previously pointed to.
+ * Postfix @p -- operator: @p iterator--. This operator moves the iterator
+ * to the previous element, but returns an iterator to the element
+ * previously pointed to.
*
- * The same applies as for the postfix operator++: If possible,
- * avoid it by using the prefix operator form to avoid the use
- * of a temporary variable.
+ * The same applies as for the postfix operator++: If possible, avoid it by
+ * using the prefix operator form to avoid the use of a temporary variable.
*/
TriaRawIterator operator -- (int);
/*@}*/
/**
- * Return the state of the iterator.
+ * Return the state of the iterator.
*/
IteratorState::IteratorStates state () const;
/**
- * Print the iterator to a stream
- * <code>out</code>. The
- * format is <tt>level.index</tt>.
+ * Print the iterator to a stream <code>out</code>. The format is
+ * <tt>level.index</tt>.
*/
template <class STREAM>
void print (STREAM &out) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
/**@name Exceptions*/
/*@{*/
/**
- * Exception for TriaObjects with
- * level, i.e. cells.
+ * Exception for TriaObjects with level, i.e. cells.
*/
DeclException1 (ExcDereferenceInvalidCell,
Accessor,
"past_the_end" : "invalid")));
/**
- * Exception for
- * lower-dimensional TriaObjects
- * without level, i.e. objects
- * faces are constructed with.
+ * Exception for lower-dimensional TriaObjects without level, i.e. objects
+ * faces are constructed with.
*/
DeclException1 (ExcDereferenceInvalidObject,
Accessor,
"past_the_end" : "invalid")));
/**
- * Exception
+ * Exception
*/
DeclException0 (ExcAdvanceInvalidObject);
/**
/**
- * Make all other iterator class templates
- * friends of this class. This is
- * necessary for the implementation of
- * conversion constructors.
+ * Make all other iterator class templates friends of this class. This is
+ * necessary for the implementation of conversion constructors.
*
- * In fact, we would not need them to
- * be friends if they were for different
- * dimensions, but the compiler dislikes
- * giving a fixed dimension and variable
- * accessor since then it says that would
- * be a artial specialization.
+ * In fact, we would not need them to be friends if they were for different
+ * dimensions, but the compiler dislikes giving a fixed dimension and
+ * variable accessor since then it says that would be a artial
+ * specialization.
*/
template <typename SomeAccessor> friend class TriaRawIterator;
template <typename SomeAccessor> friend class TriaIterator;
/**
- * This specialization of TriaRawIterator provides access only to
- * the <em>used</em> lines, quads, cells, etc.
+ * This specialization of TriaRawIterator provides access only to the
+ * <em>used</em> lines, quads, cells, etc.
*
* @ingroup grid
* @ingroup Iterators
{
public:
/**
- * Empty constructor. Such an object
- * is not usable!
+ * Empty constructor. Such an object is not usable!
*/
TriaIterator ();
/**
- * Copy constructor.
+ * Copy constructor.
*/
TriaIterator (const TriaIterator<Accessor> &);
/**
- * Cross copy constructor from
- * iterators pointing also to
- * non-active objects.
+ * Cross copy constructor from iterators pointing also to non-active
+ * objects.
*
- * If the object pointed to is not
- * past-the-end and is not
- * used, the debug version raises
- * an error!
+ * If the object pointed to is not past-the-end and is not used, the debug
+ * version raises an error!
*/
TriaIterator (const TriaRawIterator<Accessor> &);
/**
- * Proper constructor, initialized
- * with the triangulation, the
- * level and index of the object
- * pointed to. The last parameter is
- * of a type declared by the accessor
- * class.
+ * Proper constructor, initialized with the triangulation, the level and
+ * index of the object pointed to. The last parameter is of a type declared
+ * by the accessor class.
*
- * If the object pointed to is not
- * past-the-end and is not
- * used, the debug version raises
- * an error!
+ * If the object pointed to is not past-the-end and is not used, the debug
+ * version raises an error!
*/
TriaIterator (const Triangulation<Accessor::dimension,Accessor::space_dimension> *parent,
const int level,
const typename Accessor::AccessorData *local_data = 0);
/**
- * Construct from an accessor of type OtherAccessor that is convertible
- * to the type Accessor.
+ * Construct from an accessor of type OtherAccessor that is convertible to
+ * the type Accessor.
*/
template <typename OtherAccessor>
explicit TriaIterator (const OtherAccessor &a);
/**
- * This is a conversion operator
- * (constructor) which takes another
- * iterator type and copies the data;
- * this conversion works, if there is
- * a conversion path from the
- * @p OtherAccessor class to the @p Accessor
- * class of this object. One such path
- * would be derived class to base class,
- * which for example may be used to get
- * a Triangulation::cell_iterator from
- * a DoFHandler::cell_iterator, since
- * the DoFAccessor class is derived from
+ * This is a conversion operator (constructor) which takes another iterator
+ * type and copies the data; this conversion works, if there is a conversion
+ * path from the @p OtherAccessor class to the @p Accessor class of this
+ * object. One such path would be derived class to base class, which for
+ * example may be used to get a Triangulation::cell_iterator from a
+ * DoFHandler::cell_iterator, since the DoFAccessor class is derived from
* the TriaAccessorBase class.
*/
template <typename OtherAccessor>
TriaIterator (const TriaIterator<OtherAccessor> &i);
/**
- * Another conversion operator,
- * where we use the pointers to
- * the Triangulation from a
- * TriaAccessorBase object, while
- * the additional data is used
- * according to the actual type
- * of Accessor.
+ * Another conversion operator, where we use the pointers to the
+ * Triangulation from a TriaAccessorBase object, while the additional data
+ * is used according to the actual type of Accessor.
*/
TriaIterator (const TriaAccessorBase<Accessor::structure_dimension,Accessor::dimension,Accessor::space_dimension> &tria_accessor,
const typename Accessor::AccessorData *local_data);
/**
- * Similar conversion operator to the above
- * one, but does a check whether the
- * iterator points to a used element,
- * which is necessary for raw iterators.
+ * Similar conversion operator to the above one, but does a check whether
+ * the iterator points to a used element, which is necessary for raw
+ * iterators.
*/
template <typename OtherAccessor>
TriaIterator (const TriaRawIterator<OtherAccessor> &i);
/**
- * Similar conversion operator to
- * the above one, but for
- * conversion from active
- * iterators.
+ * Similar conversion operator to the above one, but for conversion from
+ * active iterators.
*/
template <typename OtherAccessor>
TriaIterator (const TriaActiveIterator<OtherAccessor> &i);
/**
- * Assignment operator.
+ * Assignment operator.
*/
TriaIterator<Accessor> &
operator = (const TriaIterator<Accessor> &);
/**
- * Cross assignment operator. This
- * assignment is only valid if the
- * given iterator points to a used
- * element.
+ * Cross assignment operator. This assignment is only valid if the given
+ * iterator points to a used element.
*/
TriaIterator<Accessor> &
operator = (const TriaRawIterator<Accessor> &);
/**
- * Assignment
- * operator. Requires, that
- * Accessor can be copied from
- * OtherAccessor.
+ * Assignment operator. Requires, that Accessor can be copied from
+ * OtherAccessor.
*/
template <class OtherAccessor>
TriaIterator<Accessor> &
operator = (const TriaIterator<OtherAccessor> &);
/**
- * Cross assignment operator. This
- * assignment is only valid if the
- * given iterator points to a used
- * element. Requires, that
- * Accessor can be copied from
- * OtherAccessor.
+ * Cross assignment operator. This assignment is only valid if the given
+ * iterator points to a used element. Requires, that Accessor can be copied
+ * from OtherAccessor.
*/
template <class OtherAccessor>
TriaIterator<Accessor> &
/**@name Advancement of iterators*/
/*@{*/
/**
- * Prefix <tt>++</tt> operator: <tt>++i</tt>. This
- * operator advances the iterator to
- * the next used element and returns
- * a reference to <tt>*this</tt>.
+ * Prefix <tt>++</tt> operator: <tt>++i</tt>. This operator advances the
+ * iterator to the next used element and returns a reference to
+ * <tt>*this</tt>.
*/
TriaIterator<Accessor> &operator ++ ();
/**
- * Postfix <tt>++</tt> operator: <tt>i++</tt>. This
- * operator advances the iterator to
- * the next used element, but
- * returns an iterator to the element
- * previously pointed to. Since this
- * involves a temporary and a copy
- * operation and since an
- * @p active_iterator is quite a large
- * object for a pointer, use the
- * prefix operator <tt>++i</tt> whenever
- * possible, especially in the head
- * of for loops
- * (<tt>for (; i!=end; ++i)</tt>) since there
- * you normally never need the
- * returned value.
+ * Postfix <tt>++</tt> operator: <tt>i++</tt>. This operator advances the
+ * iterator to the next used element, but returns an iterator to the element
+ * previously pointed to. Since this involves a temporary and a copy
+ * operation and since an @p active_iterator is quite a large object for a
+ * pointer, use the prefix operator <tt>++i</tt> whenever possible,
+ * especially in the head of for loops (<tt>for (; i!=end; ++i)</tt>) since
+ * there you normally never need the returned value.
*/
TriaIterator<Accessor> operator ++ (int);
/**
- * Prefix @p -- operator: @p --i. This
- * operator advances the iterator to
- * the previous used element and returns
- * a reference to <tt>*this</tt>.
+ * Prefix @p -- operator: @p --i. This operator advances the iterator to the
+ * previous used element and returns a reference to <tt>*this</tt>.
*/
TriaIterator<Accessor> &operator -- ();
/**
- * Postfix @p -- operator: @p i--.
+ * Postfix @p -- operator: @p i--.
*/
TriaIterator<Accessor> operator -- (int);
/*@}*/
/**
- * Exception
+ * Exception
*/
DeclException0 (ExcAssignmentOfUnusedObject);
};
/**
- * This specialization of TriaIterator provides access only to the
- * <em>active</em> lines, quads, cells, etc. An active cell is a
- * cell which is not refined and thus a cell on which calculations
- * on the finest level are done.
+ * This specialization of TriaIterator provides access only to the
+ * <em>active</em> lines, quads, cells, etc. An active cell is a cell which is
+ * not refined and thus a cell on which calculations on the finest level are
+ * done.
*
* @ingroup grid
* @ingroup Iterators
{
public:
/**
- * Empty constructor. Such an object
- * is not usable!
+ * Empty constructor. Such an object is not usable!
*/
TriaActiveIterator ();
/**
- * Copy constructor.
+ * Copy constructor.
*/
TriaActiveIterator (const TriaActiveIterator<Accessor> &);
/**
- * Cross copy constructor from
- * iterators pointing also to
- * non-active objects.
+ * Cross copy constructor from iterators pointing also to non-active
+ * objects.
*
- * If the object pointed to is not
- * past-the-end and is not
- * active, the debug version raises
- * an error!
+ * If the object pointed to is not past-the-end and is not active, the debug
+ * version raises an error!
*/
TriaActiveIterator (const TriaRawIterator<Accessor> &);
/**
- * Cross copy constructor from
- * iterators pointing also to
- * non-active objects.
+ * Cross copy constructor from iterators pointing also to non-active
+ * objects.
*
- * If the object pointed to is not
- * past-the-end and is not
- * active, the debug version raises
- * an error!
+ * If the object pointed to is not past-the-end and is not active, the debug
+ * version raises an error!
*/
TriaActiveIterator (const TriaIterator<Accessor> &);
/**
- * Proper constructor, initialized
- * with the triangulation, the
- * level and index of the object
- * pointed to. The last parameter is
- * of a type declared by the accessor
- * class.
+ * Proper constructor, initialized with the triangulation, the level and
+ * index of the object pointed to. The last parameter is of a type declared
+ * by the accessor class.
*
- * If the object pointed to is not
- * past-the-end and is not
- * active, the debug version raises
- * an error!
+ * If the object pointed to is not past-the-end and is not active, the debug
+ * version raises an error!
*/
TriaActiveIterator (const Triangulation<Accessor::dimension,Accessor::space_dimension> *parent,
const int level,
const typename Accessor::AccessorData *local_data = 0);
/**
- * This is a conversion operator
- * (constructor) which takes another
- * iterator type and copies the data;
- * this conversion works, if there is
- * a conversion path from the
- * @p OtherAccessor class to the @p Accessor
- * class of this object. One such path
- * would be derived class to base class,
- * which for example may be used to get
- * a Triangulation::active_cell_iterator from
- * a DoFHandler::active_cell_iterator, since
- * the DoFAccessor class is derived from
- * the TriaAccessorBase class.
+ * This is a conversion operator (constructor) which takes another iterator
+ * type and copies the data; this conversion works, if there is a conversion
+ * path from the @p OtherAccessor class to the @p Accessor class of this
+ * object. One such path would be derived class to base class, which for
+ * example may be used to get a Triangulation::active_cell_iterator from a
+ * DoFHandler::active_cell_iterator, since the DoFAccessor class is derived
+ * from the TriaAccessorBase class.
*/
template <typename OtherAccessor>
TriaActiveIterator (const TriaActiveIterator<OtherAccessor> &i);
/**
- * Another conversion operator,
- * where we use the pointers to
- * the Triangulation from a
- * TriaAccessorBase object, while
- * the additional data is used
- * according to the actual type
- * of Accessor.
- */
+ * Another conversion operator, where we use the pointers to the
+ * Triangulation from a TriaAccessorBase object, while the additional data
+ * is used according to the actual type of Accessor.
+ */
TriaActiveIterator (const TriaAccessorBase<Accessor::structure_dimension,Accessor::dimension,Accessor::space_dimension> &tria_accessor,
const typename Accessor::AccessorData *local_data);
/**
- * Similar conversion operator to the above
- * one, but does a check whether the
- * iterator points to a used element,
- * and is active, which is necessary for
- * raw iterators. Since usual iterators
- * are also raw iterators, this constructor
- * works also for parameters of type
+ * Similar conversion operator to the above one, but does a check whether
+ * the iterator points to a used element, and is active, which is necessary
+ * for raw iterators. Since usual iterators are also raw iterators, this
+ * constructor works also for parameters of type
* <tt>TriaIterator<OtherAccessor></tt>.
*/
template <typename OtherAccessor>
TriaActiveIterator (const TriaRawIterator<OtherAccessor> &i);
/**
- * Assignment operator.
+ * Assignment operator.
*/
TriaActiveIterator<Accessor> &
operator = (const TriaActiveIterator<Accessor> &);
/**
- * Cross assignment operator. This
- * assignment is only valid if the
- * given iterator points to an active
- * element.
+ * Cross assignment operator. This assignment is only valid if the given
+ * iterator points to an active element.
*/
TriaActiveIterator<Accessor> &
operator = (const TriaIterator<Accessor> &);
/**
- * Cross assignment operator. This
- * assignment is only valid if the
- * given iterator points to an active
- * element or past the end.
+ * Cross assignment operator. This assignment is only valid if the given
+ * iterator points to an active element or past the end.
*/
TriaActiveIterator<Accessor> &
operator = (const TriaRawIterator<Accessor> &);
/**
- * Assignment operator. Requires, that
- * Accessor can be copied from
- * OtherAccessor.
+ * Assignment operator. Requires, that Accessor can be copied from
+ * OtherAccessor.
*/
template <class OtherAccessor>
TriaActiveIterator<Accessor> &
operator = (const TriaActiveIterator<OtherAccessor> &);
/**
- * Cross assignment operator. This
- * assignment is only valid if the
- * given iterator points to an active
- * element or past the end. Requires, that
- * Accessor can be copied from
- * OtherAccessor.
+ * Cross assignment operator. This assignment is only valid if the given
+ * iterator points to an active element or past the end. Requires, that
+ * Accessor can be copied from OtherAccessor.
*/
template <class OtherAccessor>
TriaActiveIterator<Accessor> &
operator = (const TriaRawIterator<OtherAccessor> &);
/**
- * Cross assignment operator. This
- * assignment is only valid if the
- * given iterator points to an active
- * element. Requires, that
- * Accessor can be copied from
- * OtherAccessor.
+ * Cross assignment operator. This assignment is only valid if the given
+ * iterator points to an active element. Requires, that Accessor can be
+ * copied from OtherAccessor.
*/
template <class OtherAccessor>
TriaActiveIterator<Accessor> &
operator = (const TriaIterator<OtherAccessor> &);
/**
- * Prefix <tt>++</tt> operator: <tt>++i</tt>. This
- * operator advances the iterator to
- * the next active element and returns
- * a reference to <tt>*this</tt>.
+ * Prefix <tt>++</tt> operator: <tt>++i</tt>. This operator advances the
+ * iterator to the next active element and returns a reference to
+ * <tt>*this</tt>.
*/
TriaActiveIterator<Accessor> &operator ++ ();
/**@name Advancement of iterators*/
/*@{*/
/**
- * Postfix <tt>++</tt> operator: <tt>i++</tt>. This
- * operator advances the iterator to
- * the next active element, but
- * returns an iterator to the element
- * previously pointed to. Since this
- * involves a temporary and a copy
- * operation and since an
- * @p active_iterator is quite a large
- * object for a pointer, use the
- * prefix operator <tt>++i</tt> whenever
- * possible, especially in the head
- * of for loops
- * (<tt>for (; i!=end; ++i)</tt>) since there
- * you normally never need the
- * returned value.
+ * Postfix <tt>++</tt> operator: <tt>i++</tt>. This operator advances the
+ * iterator to the next active element, but returns an iterator to the
+ * element previously pointed to. Since this involves a temporary and a copy
+ * operation and since an @p active_iterator is quite a large object for a
+ * pointer, use the prefix operator <tt>++i</tt> whenever possible,
+ * especially in the head of for loops (<tt>for (; i!=end; ++i)</tt>) since
+ * there you normally never need the returned value.
*/
TriaActiveIterator<Accessor> operator ++ (int);
/**
- * Prefix @p -- operator: @p --i. This
- * operator advances the iterator to
- * the previous active element and
- * returns a reference to <tt>*this</tt>.
+ * Prefix @p -- operator: @p --i. This operator advances the iterator to the
+ * previous active element and returns a reference to <tt>*this</tt>.
*/
TriaActiveIterator<Accessor> &operator -- ();
/**
- * Postfix @p -- operator: @p i--.
+ * Postfix @p -- operator: @p i--.
*/
TriaActiveIterator<Accessor> operator -- (int);
/*@}*/
/**
- * Exception
+ * Exception
*/
DeclException0 (ExcAssignmentOfInactiveObject);
};
/**
- * Print the address to which this iterator points to @p out. The
- * address is given by the pair <tt>(level,index)</tt>, where @p index is
- * an index relative to the level in which the object is that is
- * pointed to.
+ * Print the address to which this iterator points to @p out. The address is
+ * given by the pair <tt>(level,index)</tt>, where @p index is an index
+ * relative to the level in which the object is that is pointed to.
*
* @author Wolfgang Bangerth, 1998
*/
/**
- * Print the address to which this iterator points to @p out. The
- * address is given by the pair <tt>(level,index)</tt>, where @p index is
- * an index relative to the level in which the object is that is
- * pointed to.
+ * Print the address to which this iterator points to @p out. The address is
+ * given by the pair <tt>(level,index)</tt>, where @p index is an index
+ * relative to the level in which the object is that is pointed to.
*
* @author Wolfgang Bangerth, 1998
*/
/**
- * Print the address to which this iterator points to @p out. The
- * address is given by the pair <tt>(level,index)</tt>, where @p index is
- * an index relative to the level in which the object is that is
- * pointed to.
+ * Print the address to which this iterator points to @p out. The address is
+ * given by the pair <tt>(level,index)</tt>, where @p index is an index
+ * relative to the level in which the object is that is pointed to.
*
* @author Wolfgang Bangerth, 1998
*/
DEAL_II_NAMESPACE_OPEN
/**
- * Namespace in which an enumeration is declared that denotes the
- * states in which an iterator can be in.
+ * Namespace in which an enumeration is declared that denotes the states in
+ * which an iterator can be in.
*
* @ingroup Iterators
*/
{
/**
- * The three states an iterator can be in: valid, past-the-end and
- * invalid.
+ * The three states an iterator can be in: valid, past-the-end and invalid.
*/
enum IteratorStates
{
struct Iterators;
/**
- * This class implements some types which differ between the dimensions.
- * These are the declararions for the 1D case only. See the @ref Iterators
- * module for more information.
+ * This class implements some types which differ between the dimensions.
+ * These are the declararions for the 1D case only. See the @ref Iterators
+ * module for more information.
*
- * A @p line_iterator is typdef'd to an iterator operating on the
- * @p lines member variable of a <tt>Triangulation<1></tt> object. An
- * @p active_line_iterator only operates on the active lines.
- * @p raw_line_iterator objects operate on all lines, used or not.
+ * A @p line_iterator is typdef'd to an iterator operating on the @p lines
+ * member variable of a <tt>Triangulation<1></tt> object. An @p
+ * active_line_iterator only operates on the active lines. @p
+ * raw_line_iterator objects operate on all lines, used or not.
*
- * Since we are in one dimension, the following identities are declared:
+ * Since we are in one dimension, the following identities are declared:
* @code
* typedef raw_line_iterator raw_cell_iterator;
* typedef line_iterator cell_iterator;
* typedef active_line_iterator active_cell_iterator;
* @endcode
*
- * To enable the declaration of @p begin_quad and the like in
- * <tt>Triangulation<1></tt>, the @p quad_iterators are declared as
- * iterators over InvalidAccessor. Thus these types exist, but
- * are useless and will certainly make any involuntary use
- * visible. The same holds for hexahedron iterators.
+ * To enable the declaration of @p begin_quad and the like in
+ * <tt>Triangulation<1></tt>, the @p quad_iterators are declared as
+ * iterators over InvalidAccessor. Thus these types exist, but are useless
+ * and will certainly make any involuntary use visible. The same holds for
+ * hexahedron iterators.
*
- * The same applies for the @p face_iterator types, since lines
- * have no substructures apart from vertices, which are handled in
- * a different way, however.
+ * The same applies for the @p face_iterator types, since lines have no
+ * substructures apart from vertices, which are handled in a different
+ * way, however.
*
* @author Wolfgang Bangerth, 1998
*/
/**
- * This class implements some types which differ between the dimensions.
- * These are the declararions for the 2D case only. See the @ref Iterators
- * module for more information.
+ * This class implements some types which differ between the dimensions.
+ * These are the declararions for the 2D case only. See the @ref Iterators
+ * module for more information.
*
- * A @p line_iterator is typdef'd to an iterator operating on the
- * @p lines member variable of a <tt>Triangulation<2></tt> object. An
- * @p active_line_iterator only operates on the active lines.
- * @p raw_line_iterator objects operate on all lines, used or not.
- * Using @p active_line_iterators may not be particularly in 2D useful since it
- * only operates on unrefined lines. However, also refined lines may bound
- * unrefined cells if the neighboring cell is refined once more than the
- * present one.
+ * A @p line_iterator is typdef'd to an iterator operating on the @p lines
+ * member variable of a <tt>Triangulation<2></tt> object. An @p
+ * active_line_iterator only operates on the active lines. @p
+ * raw_line_iterator objects operate on all lines, used or not. Using @p
+ * active_line_iterators may not be particularly in 2D useful since it
+ * only operates on unrefined lines. However, also refined lines may bound
+ * unrefined cells if the neighboring cell is refined once more than the
+ * present one.
*
- * Similarly to line iterators, @p quad_iterator, @p raw_quad_iterator and
- * @p active_quad_iterator are declared.
+ * Similarly to line iterators, @p quad_iterator, @p raw_quad_iterator and
+ * @p active_quad_iterator are declared.
*
- * To enable the declaration of @p begin_hex and the like in
- * <tt>Triangulation<[12]></tt>, the @p hex_iterators are declared as
- * iterators over InvalidAccessor. Thus these types exist, but
- * are useless and will certainly make any involuntary use visible.
+ * To enable the declaration of @p begin_hex and the like in
+ * <tt>Triangulation<[12]></tt>, the @p hex_iterators are declared as
+ * iterators over InvalidAccessor. Thus these types exist, but are useless
+ * and will certainly make any involuntary use visible.
*
- * Since we are in two dimension, the following identities are declared:
+ * Since we are in two dimension, the following identities are declared:
* @code
* typedef raw_quad_iterator raw_cell_iterator;
* typedef quad_iterator cell_iterator;
/**
- * This class implements some types which differ between the dimensions.
- * These are the declararions for the 3D case only. See the @ref Iterators
- * module for more information.
+ * This class implements some types which differ between the dimensions.
+ * These are the declararions for the 3D case only. See the @ref Iterators
+ * module for more information.
*
- * For the declarations of the data types, more or less the same holds
- * as for lower dimensions (see <tt>Iterators<[12]></tt>). The
- * dimension specific data types are here, since we are in three dimensions:
+ * For the declarations of the data types, more or less the same holds as
+ * for lower dimensions (see <tt>Iterators<[12]></tt>). The dimension
+ * specific data types are here, since we are in three dimensions:
* @code
* typedef raw_hex_iterator raw_cell_iterator;
* typedef hex_iterator cell_iterator;
* (what a cell actually is is declared elsewhere), etc. See also
* TriaObjects for non level-oriented data.
*
- * There is another field, which may fit in here, namely the
- * material data (for cells) or the boundary indicators (for faces),
- * but since we need for a line or quad either boundary information or
- * material data, we store them with the lines and quads rather than
- * with the common data. Likewise, in 3d, we need boundary indicators
- * for lines and quads (we need to know how to refine a line if the
- * two adjacent faces have different boundary indicators), and
- * material data for cells.
+ * There is another field, which may fit in here, namely the material data
+ * (for cells) or the boundary indicators (for faces), but since we need
+ * for a line or quad either boundary information or material data, we
+ * store them with the lines and quads rather than with the common data.
+ * Likewise, in 3d, we need boundary indicators for lines and quads (we
+ * need to know how to refine a line if the two adjacent faces have
+ * different boundary indicators), and material data for cells.
*
* @author Wolfgang Bangerth, Guido Kanschat, 1998, 2007
*/
{
public:
/**
- * @p RefinementCase<dim>::Type flags
- * for the cells to be
- * refined with or not
- * (RefinementCase<dim>::no_refinement). The
- * meaning what a cell is,
- * is dimension specific,
- * therefore also the length
- * of this vector depends on
- * the dimension: in one
- * dimension, the length of
- * this vector equals the
- * length of the @p lines
- * vector, in two dimensions
- * that of the @p quads
- * vector, etc.
+ * @p RefinementCase<dim>::Type flags for the cells to be refined with
+ * or not (RefinementCase<dim>::no_refinement). The meaning what a cell
+ * is, is dimension specific, therefore also the length of this vector
+ * depends on the dimension: in one dimension, the length of this vector
+ * equals the length of the @p lines vector, in two dimensions that of
+ * the @p quads vector, etc.
*/
std::vector<unsigned char> refine_flags;
/**
- * Same meaning as the one above, but
- * specifies whether a cell must be
+ * Same meaning as the one above, but specifies whether a cell must be
* coarsened.
*/
std::vector<bool> coarsen_flags;
/**
- * Levels and indices of the neighbors
- * of the cells. Convention is, that the
- * neighbors of the cell with index @p i
- * are stored in the fields following
- * $i*(2*real\_space\_dimension)$, e.g. in
- * one spatial dimension, the neighbors
- * of cell 0 are stored in <tt>neighbors[0]</tt>
- * and <tt>neighbors[1]</tt>, the neighbors of
- * cell 1 are stored in <tt>neighbors[2]</tt>
- * and <tt>neighbors[3]</tt>, and so on.
+ * Levels and indices of the neighbors of the cells. Convention is, that
+ * the neighbors of the cell with index @p i are stored in the fields
+ * following $i*(2*real\_space\_dimension)$, e.g. in one spatial
+ * dimension, the neighbors of cell 0 are stored in
+ * <tt>neighbors[0]</tt> and <tt>neighbors[1]</tt>, the neighbors of
+ * cell 1 are stored in <tt>neighbors[2]</tt> and <tt>neighbors[3]</tt>,
+ * and so on.
*
- * In neighbors, <tt>neighbors[i].first</tt> is
- * the level, while <tt>neighbors[i].first</tt>
- * is the index of the neighbor.
+ * In neighbors, <tt>neighbors[i].first</tt> is the level, while
+ * <tt>neighbors[i].first</tt> is the index of the neighbor.
*
- * If a neighbor does not exist (cell is
- * at the boundary), <tt>level=index=-1</tt>
- * is set.
+ * If a neighbor does not exist (cell is at the boundary),
+ * <tt>level=index=-1</tt> is set.
*
- * <em>Conventions:</em> The
- * @p ith neighbor of a cell is
- * the one which shares the
- * @p ith face (@p Line in 2D,
- * @p Quad in 3D) of this cell.
+ * <em>Conventions:</em> The @p ith neighbor of a cell is the one which
+ * shares the @p ith face (@p Line in 2D, @p Quad in 3D) of this cell.
*
- * The neighbor of a cell has at most the
- * same level as this cell, i.e. it may
- * or may not be refined.
+ * The neighbor of a cell has at most the same level as this cell, i.e.
+ * it may or may not be refined.
*
- * In one dimension, a neighbor may have
- * any level less or equal the level of
- * this cell. If it has the same level,
- * it may be refined an arbitrary number
- * of times, but the neighbor pointer
- * still points to the cell on the same
- * level, while the neighbors of the
- * childs of the neighbor may point to
- * this cell or its children.
+ * In one dimension, a neighbor may have any level less or equal the
+ * level of this cell. If it has the same level, it may be refined an
+ * arbitrary number of times, but the neighbor pointer still points to
+ * the cell on the same level, while the neighbors of the childs of the
+ * neighbor may point to this cell or its children.
*
- * In two and more dimensions, the
- * neighbor is either on the same level
- * and refined (in which case its children
- * have neighbor pointers to this cell or
- * its direct children), unrefined on
- * the same level or one level down (in
- * which case its neighbor pointer points
- * to the mother cell of this cell).
+ * In two and more dimensions, the neighbor is either on the same level
+ * and refined (in which case its children have neighbor pointers to
+ * this cell or its direct children), unrefined on the same level or one
+ * level down (in which case its neighbor pointer points to the mother
+ * cell of this cell).
*/
std::vector<std::pair<int,int> > neighbors;
/**
- * One integer per cell to store
- * which subdomain it belongs
- * to. This field is most often
- * used in parallel computations,
- * where it denotes which
- * processor shall work on the
- * cells with a given subdomain
+ * One integer per cell to store which subdomain it belongs to. This
+ * field is most often used in parallel computations, where it denotes
+ * which processor shall work on the cells with a given subdomain
* number.
*/
std::vector<types::subdomain_id> subdomain_ids;
std::vector<types::subdomain_id> level_subdomain_ids;
/**
- * One integer for every consecutive
- * pair of cells to store which
- * index their parent has.
+ * One integer for every consecutive pair of cells to store which index
+ * their parent has.
*
* (We store this information once for each pair of cells since every
* refinement, isotropic or anisotropic, and in any space dimension,
std::vector<int> parents;
/**
- * One bool per cell to indicate the
- * direction of the normal
- * true: use orientation from vertex
- * false: revert the orientation. See
- * @ref GlossDirectionFlag .
+ * One bool per cell to indicate the direction of the normal true: use
+ * orientation from vertex false: revert the orientation. See @ref
+ * GlossDirectionFlag .
*
- * This is only used for
- * codim==1 meshes.
+ * This is only used for codim==1 meshes.
*/
std::vector<bool> direction_flags;
/**
- * The object containing the data on lines and
- * related functions
+ * The object containing the data on lines and related functions
*/
TriaObjects<TriaObject<dim> > cells;
/**
- * Reserve enough space to accommodate
- * @p total_cells cells on this level.
- * Since there are no @p used flags on this
- * level, you have to give the total number
- * of cells, not only the number of newly
- * to accommodate ones, like in the
- * <tt>TriaLevel<N>::reserve_space</tt>
- * functions, with <tt>N>0</tt>.
+ * Reserve enough space to accommodate @p total_cells cells on this
+ * level. Since there are no @p used flags on this level, you have to
+ * give the total number of cells, not only the number of newly to
+ * accommodate ones, like in the <tt>TriaLevel<N>::reserve_space</tt>
+ * functions, with <tt>N>0</tt>.
*
- * Since the
- * number of neighbors per cell depends
- * on the dimensions, you have to pass
- * that additionally.
+ * Since the number of neighbors per cell depends on the dimensions, you
+ * have to pass that additionally.
*/
void reserve_space (const unsigned int total_cells,
const unsigned int space_dimension);
/**
- * Check the memory consistency of the
- * different containers. Should only be
- * called with the prepro flag @p DEBUG
- * set. The function should be called from
- * the functions of the higher
- * TriaLevel classes.
+ * Check the memory consistency of the different containers. Should only
+ * be called with the prepro flag @p DEBUG set. The function should be
+ * called from the functions of the higher TriaLevel classes.
*/
void monitor_memory (const unsigned int true_dimension) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
*/
template <class Archive>
void serialize(Archive &ar,
const unsigned int version);
/**
- * Exception
+ * Exception
*/
DeclException3 (ExcMemoryWasted,
char *, int, int,
<< arg2 << " elements, but it`s capacity is "
<< arg3 << ".");
/**
- * Exception
+ * Exception
*/
DeclException2 (ExcMemoryInexact,
int, int,
/**
* Specialization of TriaLevels for 3D. Since we need TriaObjectsHex
- * instead of TriaObjects. Refer to the documentation of the template
- * for details.
+ * instead of TriaObjects. Refer to the documentation of the template for
+ * details.
*/
template<>
class TriaLevel<3>
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
*/
template <class Archive>
void serialize(Archive &ar,
const unsigned int version);
/**
- * Exception
+ * Exception
*/
DeclException3 (ExcMemoryWasted,
char *, int, int,
<< arg2 << " elements, but it`s capacity is "
<< arg3 << ".");
/**
- * Exception
+ * Exception
*/
DeclException2 (ExcMemoryInexact,
int, int,
{
/**
- * Class template for the <tt>structdim</tt>-dimensional cells constituting
- * a dealii::Triangulation of dimension <tt>structdim</tt> or lower dimensional
- * objects of higher dimensions. They are characterized by the
- * (global) indices of their faces, which are cells of dimension
+ * Class template for the <tt>structdim</tt>-dimensional cells
+ * constituting a dealii::Triangulation of dimension <tt>structdim</tt> or
+ * lower dimensional objects of higher dimensions. They are characterized
+ * by the (global) indices of their faces, which are cells of dimension
* <tt>structdim-1</tt> or vertices if <tt>structdim=1</tt>.
*
* @author Guido Kanschat, 2007
static const unsigned int dimension = structdim;
/**
- * Default constructor,
- * setting all face indices
- * to invalid values.
+ * Default constructor, setting all face indices to invalid values.
*/
TriaObject ();
/**
- * Constructor for a line
- * object with the numbers of
- * its two end points.
+ * Constructor for a line object with the numbers of its two end points.
*
- * Throws an exception if
- * dimension is not one.
+ * Throws an exception if dimension is not one.
*/
TriaObject (const int i0, const int i1);
/**
- * Constructor for a quadrilateral
- * object with the numbers of
- * its four lines.
+ * Constructor for a quadrilateral object with the numbers of its four
+ * lines.
*
- * Throws an exception if
- * dimension is not two.
+ * Throws an exception if dimension is not two.
*/
TriaObject (const int i0, const int i1,
const int i2, const int i3);
/**
- * Constructor for a hexahedron
- * object with the numbers of
- * its six quadrilaterals.
+ * Constructor for a hexahedron object with the numbers of its six
+ * quadrilaterals.
*
- * Throws an exception if
- * dimension is not two.
+ * Throws an exception if dimension is not two.
*/
TriaObject (const int i0, const int i1,
const int i2, const int i3,
/**
- * Return the index of the
- * ith face object.
+ * Return the index of the ith face object.
*/
int face (const unsigned int i) const;
/**
- * Set the index of the ith
- * face object.
+ * Set the index of the ith face object.
*/
void set_face (const unsigned int i, const int index);
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
static std::size_t memory_consumption ();
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
*/
template <class Archive>
void serialize(Archive &ar,
protected:
/**
- * Global indices of the
- * face iterators bounding
- * this cell if dim@>1, and
- * the two vertex indices in
- * 1d.
+ * Global indices of the face iterators bounding this cell if dim@>1,
+ * and the two vertex indices in 1d.
*/
int faces[GeometryInfo<structdim>::faces_per_cell];
};
{
/**
- * General template for information belonging to the geometrical objects of a
- * triangulation, i.e. lines, quads, hexahedra... Apart from the vector of
- * objects additional information is included, namely vectors indicating the
- * children, the used-status, user-flags, material-ids..
+ * General template for information belonging to the geometrical objects
+ * of a triangulation, i.e. lines, quads, hexahedra... Apart from the
+ * vector of objects additional information is included, namely vectors
+ * indicating the children, the used-status, user-flags, material-ids..
*
* Objects of these classes are included in the TriaLevel and TriaFaces
* classes.
TriaObjects();
/**
- * Vector of the objects belonging to
- * this level. The index of the object
- * equals the index in this container.
+ * Vector of the objects belonging to this level. The index of the
+ * object equals the index in this container.
*/
std::vector<G> cells;
/**
- * Index of the even children of an object.
- * Since when objects are refined, all
- * children are created at the same
- * time, they are appended to the list
- * at least in pairs after each other.
- * We therefore only store the index
- * of the even children, the uneven
- * follow immediately afterwards.
+ * Index of the even children of an object. Since when objects are
+ * refined, all children are created at the same time, they are appended
+ * to the list at least in pairs after each other. We therefore only
+ * store the index of the even children, the uneven follow immediately
+ * afterwards.
*
- * If an object has no children, -1 is
- * stored in this list. An object is
- * called active if it has no
- * children. The function
- * TriaAccessorBase::has_children()
- * tests for this.
+ * If an object has no children, -1 is stored in this list. An object is
+ * called active if it has no children. The function
+ * TriaAccessorBase::has_children() tests for this.
*/
std::vector<int> children;
/**
- * Store the refinement
- * case each of the
- * cells is refined
- * with. This vector
- * might be replaced by
- * vector<vector<bool> >
- * (dim, vector<bool>
- * (n_cells)) which is
- * more memory efficient.
+ * Store the refinement case each of the cells is refined with. This
+ * vector might be replaced by vector<vector<bool> > (dim, vector<bool>
+ * (n_cells)) which is more memory efficient.
*/
std::vector<RefinementCase<G::dimension> > refinement_cases;
/**
- * Vector storing whether an object is
- * used in the @p cells vector.
+ * Vector storing whether an object is used in the @p cells vector.
*
- * Since it is difficult to delete
- * elements in a @p vector, when an
- * element is not needed any more
- * (e.g. after derefinement), it is
- * not deleted from the list, but
- * rather the according @p used flag
- * is set to @p false.
+ * Since it is difficult to delete elements in a @p vector, when an
+ * element is not needed any more (e.g. after derefinement), it is not
+ * deleted from the list, but rather the according @p used flag is set
+ * to @p false.
*/
std::vector<bool> used;
/**
- * Make available a field for user data,
- * one bit per object. This field is usually
- * used when an operation runs over all
- * cells and needs information whether
- * another cell (e.g. a neighbor) has
- * already been processed.
+ * Make available a field for user data, one bit per object. This field
+ * is usually used when an operation runs over all cells and needs
+ * information whether another cell (e.g. a neighbor) has already been
+ * processed.
*
- * You can clear all used flags using
- * dealii::Triangulation::clear_user_flags().
+ * You can clear all used flags using
+ * dealii::Triangulation::clear_user_flags().
*/
std::vector<bool> user_flags;
/**
- * We use this union to store
- * boundary and material
- * data. Because only one one
- * out of these two is
- * actually needed here, we
- * use an union.
+ * We use this union to store boundary and material data. Because only
+ * one one out of these two is actually needed here, we use an union.
*/
struct BoundaryOrMaterialId
{
BoundaryOrMaterialId ();
/**
- * Return the size of objects
- * of this kind.
+ * Return the size of objects of this kind.
*/
static
std::size_t memory_consumption ();
/**
- * Read or write the data
- * of this object to or
- * from a stream for the
- * purpose of
- * serialization
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
*/
template <class Archive>
void serialize(Archive &ar,
};
/**
- * Store boundary and material data. For
- * example, in one dimension, this field
- * stores the material id of a line, which
- * is a number between 0 and
- * numbers::invalid_material_id-1. In more
- * than one dimension, lines have no
- * material id, but they may be at the
- * boundary; then, we store the
- * boundary indicator in this field,
- * which denotes to which part of the
- * boundary this line belongs and which
- * boundary conditions hold on this
- * part. The boundary indicator also
- * is a number between zero and
- * numbers::internal_face_boundary_id-1;
- * the id numbers::internal_face_boundary_id
- * is reserved for lines
- * in the interior and may be used
- * to check whether a line is at the
- * boundary or not, which otherwise
- * is not possible if you don't know
- * which cell it belongs to.
+ * Store boundary and material data. For example, in one dimension, this
+ * field stores the material id of a line, which is a number between 0
+ * and numbers::invalid_material_id-1. In more than one dimension, lines
+ * have no material id, but they may be at the boundary; then, we store
+ * the boundary indicator in this field, which denotes to which part of
+ * the boundary this line belongs and which boundary conditions hold on
+ * this part. The boundary indicator also is a number between zero and
+ * numbers::internal_face_boundary_id-1; the id
+ * numbers::internal_face_boundary_id is reserved for lines in the
+ * interior and may be used to check whether a line is at the boundary
+ * or not, which otherwise is not possible if you don't know which cell
+ * it belongs to.
*/
std::vector<BoundaryOrMaterialId> boundary_or_material_id;
/**
- * Store manifold ids. This field
- * stores the manifold id of each object, which
- * is a number between 0 and
- * numbers::invalid_manifold_id-1.
+ * Store manifold ids. This field stores the manifold id of each object,
+ * which is a number between 0 and numbers::invalid_manifold_id-1.
*/
std::vector<types::manifold_id> manifold_id;
/**
- * Assert that enough space
- * is allocated to
- * accommodate
- * <code>new_objs_in_pairs</code>
- * new objects, stored in
- * pairs, plus
- * <code>new_obj_single</code>
- * stored individually.
- * This function does not
- * only call
- * <code>vector::reserve()</code>,
- * but does really append
- * the needed elements.
+ * Assert that enough space is allocated to accommodate
+ * <code>new_objs_in_pairs</code> new objects, stored in pairs, plus
+ * <code>new_obj_single</code> stored individually. This function does
+ * not only call <code>vector::reserve()</code>, but does really append
+ * the needed elements.
*
- * In 2D e.g. refined lines have to be
- * stored in pairs, whereas new lines in the
- * interior of refined cells can be stored as
- * single lines.
+ * In 2D e.g. refined lines have to be stored in pairs, whereas new
+ * lines in the interior of refined cells can be stored as single lines.
*/
void reserve_space (const unsigned int new_objs_in_pairs,
const unsigned int new_objs_single = 0);
/**
- * Return an iterator to the
- * next free slot for a
- * single object. This
- * function is only used by
- * dealii::Triangulation::execute_refinement()
+ * Return an iterator to the next free slot for a single object. This
+ * function is only used by dealii::Triangulation::execute_refinement()
* in 3D.
*
- * @warning Interestingly,
- * this function is not used
- * for 1D or 2D
- * triangulations, where it
- * seems the authors of the
- * refinement function insist
- * on reimplementing its
- * contents.
+ * @warning Interestingly, this function is not used for 1D or 2D
+ * triangulations, where it seems the authors of the refinement function
+ * insist on reimplementing its contents.
*
- * @todo This function is
- * not instantiated for the
- * codim-one case
+ * @todo This function is not instantiated for the codim-one case
*/
template <int dim, int spacedim>
dealii::TriaRawIterator<dealii::TriaAccessor<G::dimension,dim,spacedim> >
next_free_single_object (const dealii::Triangulation<dim,spacedim> &tria);
/**
- * Return an iterator to the
- * next free slot for a pair
- * of objects. This
- * function is only used by
- * dealii::Triangulation::execute_refinement()
+ * Return an iterator to the next free slot for a pair of objects. This
+ * function is only used by dealii::Triangulation::execute_refinement()
* in 3D.
*
- * @warning Interestingly,
- * this function is not used
- * for 1D or 2D
- * triangulations, where it
- * seems the authors of the
- * refinement function insist
- * on reimplementing its
- * contents.
+ * @warning Interestingly, this function is not used for 1D or 2D
+ * triangulations, where it seems the authors of the refinement function
+ * insist on reimplementing its contents.
*
- * @todo This function is
- * not instantiated for the
- * codim-one case
+ * @todo This function is not instantiated for the codim-one case
*/
template <int dim, int spacedim>
dealii::TriaRawIterator<dealii::TriaAccessor<G::dimension,dim,spacedim> >
next_free_pair_object (const dealii::Triangulation<dim,spacedim> &tria);
/**
- * Return an iterator to the
- * next free slot for a pair
- * of hexes. Only implemented
- * for
- * <code>G=Hexahedron</code>.
+ * Return an iterator to the next free slot for a pair of hexes. Only
+ * implemented for <code>G=Hexahedron</code>.
*/
template <int dim, int spacedim>
typename dealii::Triangulation<dim,spacedim>::raw_hex_iterator
const unsigned int level);
/**
- * Clear all the data contained in this object.
+ * Clear all the data contained in this object.
*/
void clear();
/**
- * The orientation of the
- * face number <code>face</code>
- * of the cell with number
- * <code>cell</code>. The return
- * value is <code>true</code>, if
- * the normal vector points
- * the usual way
- * (GeometryInfo::unit_normal_orientation)
- * and <code>false</code> else.
+ * The orientation of the face number <code>face</code> of the cell with
+ * number <code>cell</code>. The return value is <code>true</code>, if
+ * the normal vector points the usual way
+ * (GeometryInfo::unit_normal_orientation) and <code>false</code> else.
*
- * The result is always
- * <code>true</code> in this
- * class, but derived classes
- * will reimplement this.
+ * The result is always <code>true</code> in this class, but derived
+ * classes will reimplement this.
*
- * @warning There is a bug in
- * the class hierarchy right
- * now. Avoid ever calling
- * this function through a
- * reference, since you might
- * end up with the base class
- * function instead of the
- * derived class. Still, we
- * do not want to make it
- * virtual for efficiency
- * reasons.
+ * @warning There is a bug in the class hierarchy right now. Avoid ever
+ * calling this function through a reference, since you might end up
+ * with the base class function instead of the derived class. Still, we
+ * do not want to make it virtual for efficiency reasons.
*/
bool face_orientation(const unsigned int cell, const unsigned int face) const;
void clear_user_data(const unsigned int i);
/**
- * Clear all user pointers or
- * indices and reset their
- * type, such that the next
- * access may be aither or.
+ * Clear all user pointers or indices and reset their type, such that
+ * the next access may be aither or.
*/
void clear_user_data();
void clear_user_flags();
/**
- * Check the memory consistency of the
- * different containers. Should only be
- * called with the prepro flag @p DEBUG
- * set. The function should be called from
- * the functions of the higher
- * TriaLevel classes.
+ * Check the memory consistency of the different containers. Should only
+ * be called with the prepro flag @p DEBUG set. The function should be
+ * called from the functions of the higher TriaLevel classes.
*/
void monitor_memory (const unsigned int true_dimension) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
*/
template <class Archive>
void serialize(Archive &ar,
const unsigned int version);
/**
- * Exception
+ * Exception
*/
DeclException3 (ExcMemoryWasted,
char *, int, int,
<< arg2 << " elements, but it`s capacity is "
<< arg3 << ".");
/**
- * Exception
+ * Exception
* @ingroup Exceptions
*/
DeclException2 (ExcMemoryInexact,
<< arg2 << ", which is not as expected.");
/**
- * Exception
+ * Exception
*/
DeclException2 (ExcWrongIterator,
char *, char *,
"but you can only ask for " << arg2 <<"_iterators.");
/**
- * dealii::Triangulation objects can
- * either access a user
- * pointer or a user
- * index. What you tried to
- * do is trying to access one
- * of those after using the
- * other.
+ * dealii::Triangulation objects can either access a user pointer or a
+ * user index. What you tried to do is trying to access one of those
+ * after using the other.
*
* @ingroup Exceptions
*/
bool reverse_order_next_free_single;
/**
- * The data type storing user
- * pointers or user indices.
+ * The data type storing user pointers or user indices.
*/
struct UserData
{
}
/**
- * Write the data of this object
- * to a stream for the purpose of
+ * Write the data of this object to a stream for the purpose of
* serialization.
*/
template <class Archive>
};
/**
- * Enum descibing the
- * possible types of
- * userdata.
+ * Enum descibing the possible types of userdata.
*/
enum UserDataType
{
/**
- * Pointer which is not used by the
- * library but may be accessed and set
- * by the user to handle data local to
- * a line/quad/etc.
+ * Pointer which is not used by the library but may be accessed and set
+ * by the user to handle data local to a line/quad/etc.
*/
std::vector<UserData> user_data;
/**
- * In order to avoid
- * confusion between user
- * pointers and indices, this
- * enum is set by the first
- * function accessing either
- * and subsequent access will
- * not be allowed to change
- * the type of data accessed.
+ * In order to avoid confusion between user pointers and indices, this
+ * enum is set by the first function accessing either and subsequent
+ * access will not be allowed to change the type of data accessed.
*/
mutable UserDataType user_data_type;
};
/**
- * For hexahedra the data of TriaObjects needs to be extended, as we can obtain faces
- * (quads) in non-standard-orientation, therefore we declare a class TriaObjectsHex, which
- * additionally contains a bool-vector of the face-orientations.
+ * For hexahedra the data of TriaObjects needs to be extended, as we can
+ * obtain faces (quads) in non-standard-orientation, therefore we declare
+ * a class TriaObjectsHex, which additionally contains a bool-vector of
+ * the face-orientations.
*/
class TriaObjectsHex : public TriaObjects<TriaObject<3> >
{
public:
/**
- * The orientation of the
- * face number <code>face</code>
- * of the cell with number
- * <code>cell</code>. The return
- * value is <code>true</code>, if
- * the normal vector points
- * the usual way
- * (GeometryInfo::unit_normal_orientation)
- * and <code>false</code> if they
- * point in opposite
- * direction.
+ * The orientation of the face number <code>face</code> of the cell with
+ * number <code>cell</code>. The return value is <code>true</code>, if
+ * the normal vector points the usual way
+ * (GeometryInfo::unit_normal_orientation) and <code>false</code> if
+ * they point in opposite direction.
*/
bool face_orientation(const unsigned int cell, const unsigned int face) const;
/**
- * For edges, we enforce a
- * standard convention that
- * opposite edges should be
- * parallel. Now, that's
- * enforcable in most cases,
- * and we have code that
- * makes sure that if a mesh
- * allows this to happen,
- * that we have this
- * convention. We also know
- * that it is always possible
- * to have opposite faces
- * have parallel normal
- * vectors. (For both things,
- * see the Agelek, Anderson,
- * Bangerth, Barth paper
- * mentioned in the
+ * For edges, we enforce a standard convention that opposite edges
+ * should be parallel. Now, that's enforcable in most cases, and we have
+ * code that makes sure that if a mesh allows this to happen, that we
+ * have this convention. We also know that it is always possible to have
+ * opposite faces have parallel normal vectors. (For both things, see
+ * the Agelek, Anderson, Bangerth, Barth paper mentioned in the
* publications list.)
*
- * The problem is that we
- * originally had another
- * condition, namely that
- * faces 0, 2 and 6 have
- * normals that point into
- * the cell, while the other
- * faces have normals that
- * point outward. It turns
- * out that this is not
- * always possible. In
- * effect, we have to store
- * whether the normal vector
- * of each face of each cell
- * follows this convention or
- * not. If this is so, then
- * this variable stores a
- * @p true value, otherwise
- * a @p false value.
+ * The problem is that we originally had another condition, namely that
+ * faces 0, 2 and 6 have normals that point into the cell, while the
+ * other faces have normals that point outward. It turns out that this
+ * is not always possible. In effect, we have to store whether the
+ * normal vector of each face of each cell follows this convention or
+ * not. If this is so, then this variable stores a @p true value,
+ * otherwise a @p false value.
*
- * In effect, this field has
- * <code>6*n_cells</code> elements,
- * being the number of cells
- * times the six faces each
- * has.
+ * In effect, this field has <code>6*n_cells</code> elements, being the
+ * number of cells times the six faces each has.
*/
std::vector<bool> face_orientations;
std::vector<bool> face_rotations;
/**
- * Assert that enough space is
- * allocated to accommodate
- * <code>new_objs</code> new objects.
- * This function does not only call
- * <code>vector::reserve()</code>, but
- * does really append the needed
- * elements.
+ * Assert that enough space is allocated to accommodate
+ * <code>new_objs</code> new objects. This function does not only call
+ * <code>vector::reserve()</code>, but does really append the needed
+ * elements.
*/
void reserve_space (const unsigned int new_objs);
/**
- * Clear all the data contained in this object.
+ * Clear all the data contained in this object.
*/
void clear();
/**
- * Check the memory consistency of the
- * different containers. Should only be
- * called with the prepro flag @p DEBUG
- * set. The function should be called from
- * the functions of the higher
- * TriaLevel classes.
+ * Check the memory consistency of the different containers. Should only
+ * be called with the prepro flag @p DEBUG set. The function should be
+ * called from the functions of the higher TriaLevel classes.
*/
void monitor_memory (const unsigned int true_dimension) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
*/
template <class Archive>
void serialize(Archive &ar,
/**
- * For quadrilaterals in 3D the data of TriaObjects needs to be extended, as we
- * can obtain faces (quads) with lines in non-standard-orientation, therefore we
- * declare a class TriaObjectsQuad3D, which additionally contains a bool-vector
- * of the line-orientations.
+ * For quadrilaterals in 3D the data of TriaObjects needs to be extended,
+ * as we can obtain faces (quads) with lines in non-standard-orientation,
+ * therefore we declare a class TriaObjectsQuad3D, which additionally
+ * contains a bool-vector of the line-orientations.
*/
class TriaObjectsQuad3D: public TriaObjects<TriaObject<2> >
{
public:
/**
- * The orientation of the
- * face number <code>face</code>
- * of the cell with number
- * <code>cell</code>. The return
- * value is <code>true</code>, if
- * the normal vector points
- * the usual way
- * (GeometryInfo::unit_normal_orientation)
- * and <code>false</code> if they
- * point in opposite
- * direction.
+ * The orientation of the face number <code>face</code> of the cell with
+ * number <code>cell</code>. The return value is <code>true</code>, if
+ * the normal vector points the usual way
+ * (GeometryInfo::unit_normal_orientation) and <code>false</code> if
+ * they point in opposite direction.
*/
bool face_orientation(const unsigned int cell, const unsigned int face) const;
/**
- * In effect, this field has
- * <code>4*n_quads</code> elements,
- * being the number of quads
- * times the four lines each
- * has.
+ * In effect, this field has <code>4*n_quads</code> elements, being the
+ * number of quads times the four lines each has.
*/
std::vector<bool> line_orientations;
/**
- * Assert that enough space
- * is allocated to
- * accommodate
- * <code>new_quads_in_pairs</code>
- * new quads, stored in
- * pairs, plus
- * <code>new_quads_single</code>
- * stored individually.
- * This function does not
- * only call
- * <code>vector::reserve()</code>,
- * but does really append
- * the needed elements.
+ * Assert that enough space is allocated to accommodate
+ * <code>new_quads_in_pairs</code> new quads, stored in pairs, plus
+ * <code>new_quads_single</code> stored individually. This function does
+ * not only call <code>vector::reserve()</code>, but does really append
+ * the needed elements.
*/
void reserve_space (const unsigned int new_quads_in_pairs,
const unsigned int new_quads_single = 0);
/**
- * Clear all the data contained in this object.
+ * Clear all the data contained in this object.
*/
void clear();
/**
- * Check the memory consistency of the
- * different containers. Should only be
- * called with the prepro flag @p DEBUG
- * set. The function should be called from
- * the functions of the higher
- * TriaLevel classes.
+ * Check the memory consistency of the different containers. Should only
+ * be called with the prepro flag @p DEBUG set. The function should be
+ * called from the functions of the higher TriaLevel classes.
*/
void monitor_memory (const unsigned int true_dimension) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
/**
- * Read or write the data of this object to or
- * from a stream for the purpose of serialization
+ * Read or write the data of this object to or from a stream for the
+ * purpose of serialization
*/
template <class Archive>
void serialize(Archive &ar,
{
/**
* Store the indices of the degrees of freedom which are located on
- * objects of dimension @p structdim < dim, i.e., for faces or edges
- * of cells. This is opposed to the internal::hp::DoFLevels class
- * that stores the DoF indices on cells.
+ * objects of dimension @p structdim < dim, i.e., for faces or edges of
+ * cells. This is opposed to the internal::hp::DoFLevels class that stores
+ * the DoF indices on cells.
*
* The things we store here is very similar to what is stored in the
* internal::DoFHandler::DoFObjects classes (see there for more
- * information, in particular on the layout of the class hierarchy,
- * and the use of file names).
+ * information, in particular on the layout of the class hierarchy, and
+ * the use of file names).
*
* <h4>Offset computations</h4>
*
- * For hp methods, not all cells may use the same finite element, and
- * it is consequently more complicated to determine where the DoF
- * indices for a given line, quad, or hex are stored. As described in
- * the documentation of the internal::DoFHandler::DoFLevel class, we
- * can compute the location of the first line DoF, for example, by
- * calculating the offset as <code>line_index *
- * dof_handler.get_fe().dofs_per_line</code>. This of course doesn't
- * work any more if different lines may have different numbers of
- * degrees of freedom associated with them. Consequently, rather than
- * using this simple multiplication, the dofs array has an associated
- * array dof_offsets. The data corresponding to a
- * line then starts at index <code>line_dof_offsets[line_index]</code>
- * within the <code>line_dofs</code> array.
+ * For hp methods, not all cells may use the same finite element, and it
+ * is consequently more complicated to determine where the DoF indices for
+ * a given line, quad, or hex are stored. As described in the
+ * documentation of the internal::DoFHandler::DoFLevel class, we can
+ * compute the location of the first line DoF, for example, by calculating
+ * the offset as <code>line_index *
+ * dof_handler.get_fe().dofs_per_line</code>. This of course doesn't work
+ * any more if different lines may have different numbers of degrees of
+ * freedom associated with them. Consequently, rather than using this
+ * simple multiplication, the dofs array has an associated array
+ * dof_offsets. The data corresponding to a line then starts at index
+ * <code>line_dof_offsets[line_index]</code> within the
+ * <code>line_dofs</code> array.
*
*
* <h4>Multiple data sets per object</h4>
*
- * If two adjacent cells use different finite elements, then
- * the face that they share needs to store DoF indices for both
- * involved finite elements. While faces therefore have to have at
- * most two sets of DoF indices, it is easy to see that edges and
- * vertices can have as many sets of DoF indices associated with them
- * as there are adjacent cells.
+ * If two adjacent cells use different finite elements, then the face that
+ * they share needs to store DoF indices for both involved finite
+ * elements. While faces therefore have to have at most two sets of DoF
+ * indices, it is easy to see that edges and vertices can have as many
+ * sets of DoF indices associated with them as there are adjacent cells.
*
- * Consequently, for objects that have a lower dimensionality than
- * cells, we have to store a map from the finite element index to the
- * set of DoF indices associated. Since real sets are typically very
- * inefficient to store, and since most of the time we expect the
- * number of individual keys to be small (frequently, adjacent cells
- * will have the same finite element, and only a single entry will
- * exist in the map), what we do is instead to store a linked list. In
- * this format, the first entry starting at position
- * <code>lines.dofs[lines.dof_offsets[line_index]]</code> will denote
- * the finite element index of the set of DoF indices following; after
- * this set, we will store the finite element index of the second set
- * followed by the corresponding DoF indices; and so on. Finally, when
- * all finite element indices adjacent to this object have been
- * covered, we write a -1 to indicate the end of the list.
+ * Consequently, for objects that have a lower dimensionality than cells,
+ * we have to store a map from the finite element index to the set of DoF
+ * indices associated. Since real sets are typically very inefficient to
+ * store, and since most of the time we expect the number of individual
+ * keys to be small (frequently, adjacent cells will have the same finite
+ * element, and only a single entry will exist in the map), what we do is
+ * instead to store a linked list. In this format, the first entry
+ * starting at position
+ * <code>lines.dofs[lines.dof_offsets[line_index]]</code> will denote the
+ * finite element index of the set of DoF indices following; after this
+ * set, we will store the finite element index of the second set followed
+ * by the corresponding DoF indices; and so on. Finally, when all finite
+ * element indices adjacent to this object have been covered, we write a
+ * -1 to indicate the end of the list.
*
- * Access to this kind of data, as well as the distinction between
- * cells and objects of lower dimensionality are encoded in the
- * accessor functions, DoFObjects::set_dof_index() and
- * DoFLevel::get_dof_index(). They are able to traverse this
- * list and pick out or set a DoF index given the finite element index
- * and its location within the set of DoFs corresponding to this
- * finite element.
+ * Access to this kind of data, as well as the distinction between cells
+ * and objects of lower dimensionality are encoded in the accessor
+ * functions, DoFObjects::set_dof_index() and DoFLevel::get_dof_index().
+ * They are able to traverse this list and pick out or set a DoF index
+ * given the finite element index and its location within the set of DoFs
+ * corresponding to this finite element.
*
*
* @ingroup hp
{
public:
/**
- * Store the start index for
- * the degrees of freedom of each
- * object in the @p dofs array.
+ * Store the start index for the degrees of freedom of each object in
+ * the @p dofs array.
*
- * The type we store is then obviously the type the @p dofs array
- * uses for indexing.
+ * The type we store is then obviously the type the @p dofs array uses
+ * for indexing.
*/
std::vector<unsigned int> dof_offsets;
/**
- * Store the global indices of
- * the degrees of freedom. See
- * DoFLevel() for detailed
- * information.
+ * Store the global indices of the degrees of freedom. See DoFLevel()
+ * for detailed information.
*/
std::vector<types::global_dof_index> dofs;
/**
- * Set the global index of
- * the @p local_index-th
- * degree of freedom located
- * on the object with number @p
- * obj_index to the value
- * given by @p global_index. The @p
- * dof_handler argument is
- * used to access the finite
- * element that is to be used
- * to compute the location
- * where this data is stored.
+ * Set the global index of the @p local_index-th degree of freedom
+ * located on the object with number @p obj_index to the value given by
+ * @p global_index. The @p dof_handler argument is used to access the
+ * finite element that is to be used to compute the location where this
+ * data is stored.
*
- * The third argument, @p
- * fe_index, denotes which of
- * the finite elements
- * associated with this
- * object we shall
- * access. Refer to the
- * general documentation of
- * the internal::hp::DoFLevel
- * class template for more
+ * The third argument, @p fe_index, denotes which of the finite elements
+ * associated with this object we shall access. Refer to the general
+ * documentation of the internal::hp::DoFLevel class template for more
* information.
*/
template <int dim, int spacedim>
const unsigned int obj_level);
/**
- * Return the global index of
- * the @p local_index-th
- * degree of freedom located
- * on the object with number @p
- * obj_index. The @p
- * dof_handler argument is
- * used to access the finite
- * element that is to be used
- * to compute the location
- * where this data is stored.
+ * Return the global index of the @p local_index-th degree of freedom
+ * located on the object with number @p obj_index. The @p dof_handler
+ * argument is used to access the finite element that is to be used to
+ * compute the location where this data is stored.
*
- * The third argument, @p
- * fe_index, denotes which of
- * the finite elements
- * associated with this
- * object we shall
- * access. Refer to the
- * general documentation of
- * the internal::hp::DoFLevel
- * class template for more
+ * The third argument, @p fe_index, denotes which of the finite elements
+ * associated with this object we shall access. Refer to the general
+ * documentation of the internal::hp::DoFLevel class template for more
* information.
*/
template <int dim, int spacedim>
const unsigned int obj_level) const;
/**
- * Return the number of
- * finite elements that are
- * active on a given
- * object. If this is a cell,
- * the answer is of course
- * one. If it is a face, the
- * answer may be one or two,
- * depending on whether the
- * two adjacent cells use the
- * same finite element or
- * not. If it is an edge in
- * 3d, the possible return
- * value may be one or any
- * other value larger than
- * that.
+ * Return the number of finite elements that are active on a given
+ * object. If this is a cell, the answer is of course one. If it is a
+ * face, the answer may be one or two, depending on whether the two
+ * adjacent cells use the same finite element or not. If it is an edge
+ * in 3d, the possible return value may be one or any other value larger
+ * than that.
*
- * If the object is not part
- * of an active cell, then no
- * degrees of freedom have
- * been distributed and zero
- * is returned.
+ * If the object is not part of an active cell, then no degrees of
+ * freedom have been distributed and zero is returned.
*/
template <int dim, int spacedim>
unsigned int
const unsigned int obj_index) const;
/**
- * Return the fe_index of the
- * n-th active finite element
- * on this object.
+ * Return the fe_index of the n-th active finite element on this object.
*/
template <int dim, int spacedim>
types::global_dof_index
const unsigned int n) const;
/**
- * Check whether a given
- * finite element index is
- * used on the present
+ * Check whether a given finite element index is used on the present
* object or not.
*/
template <int dim, int spacedim>
const unsigned int obj_level) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
};
/**
- * These classes are similar to the internal::hp::DoFLevel classes. We here store
- * information that is associated with faces, rather than cells, as this information is
- * independent of the hierarchical structure of cells, which are organized in levels. In 2D
- * we store information on degrees of freedom located on lines whereas in 3D we store
- * information on drefrees of freedom located on quads and lines. In 1D we do nothing, as
- * the faces of lines are vertices which are treated separately.
+ * These classes are similar to the internal::hp::DoFLevel classes. We
+ * here store information that is associated with faces, rather than
+ * cells, as this information is independent of the hierarchical structure
+ * of cells, which are organized in levels. In 2D we store information on
+ * degrees of freedom located on lines whereas in 3D we store information
+ * on drefrees of freedom located on quads and lines. In 1D we do nothing,
+ * as the faces of lines are vertices which are treated separately.
*
- * Apart from the internal::hp::DoFObjects object containing the data to store
- * (degree of freedom indices) and all the access-functionality to this data, we do not
- * store any data or provide any functionality. However, we do implement a function to
- * determine an estimate of the memory consumption of the contained
- * internal::hp::DoFObjects object(s).
+ * Apart from the internal::hp::DoFObjects object containing the data to
+ * store (degree of freedom indices) and all the access-functionality to
+ * this data, we do not store any data or provide any functionality.
+ * However, we do implement a function to determine an estimate of the
+ * memory consumption of the contained internal::hp::DoFObjects object(s).
*
- * The data contained isn't usually directly accessed. Rather, except for some access from
- * the DoFHandler class, access is usually through the DoFAccessor::set_dof_index() and
- * DoFAccessor::dof_index() functions or similar functions of derived classes that in turn
- * access the member variables using the DoFHandler::get_dof_index() and corresponding
- * setter functions. Knowledge of the actual data format is therefore encapsulated to the
- * present hierarchy of classes as well as the ::DoFHandler class.
+ * The data contained isn't usually directly accessed. Rather, except for
+ * some access from the DoFHandler class, access is usually through the
+ * DoFAccessor::set_dof_index() and DoFAccessor::dof_index() functions or
+ * similar functions of derived classes that in turn access the member
+ * variables using the DoFHandler::get_dof_index() and corresponding
+ * setter functions. Knowledge of the actual data format is therefore
+ * encapsulated to the present hierarchy of classes as well as the
+ * ::DoFHandler class.
*
* @ingroup dofs
* @author Tobias Leicht, 2006
/**
- * Store the indices of degrees of freedom on faces in 1D. As these would be vertices, which
- * are treated separately, don't do anything.
+ * Store the indices of degrees of freedom on faces in 1D. As these would
+ * be vertices, which are treated separately, don't do anything.
*
* @ingroup hp
* @author Tobias Leicht, 2006
{
public:
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
};
/**
- * Store the indices of degrees of freedom on faces in 2D, which are lines.
+ * Store the indices of degrees of freedom on faces in 2D, which are
+ * lines.
*
* @ingroup hp
* @author Tobias Leicht, 2006
internal::hp::DoFIndicesOnFacesOrEdges<1> lines;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
};
internal::hp::DoFIndicesOnFacesOrEdges<2> quads;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
};
{
/**
- * Manage the distribution and numbering of the degrees of freedom for
- * hp-FEM algorithms. This class satisfies the requirements outlined in
- * @ref GlossMeshAsAContainer "Meshes as containers".
+ * Manage the distribution and numbering of the degrees of freedom for hp-
+ * FEM algorithms. This class satisfies the requirements outlined in @ref
+ * GlossMeshAsAContainer "Meshes as containers".
*
- * The purpose of this class is to allow for an enumeration of degrees
- * of freedom in the same way as the ::DoFHandler class, but it allows
- * to use a different finite element on every cell. To this end, one
- * assigns an <code>active_fe_index</code> to every cell that indicates which
- * element within a collection of finite elements (represented by an object
- * of type hp::FECollection) is the one that lives on this cell.
- * The class then enumerates the degree of freedom associated with these
- * finite elements on each cell of a triangulation and, if possible,
- * identifies degrees of freedom at the interfaces of cells if they
- * match. If neighboring cells have degrees of freedom along the common
- * interface that do not immediate match (for example, if you have
- * $Q_2$ and $Q_3$ elements meeting at a common face), then one needs
- * to compute constraints to ensure that the resulting finite element
- * space on the mesh remains conforming.
+ * The purpose of this class is to allow for an enumeration of degrees of
+ * freedom in the same way as the ::DoFHandler class, but it allows to use a
+ * different finite element on every cell. To this end, one assigns an
+ * <code>active_fe_index</code> to every cell that indicates which element
+ * within a collection of finite elements (represented by an object of type
+ * hp::FECollection) is the one that lives on this cell. The class then
+ * enumerates the degree of freedom associated with these finite elements on
+ * each cell of a triangulation and, if possible, identifies degrees of
+ * freedom at the interfaces of cells if they match. If neighboring cells
+ * have degrees of freedom along the common interface that do not immediate
+ * match (for example, if you have $Q_2$ and $Q_3$ elements meeting at a
+ * common face), then one needs to compute constraints to ensure that the
+ * resulting finite element space on the mesh remains conforming.
*
* The whole process of working with objects of this type is explained in
- * step-27. Many of the algorithms this class implements are described
- * in the @ref hp_paper "hp paper".
+ * step-27. Many of the algorithms this class implements are described in
+ * the @ref hp_paper "hp paper".
*
*
* <h3>Active FE indices and their behavior under mesh refinement</h3>
*
- * The typical workflow for using this class is to create a mesh,
- * assign an active FE index to every active cell, calls
- * hp::DoFHandler::distribute_dofs(), and then assemble a linear
- * system and solve a problem on this finite element space. However,
- * one can skip assigning active FE indices upon mesh refinement
- * in certain circumstances. In particular, the following rules apply:
- * - Upon mesh refinement, child cells inherit the active FE index
- * of the parent.
- * - On the other hand, when coarsening cells, the (now active) parent
- * cell will not have an active FE index set and you will have to
- * set it explicitly before calling hp::DoFHandler::distribute_dofs().
- * In particular, to avoid stale information to be used by accident,
- * this class deletes the active FE index of cells that are
- * refined after inheriting this index to the children; this implies
- * that if the children are coarsened away, the old value is no
- * longer available on the parent cell.
+ * The typical workflow for using this class is to create a mesh, assign an
+ * active FE index to every active cell, calls
+ * hp::DoFHandler::distribute_dofs(), and then assemble a linear system and
+ * solve a problem on this finite element space. However, one can skip
+ * assigning active FE indices upon mesh refinement in certain
+ * circumstances. In particular, the following rules apply: - Upon mesh
+ * refinement, child cells inherit the active FE index of the parent. - On
+ * the other hand, when coarsening cells, the (now active) parent cell will
+ * not have an active FE index set and you will have to set it explicitly
+ * before calling hp::DoFHandler::distribute_dofs(). In particular, to avoid
+ * stale information to be used by accident, this class deletes the active
+ * FE index of cells that are refined after inheriting this index to the
+ * children; this implies that if the children are coarsened away, the old
+ * value is no longer available on the parent cell.
*
* @ingroup dofs
* @ingroup hp
typedef typename ActiveSelector::active_hex_iterator active_hex_iterator;
/**
- * A typedef that is used to to identify
- * @ref GlossActive "active cell iterators". The
- * concept of iterators is discussed at length in the
- * @ref Iterators "iterators documentation module".
+ * A typedef that is used to to identify @ref GlossActive "active cell
+ * iterators". The concept of iterators is discussed at length in the @ref
+ * Iterators "iterators documentation module".
*
* The current typedef identifies active cells in a hp::DoFHandler object.
* While the actual data type of the typedef is hidden behind a few layers
* of (unfortunately necessary) indirections, it is in essence
- * TriaActiveIterator<DoFCellAccessor>. The TriaActiveIterator
- * class works like a pointer to active objects that when you
- * dereference it yields an object of type DoFCellAccessor.
- * DoFCellAccessor is a class that identifies properties that
- * are specific to cells in a DoFHandler, but it is derived
- * (and consequently inherits) from both DoFAccessor, TriaCellAccessor
- * and TriaAccessor that describe
- * what you can ask of more general objects (lines, faces, as
- * well as cells) in a triangulation and hp::DoFHandler objects.
+ * TriaActiveIterator<DoFCellAccessor>. The TriaActiveIterator class works
+ * like a pointer to active objects that when you dereference it yields an
+ * object of type DoFCellAccessor. DoFCellAccessor is a class that
+ * identifies properties that are specific to cells in a DoFHandler, but
+ * it is derived (and consequently inherits) from both DoFAccessor,
+ * TriaCellAccessor and TriaAccessor that describe what you can ask of
+ * more general objects (lines, faces, as well as cells) in a
+ * triangulation and hp::DoFHandler objects.
*
* @ingroup Iterators
*/
typedef typename LevelSelector::cell_iterator level_cell_iterator;
/**
- * A typedef that is used to to identify cell iterators. The
- * concept of iterators is discussed at length in the
- * @ref Iterators "iterators documentation module".
+ * A typedef that is used to to identify cell iterators. The concept of
+ * iterators is discussed at length in the @ref Iterators "iterators
+ * documentation module".
*
- * The current typedef identifies cells in a DoFHandler object. Some
- * of these cells may in fact be active (see @ref GlossActive "active cell iterators")
- * in which case they can in fact be asked for the degrees of freedom
- * that live on them. On the other hand, if the cell is not active,
- * any such query will result in an error. Note that this is what distinguishes
- * this typedef from the level_cell_iterator typedef.
+ * The current typedef identifies cells in a DoFHandler object. Some of
+ * these cells may in fact be active (see @ref GlossActive "active cell
+ * iterators") in which case they can in fact be asked for the degrees of
+ * freedom that live on them. On the other hand, if the cell is not
+ * active, any such query will result in an error. Note that this is what
+ * distinguishes this typedef from the level_cell_iterator typedef.
*
* While the actual data type of the typedef is hidden behind a few layers
* of (unfortunately necessary) indirections, it is in essence
- * TriaIterator<DoFCellAccessor>. The TriaIterator
- * class works like a pointer to objects that when you
- * dereference it yields an object of type DoFCellAccessor.
- * DoFCellAccessor is a class that identifies properties that
- * are specific to cells in a DoFHandler, but it is derived
- * (and consequently inherits) from both DoFAccessor, TriaCellAccessor
- * and TriaAccessor that describe
- * what you can ask of more general objects (lines, faces, as
- * well as cells) in a triangulation and DoFHandler objects.
+ * TriaIterator<DoFCellAccessor>. The TriaIterator class works like a
+ * pointer to objects that when you dereference it yields an object of
+ * type DoFCellAccessor. DoFCellAccessor is a class that identifies
+ * properties that are specific to cells in a DoFHandler, but it is
+ * derived (and consequently inherits) from both DoFAccessor,
+ * TriaCellAccessor and TriaAccessor that describe what you can ask of
+ * more general objects (lines, faces, as well as cells) in a
+ * triangulation and DoFHandler objects.
*
* @ingroup Iterators
*/
typedef typename LevelSelector::face_iterator level_face_iterator;
/**
- * Alias the @p FunctionMap type
- * declared elsewhere.
+ * Alias the @p FunctionMap type declared elsewhere.
*/
typedef typename FunctionMap<spacedim>::type FunctionMap;
/**
- * Make the dimension available
- * in function templates.
+ * Make the dimension available in function templates.
*/
static const unsigned int dimension = dim;
/**
- * Make the space dimension available
- * in function templates.
+ * Make the space dimension available in function templates.
*/
static const unsigned int space_dimension = spacedim;
/**
- * When the arrays holding the
- * DoF indices are set up, but
- * before they are filled with
- * actual values, they are set to
- * an invalid value, in order to
- * monitor possible
- * problems. This invalid value
- * is the constant defined here.
+ * When the arrays holding the DoF indices are set up, but before they are
+ * filled with actual values, they are set to an invalid value, in order
+ * to monitor possible problems. This invalid value is the constant
+ * defined here.
*
- * Please note that you should
- * not rely on it having a
- * certain value, but rather take
- * its symbolic name.
+ * Please note that you should not rely on it having a certain value, but
+ * rather take its symbolic name.
*/
static const types::global_dof_index invalid_dof_index = numbers::invalid_dof_index;
/**
- * The default index of the
- * finite element to be used on
- * a given cell. For the usual,
- * non-hp dealii::DoFHandler class
- * that only supports the same
- * finite element to be used on
- * all cells, the index of the
- * finite element needs to be
- * the same on all cells
- * anyway, and by convention we
- * pick zero for this
- * value. The situation here is
- * different, since the hp
- * classes support the case
- * where different finite
- * element indices may be used
- * on different cells. The
- * default index consequently
- * corresponds to an invalid
- * value.
+ * The default index of the finite element to be used on a given cell. For
+ * the usual, non-hp dealii::DoFHandler class that only supports the same
+ * finite element to be used on all cells, the index of the finite element
+ * needs to be the same on all cells anyway, and by convention we pick
+ * zero for this value. The situation here is different, since the hp
+ * classes support the case where different finite element indices may be
+ * used on different cells. The default index consequently corresponds to
+ * an invalid value.
*/
static const unsigned int default_fe_index = numbers::invalid_unsigned_int;
/**
- * Constructor. Take @p tria as the
- * triangulation to work on.
+ * Constructor. Take @p tria as the triangulation to work on.
*/
DoFHandler (const Triangulation<dim,spacedim> &tria);
virtual ~DoFHandler ();
/**
- * Go through the triangulation and "distribute" the degrees of
- * freedoms needed for the given finite element. "Distributing"
- * degrees of freedom involved allocating memory to store the
- * information that describes it (e.g., whether it is located on a
- * vertex, edge, face, etc) and to sequentially enumerate all
- * degrees of freedom. In other words, while the mesh and the finite
- * element object by themselves simply define a finite element space
- * $V_h$, the process of distributing degrees of freedom makes sure
- * that there is a basis for this space and that the shape functions
- * of this basis are enumerated in an indexable, predictable way.
+ * Go through the triangulation and "distribute" the degrees of freedoms
+ * needed for the given finite element. "Distributing" degrees of freedom
+ * involved allocating memory to store the information that describes it
+ * (e.g., whether it is located on a vertex, edge, face, etc) and to
+ * sequentially enumerate all degrees of freedom. In other words, while
+ * the mesh and the finite element object by themselves simply define a
+ * finite element space $V_h$, the process of distributing degrees of
+ * freedom makes sure that there is a basis for this space and that the
+ * shape functions of this basis are enumerated in an indexable,
+ * predictable way.
*
- * The purpose of this function
- * is first discussed in the introduction
- * to the step-2 tutorial program.
+ * The purpose of this function is first discussed in the introduction to
+ * the step-2 tutorial program.
*
- * @note A pointer of the finite element given as argument is
- * stored. Therefore, the lifetime of the finite element object
- * shall be longer than that of this object. If you don't want this
- * behavior, you may want to call the @p clear member function which
- * also releases the lock of this object to the finite element.
+ * @note A pointer of the finite element given as argument is stored.
+ * Therefore, the lifetime of the finite element object shall be longer
+ * than that of this object. If you don't want this behavior, you may want
+ * to call the @p clear member function which also releases the lock of
+ * this object to the finite element.
*/
virtual void distribute_dofs (const hp::FECollection<dim,spacedim> &fe);
/**
- * Go through the triangulation and set
- * the active FE indices of all active
- * cells to the values given in @p
- * active_fe_indices.
+ * Go through the triangulation and set the active FE indices of all
+ * active cells to the values given in @p active_fe_indices.
*/
void set_active_fe_indices (const std::vector<unsigned int> &active_fe_indices);
/**
- * Go through the triangulation and
- * store the active FE indices of all
- * active cells to the vector @p
- * active_fe_indices. This vector is
+ * Go through the triangulation and store the active FE indices of all
+ * active cells to the vector @p active_fe_indices. This vector is
* resized, if necessary.
*/
void get_active_fe_indices (std::vector<unsigned int> &active_fe_indices) const;
/**
- * Clear all data of this object and
- * especially delete the lock this object
- * has to the finite element used the last
- * time when @p distribute_dofs was called.
+ * Clear all data of this object and especially delete the lock this
+ * object has to the finite element used the last time when @p
+ * distribute_dofs was called.
*/
virtual void clear ();
/**
- * Renumber degrees of freedom based on
- * a list of new dof numbers for all the
- * dofs.
+ * Renumber degrees of freedom based on a list of new dof numbers for all
+ * the dofs.
*
- * @p new_numbers is an array of integers
- * with size equal to the number of dofs
- * on the present grid. It stores the new
- * indices after renumbering in the
- * order of the old indices.
+ * @p new_numbers is an array of integers with size equal to the number of
+ * dofs on the present grid. It stores the new indices after renumbering
+ * in the order of the old indices.
*
- * This function is called by
- * the functions in
- * DoFRenumbering function
- * after computing the ordering
- * of the degrees of freedom.
- * However, you can call this
- * function yourself, which is
- * necessary if a user wants to
- * implement an ordering scheme
- * herself, for example
- * downwind numbering.
+ * This function is called by the functions in DoFRenumbering function
+ * after computing the ordering of the degrees of freedom. However, you
+ * can call this function yourself, which is necessary if a user wants to
+ * implement an ordering scheme herself, for example downwind numbering.
*
- * The @p new_number array must
- * have a size equal to the
- * number of degrees of
- * freedom. Each entry must
- * state the new global DoF
- * number of the degree of
- * freedom referenced.
+ * The @p new_number array must have a size equal to the number of degrees
+ * of freedom. Each entry must state the new global DoF number of the
+ * degree of freedom referenced.
*/
void renumber_dofs (const std::vector<types::global_dof_index> &new_numbers);
/**
- * Return the maximum number of
- * degrees of freedom a degree of freedom
- * in the given triangulation with the
- * given finite element may couple with.
- * This is the maximum number of entries
- * per line in the system matrix; this
- * information can therefore be used upon
- * construction of the SparsityPattern
- * object.
+ * Return the maximum number of degrees of freedom a degree of freedom in
+ * the given triangulation with the given finite element may couple with.
+ * This is the maximum number of entries per line in the system matrix;
+ * this information can therefore be used upon construction of the
+ * SparsityPattern object.
*
- * The returned number is not really the
- * maximum number but an estimate based
- * on the finite element and the maximum
- * number of cells meeting at a vertex.
- * The number holds for the constrained
- * matrix also.
+ * The returned number is not really the maximum number but an estimate
+ * based on the finite element and the maximum number of cells meeting at
+ * a vertex. The number holds for the constrained matrix also.
*
- * As for
- * ::DoFHandler::max_couplings_between_dofs(),
- * the result of this function is often
- * not very accurate for 3d and/or high
- * polynomial degrees. The consequences
- * are discussed in the documentation
- * of the module on @ref Sparsity.
+ * As for ::DoFHandler::max_couplings_between_dofs(), the result of this
+ * function is often not very accurate for 3d and/or high polynomial
+ * degrees. The consequences are discussed in the documentation of the
+ * module on @ref Sparsity.
*/
unsigned int max_couplings_between_dofs () const;
/**
- * Return the number of degrees of freedom
- * located on the boundary another dof on
- * the boundary can couple with.
+ * Return the number of degrees of freedom located on the boundary another
+ * dof on the boundary can couple with.
*
- * The number is the same as for
- * @p max_coupling_between_dofs in one
+ * The number is the same as for @p max_coupling_between_dofs in one
* dimension less.
*
* @note The same applies to this function as to max_couplings_per_dofs()
unsigned int max_couplings_between_boundary_dofs () const;
/**
- * @name Cell iterator functions
- */
+ * @name Cell iterator functions
+ */
/*@{*/
/**
- * Iterator to the first used
- * cell on level @p level.
- */
+ * Iterator to the first used cell on level @p level.
+ */
cell_iterator begin (const unsigned int level = 0) const;
/**
- * Iterator to the first active cell on level @p level. If the
- * given level does not contain any active cells (i.e., all cells
- * on this level are further refined, then this function returns
- * <code>end_active(level)</code> so that loops of the kind
+ * Iterator to the first active cell on level @p level. If the given level
+ * does not contain any active cells (i.e., all cells on this level are
+ * further refined, then this function returns
+ * <code>end_active(level)</code> so that loops of the kind
* @code
* for (cell=dof_handler.begin_active(level); cell!=dof_handler.end_active(level); ++cell)
* ...
* @endcode
- * have zero iterations, as may be expected if there are no active
- * cells on this level.
+ * have zero iterations, as may be expected if there are no active cells
+ * on this level.
*/
active_cell_iterator begin_active(const unsigned int level = 0) const;
/**
- * Iterator past the end; this
- * iterator serves for
- * comparisons of iterators with
- * past-the-end or
- * before-the-beginning states.
- */
+ * Iterator past the end; this iterator serves for comparisons of
+ * iterators with past-the-end or before-the-beginning states.
+ */
cell_iterator end () const;
/**
- * Return an iterator which is
- * the first iterator not on
- * level. If @p level is the
- * last level, then this returns
- * <tt>end()</tt>.
- */
+ * Return an iterator which is the first iterator not on level. If @p
+ * level is the last level, then this returns <tt>end()</tt>.
+ */
cell_iterator end (const unsigned int level) const;
/**
- * Return an active iterator which is the first active iterator not
- * on the given level. If @p level is the last level, then this
- * returns <tt>end()</tt>.
+ * Return an active iterator which is the first active iterator not on the
+ * given level. If @p level is the last level, then this returns
+ * <tt>end()</tt>.
*/
active_cell_iterator end_active (const unsigned int level) const;
/**
- * @name Cell iterator functions returning ranges of iterators
+ * @name Cell iterator functions returning ranges of iterators
*/
/**
- * Return an iterator range that contains all cells (active or not)
- * that make up this DoFHandler. Such a range is useful to
- * initialize range-based for loops as supported by C++11. See the
- * example in the documentation of active_cell_iterators().
+ * Return an iterator range that contains all cells (active or not) that
+ * make up this DoFHandler. Such a range is useful to initialize range-
+ * based for loops as supported by C++11. See the example in the
+ * documentation of active_cell_iterators().
*
* @return The half open range <code>[this->begin(), this->end())</code>
*
IteratorRange<cell_iterator> cell_iterators () const;
/**
- * Return an iterator range that contains all active cells
- * that make up this DoFHandler. Such a range is useful to
- * initialize range-based for loops as supported by C++11,
- * see also @ref CPP11 "C++11 standard".
+ * Return an iterator range that contains all active cells that make up
+ * this DoFHandler. Such a range is useful to initialize range-based for
+ * loops as supported by C++11, see also @ref CPP11 "C++11 standard".
*
- * Range-based for loops are useful in that they require much less
- * code than traditional loops (see
- * <a href="http://en.wikipedia.org/wiki/C%2B%2B11#Range-based_for_loop">here</a>
- * for a discussion of how they work). An example is that without
- * range-based for loops, one often writes code such as the following:
+ * Range-based for loops are useful in that they require much less code
+ * than traditional loops (see <a
+ * href="http://en.wikipedia.org/wiki/C%2B%2B11#Range-
+ * based_for_loop">here</a> for a discussion of how they work). An example
+ * is that without range-based for loops, one often writes code such as
+ * the following:
* @code
* DoFHandler<dim> dof_handler;
* ...
* ...do the local integration on 'cell'...;
* }
* @endcode
- * Using C++11's range-based for loops, this is now entirely
- * equivalent to the following:
+ * Using C++11's range-based for loops, this is now entirely equivalent to
+ * the following:
* @code
* DoFHandler<dim> dof_handler;
* ...
* @endcode
* To use this feature, you need a compiler that supports C++11.
*
- * @return The half open range <code>[this->begin_active(), this->end())</code>
+ * @return The half open range <code>[this->begin_active(),
+ * this->end())</code>
*
* @ingroup CPP11
*/
IteratorRange<active_cell_iterator> active_cell_iterators () const;
/**
- * Return an iterator range that contains all cells (active or not)
- * that make up the given level of this DoFHandler. Such a range is useful to
- * initialize range-based for loops as supported by C++11. See the
- * example in the documentation of active_cell_iterators().
+ * Return an iterator range that contains all cells (active or not) that
+ * make up the given level of this DoFHandler. Such a range is useful to
+ * initialize range-based for loops as supported by C++11. See the example
+ * in the documentation of active_cell_iterators().
*
* @param[in] level A given level in the refinement hierarchy of this
- * triangulation.
- * @return The half open range <code>[this->begin(level), this->end(level))</code>
+ * triangulation. @return The half open range <code>[this->begin(level),
+ * this->end(level))</code>
*
* @pre level must be less than this->n_levels().
*
IteratorRange<cell_iterator> cell_iterators_on_level (const unsigned int level) const;
/**
- * Return an iterator range that contains all active cells
- * that make up the given level of this DoFHandler. Such a range is useful to
- * initialize range-based for loops as supported by C++11. See the
- * example in the documentation of active_cell_iterators().
+ * Return an iterator range that contains all active cells that make up
+ * the given level of this DoFHandler. Such a range is useful to
+ * initialize range-based for loops as supported by C++11. See the example
+ * in the documentation of active_cell_iterators().
*
* @param[in] level A given level in the refinement hierarchy of this
- * triangulation.
- * @return The half open range <code>[this->begin_active(level), this->end(level))</code>
+ * triangulation. @return The half open range
+ * <code>[this->begin_active(level), this->end(level))</code>
*
* @pre level must be less than this->n_levels().
*
/**
- * Return the global number of
- * degrees of freedom. If the
- * current object handles all
- * degrees of freedom itself
- * (even if you may intend to
- * solve your linear system in
- * parallel, such as in step-17
- * or step-18), then this number
- * equals the number of locally
- * owned degrees of freedom since
- * this object doesn't know
- * anything about what you want
- * to do with it and believes
- * that it owns every degree of
- * freedom it knows about.
+ * Return the global number of degrees of freedom. If the current object
+ * handles all degrees of freedom itself (even if you may intend to solve
+ * your linear system in parallel, such as in step-17 or step-18), then
+ * this number equals the number of locally owned degrees of freedom since
+ * this object doesn't know anything about what you want to do with it and
+ * believes that it owns every degree of freedom it knows about.
*
- * On the other hand, if this
- * object operates on a
- * parallel::distributed::Triangulation
- * object, then this function
- * returns the global number of
- * degrees of freedom,
- * accumulated over all
+ * On the other hand, if this object operates on a
+ * parallel::distributed::Triangulation object, then this function returns
+ * the global number of degrees of freedom, accumulated over all
* processors.
*
- * In either case, included in
- * the returned number are those
- * DoFs which are constrained by
- * hanging nodes, see @ref constraints.
+ * In either case, included in the returned number are those DoFs which
+ * are constrained by hanging nodes, see @ref constraints.
*/
types::global_dof_index n_dofs () const;
/**
- * The number of multilevel
- * dofs on given level. Since
- * hp::DoFHandler does not
- * support multilevel methods
- * yet, this function returns
- * numbers::invalid_unsigned
- * int independent of its argument.
- */
+ * The number of multilevel dofs on given level. Since hp::DoFHandler does
+ * not support multilevel methods yet, this function returns
+ * numbers::invalid_unsigned int independent of its argument.
+ */
types::global_dof_index n_dofs(const unsigned int level) const;
/**
- * Return the number of degrees of freedom
- * located on the boundary.
+ * Return the number of degrees of freedom located on the boundary.
*/
types::global_dof_index n_boundary_dofs () const;
/**
- * Return the number of degrees
- * of freedom located on those
- * parts of the boundary which
- * have a boundary indicator
- * listed in the given set. The
- * reason that a @p map rather
- * than a @p set is used is the
- * same as described in the
- * section on the
- * @p make_boundary_sparsity_pattern
+ * Return the number of degrees of freedom located on those parts of the
+ * boundary which have a boundary indicator listed in the given set. The
+ * reason that a @p map rather than a @p set is used is the same as
+ * described in the section on the @p make_boundary_sparsity_pattern
* function.
*/
types::global_dof_index
n_boundary_dofs (const FunctionMap &boundary_indicators) const;
/**
- * Same function, but with
- * different data type of the
- * argument, which is here simply
- * a list of the boundary
- * indicators under
- * consideration.
+ * Same function, but with different data type of the argument, which is
+ * here simply a list of the boundary indicators under consideration.
*/
types::global_dof_index
n_boundary_dofs (const std::set<types::boundary_id> &boundary_indicators) const;
/**
- * Return the number of
- * degrees of freedom that
- * belong to this
- * process.
+ * Return the number of degrees of freedom that belong to this process.
*
- * If this is a sequential job,
- * then the result equals that
- * produced by n_dofs(). On the
- * other hand, if we are
- * operating on a
- * parallel::distributed::Triangulation,
- * then it includes only the
- * degrees of freedom that the
- * current processor owns. Note
- * that in this case this does
- * not include all degrees of
- * freedom that have been
- * distributed on the current
- * processor's image of the mesh:
- * in particular, some of the
- * degrees of freedom on the
- * interface between the cells
- * owned by this processor and
- * cells owned by other
- * processors may be theirs, and
- * degrees of freedom on ghost
- * cells are also not necessarily
- * included.
+ * If this is a sequential job, then the result equals that produced by
+ * n_dofs(). On the other hand, if we are operating on a
+ * parallel::distributed::Triangulation, then it includes only the degrees
+ * of freedom that the current processor owns. Note that in this case this
+ * does not include all degrees of freedom that have been distributed on
+ * the current processor's image of the mesh: in particular, some of the
+ * degrees of freedom on the interface between the cells owned by this
+ * processor and cells owned by other processors may be theirs, and
+ * degrees of freedom on ghost cells are also not necessarily included.
*/
types::global_dof_index n_locally_owned_dofs() const;
/**
- * Return an IndexSet describing
- * the set of locally owned DoFs
- * as a subset of
- * 0..n_dofs(). The number of
- * elements of this set equals
+ * Return an IndexSet describing the set of locally owned DoFs as a subset
+ * of 0..n_dofs(). The number of elements of this set equals
* n_locally_owned_dofs().
*/
const IndexSet &locally_owned_dofs() const;
/**
- * Returns a vector that
- * stores the locally owned
- * DoFs of each processor. If
- * you are only interested in
- * the number of elements
- * each processor owns then
- * n_dofs_per_processor() is
- * a better choice.
+ * Returns a vector that stores the locally owned DoFs of each processor.
+ * If you are only interested in the number of elements each processor
+ * owns then n_dofs_per_processor() is a better choice.
*
- * If this is a sequential job,
- * then the vector has a single
- * element that equals the
- * IndexSet representing the
- * entire range [0,n_dofs()].
+ * If this is a sequential job, then the vector has a single element that
+ * equals the IndexSet representing the entire range [0,n_dofs()].
*/
const std::vector<IndexSet> &
locally_owned_dofs_per_processor () const;
/**
- * Return a vector that
- * stores the number of
- * degrees of freedom each
- * processor that
- * participates in this
- * triangulation owns
- * locally. The sum of all
- * these numbers equals the
- * number of degrees of
- * freedom that exist
- * globally, i.e. what
- * n_dofs() returns.
+ * Return a vector that stores the number of degrees of freedom each
+ * processor that participates in this triangulation owns locally. The sum
+ * of all these numbers equals the number of degrees of freedom that exist
+ * globally, i.e. what n_dofs() returns.
*
- * Each element of the vector
- * returned by this function
- * equals the number of
- * elements of the
- * corresponding sets
- * returned by
- * global_dof_indices().
+ * Each element of the vector returned by this function equals the number
+ * of elements of the corresponding sets returned by global_dof_indices().
*
- * If this is a sequential job,
- * then the vector has a single
- * element equal to n_dofs().
+ * If this is a sequential job, then the vector has a single element equal
+ * to n_dofs().
*/
const std::vector<types::global_dof_index> &
n_locally_owned_dofs_per_processor () const;
/**
- * Return a constant reference to
- * the set of finite element
- * objects that are used by this
- * @p DoFHandler.
+ * Return a constant reference to the set of finite element objects that
+ * are used by this @p DoFHandler.
*/
const hp::FECollection<dim,spacedim> &get_fe () const;
/**
- * Return a constant reference to the
- * triangulation underlying this object.
+ * Return a constant reference to the triangulation underlying this
+ * object.
*/
const Triangulation<dim,spacedim> &get_tria () const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*
- * This function is made virtual,
- * since a dof handler object
- * might be accessed through a
- * pointers to thisr base class,
- * although the actual object
- * might be a derived class.
+ * This function is made virtual, since a dof handler object might be
+ * accessed through a pointers to thisr base class, although the actual
+ * object might be a derived class.
*/
virtual std::size_t memory_consumption () const;
int,
<< "The matrix has the wrong dimension " << arg1);
/**
- * Exception
+ * Exception
*/
DeclException0 (ExcFunctionNotUseful);
/**
<< arg1 << ", but the finite element collection only has "
<< arg2 << " elements");
/**
- * Exception
+ * Exception
*/
DeclException1 (ExcInvalidLevel,
int,
*/
DeclException0 (ExcFacesHaveNoLevel);
/**
- * The triangulation level you
- * accessed is empty.
+ * The triangulation level you accessed is empty.
*/
DeclException1 (ExcEmptyLevel,
int,
protected:
/**
- * Address of the triangulation to
- * work on.
+ * Address of the triangulation to work on.
*/
SmartPointer<const Triangulation<dim,spacedim>,DoFHandler<dim,spacedim> > tria;
/**
- * Store a pointer to the finite
- * element set given latest for
- * the distribution of dofs. In
- * order to avoid destruction of
- * the object before the lifetime
- * of the DoF handler, we
- * subscribe to the finite
- * element object. To unlock the
- * FE before the end of the
- * lifetime of this DoF handler,
- * use the <tt>clear()</tt> function
- * (this clears all data of this
- * object as well, though).
+ * Store a pointer to the finite element set given latest for the
+ * distribution of dofs. In order to avoid destruction of the object
+ * before the lifetime of the DoF handler, we subscribe to the finite
+ * element object. To unlock the FE before the end of the lifetime of this
+ * DoF handler, use the <tt>clear()</tt> function (this clears all data of
+ * this object as well, though).
*/
SmartPointer<const hp::FECollection<dim,spacedim>,hp::DoFHandler<dim,spacedim> > finite_elements;
private:
/**
- * Copy constructor. I can see no reason
- * why someone might want to use it, so
- * I don't provide it. Since this class
- * has pointer members, making it private
- * prevents the compiler to provide it's
- * own, incorrect one if anyone chose to
- * copy such an object.
+ * Copy constructor. I can see no reason why someone might want to use it,
+ * so I don't provide it. Since this class has pointer members, making it
+ * private prevents the compiler to provide it's own, incorrect one if
+ * anyone chose to copy such an object.
*/
DoFHandler (const DoFHandler &);
/**
- * Copy operator. I can see no reason
- * why someone might want to use it, so
- * I don't provide it. Since this class
- * has pointer members, making it private
- * prevents the compiler to provide it's
- * own, incorrect one if anyone chose to
- * copy such an object.
+ * Copy operator. I can see no reason why someone might want to use it, so
+ * I don't provide it. Since this class has pointer members, making it
+ * private prevents the compiler to provide it's own, incorrect one if
+ * anyone chose to copy such an object.
*/
DoFHandler &operator = (const DoFHandler &);
void set_dof_index (const unsigned int obj_level, const unsigned int obj_index, const unsigned int fe_index, const unsigned int local_index, const types::global_dof_index global_index) const;
/**
- * Create default tables for
- * the active_fe_indices in
- * the
- * dealii::internal::hp::DoFLevel. They
- * are initialized with a
- * zero indicator, meaning
- * that fe[0] is going to be
- * used by default. This
- * method is called before
- * refinement and before
- * distribute_dofs is
- * called. It ensures each
- * cell has a valid
- * active_fe_index.
+ * Create default tables for the active_fe_indices in the
+ * dealii::internal::hp::DoFLevel. They are initialized with a zero
+ * indicator, meaning that fe[0] is going to be used by default. This
+ * method is called before refinement and before distribute_dofs is
+ * called. It ensures each cell has a valid active_fe_index.
*/
void create_active_fe_table ();
/**
- * Functions that will be triggered
- * through signals whenever the
- * triangulation is modified.
+ * Functions that will be triggered through signals whenever the
+ * triangulation is modified.
*
- * Here they are used to
- * administrate the the
- * active_fe_fields during the
- * spatial refinement.
+ * Here they are used to administrate the the active_fe_fields during the
+ * spatial refinement.
*/
void pre_refinement_action ();
void post_refinement_action ();
/**
- * Compute identities between
- * DoFs located on
- * vertices. Called from
+ * Compute identities between DoFs located on vertices. Called from
* distribute_dofs().
*/
void
compute_vertex_dof_identities (std::vector<types::global_dof_index> &new_dof_indices) const;
/**
- * Compute identities between
- * DoFs located on
- * lines. Called from
+ * Compute identities between DoFs located on lines. Called from
* distribute_dofs().
*/
void
compute_line_dof_identities (std::vector<types::global_dof_index> &new_dof_indices) const;
/**
- * Compute identities between
- * DoFs located on
- * quads. Called from
+ * Compute identities between DoFs located on quads. Called from
* distribute_dofs().
*/
void
compute_quad_dof_identities (std::vector<types::global_dof_index> &new_dof_indices) const;
/**
- * Renumber the objects with
- * the given and all lower
- * structural dimensions,
- * i.e. renumber vertices by
- * giving a template argument
- * of zero to the int2type
- * argument, lines and vertices
- * with one, etc.
+ * Renumber the objects with the given and all lower structural
+ * dimensions, i.e. renumber vertices by giving a template argument of
+ * zero to the int2type argument, lines and vertices with one, etc.
*
- * Note that in contrast to the
- * public renumber_dofs()
- * function, these internal
- * functions do not ensure that
- * the new DoFs are
- * contiguously numbered. The
- * function may therefore also
- * be used to assign different
- * DoFs the same number, for
- * example to unify hp DoFs
- * corresponding to different
- * finite elements but
- * co-located on the same
- * entity.
+ * Note that in contrast to the public renumber_dofs() function, these
+ * internal functions do not ensure that the new DoFs are contiguously
+ * numbered. The function may therefore also be used to assign different
+ * DoFs the same number, for example to unify hp DoFs corresponding to
+ * different finite elements but co-located on the same entity.
*/
void renumber_dofs_internal (const std::vector<types::global_dof_index> &new_numbers,
dealii::internal::int2type<0>);
dealii::internal::int2type<3>);
/**
- * Space to store the DoF
- * numbers for the different
- * levels. Analogous to the
- * <tt>levels[]</tt> tree of
- * the Triangulation objects.
+ * Space to store the DoF numbers for the different levels. Analogous to
+ * the <tt>levels[]</tt> tree of the Triangulation objects.
*/
std::vector<dealii::internal::hp::DoFLevel *> levels;
/**
- * Space to store the DoF
- * numbers for the faces.
- * Analogous to the
- * <tt>faces</tt> pointer of
- * the Triangulation objects.
+ * Space to store the DoF numbers for the faces. Analogous to the
+ * <tt>faces</tt> pointer of the Triangulation objects.
*/
dealii::internal::hp::DoFIndicesOnFaces<dim> *faces;
/**
- * A structure that contains all
- * sorts of numbers that
- * characterize the degrees of
- * freedom this object works on.
+ * A structure that contains all sorts of numbers that characterize the
+ * degrees of freedom this object works on.
*
- * For most members of this
- * structure, there is an
- * accessor function in this
- * class that returns its value.
+ * For most members of this structure, there is an accessor function in
+ * this class that returns its value.
*/
dealii::internal::DoFHandler::NumberCache number_cache;
/**
- * Array to store the indices
- * for degrees of freedom
- * located at vertices.
+ * Array to store the indices for degrees of freedom located at vertices.
*
- * The format used here, in the
- * form of a linked list, is
- * the same as used for the
- * arrays used in the
- * internal::hp::DoFLevel
- * hierarchy. Starting indices
- * into this array are provided
- * by the vertex_dofs_offsets
- * field.
+ * The format used here, in the form of a linked list, is the same as used
+ * for the arrays used in the internal::hp::DoFLevel hierarchy. Starting
+ * indices into this array are provided by the vertex_dofs_offsets field.
*
- * Access to this field is
- * generally through the
+ * Access to this field is generally through the
* DoFAccessor::get_vertex_dof_index() and
- * DoFAccessor::set_vertex_dof_index()
- * functions, encapsulating the
- * actual data format used to
- * the present class.
+ * DoFAccessor::set_vertex_dof_index() functions, encapsulating the actual
+ * data format used to the present class.
*/
std::vector<types::global_dof_index> vertex_dofs;
/**
- * For each vertex in the
- * triangulation, store the
- * offset within the
- * vertex_dofs array where the
- * dofs for this vertex start.
+ * For each vertex in the triangulation, store the offset within the
+ * vertex_dofs array where the dofs for this vertex start.
*
- * As for that array, the
- * format is the same as
- * described in the
- * documentation of
- * hp::DoFLevel.
+ * As for that array, the format is the same as described in the
+ * documentation of hp::DoFLevel.
*
- * Access to this field is
- * generally through the
- * Accessor::get_vertex_dof_index() and
- * Accessor::set_vertex_dof_index()
- * functions, encapsulating the
- * actual data format used to
- * the present class.
+ * Access to this field is generally through the
+ * Accessor::get_vertex_dof_index() and Accessor::set_vertex_dof_index()
+ * functions, encapsulating the actual data format used to the present
+ * class.
*/
std::vector<types::global_dof_index> vertex_dofs_offsets;
std::vector<MGVertexDoFs> mg_vertex_dofs; // we should really remove this field!
/**
- * Array to store the
- * information if a cell on
- * some level has children or
- * not. It is used by the
- * signal slots as a
- * persistent buffer during the
- * refinement, i.e. from between
- * when pre_refinement_action is
- * called and when post_refinement_action
- * runs.
+ * Array to store the information if a cell on some level has children or
+ * not. It is used by the signal slots as a persistent buffer during the
+ * refinement, i.e. from between when pre_refinement_action is called and
+ * when post_refinement_action runs.
*/
std::vector<std::vector<bool> *> has_children;
/**
- * A list of connections with which this object connects
- * to the triangulation to get information about when the
- * triangulation changes.
+ * A list of connections with which this object connects to the
+ * triangulation to get information about when the triangulation changes.
*/
std::vector<boost::signals2::connection> tria_listeners;
friend struct dealii::internal::DoFCellAccessor::Implementation;
/**
- * Likewise for DoFLevel
- * objects since they need to
- * access the vertex dofs in
- * the functions that set and
- * retrieve vertex dof indices.
+ * Likewise for DoFLevel objects since they need to access the vertex dofs
+ * in the functions that set and retrieve vertex dof indices.
*/
template <int> friend class dealii::internal::hp::DoFIndicesOnFacesOrEdges;
friend struct dealii::internal::hp::DoFHandler::Implementation;
/**
* This is the class that stores the degrees of freedom on cells in a hp
* hierarchy. Compared to faces and edges, the task here is simple since
- * each cell can only have a single active finite element index. Consequently,
- * all we need is one long array with DoF indices and one array of offsets
- * where each cell's indices start within the array of indices. This is in
- * contrast to the DoFObjects class where each face or edge may have more than
- * one associated finite element with corresponding degrees of freedom.
+ * each cell can only have a single active finite element index.
+ * Consequently, all we need is one long array with DoF indices and one
+ * array of offsets where each cell's indices start within the array of
+ * indices. This is in contrast to the DoFObjects class where each face or
+ * edge may have more than one associated finite element with
+ * corresponding degrees of freedom.
*
- * The data stored here is represented by three arrays
- * - The @p active_fe_indices array stores for each cell which
- * finite element is used on this cell. Since some cells are not active
- * on the current level, some entries in this array may represent an
- * invalid value.
- * - The @p dof_indices array stores for each active cell on the current
- * level the dofs that associated with the <i>interior</i> of the cell,
- * i.e., the @p dofs_per_line dofs associated with the line in 1d, and
- * @p dofs_per_quad and @p dofs_per_hex in 2d and 3d. These numbers are
- * in general smaller than @p dofs_per_cell.
- * - The @p dof_offsets array stores, for each cell, the starting point
- * of the dof indices corresponding to this cell in the @p dof_indices
- * array. This is analogous to how we store data in compressed row storage
- * for sparse matrices. For cells that are not active on the current level,
- * we store an invalid value for the starting index.
+ * The data stored here is represented by three arrays - The @p
+ * active_fe_indices array stores for each cell which finite element is
+ * used on this cell. Since some cells are not active on the current
+ * level, some entries in this array may represent an invalid value. - The
+ * @p dof_indices array stores for each active cell on the current level
+ * the dofs that associated with the <i>interior</i> of the cell, i.e.,
+ * the @p dofs_per_line dofs associated with the line in 1d, and @p
+ * dofs_per_quad and @p dofs_per_hex in 2d and 3d. These numbers are in
+ * general smaller than @p dofs_per_cell. - The @p dof_offsets array
+ * stores, for each cell, the starting point of the dof indices
+ * corresponding to this cell in the @p dof_indices array. This is
+ * analogous to how we store data in compressed row storage for sparse
+ * matrices. For cells that are not active on the current level, we store
+ * an invalid value for the starting index.
*
* <h3>Compression</h3>
*
- * It is common for the indices stored in @p dof_indices for one cell to be
- * numbered consecutively. For example, using the standard numbering (without
- * renumbering DoFs), the quad dofs on the first cell of a mesh when using a
- * $Q_3$ element will be numbered <tt>12, 13, 14, 15</tt>. This allows for
- * compression if we only store the first entry and have some way to mark
- * the DoFs on this object as compressed. Here, compression means that we
- * know that subsequent DoF indices can be obtained from the previous ones
- * by just incrementing them by one -- in other words, we use a variant of doing
- * run-length encoding. The way to do this is that we
- * use positive FE indices for uncompressed sets of DoFs and if a set of indices
- * is compressed, then we instead store the FE index in binary complement (which
- * we can identify by looking at the sign bit when interpreting the number as a
- * signed one). There are two functions, compress_data() and uncompress_data()
- * that convert between the two possible representations.
+ * It is common for the indices stored in @p dof_indices for one cell to
+ * be numbered consecutively. For example, using the standard numbering
+ * (without renumbering DoFs), the quad dofs on the first cell of a mesh
+ * when using a $Q_3$ element will be numbered <tt>12, 13, 14, 15</tt>.
+ * This allows for compression if we only store the first entry and have
+ * some way to mark the DoFs on this object as compressed. Here,
+ * compression means that we know that subsequent DoF indices can be
+ * obtained from the previous ones by just incrementing them by one -- in
+ * other words, we use a variant of doing run-length encoding. The way to
+ * do this is that we use positive FE indices for uncompressed sets of
+ * DoFs and if a set of indices is compressed, then we instead store the
+ * FE index in binary complement (which we can identify by looking at the
+ * sign bit when interpreting the number as a signed one). There are two
+ * functions, compress_data() and uncompress_data() that convert between
+ * the two possible representations.
*
- * Note that compression is not always possible. For example, if one renumbered
- * the example above using DoFRenumbering::downstream with $(1,0)^T$ as
- * direction, then they would likely be numbered <tt>12, 14, 13, 15</tt>, which
- * can not be compressed using run-length encoding.
+ * Note that compression is not always possible. For example, if one
+ * renumbered the example above using DoFRenumbering::downstream with
+ * $(1,0)^T$ as direction, then they would likely be numbered <tt>12, 14,
+ * 13, 15</tt>, which can not be compressed using run-length encoding.
*/
class DoFLevel
{
typedef signed short int signed_active_fe_index_type;
/**
- * Indices specifying the finite element of hp::FECollection to
- * use for the different cells on the current level. The vector
- * stores one element per cell since the active_fe_index is
- * unique for cells.
+ * Indices specifying the finite element of hp::FECollection to use for
+ * the different cells on the current level. The vector stores one
+ * element per cell since the active_fe_index is unique for cells.
*
- * If a cell is not active on the level corresponding to the
- * current object (i.e., it has children on higher levels) then
- * it does not have an associated fe index and we store
- * an invalid fe index marker instead.
+ * If a cell is not active on the level corresponding to the current
+ * object (i.e., it has children on higher levels) then it does not have
+ * an associated fe index and we store an invalid fe index marker
+ * instead.
*/
std::vector<active_fe_index_type> active_fe_indices;
/**
- * Store the start index for the degrees of freedom of each
- * object in the @p dof_indices array. If the cell corresponding to
- * a particular index in this array is not active on this level,
- * then we do not store any DoFs for it. In that case, the offset
- * we store here must be an invalid number and indeed we store
+ * Store the start index for the degrees of freedom of each object in
+ * the @p dof_indices array. If the cell corresponding to a particular
+ * index in this array is not active on this level, then we do not store
+ * any DoFs for it. In that case, the offset we store here must be an
+ * invalid number and indeed we store
* <code>(std::vector<types::global_dof_index>::size_type)(-1)</code>
* for it.
*
std::vector<offset_type> dof_offsets;
/**
- * Store the global indices of the degrees of freedom.
- * information. The dof_offsets field determines where each
- * (active) cell's data is stored.
+ * Store the global indices of the degrees of freedom. information. The
+ * dof_offsets field determines where each (active) cell's data is
+ * stored.
*/
std::vector<types::global_dof_index> dof_indices;
std::vector<offset_type> cell_cache_offsets;
/**
- * Cache for the DoF indices
- * on cells. The size of this
- * array equals the sum over all cells of selected_fe[active_fe_index[cell]].dofs_per_cell.
+ * Cache for the DoF indices on cells. The size of this array equals the
+ * sum over all cells of
+ * selected_fe[active_fe_index[cell]].dofs_per_cell.
*/
std::vector<types::global_dof_index> cell_dof_indices_cache;
public:
/**
- * Set the global index of
- * the @p local_index-th
- * degree of freedom located
- * on the object with number @p
- * obj_index to the value
- * given by @p global_index. The @p
- * dof_handler argument is
- * used to access the finite
- * element that is to be used
- * to compute the location
- * where this data is stored.
+ * Set the global index of the @p local_index-th degree of freedom
+ * located on the object with number @p obj_index to the value given by
+ * @p global_index. The @p dof_handler argument is used to access the
+ * finite element that is to be used to compute the location where this
+ * data is stored.
*
- * The third argument, @p
- * fe_index, denotes which of
- * the finite elements
- * associated with this
- * object we shall
- * access. Refer to the
- * general documentation of
- * the internal::hp::DoFLevel
- * class template for more
+ * The third argument, @p fe_index, denotes which of the finite elements
+ * associated with this object we shall access. Refer to the general
+ * documentation of the internal::hp::DoFLevel class template for more
* information.
*/
void
const types::global_dof_index global_index);
/**
- * Return the global index of
- * the @p local_index-th
- * degree of freedom located
- * on the object with number @p
- * obj_index. The @p
- * dof_handler argument is
- * used to access the finite
- * element that is to be used
- * to compute the location
- * where this data is stored.
+ * Return the global index of the @p local_index-th degree of freedom
+ * located on the object with number @p obj_index. The @p dof_handler
+ * argument is used to access the finite element that is to be used to
+ * compute the location where this data is stored.
*
- * The third argument, @p
- * fe_index, denotes which of
- * the finite elements
- * associated with this
- * object we shall
- * access. Refer to the
- * general documentation of
- * the internal::hp::DoFLevel
- * class template for more
+ * The third argument, @p fe_index, denotes which of the finite elements
+ * associated with this object we shall access. Refer to the general
+ * documentation of the internal::hp::DoFLevel class template for more
* information.
*/
types::global_dof_index
const unsigned int local_index) const;
/**
- * Return the fe_index of the
- * active finite element
- * on this object.
+ * Return the fe_index of the active finite element on this object.
*/
unsigned int
active_fe_index (const unsigned int obj_index) const;
/**
- * Check whether a given
- * finite element index is
- * used on the present
+ * Check whether a given finite element index is used on the present
* object or not.
*/
bool
const unsigned int fe_index) const;
/**
- * Set the fe_index of the
- * active finite element
- * on this object.
+ * Set the fe_index of the active finite element on this object.
*/
void
set_active_fe_index (const unsigned int obj_index,
const unsigned int fe_index);
/**
- * Return a pointer to the beginning of the DoF indices cache
- * for a given cell.
+ * Return a pointer to the beginning of the DoF indices cache for a
+ * given cell.
*
* @param obj_index The number of the cell we are looking at.
* @param dofs_per_cell The number of DoFs per cell for this cell. This
- * is not used for the hp case but necessary to keep the interface
- * the same as for the non-hp case.
- * @return A pointer to the first DoF index for the current cell. The
- * next dofs_per_cell indices are for the current cell.
+ * is not used for the hp case but necessary to keep the interface the
+ * same as for the non-hp case. @return A pointer to the first DoF index
+ * for the current cell. The next dofs_per_cell indices are for the
+ * current cell.
*/
const types::global_dof_index *
get_cell_cache_start (const unsigned int obj_index,
const unsigned int dofs_per_cell) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
private:
/**
- * Compress the arrays that store dof indices by using a variant
- * of run-length encoding. See the general documentation of this
- * class for more information.
+ * Compress the arrays that store dof indices by using a variant of run-
+ * length encoding. See the general documentation of this class for more
+ * information.
*
- * @param fe_collection The object that can tell us how many
- * degrees of freedom each of the finite elements has that we
- * store in this object.
+ * @param fe_collection The object that can tell us how many degrees of
+ * freedom each of the finite elements has that we store in this object.
*/
template <int dim, int spacedim>
void compress_data (const dealii::hp::FECollection<dim,spacedim> &fe_collection);
/**
- * Uncompress the arrays that store dof indices by using a variant
- * of run-length encoding. See the general documentation of this
- * class for more information.
+ * Uncompress the arrays that store dof indices by using a variant of
+ * run-length encoding. See the general documentation of this class for
+ * more information.
*
- * @param fe_collection The object that can tell us how many
- * degrees of freedom each of the finite elements has that we
- * store in this object.
+ * @param fe_collection The object that can tell us how many degrees of
+ * freedom each of the finite elements has that we store in this object.
*/
template <int dim, int spacedim>
void uncompress_data (const dealii::hp::FECollection<dim,spacedim> &fe_collection);
/**
- * Make hp::DoFHandler and its auxiliary class a friend since it
- * is the class that needs to create these data structures.
+ * Make hp::DoFHandler and its auxiliary class a friend since it is the
+ * class that needs to create these data structures.
*/
template <int, int> friend class dealii::hp::DoFHandler;
friend struct dealii::internal::hp::DoFHandler::Implementation;
/**
* This class acts as a collection of finite element objects used in the
- * hp::DoFHandler. It is thus to a hp::DoFHandler what a
- * FiniteElement is to a ::DoFHandler.
+ * hp::DoFHandler. It is thus to a hp::DoFHandler what a FiniteElement is to
+ * a ::DoFHandler.
*
- * It implements the concepts stated in the @ref hpcollection module described
- * in the doxygen documentation.
+ * It implements the concepts stated in the @ref hpcollection module
+ * described in the doxygen documentation.
*
* In addition to offering access to the elements of the collection, this
* class provides access to the maximal number of degrees of freedom per
- * vertex, line, etc, to allow allocation of as much memory as is necessary in
- * the worst case when using the finite elements associated with the cells of
- * a triangulation.
+ * vertex, line, etc, to allow allocation of as much memory as is necessary
+ * in the worst case when using the finite elements associated with the
+ * cells of a triangulation.
*
* This class has not yet been implemented for the use in the codimension
* one case (<tt>spacedim != dim </tt>).
{
public:
/**
- * Default constructor. Leads
- * to an empty collection that
- * can later be filled using
- * push_back().
+ * Default constructor. Leads to an empty collection that can later be
+ * filled using push_back().
*/
FECollection ();
/**
- * Conversion constructor. This
- * constructor creates a
- * FECollection from a single
- * finite element. More finite
- * element objects can be added
- * with push_back(), if
- * desired, though it would
- * probably be clearer to add
- * all mappings the same way.
+ * Conversion constructor. This constructor creates a FECollection from a
+ * single finite element. More finite element objects can be added with
+ * push_back(), if desired, though it would probably be clearer to add all
+ * mappings the same way.
*/
explicit FECollection (const FiniteElement<dim,spacedim> &fe);
FECollection (const FECollection<dim,spacedim> &fe_collection);
/**
- * Add a finite element. This
- * function generates a copy of
- * the given element, i.e. you
- * can do things like
- * <tt>push_back(FE_Q<dim>(1));</tt>. The
- * internal copy is later
- * destroyed by this object
- * upon destruction of the
- * entire collection.
+ * Add a finite element. This function generates a copy of the given
+ * element, i.e. you can do things like <tt>push_back(FE_Q<dim>(1));</tt>.
+ * The internal copy is later destroyed by this object upon destruction of
+ * the entire collection.
*
- * When a new element is added,
- * it needs to have the same
- * number of vector components
- * as all other elements
- * already in the collection.
+ * When a new element is added, it needs to have the same number of vector
+ * components as all other elements already in the collection.
*/
void push_back (const FiniteElement<dim,spacedim> &new_fe);
/**
- * Get a reference to the given
- * element in this collection.
+ * Get a reference to the given element in this collection.
*
- * @pre @p index must be
- * between zero and the number
- * of elements of the
+ * @pre @p index must be between zero and the number of elements of the
* collection.
*/
const FiniteElement<dim,spacedim> &
operator[] (const unsigned int index) const;
/**
- * Return the number of finite
- * element objects stored in
- * this collection.
+ * Return the number of finite element objects stored in this collection.
*/
unsigned int size () const;
/**
- * Return the number of vector
- * components of the finite elements in
- * this collection. This number must
- * be the same for all elements in the
+ * Return the number of vector components of the finite elements in this
+ * collection. This number must be the same for all elements in the
* collection.
- *
- * This function calls
- * FiniteElement::n_components. See
- * @ref GlossComponent "the glossary"
- * for more information.
+ *
+ * This function calls FiniteElement::n_components. See @ref
+ * GlossComponent "the glossary" for more information.
*/
unsigned int n_components () const;
/**
- * Return the number of vector
- * blocks of the finite elements in
- * this collection. While this class ensures that all
- * elements stored in it have the same number of vector
- * components, there is no such guarantees for the number
- * of blocks each element is made up of (an element may
- * have fewer blocks than vector components; see
- * @ref GlossBlock "the glossary" for more information).
- * For example, you may have an FECollection object that stores
- * one copy of an FESystem with <code>dim</code> FE_Q objects
- * and one copy of an FE_RaviartThomas element. Both have
- * <code>dim</code> vector components but while the former has
- * <code>dim</code> blocks the latter has only one.
- * Consequently, this function will throw an assertion
- * if the number of blocks is not the same for all elements.
- * If they are the same, this function returns the result
- * of FiniteElement::n_blocks().
+ * Return the number of vector blocks of the finite elements in this
+ * collection. While this class ensures that all elements stored in it
+ * have the same number of vector components, there is no such guarantees
+ * for the number of blocks each element is made up of (an element may
+ * have fewer blocks than vector components; see @ref GlossBlock "the
+ * glossary" for more information). For example, you may have an
+ * FECollection object that stores one copy of an FESystem with
+ * <code>dim</code> FE_Q objects and one copy of an FE_RaviartThomas
+ * element. Both have <code>dim</code> vector components but while the
+ * former has <code>dim</code> blocks the latter has only one.
+ * Consequently, this function will throw an assertion if the number of
+ * blocks is not the same for all elements. If they are the same, this
+ * function returns the result of FiniteElement::n_blocks().
*/
unsigned int n_blocks () const;
/**
- * Return the maximal number of degrees
- * of freedom per vertex over all
+ * Return the maximal number of degrees of freedom per vertex over all
* elements of this collection.
*/
unsigned int max_dofs_per_vertex () const;
/**
- * Return the maximal number of degrees
- * of freedom per line over all elements
- * of this collection.
+ * Return the maximal number of degrees of freedom per line over all
+ * elements of this collection.
*/
unsigned int max_dofs_per_line () const;
/**
- * Return the maximal number of degrees
- * of freedom per quad over all elements
- * of this collection.
+ * Return the maximal number of degrees of freedom per quad over all
+ * elements of this collection.
*/
unsigned int max_dofs_per_quad () const;
/**
- * Return the maximal number of degrees
- * of freedom per hex over all elements
- * of this collection.
+ * Return the maximal number of degrees of freedom per hex over all
+ * elements of this collection.
*/
unsigned int max_dofs_per_hex () const;
/**
- * Return the maximal number of degrees
- * of freedom per face over all elements
- * of this collection.
+ * Return the maximal number of degrees of freedom per face over all
+ * elements of this collection.
*/
unsigned int max_dofs_per_face () const;
/**
- * Return the maximal number of degrees
- * of freedom per cell over all elements
- * of this collection.
+ * Return the maximal number of degrees of freedom per cell over all
+ * elements of this collection.
*/
unsigned int max_dofs_per_cell () const;
/**
- * Return an estimate for the memory
- * allocated for this object.
+ * Return an estimate for the memory allocated for this object.
*/
std::size_t memory_consumption () const;
/**
- * Return whether all elements
- * in this collection
- * implement the hanging node
- * constraints in the new way,
- * which has to be used to make
- * elements "hp compatible".
- * If this is not the case,
- * the function returns false,
- * which implies, that at least
- * one element in the FECollection
- * does not support the new face
- * interface constraints.
- * On the other hand, if this
- * method does return
- * true, this does not imply
- * that the hp method will work!
+ * Return whether all elements in this collection implement the hanging
+ * node constraints in the new way, which has to be used to make elements
+ * "hp compatible". If this is not the case, the function returns false,
+ * which implies, that at least one element in the FECollection does not
+ * support the new face interface constraints. On the other hand, if this
+ * method does return true, this does not imply that the hp method will
+ * work!
*
- * This behaviour is related to
- * the fact, that FiniteElement
- * classes, which provide the
- * new style hanging node constraints
- * might still not provide
- * them for all possible cases.
- * If FE_Q and FE_RaviartThomas
- * elements are included in the
- * FECollection and both properly implement
- * the get_face_interpolation_matrix
- * method, this method will return
- * true. But the get_face_interpolation_matrix
- * might still fail to find an interpolation
- * matrix between these two elements.
+ * This behaviour is related to the fact, that FiniteElement classes,
+ * which provide the new style hanging node constraints might still not
+ * provide them for all possible cases. If FE_Q and FE_RaviartThomas
+ * elements are included in the FECollection and both properly implement
+ * the get_face_interpolation_matrix method, this method will return true.
+ * But the get_face_interpolation_matrix might still fail to find an
+ * interpolation matrix between these two elements.
*/
bool hp_constraints_are_implemented () const;
/**
- * Return a component mask with as many elements as this
- * object has vector components and of which exactly the
- * one component is true that corresponds to the given
- * argument.
+ * Return a component mask with as many elements as this object has vector
+ * components and of which exactly the one component is true that
+ * corresponds to the given argument.
*
* @note This function is the equivalent of
- * FiniteElement::component_mask() with the same arguments.
- * It verifies that it gets the same result from every one
- * of the elements that are stored in this FECollection. If
- * this is not the case, it throws an exception.
+ * FiniteElement::component_mask() with the same arguments. It verifies
+ * that it gets the same result from every one of the elements that are
+ * stored in this FECollection. If this is not the case, it throws an
+ * exception.
*
- * @param scalar An object that represents a single scalar
- * vector component of this finite element.
- * @return A component mask that is false in all components
- * except for the one that corresponds to the argument.
+ * @param scalar An object that represents a single scalar vector
+ * component of this finite element. @return A component mask that is
+ * false in all components except for the one that corresponds to the
+ * argument.
*/
ComponentMask
component_mask (const FEValuesExtractors::Scalar &scalar) const;
/**
- * Return a component mask with as many elements as this
- * object has vector components and of which exactly the
- * <code>dim</code> components are true that correspond to the given
- * argument.
+ * Return a component mask with as many elements as this object has vector
+ * components and of which exactly the <code>dim</code> components are
+ * true that correspond to the given argument.
*
* @note This function is the equivalent of
- * FiniteElement::component_mask() with the same arguments.
- * It verifies that it gets the same result from every one
- * of the elements that are stored in this FECollection. If
- * this is not the case, it throws an exception.
+ * FiniteElement::component_mask() with the same arguments. It verifies
+ * that it gets the same result from every one of the elements that are
+ * stored in this FECollection. If this is not the case, it throws an
+ * exception.
*
- * @param vector An object that represents dim
- * vector components of this finite element.
- * @return A component mask that is false in all components
- * except for the ones that corresponds to the argument.
+ * @param vector An object that represents dim vector components of this
+ * finite element. @return A component mask that is false in all
+ * components except for the ones that corresponds to the argument.
*/
ComponentMask
component_mask (const FEValuesExtractors::Vector &vector) const;
/**
- * Return a component mask with as many elements as this
- * object has vector components and of which exactly the
- * <code>dim*(dim+1)/2</code> components are true that
- * correspond to the given argument.
+ * Return a component mask with as many elements as this object has vector
+ * components and of which exactly the <code>dim*(dim+1)/2</code>
+ * components are true that correspond to the given argument.
*
* @note This function is the equivalent of
- * FiniteElement::component_mask() with the same arguments.
- * It verifies that it gets the same result from every one
- * of the elements that are stored in this FECollection. If
- * this is not the case, it throws an exception.
+ * FiniteElement::component_mask() with the same arguments. It verifies
+ * that it gets the same result from every one of the elements that are
+ * stored in this FECollection. If this is not the case, it throws an
+ * exception.
*
- * @param sym_tensor An object that represents dim*(dim+1)/2
- * components of this finite element that are jointly to be
- * interpreted as forming a symmetric tensor.
- * @return A component mask that is false in all components
- * except for the ones that corresponds to the argument.
+ * @param sym_tensor An object that represents dim*(dim+1)/2 components of
+ * this finite element that are jointly to be interpreted as forming a
+ * symmetric tensor. @return A component mask that is false in all
+ * components except for the ones that corresponds to the argument.
*/
ComponentMask
component_mask (const FEValuesExtractors::SymmetricTensor<2> &sym_tensor) const;
/**
- * Given a block mask (see @ref GlossBlockMask "this glossary entry"),
- * produce a component mask (see @ref GlossComponentMask "this glossary entry")
- * that represents the components that correspond to the blocks selected in
- * the input argument. This is essentially a conversion operator from
- * BlockMask to ComponentMask.
- *
- * @note This function is the equivalent of
- * FiniteElement::component_mask() with the same arguments.
- * It verifies that it gets the same result from every one
- * of the elements that are stored in this FECollection. If
- * this is not the case, it throws an exception.
- *
- * @param block_mask The mask that selects individual blocks of the finite
- * element
- * @return A mask that selects those components corresponding to the selected
- * blocks of the input argument.
- */
+ * Given a block mask (see @ref GlossBlockMask "this glossary entry"),
+ * produce a component mask (see @ref GlossComponentMask "this glossary
+ * entry") that represents the components that correspond to the blocks
+ * selected in the input argument. This is essentially a conversion
+ * operator from BlockMask to ComponentMask.
+ *
+ * @note This function is the equivalent of
+ * FiniteElement::component_mask() with the same arguments. It verifies
+ * that it gets the same result from every one of the elements that are
+ * stored in this FECollection. If this is not the case, it throws an
+ * exception.
+ *
+ * @param block_mask The mask that selects individual blocks of the finite
+ * element @return A mask that selects those components corresponding to
+ * the selected blocks of the input argument.
+ */
ComponentMask
component_mask (const BlockMask &block_mask) const;
/**
- * Return a block mask with as many elements as this
- * object has blocks and of which exactly the
- * one component is true that corresponds to the given
- * argument. See @ref GlossBlockMask "the glossary"
- * for more information.
- *
- * @note This function will only succeed if the scalar referenced
- * by the argument encompasses a complete block. In other words,
- * if, for example, you pass an extractor for the single
- * $x$ velocity and this object represents an FE_RaviartThomas
- * object, then the single scalar object you selected is part
- * of a larger block and consequently there is no block mask that
- * would represent it. The function will then produce an exception.
- *
- * @note This function is the equivalent of
- * FiniteElement::component_mask() with the same arguments.
- * It verifies that it gets the same result from every one
- * of the elements that are stored in this FECollection. If
- * this is not the case, it throws an exception.
- *
- * @param scalar An object that represents a single scalar
- * vector component of this finite element.
- * @return A component mask that is false in all components
- * except for the one that corresponds to the argument.
- */
+ * Return a block mask with as many elements as this object has blocks and
+ * of which exactly the one component is true that corresponds to the
+ * given argument. See @ref GlossBlockMask "the glossary" for more
+ * information.
+ *
+ * @note This function will only succeed if the scalar referenced by the
+ * argument encompasses a complete block. In other words, if, for example,
+ * you pass an extractor for the single $x$ velocity and this object
+ * represents an FE_RaviartThomas object, then the single scalar object
+ * you selected is part of a larger block and consequently there is no
+ * block mask that would represent it. The function will then produce an
+ * exception.
+ *
+ * @note This function is the equivalent of
+ * FiniteElement::component_mask() with the same arguments. It verifies
+ * that it gets the same result from every one of the elements that are
+ * stored in this FECollection. If this is not the case, it throws an
+ * exception.
+ *
+ * @param scalar An object that represents a single scalar vector
+ * component of this finite element. @return A component mask that is
+ * false in all components except for the one that corresponds to the
+ * argument.
+ */
BlockMask
block_mask (const FEValuesExtractors::Scalar &scalar) const;
/**
- * Return a component mask with as many elements as this
- * object has vector components and of which exactly the
- * <code>dim</code> components are true that correspond to the given
- * argument. See @ref GlossBlockMask "the glossary"
- * for more information.
- *
- * @note This function is the equivalent of
- * FiniteElement::component_mask() with the same arguments.
- * It verifies that it gets the same result from every one
- * of the elements that are stored in this FECollection. If
- * this is not the case, it throws an exception.
- *
- * @note The same caveat applies as to the version of the function above:
- * The extractor object passed as argument must be so that it corresponds
- * to full blocks and does not split blocks of this element.
- *
- * @param vector An object that represents dim
- * vector components of this finite element.
- * @return A component mask that is false in all components
- * except for the ones that corresponds to the argument.
- */
+ * Return a component mask with as many elements as this object has vector
+ * components and of which exactly the <code>dim</code> components are
+ * true that correspond to the given argument. See @ref GlossBlockMask
+ * "the glossary" for more information.
+ *
+ * @note This function is the equivalent of
+ * FiniteElement::component_mask() with the same arguments. It verifies
+ * that it gets the same result from every one of the elements that are
+ * stored in this FECollection. If this is not the case, it throws an
+ * exception.
+ *
+ * @note The same caveat applies as to the version of the function above:
+ * The extractor object passed as argument must be so that it corresponds
+ * to full blocks and does not split blocks of this element.
+ *
+ * @param vector An object that represents dim vector components of this
+ * finite element. @return A component mask that is false in all
+ * components except for the ones that corresponds to the argument.
+ */
BlockMask
block_mask (const FEValuesExtractors::Vector &vector) const;
/**
- * Return a component mask with as many elements as this
- * object has vector components and of which exactly the
- * <code>dim*(dim+1)/2</code> components are true that
- * correspond to the given argument. See @ref GlossBlockMask "the glossary"
- * for more information.
- *
- * @note The same caveat applies as to the version of the function above:
- * The extractor object passed as argument must be so that it corresponds
- * to full blocks and does not split blocks of this element.
- *
- * @note This function is the equivalent of
- * FiniteElement::component_mask() with the same arguments.
- * It verifies that it gets the same result from every one
- * of the elements that are stored in this FECollection. If
- * this is not the case, it throws an exception.
- *
- * @param sym_tensor An object that represents dim*(dim+1)/2
- * components of this finite element that are jointly to be
- * interpreted as forming a symmetric tensor.
- * @return A component mask that is false in all components
- * except for the ones that corresponds to the argument.
- */
+ * Return a component mask with as many elements as this object has vector
+ * components and of which exactly the <code>dim*(dim+1)/2</code>
+ * components are true that correspond to the given argument. See @ref
+ * GlossBlockMask "the glossary" for more information.
+ *
+ * @note The same caveat applies as to the version of the function above:
+ * The extractor object passed as argument must be so that it corresponds
+ * to full blocks and does not split blocks of this element.
+ *
+ * @note This function is the equivalent of
+ * FiniteElement::component_mask() with the same arguments. It verifies
+ * that it gets the same result from every one of the elements that are
+ * stored in this FECollection. If this is not the case, it throws an
+ * exception.
+ *
+ * @param sym_tensor An object that represents dim*(dim+1)/2 components of
+ * this finite element that are jointly to be interpreted as forming a
+ * symmetric tensor. @return A component mask that is false in all
+ * components except for the ones that corresponds to the argument.
+ */
BlockMask
block_mask (const FEValuesExtractors::SymmetricTensor<2> &sym_tensor) const;
/**
- * Given a component mask (see @ref GlossComponentMask "this glossary entry"),
- * produce a block mask (see @ref GlossBlockMask "this glossary entry")
- * that represents the blocks that correspond to the components selected in
- * the input argument. This is essentially a conversion operator from
- * ComponentMask to BlockMask.
- *
- * @note This function will only succeed if the components referenced
- * by the argument encompasses complete blocks. In other words,
- * if, for example, you pass an component mask for the single
- * $x$ velocity and this object represents an FE_RaviartThomas
- * object, then the single component you selected is part
- * of a larger block and consequently there is no block mask that
- * would represent it. The function will then produce an exception.
- *
- * @note This function is the equivalent of
- * FiniteElement::component_mask() with the same arguments.
- * It verifies that it gets the same result from every one
- * of the elements that are stored in this FECollection. If
- * this is not the case, it throws an exception.
- *
- * @param component_mask The mask that selects individual components of the finite
- * element
- * @return A mask that selects those blocks corresponding to the selected
- * blocks of the input argument.
- */
+ * Given a component mask (see @ref GlossComponentMask "this glossary
+ * entry"), produce a block mask (see @ref GlossBlockMask "this glossary
+ * entry") that represents the blocks that correspond to the components
+ * selected in the input argument. This is essentially a conversion
+ * operator from ComponentMask to BlockMask.
+ *
+ * @note This function will only succeed if the components referenced by
+ * the argument encompasses complete blocks. In other words, if, for
+ * example, you pass an component mask for the single $x$ velocity and
+ * this object represents an FE_RaviartThomas object, then the single
+ * component you selected is part of a larger block and consequently there
+ * is no block mask that would represent it. The function will then
+ * produce an exception.
+ *
+ * @note This function is the equivalent of
+ * FiniteElement::component_mask() with the same arguments. It verifies
+ * that it gets the same result from every one of the elements that are
+ * stored in this FECollection. If this is not the case, it throws an
+ * exception.
+ *
+ * @param component_mask The mask that selects individual components of
+ * the finite element @return A mask that selects those blocks
+ * corresponding to the selected blocks of the input argument.
+ */
BlockMask
block_mask (const ComponentMask &component_mask) const;
private:
/**
- * Array of pointers to the finite
- * elements stored by this collection.
+ * Array of pointers to the finite elements stored by this collection.
*/
std::vector<std_cxx11::shared_ptr<const FiniteElement<dim,spacedim> > > finite_elements;
};
* Base class for the <tt>hp::FE*Values</tt> classes, storing the data
* that is common to them. The main task of this class is to provide a
* table where for every combination of finite element, mapping, and
- * quadrature object from their corresponding collection objects there
- * is a matching ::FEValues, ::FEFaceValues, or ::FESubfaceValues
- * object. To make things more efficient, however, these FE*Values
- * objects are only created once requested (lazy allocation).
+ * quadrature object from their corresponding collection objects there is
+ * a matching ::FEValues, ::FEFaceValues, or ::FESubfaceValues object. To
+ * make things more efficient, however, these FE*Values objects are only
+ * created once requested (lazy allocation).
*
- * The first template parameter denotes the space dimension we are in,
- * the second the dimensionality of the object that we integrate on,
- * i.e. for usual @p hp::FEValues it is equal to the first one, while
- * for face integration it is one less. The third template parameter
- * indicates the type of underlying non-hp FE*Values base type,
- * i.e. it could either be dealii::FEValues, dealii::FEFaceValues, or
- * dealii::FESubfaceValues.
+ * The first template parameter denotes the space dimension we are in, the
+ * second the dimensionality of the object that we integrate on, i.e. for
+ * usual @p hp::FEValues it is equal to the first one, while for face
+ * integration it is one less. The third template parameter indicates the
+ * type of underlying non-hp FE*Values base type, i.e. it could either be
+ * dealii::FEValues, dealii::FEFaceValues, or dealii::FESubfaceValues.
*
* @ingroup hp
*
get_fe_collection () const;
/**
- * Get a reference to the collection of mapping objects used
- * here.
+ * Get a reference to the collection of mapping objects used here.
*/
const dealii::hp::MappingCollection<dim,FEValues::space_dimension> &
get_mapping_collection () const;
/**
- * Get a reference to the collection of quadrature objects used
- * here.
+ * Get a reference to the collection of quadrature objects used here.
*/
const dealii::hp::QCollection<q_dim> &
get_quadrature_collection () const;
private:
/**
* A table in which we store pointers to fe_values objects for different
- * finite element, mapping, and quadrature objects from our
- * collection. The first index indicates the index of the finite element
- * within the fe_collection, the second the index of the mapping within
- * the mapping collection, and the last one the index of the quadrature
- * formula within the q_collection.
+ * finite element, mapping, and quadrature objects from our collection.
+ * The first index indicates the index of the finite element within the
+ * fe_collection, the second the index of the mapping within the mapping
+ * collection, and the last one the index of the quadrature formula
+ * within the q_collection.
*
* Initially, all entries have zero pointers, and we will allocate them
* lazily as needed in select_fe_values().
{
/**
- * An hp equivalent of the ::FEValues class. See the step-27
- * tutorial program for examples of use.
+ * An hp equivalent of the ::FEValues class. See the step-27 tutorial
+ * program for examples of use.
*
- * The idea of this class is as follows: when one assembled matrices in the hp
- * finite element method, there may be different finite elements on different
- * cells, and consequently one may also want to use different quadrature
- * formulas for different cells. On the other hand, the ::FEValues efficiently
- * handles pre-evaluating whatever information is necessary for a single
- * finite element and quadrature object. This class brings these concepts
- * together: it provides a "collection" of ::FEValues objects.
+ * The idea of this class is as follows: when one assembled matrices in the
+ * hp finite element method, there may be different finite elements on
+ * different cells, and consequently one may also want to use different
+ * quadrature formulas for different cells. On the other hand, the
+ * ::FEValues efficiently handles pre-evaluating whatever information is
+ * necessary for a single finite element and quadrature object. This class
+ * brings these concepts together: it provides a "collection" of ::FEValues
+ * objects.
*
- * Upon construction, one passes not one finite element and quadrature object
- * (and possible a mapping), but a whole collection of type hp::FECollection
- * and hp::QCollection. Later on, when one sits on a concrete cell, one would
- * call the reinit() function for this particular cell, just as one does for a
- * regular ::FEValues object. The difference is that this time, the reinit()
- * function looks up the active_fe_index of that cell, if necessary creates a
- * ::FEValues object that matches the finite element and quadrature formulas
- * with that particular index in their collections, and then re-initializes it
- * for the current cell. The ::FEValues object that then fits the finite
- * element and quadrature formula for the current cell can then be accessed
- * using the get_present_fe_values() function, and one would work with it just
- * like with any ::FEValues object for non-hp DoF handler objects.
+ * Upon construction, one passes not one finite element and quadrature
+ * object (and possible a mapping), but a whole collection of type
+ * hp::FECollection and hp::QCollection. Later on, when one sits on a
+ * concrete cell, one would call the reinit() function for this particular
+ * cell, just as one does for a regular ::FEValues object. The difference is
+ * that this time, the reinit() function looks up the active_fe_index of
+ * that cell, if necessary creates a ::FEValues object that matches the
+ * finite element and quadrature formulas with that particular index in
+ * their collections, and then re-initializes it for the current cell. The
+ * ::FEValues object that then fits the finite element and quadrature
+ * formula for the current cell can then be accessed using the
+ * get_present_fe_values() function, and one would work with it just like
+ * with any ::FEValues object for non-hp DoF handler objects.
*
* The reinit() functions have additional arguments with default values. If
* not specified, the function takes the index into the hp::FECollection,
- * hp::QCollection, and hp::MappingCollection objects from the active_fe_index
- * of the cell, as explained above. However, one can also select different
- * indices for a current cell. For example, by specifying a different index
- * into the hp::QCollection class, one does not need to sort the quadrature
- * objects in the quadrature collection so that they match one-to-one the
- * order of finite element objects in the FE collection (even though choosing
- * such an order is certainly convenient).
+ * hp::QCollection, and hp::MappingCollection objects from the
+ * active_fe_index of the cell, as explained above. However, one can also
+ * select different indices for a current cell. For example, by specifying a
+ * different index into the hp::QCollection class, one does not need to sort
+ * the quadrature objects in the quadrature collection so that they match
+ * one-to-one the order of finite element objects in the FE collection (even
+ * though choosing such an order is certainly convenient).
*
- * Note that ::FEValues objects are created on the fly, i.e. only as they are
- * needed. This ensures that we do not create objects for every combination of
- * finite element, quadrature formula and mapping, but only those that will
- * actually be needed.
+ * Note that ::FEValues objects are created on the fly, i.e. only as they
+ * are needed. This ensures that we do not create objects for every
+ * combination of finite element, quadrature formula and mapping, but only
+ * those that will actually be needed.
*
* This class has not yet been implemented for the use in the codimension
* one case (<tt>spacedim != dim </tt>).
* Reinitialize the object for the given cell.
*
* After the call, you can get an FEValues object using the
- * get_present_fe_values() function that corresponds to the present
- * cell. For this FEValues object, we use the additional arguments
- * described below to determine which finite element, mapping, and
- * quadrature formula to use. They are order in such a way that the
- * arguments one may want to change most frequently come first. The rules
- * for these arguments are as follows:
+ * get_present_fe_values() function that corresponds to the present cell.
+ * For this FEValues object, we use the additional arguments described
+ * below to determine which finite element, mapping, and quadrature
+ * formula to use. They are order in such a way that the arguments one may
+ * want to change most frequently come first. The rules for these
+ * arguments are as follows:
*
* If the @p fe_index argument to this function is left at its default
* value, then we use that finite element within the hp::FECollection
/**
- * This is the equivalent of the hp::FEValues class but for face integrations,
- * i.e. it is to hp::FEValues what ::FEFaceValues is to ::FEValues.
+ * This is the equivalent of the hp::FEValues class but for face
+ * integrations, i.e. it is to hp::FEValues what ::FEFaceValues is to
+ * ::FEValues.
*
* The same comments apply as in the documentation of the hp::FEValues
* class. However, it is important to note that it is here more common that
* Reinitialize the object for the given cell and face.
*
* After the call, you can get an FEFaceValues object using the
- * get_present_fe_values() function that corresponds to the present
- * cell. For this FEFaceValues object, we use the additional arguments
- * described below to determine which finite element, mapping, and
- * quadrature formula to use. They are order in such a way that the
- * arguments one may want to change most frequently come first. The rules
- * for these arguments are as follows:
+ * get_present_fe_values() function that corresponds to the present cell.
+ * For this FEFaceValues object, we use the additional arguments described
+ * below to determine which finite element, mapping, and quadrature
+ * formula to use. They are order in such a way that the arguments one may
+ * want to change most frequently come first. The rules for these
+ * arguments are as follows:
*
* If the @p fe_index argument to this function is left at its default
* value, then we use that finite element within the hp::FECollection
/**
- * This class implements for subfaces what hp::FEFaceValues does for
- * faces. See there for further documentation.
+ * This class implements for subfaces what hp::FEFaceValues does for faces.
+ * See there for further documentation.
*
* @ingroup hp hpcollection
* @author Wolfgang Bangerth, 2003
* Reinitialize the object for the given cell, face, and subface.
*
* After the call, you can get an FESubfaceValues object using the
- * get_present_fe_values() function that corresponds to the present
- * cell. For this FESubfaceValues object, we use the additional arguments
+ * get_present_fe_values() function that corresponds to the present cell.
+ * For this FESubfaceValues object, we use the additional arguments
* described below to determine which finite element, mapping, and
* quadrature formula to use. They are order in such a way that the
* arguments one may want to change most frequently come first. The rules
* This class implements a collection of mapping objects in the same way as
* the hp::FECollection implements a collection of finite element classes.
*
- * It implements the concepts stated in the @ref hpcollection module described
- * in the doxygen documentation.
+ * It implements the concepts stated in the @ref hpcollection module
+ * described in the doxygen documentation.
*
- * Although it is recommended to supply an appropriate mapping for
- * each finite element kind used in a hp-computation, the
- * MappingCollection class implements a conversion constructor from a
- * single mapping. Therefore it is possible to offer only a single
- * mapping to the hp::FEValues class instead of a
- * hp::MappingCollection. This is for the convenience of the user, as
- * many simple geometries do not require different mappings along the
- * boundary to achieve optimal convergence rates. Hence providing a
- * single mapping object will usually suffice. See the hp::FEValues
- * class for the rules which mapping will be selected for a given
- * cell.
+ * Although it is recommended to supply an appropriate mapping for each
+ * finite element kind used in a hp-computation, the MappingCollection class
+ * implements a conversion constructor from a single mapping. Therefore it
+ * is possible to offer only a single mapping to the hp::FEValues class
+ * instead of a hp::MappingCollection. This is for the convenience of the
+ * user, as many simple geometries do not require different mappings along
+ * the boundary to achieve optimal convergence rates. Hence providing a
+ * single mapping object will usually suffice. See the hp::FEValues class
+ * for the rules which mapping will be selected for a given cell.
*
* @ingroup hp hpcollection
*
{
public:
/**
- * Default constructor. Leads
- * to an empty collection that
- * can later be filled using
- * push_back().
+ * Default constructor. Leads to an empty collection that can later be
+ * filled using push_back().
*/
MappingCollection ();
/**
- * Conversion constructor. This
- * constructor creates a
- * MappingCollection from a
- * single mapping. More
- * mappings can be added with
- * push_back(), if desired,
- * though it would probably be
- * clearer to add all mappings
- * the same way.
+ * Conversion constructor. This constructor creates a MappingCollection
+ * from a single mapping. More mappings can be added with push_back(), if
+ * desired, though it would probably be clearer to add all mappings the
+ * same way.
*/
explicit MappingCollection (const Mapping<dim,spacedim> &mapping);
MappingCollection (const MappingCollection<dim,spacedim> &mapping_collection);
/**
- * Adds a new mapping to the
- * MappingCollection. The
- * mappings have to be added in
- * the order of the
- * active_fe_indices. Thus the
- * reference to the mapping
- * object for active_fe_index 0
- * has to be added first,
- * followed by the mapping
- * object for active_fe_index
- * 1.
+ * Adds a new mapping to the MappingCollection. The mappings have to be
+ * added in the order of the active_fe_indices. Thus the reference to the
+ * mapping object for active_fe_index 0 has to be added first, followed by
+ * the mapping object for active_fe_index 1.
*/
void push_back (const Mapping<dim,spacedim> &new_mapping);
/**
- * Returns the mapping object
- * which was specified by the
- * user for the active_fe_index
- * which is provided as a
- * parameter to this method.
+ * Returns the mapping object which was specified by the user for the
+ * active_fe_index which is provided as a parameter to this method.
*
- * @pre @p index must be
- * between zero and the number
- * of elements of the
+ * @pre @p index must be between zero and the number of elements of the
* collection.
*/
const Mapping<dim,spacedim> &
operator[] (const unsigned int index) const;
/**
- * Returns the number of
- * mapping objects stored in
- * this container.
+ * Returns the number of mapping objects stored in this container.
*/
unsigned int size () const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
private:
/**
- * The real container, which stores
- * pointers to the different Mapping
+ * The real container, which stores pointers to the different Mapping
* objects.
*/
std::vector<std_cxx11::shared_ptr<const Mapping<dim,spacedim> > > mappings;
/**
- * In order to avoid creation of static MappingQ1 objects at several
- * places in the library, this class
- * defines a static collection of mappings with a single
- * MappingQ1 mapping object once and for all places where it is
+ * In order to avoid creation of static MappingQ1 objects at several places
+ * in the library, this class defines a static collection of mappings with a
+ * single MappingQ1 mapping object once and for all places where it is
* needed.
*/
template<int dim, int spacedim=dim>
{
public:
/**
- * The publicly available
- * static Q1 mapping collection
- * object.
+ * The publicly available static Q1 mapping collection object.
*/
static MappingCollection<dim,spacedim> mapping_collection;
};
namespace hp
{
/**
- * This class implements a collection of quadrature objects in the same way as
- * the hp::FECollection implements a collection of finite element classes.
+ * This class implements a collection of quadrature objects in the same way
+ * as the hp::FECollection implements a collection of finite element
+ * classes.
*
- * It implements the concepts stated in the @ref hpcollection module described
- * in the doxygen documentation.
+ * It implements the concepts stated in the @ref hpcollection module
+ * described in the doxygen documentation.
*
* @ingroup hp hpcollection
*
{
public:
/**
- * Default constructor. Leads
- * to an empty collection that
- * can later be filled using
- * push_back().
+ * Default constructor. Leads to an empty collection that can later be
+ * filled using push_back().
*/
QCollection ();
/**
- * Conversion constructor. This
- * constructor creates a
- * QCollection from a single
- * quadrature rule. More
- * quadrature formulas can be
- * added with push_back(), if
- * desired, though it would
- * probably be clearer to add
- * all mappings the same way.
+ * Conversion constructor. This constructor creates a QCollection from a
+ * single quadrature rule. More quadrature formulas can be added with
+ * push_back(), if desired, though it would probably be clearer to add all
+ * mappings the same way.
*/
explicit QCollection (const Quadrature<dim> &quadrature);
QCollection (const QCollection<dim> &q_collection);
/**
- * Adds a new quadrature rule
- * to the QCollection. The
- * quadrature rules have to be
- * added in the same order as
- * for the FECollection for
- * which this quadrature rule
- * collection is meant. Thus
- * the reference to the
- * quadrature rule for
- * active_fe_index 0 has to be
- * added first, followed by the
- * quadrature rule for
- * active_fe_index 1.
+ * Adds a new quadrature rule to the QCollection. The quadrature rules
+ * have to be added in the same order as for the FECollection for which
+ * this quadrature rule collection is meant. Thus the reference to the
+ * quadrature rule for active_fe_index 0 has to be added first, followed
+ * by the quadrature rule for active_fe_index 1.
*
- * This class creates a copy of
- * the given quadrature object,
- * i.e. you can do things like
- * <tt>push_back(QGauss<dim>(3));</tt>. The
- * internal copy is later
- * destroyed by this object
- * upon destruction of the
- * entire collection.
+ * This class creates a copy of the given quadrature object, i.e. you can
+ * do things like <tt>push_back(QGauss<dim>(3));</tt>. The internal copy
+ * is later destroyed by this object upon destruction of the entire
+ * collection.
*/
void push_back (const Quadrature<dim> &new_quadrature);
/**
- * Returns a reference to the
- * quadrature rule specified by the
- * argument.
+ * Returns a reference to the quadrature rule specified by the argument.
*
- * @pre @p index must be between zero
- * and the number of elements of the
+ * @pre @p index must be between zero and the number of elements of the
* collection.
*/
const Quadrature<dim> &
operator[] (const unsigned int index) const;
/**
- * Returns the number of
- * quadrature pointers stored
- * in this object.
+ * Returns the number of quadrature pointers stored in this object.
*/
unsigned int size () const;
/**
- * Return the maximum number of
- * quadrature points over all
- * the elements of the
- * collection. This is mostly
- * useful to initialize arrays
- * to allocate the maxmimum
- * amount of memory that may be
- * used when re-sizing later on
- * to a articular quadrature
- * formula from within this
- * collection.
+ * Return the maximum number of quadrature points over all the elements of
+ * the collection. This is mostly useful to initialize arrays to allocate
+ * the maxmimum amount of memory that may be used when re-sizing later on
+ * to a articular quadrature formula from within this collection.
*/
unsigned int max_n_quadrature_points () const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
private:
/**
- * The real container, which stores
- * pointers to the different quadrature
+ * The real container, which stores pointers to the different quadrature
* objects.
*/
std::vector<std_cxx11::shared_ptr<const Quadrature<dim> > > quadratures;
namespace LocalIntegrators
{
/**
- * @brief Local integrators related to advection along a vector field and its DG formulations
+ * @brief Local integrators related to advection along a vector field and
+ * its DG formulations
*
* All advection operators depend on an advection velocity denoted by
- * <b>w</b> in the formulas below. It is denoted as <tt>velocity</tt>
- * in the parameter lists.
+ * <b>w</b> in the formulas below. It is denoted as <tt>velocity</tt> in the
+ * parameter lists.
*
- * The functions cell_matrix() and both upwind_value_matrix() are
- * taking the equation in weak form, that is, the directional
- * derivative is on the test function.
+ * The functions cell_matrix() and both upwind_value_matrix() are taking the
+ * equation in weak form, that is, the directional derivative is on the test
+ * function.
*
* @ingroup Integrators
* @author Guido Kanschat
namespace Advection
{
/**
- * Advection along the direction <b>w</b> in weak form
- * with derivative on the test function
- * \f[
- * m_{ij} = \int_Z u_j\,(\mathbf w \cdot \nabla) v_i \, dx.
- * \f]
+ * Advection along the direction <b>w</b> in weak form with derivative on
+ * the test function \f[ m_{ij} = \int_Z u_j\,(\mathbf w \cdot \nabla) v_i
+ * \, dx. \f]
*
- * The FiniteElement in <tt>fe</tt> may be scalar or vector valued. In
- * the latter case, the advection operator is applied to each component
+ * The FiniteElement in <tt>fe</tt> may be scalar or vector valued. In the
+ * latter case, the advection operator is applied to each component
* separately.
*
* @param M: The advection matrix obtained as result
* @param fe: The FEValues object describing the local trial function
* space. #update_values and #update_gradients, and #update_JxW_values
* must be set.
- * @param fetest: The FEValues object describing the local test
- * function space. #update_values and #update_gradients must be set.
+ * @param fetest: The FEValues object describing the local test function
+ * space. #update_values and #update_gradients must be set.
* @param velocity: The advection velocity, a vector of dimension
- * <tt>dim</tt>. Each component may either contain a vector of length
- * one, in which case a constant velocity is assumed, or a vector with
- * as many entries as quadrature points if the velocity is not constant.
+ * <tt>dim</tt>. Each component may either contain a vector of length one,
+ * in which case a constant velocity is assumed, or a vector with as many
+ * entries as quadrature points if the velocity is not constant.
* @param factor is an optional multiplication factor for the result.
*
* @author Guido Kanschat
/**
* Advection residual operator in strong form
*
- * \f[
- * r_i = \int_Z (\mathbf w \cdot \nabla)u\, v_i \, dx.
- * \f]
+ * \f[ r_i = \int_Z (\mathbf w \cdot \nabla)u\, v_i \, dx. \f]
*/
template <int dim>
inline void
* Vector-valued advection residual operator in strong form
*
*
- * \f[
- * r_i = \int_Z \bigl((\mathbf w \cdot \nabla) \mathbf u\bigr) \cdot\mathbf v_i \, dx.
- * \f]
+ * \f[ r_i = \int_Z \bigl((\mathbf w \cdot \nabla) \mathbf u\bigr)
+ * \cdot\mathbf v_i \, dx. \f]
*/
template <int dim>
inline void
}
/**
- * Upwind flux at the boundary
- * for weak advection
- * operator. This is the value of
- * the trial function at the
- * outflow boundary and zero
- * else:
+ * Upwind flux at the boundary for weak advection operator. This is the
+ * value of the trial function at the outflow boundary and zero else:
* @f[
* a_{ij} = \int_{\partial\Omega}
* [\mathbf w\cdot\mathbf n]_+
* u_i v_j \, ds
* @f]
*
- * The <tt>velocity</tt> is
- * provided as a VectorSlice,
- * having <tt>dim</tt> vectors,
- * one for each velocity
- * component. Each of the
- * vectors must either have only
- * a single entry, if t he
- * advection velocity is
- * constant, or have an entry
- * for each quadrature point.
+ * The <tt>velocity</tt> is provided as a VectorSlice, having <tt>dim</tt>
+ * vectors, one for each velocity component. Each of the vectors must
+ * either have only a single entry, if t he advection velocity is
+ * constant, or have an entry for each quadrature point.
*
- * The finite element can have
- * several components, in which
- * case each component is
- * advected by the same velocity.
+ * The finite element can have several components, in which case each
+ * component is advected by the same velocity.
*/
template <int dim>
void upwind_value_matrix(
}
/**
- * Upwind flux in the interior
- * for weak advection
- * operator. Matrix entries
- * correspond to the upwind value
- * of the trial function, multiplied
- * by the jump of the test
- * functions
- * @f[
- * a_{ij} = \int_F \left|\mathbf w
- * \cdot \mathbf n\right|
- * u^\uparrow
- * (v^\uparrow-v^\downarrow)
- * \,ds
- * @f]
- *
- * The <tt>velocity</tt> is
- * provided as a VectorSlice,
- * having <tt>dim</tt> vectors,
- * one for each velocity
- * component. Each of the
- * vectors must either have only
- * a single entry, if t he
- * advection velocity is
- * constant, or have an entry
- * for each quadrature point.
- *
- * The finite element can have
- * several components, in which
- * case each component is
- * advected the same way.
- */
+ * Upwind flux in the interior for weak advection operator. Matrix entries
+ * correspond to the upwind value of the trial function, multiplied by the
+ * jump of the test functions
+ * @f[
+ * a_{ij} = \int_F \left|\mathbf w
+ * \cdot \mathbf n\right|
+ * u^\uparrow
+ * (v^\uparrow-v^\downarrow)
+ * \,ds
+ * @f]
+ *
+ * The <tt>velocity</tt> is provided as a VectorSlice, having <tt>dim</tt>
+ * vectors, one for each velocity component. Each of the vectors must
+ * either have only a single entry, if t he advection velocity is
+ * constant, or have an entry for each quadrature point.
+ *
+ * The finite element can have several components, in which case each
+ * component is advected the same way.
+ */
template <int dim>
void upwind_value_matrix (
FullMatrix<double> &M11,
namespace LocalIntegrators
{
/**
- * @brief Local integrators related to the divergence operator and its trace.
+ * @brief Local integrators related to the divergence operator and its
+ * trace.
*
* @ingroup Integrators
* @author Guido Kanschat
* Auxiliary function. Computes the grad-div-operator from a set of
* Hessians.
*
- * @note The third tensor argument is not used in two dimensions and
- * can for instance duplicate one of the previous.
+ * @note The third tensor argument is not used in two dimensions and can
+ * for instance duplicate one of the previous.
*
* @author Guido Kanschat
* @date 2011
/**
- * Cell matrix for divergence. The derivative is on the trial
- * function.
- * \f[
- * \int_Z v\nabla \cdot \mathbf u \,dx
- * \f]
- * This is the strong divergence operator and the trial
- * space should be at least <b>H</b><sup>div</sup>. The test functions
- * may be discontinuous.
+ * Cell matrix for divergence. The derivative is on the trial function.
+ * \f[ \int_Z v\nabla \cdot \mathbf u \,dx \f] This is the strong
+ * divergence operator and the trial space should be at least
+ * <b>H</b><sup>div</sup>. The test functions may be discontinuous.
*
* @author Guido Kanschat
* @date 2011
}
/**
- * The residual of the divergence operator in strong form.
- * \f[
- * \int_Z v\nabla \cdot \mathbf u \,dx
- * \f]
- * This is the strong divergence operator and the trial
- * space should be at least <b>H</b><sup>div</sup>. The test functions
- * may be discontinuous.
+ * The residual of the divergence operator in strong form. \f[ \int_Z
+ * v\nabla \cdot \mathbf u \,dx \f] This is the strong divergence operator
+ * and the trial space should be at least <b>H</b><sup>div</sup>. The test
+ * functions may be discontinuous.
*
- * The function cell_matrix() is the Frechet derivative of this function with respect
- * to the test functions.
+ * The function cell_matrix() is the Frechet derivative of this function
+ * with respect to the test functions.
*
* @author Guido Kanschat
* @date 2011
/**
- * The residual of the divergence operator in weak form.
- * \f[
- * - \int_Z \nabla v \cdot \mathbf u \,dx
- * \f]
- * This is the weak divergence operator and the test
- * space should be at least <b>H</b><sup>1</sup>. The trial functions
- * may be discontinuous.
+ * The residual of the divergence operator in weak form. \f[ - \int_Z
+ * \nabla v \cdot \mathbf u \,dx \f] This is the weak divergence operator
+ * and the test space should be at least <b>H</b><sup>1</sup>. The trial
+ * functions may be discontinuous.
*
- * @todo Verify: The function cell_matrix() is the Frechet derivative of this function with respect
- * to the test functions.
+ * @todo Verify: The function cell_matrix() is the Frechet derivative of
+ * this function with respect to the test functions.
*
* @author Guido Kanschat
* @date 2013
/**
- * Cell matrix for gradient. The derivative is on the trial function.
- * \f[
- * \int_Z \nabla u \cdot \mathbf v\,dx
- * \f]
+ * Cell matrix for gradient. The derivative is on the trial function. \f[
+ * \int_Z \nabla u \cdot \mathbf v\,dx \f]
*
- * This is the strong gradient and the trial space should be at least
- * in <i>H</i><sup>1</sup>. The test functions can be discontinuous.
+ * This is the strong gradient and the trial space should be at least in
+ * <i>H</i><sup>1</sup>. The test functions can be discontinuous.
*
* @author Guido Kanschat
* @date 2011
}
/**
- * The residual of the gradient operator in strong form.
- * \f[
- * \int_Z \mathbf v\cdot\nabla u \,dx
- * \f]
- * This is the strong gradient operator and the trial
- * space should be at least <b>H</b><sup>1</sup>. The test functions
- * may be discontinuous.
+ * The residual of the gradient operator in strong form. \f[ \int_Z
+ * \mathbf v\cdot\nabla u \,dx \f] This is the strong gradient operator
+ * and the trial space should be at least <b>H</b><sup>1</sup>. The test
+ * functions may be discontinuous.
*
- * The function gradient_matrix() is the Frechet derivative of this function with respect to the test functions.
+ * The function gradient_matrix() is the Frechet derivative of this
+ * function with respect to the test functions.
*
* @author Guido Kanschat
* @date 2011
}
/**
- * The residual of the gradient operator in weak form.
- * \f[
- * -\int_Z \nabla\cdot \mathbf v u \,dx
- * \f]
- * This is the weak gradient operator and the test
- * space should be at least <b>H</b><sup>div</sup>. The trial functions
- * may be discontinuous.
+ * The residual of the gradient operator in weak form. \f[ -\int_Z
+ * \nabla\cdot \mathbf v u \,dx \f] This is the weak gradient operator and
+ * the test space should be at least <b>H</b><sup>div</sup>. The trial
+ * functions may be discontinuous.
*
- * @todo Verify: The function gradient_matrix() is the Frechet derivative of this function with respect to the test functions.
+ * @todo Verify: The function gradient_matrix() is the Frechet derivative
+ * of this function with respect to the test functions.
*
* @author Guido Kanschat
* @date 2013
}
/**
- * The trace of the divergence operator, namely the product of the
- * normal component of the vector valued trial space and the test
- * space.
+ * The trace of the divergence operator, namely the product of the normal
+ * component of the vector valued trial space and the test space.
* @f[ \int_F (\mathbf u\cdot \mathbf n) v \,ds @f]
*
* @author Guido Kanschat
}
/**
- * The trace of the divergence
- * operator, namely the product
- * of the normal component of the
- * vector valued trial space and
- * the test space.
+ * The trace of the divergence operator, namely the product of the normal
+ * component of the vector valued trial space and the test space.
* @f[
* \int_F (\mathbf u\cdot \mathbf n) v \,ds
* @f]
}
/**
- * The trace of the gradient
- * operator, namely the product
- * of the normal component of the
- * vector valued test space and
- * the trial space.
+ * The trace of the gradient operator, namely the product of the normal
+ * component of the vector valued test space and the trial space.
* @f[
* \int_F u (\mathbf v\cdot \mathbf n) \,ds
* @f]
}
/**
- * The trace of the divergence
- * operator, namely the product
- * of the jump of the normal component of the
- * vector valued trial function and
- * the mean value of the test function.
+ * The trace of the divergence operator, namely the product of the jump of
+ * the normal component of the vector valued trial function and the mean
+ * value of the test function.
* @f[
* \int_F (\mathbf u_1\cdot \mathbf n_1 + \mathbf u_2 \cdot \mathbf n_2) \frac{v_1+v_2}{2} \,ds
* @f]
}
/**
- * The <i>L</i><sup>2</sup>-norm of the divergence over the
- * quadrature set determined by the FEValuesBase object.
+ * The <i>L</i><sup>2</sup>-norm of the divergence over the quadrature set
+ * determined by the FEValuesBase object.
*
- * The vector is expected to consist of dim vectors of length
- * equal to the number of quadrature points. The number of
- * components of the finite element has to be equal to the space
- * dimension.
+ * The vector is expected to consist of dim vectors of length equal to the
+ * number of quadrature points. The number of components of the finite
+ * element has to be equal to the space dimension.
*
* @author Guido Kanschat
* @date 2013
namespace Elasticity
{
/**
- * The linear elasticity operator in weak form, namely double
- * contraction of symmetric gradients.
+ * The linear elasticity operator in weak form, namely double contraction
+ * of symmetric gradients.
*
- * \f[
- * \int_Z \varepsilon(u): \varepsilon(v)\,dx
- * \f]
+ * \f[ \int_Z \varepsilon(u): \varepsilon(v)\,dx \f]
*/
template <int dim>
inline void cell_matrix (
/**
* Vector-valued residual operator for linear elasticity in weak form
*
- * \f[
- * - \int_Z \varepsilon(u): \varepsilon(v) \,dx
- * \f]
+ * \f[ - \int_Z \varepsilon(u): \varepsilon(v) \,dx \f]
*/
template <int dim, typename number>
inline void
/**
- * The weak boundary condition of Nitsche type for linear
- * elasticity:
+ * The weak boundary condition of Nitsche type for linear elasticity:
* @f[
* \int_F \Bigl(\gamma (u-g) \cdot v - n^T \epsilon(u) v - (u-g) \epsilon(v) n^T\Bigr)\;ds.
* @f]
}
/**
- * Weak boundary condition for the elasticity operator by Nitsche,
- * namely on the face <i>F</i> the vector
+ * Weak boundary condition for the elasticity operator by Nitsche, namely
+ * on the face <i>F</i> the vector
* @f[
* \int_F \Bigl(\gamma (u-g) \cdot v - n^T \epsilon(u) v - (u-g) \epsilon(v) n^T\Bigr)\;ds.
* @f]
*
- * Here, <i>u</i> is the finite element function whose values and
- * gradient are given in the arguments <tt>input</tt> and
- * <tt>Dinput</tt>, respectively. <i>g</i> is the inhomogeneous
- * boundary value in the argument <tt>data</tt>. $n$ is the outer
- * normal vector and $\gamma$ is the usual penalty parameter.
+ * Here, <i>u</i> is the finite element function whose values and gradient
+ * are given in the arguments <tt>input</tt> and <tt>Dinput</tt>,
+ * respectively. <i>g</i> is the inhomogeneous boundary value in the
+ * argument <tt>data</tt>. $n$ is the outer normal vector and $\gamma$ is
+ * the usual penalty parameter.
*
* @author Guido Kanschat
* @date 2013
}
/**
- * Homogeneous weak boundary condition for the elasticity operator by Nitsche,
- * namely on the face <i>F</i> the vector
+ * Homogeneous weak boundary condition for the elasticity operator by
+ * Nitsche, namely on the face <i>F</i> the vector
* @f[
* \int_F \Bigl(\gamma u \cdot v - n^T \epsilon(u) v - u \epsilon(v) n^T\Bigr)\;ds.
* @f]
*
- * Here, <i>u</i> is the finite element function whose values and
- * gradient are given in the arguments <tt>input</tt> and
- * <tt>Dinput</tt>, respectively. $n$ is the outer
- * normal vector and $\gamma$ is the usual penalty parameter.
+ * Here, <i>u</i> is the finite element function whose values and gradient
+ * are given in the arguments <tt>input</tt> and <tt>Dinput</tt>,
+ * respectively. $n$ is the outer normal vector and $\gamma$ is the usual
+ * penalty parameter.
*
* @author Guido Kanschat
* @date 2013
}
/**
- * The interior penalty flux
- * for symmetric gradients.
+ * The interior penalty flux for symmetric gradients.
*/
template <int dim>
inline void ip_matrix (
namespace L2
{
/**
- * The mass matrix for scalar or vector values finite elements.
- * \f[
- * \int_Z uv\,dx \quad \text{or} \quad \int_Z \mathbf u\cdot \mathbf v\,dx
- * \f]
+ * The mass matrix for scalar or vector values finite elements. \f[ \int_Z
+ * uv\,dx \quad \text{or} \quad \int_Z \mathbf u\cdot \mathbf v\,dx \f]
*
- * Likewise, this term can be used on faces, where it computes the integrals
- * \f[
- * \int_F uv\,ds \quad \text{or} \quad \int_F \mathbf u\cdot \mathbf v\,ds
- * \f]
+ * Likewise, this term can be used on faces, where it computes the
+ * integrals \f[ \int_F uv\,ds \quad \text{or} \quad \int_F \mathbf u\cdot
+ * \mathbf v\,ds \f]
*
* @author Guido Kanschat
* @date 2008, 2009, 2010
/**
* The weighted mass matrix for scalar or vector values finite elements.
- * \f[
- * \int_Z \omega(x) uv\,dx \quad \text{or} \quad \int_Z \omega(x) \mathbf u\cdot \mathbf v\,dx
- * \f]
+ * \f[ \int_Z \omega(x) uv\,dx \quad \text{or} \quad \int_Z \omega(x)
+ * \mathbf u\cdot \mathbf v\,dx \f]
*
- * Likewise, this term can be used on faces, where it computes the integrals
- * \f[
- * \int_F \omega(x) uv\,ds \quad \text{or} \quad \int_F \omega(x) \mathbf u\cdot \mathbf v\,ds
- * \f]
+ * Likewise, this term can be used on faces, where it computes the
+ * integrals \f[ \int_F \omega(x) uv\,ds \quad \text{or} \quad \int_F
+ * \omega(x) \mathbf u\cdot \mathbf v\,ds \f]
*
- * The size of the vector <tt>weights</tt> must be equal to the
- * number of quadrature points in the finite element.
+ * The size of the vector <tt>weights</tt> must be equal to the number of
+ * quadrature points in the finite element.
*
* @author Guido Kanschat
* @date 2014
/**
* <i>L<sup>2</sup></i>-inner product for scalar functions.
*
- * \f[
- * \int_Z fv\,dx \quad \text{or} \quad \int_F fv\,ds
- * \f]
+ * \f[ \int_Z fv\,dx \quad \text{or} \quad \int_F fv\,ds \f]
*
* @author Guido Kanschat
* @date 2008, 2009, 2010
}
/**
- * <i>L<sup>2</sup></i>-inner product for a slice of a vector valued
- * right hand side.
- * \f[
- * \int_Z \mathbf f\cdot \mathbf v\,dx
- * \quad \text{or} \quad
- * \int_F \mathbf f\cdot \mathbf v\,ds
- * \f]
+ * <i>L<sup>2</sup></i>-inner product for a slice of a vector valued right
+ * hand side. \f[ \int_Z \mathbf f\cdot \mathbf v\,dx \quad \text{or}
+ * \quad \int_F \mathbf f\cdot \mathbf v\,ds \f]
*
* @author Guido Kanschat
* @date 2008, 2009, 2010
}
/**
- * The jump matrix between two cells for scalar or vector values
- * finite elements. Note that the factor $\gamma$ can be used to
- * implement weighted jumps.
- * \f[
- * \int_F [\gamma u][\gamma v]\,ds
- * \quad \text{or}
- * \int_F [\gamma \mathbf u]\cdot [\gamma \mathbf v]\,ds
- * \f]
+ * The jump matrix between two cells for scalar or vector values finite
+ * elements. Note that the factor $\gamma$ can be used to implement
+ * weighted jumps. \f[ \int_F [\gamma u][\gamma v]\,ds \quad \text{or}
+ * \int_F [\gamma \mathbf u]\cdot [\gamma \mathbf v]\,ds \f]
*
- * Using appropriate weights, this term can be used to penalize
- * violation of conformity in <i>H<sup>1</sup></i>.
+ * Using appropriate weights, this term can be used to penalize violation
+ * of conformity in <i>H<sup>1</sup></i>.
*
* @author Guido Kanschat
* @date 2008, 2009, 2010
namespace Laplace
{
/**
- * Laplacian in weak form, namely on the cell <i>Z</i> the matrix
- * \f[
- * \int_Z \nu \nabla u \cdot \nabla v \, dx.
- * \f]
+ * Laplacian in weak form, namely on the cell <i>Z</i> the matrix \f[
+ * \int_Z \nu \nabla u \cdot \nabla v \, dx. \f]
*
- * The FiniteElement in <tt>fe</tt> may be scalar or vector valued. In
- * the latter case, the Laplacian is applied to each component
- * separately.
+ * The FiniteElement in <tt>fe</tt> may be scalar or vector valued. In the
+ * latter case, the Laplacian is applied to each component separately.
*
* @author Guido Kanschat
* @date 2008, 2009, 2010
/**
* Laplacian residual operator in weak form
*
- * \f[
- * \int_Z \nu \nabla u \cdot \nabla v \, dx.
- * \f]
+ * \f[ \int_Z \nu \nabla u \cdot \nabla v \, dx. \f]
*/
template <int dim>
inline void
/**
* Vector-valued Laplacian residual operator in weak form
*
- * \f[
- * \int_Z \nu \nabla u : \nabla v \, dx.
- * \f]
+ * \f[ \int_Z \nu \nabla u : \nabla v \, dx. \f]
*/
template <int dim>
inline void
/**
- * Weak boundary condition of Nitsche type for the Laplacian, namely on the face <i>F</i> the matrix
+ * Weak boundary condition of Nitsche type for the Laplacian, namely on
+ * the face <i>F</i> the matrix
* @f[
* \int_F \Bigl(\gamma u v - \partial_n u v - u \partial_n v\Bigr)\;ds.
* @f]
*
- * Here, $\gamma$ is the <tt>penalty</tt> parameter suitably computed
- * with compute_penalty().
+ * Here, $\gamma$ is the <tt>penalty</tt> parameter suitably computed with
+ * compute_penalty().
*
* @author Guido Kanschat
* @date 2008, 2009, 2010
* \int_F \Bigl(\gamma (u-g) v - \partial_n u v - (u-g) \partial_n v\Bigr)\;ds.
* @f]
*
- * Here, <i>u</i> is the finite element function whose values and
- * gradient are given in the arguments <tt>input</tt> and
- * <tt>Dinput</tt>, respectively. <i>g</i> is the inhomogeneous
- * boundary value in the argument <tt>data</tt>. $\gamma$ is the usual
- * penalty parameter.
+ * Here, <i>u</i> is the finite element function whose values and gradient
+ * are given in the arguments <tt>input</tt> and <tt>Dinput</tt>,
+ * respectively. <i>g</i> is the inhomogeneous boundary value in the
+ * argument <tt>data</tt>. $\gamma$ is the usual penalty parameter.
*
* @author Guido Kanschat
* @date 2008, 2009, 2010
/**
* Weak boundary condition for the Laplace operator by Nitsche, vector
- * valued version, namely on the face <i>F</i>
- * the vector
+ * valued version, namely on the face <i>F</i> the vector
* @f[
* \int_F \Bigl(\gamma (\mathbf u- \mathbf g) \cdot \mathbf v
- - \partial_n \mathbf u \cdot \mathbf v
- - (\mathbf u-\mathbf g) \cdot \partial_n \mathbf v\Bigr)\;ds.
+ * - \partial_n \mathbf u \cdot \mathbf v
+ * - (\mathbf u-\mathbf g) \cdot \partial_n \mathbf v\Bigr)\;ds.
* @f]
*
- * Here, <i>u</i> is the finite element function whose values and
- * gradient are given in the arguments <tt>input</tt> and
- * <tt>Dinput</tt>, respectively. <i>g</i> is the inhomogeneous
- * boundary value in the argument <tt>data</tt>. $\gamma$ is the usual
- * penalty parameter.
+ * Here, <i>u</i> is the finite element function whose values and gradient
+ * are given in the arguments <tt>input</tt> and <tt>Dinput</tt>,
+ * respectively. <i>g</i> is the inhomogeneous boundary value in the
+ * argument <tt>data</tt>. $\gamma$ is the usual penalty parameter.
*
* @author Guido Kanschat
* @date 2008, 2009, 2010
}
/**
- * Flux for the interior penalty method for the Laplacian, namely on
- * the face <i>F</i> the matrices associated with the bilinear form
+ * Flux for the interior penalty method for the Laplacian, namely on the
+ * face <i>F</i> the matrices associated with the bilinear form
* @f[
* \int_F \Bigl( \gamma [u][v] - \{\nabla u\}[v\mathbf n] - [u\mathbf
* n]\{\nabla v\} \Bigr) \; ds.
* @f]
*
- * The penalty parameter should always be the mean value of the
- * penalties needed for stability on each side. In the case of
- * constant coefficients, it can be computed using compute_penalty().
+ * The penalty parameter should always be the mean value of the penalties
+ * needed for stability on each side. In the case of constant
+ * coefficients, it can be computed using compute_penalty().
*
- * If <tt>factor2</tt> is missing or negative, the factor is assumed
- * the same on both sides. If factors differ, note that the penalty
- * parameter has to be computed accordingly.
+ * If <tt>factor2</tt> is missing or negative, the factor is assumed the
+ * same on both sides. If factors differ, note that the penalty parameter
+ * has to be computed accordingly.
*
* @author Guido Kanschat
* @date 2008, 2009, 2010
}
/**
- * Flux for the interior penalty method for the Laplacian applied
- * to the tangential components of a vector field, namely on
- * the face <i>F</i> the matrices associated with the bilinear form
+ * Flux for the interior penalty method for the Laplacian applied to the
+ * tangential components of a vector field, namely on the face <i>F</i>
+ * the matrices associated with the bilinear form
* @f[
* \int_F \Bigl( \gamma [u_\tau][v_\tau] - \{\nabla u_\tau\}[v_\tau\mathbf n] - [u_\tau\mathbf
* n]\{\nabla v_\tau\} \Bigr) \; ds.
* Vector-valued residual term for the symmetric interior penalty method:
* @f[
* \int_F \Bigl( \gamma [\mathbf u]\cdot[\mathbf v]
- - \{\nabla \mathbf u\}[\mathbf v\otimes \mathbf n]
- - [\mathbf u\otimes \mathbf n]\{\nabla \mathbf v\} \Bigr) \; ds.
+ * - \{\nabla \mathbf u\}[\mathbf v\otimes \mathbf n]
+ * - [\mathbf u\otimes \mathbf n]\{\nabla \mathbf v\} \Bigr) \; ds.
* @f]
*
* @author Guido Kanschat
/**
- * Auxiliary function computing the penalty parameter for interior
- * penalty methods on rectangles.
+ * Auxiliary function computing the penalty parameter for interior penalty
+ * methods on rectangles.
*
* Computation is done in two steps: first, we compute on each cell
* <i>Z<sub>i</sub></i> the value <i>P<sub>i</sub> =
- * p<sub>i</sub>(p<sub>i</sub>+1)/h<sub>i</sub></i>, where <i>p<sub>i</sub></i> is
- * the polynomial degree on cell <i>Z<sub>i</sub></i> and
- * <i>h<sub>i</sub></i> is the length of <i>Z<sub>i</sub></i>
- * orthogonal to the current face.
+ * p<sub>i</sub>(p<sub>i</sub>+1)/h<sub>i</sub></i>, where
+ * <i>p<sub>i</sub></i> is the polynomial degree on cell
+ * <i>Z<sub>i</sub></i> and <i>h<sub>i</sub></i> is the length of
+ * <i>Z<sub>i</sub></i> orthogonal to the current face.
*
* @author Guido Kanschat
* @date 2010
/**
* @brief Library of integrals over cells and faces
*
- * This namespace contains application specific local integrals for
- * bilinear forms, forms and error estimates. It is a collection of
- * functions organized into namespaces devoted to certain
- * applications. For instance, the namespace Laplace contains
- * functions for computing cell matrices and cell residuals for the
- * Laplacian operator, as well as functions for the weak boundary
- * conditions by Nitsche or the interior penalty discontinuous
- * Galerkin method. The namespace Maxwell does the same for
- * curl-curl type problems.
+ * This namespace contains application specific local integrals for bilinear
+ * forms, forms and error estimates. It is a collection of functions organized
+ * into namespaces devoted to certain applications. For instance, the
+ * namespace Laplace contains functions for computing cell matrices and cell
+ * residuals for the Laplacian operator, as well as functions for the weak
+ * boundary conditions by Nitsche or the interior penalty discontinuous
+ * Galerkin method. The namespace Maxwell does the same for curl-curl type
+ * problems.
*
* The namespace L2 contains functions for mass matrices and
* <i>L<sup>2</sup></i>-inner products.
*
* <h3>Notational conventions</h3>
*
- * In most cases, the action of a function in this namespace can be
- * described by a single integral. We distinguish between integrals
- * over cells <i>Z</i> and over faces <i>F</i>. If an integral is
- * denoted as
+ * In most cases, the action of a function in this namespace can be described
+ * by a single integral. We distinguish between integrals over cells <i>Z</i>
+ * and over faces <i>F</i>. If an integral is denoted as
* @f[
* \int_Z u \otimes v \,dx,
* @f]
- * it will yield the following results, depending on the type of
- * operation
+ * it will yield the following results, depending on the type of operation
* <ul>
- * <li> If the function returns a matrix, the entry at
- * position <i>(i,j)</i> will be the integrated product of test function
- * <i>v<sub>i</sub></i> and trial function <i>u<sub>j</sub></i> (note
- * the reversion of indices)</li>
- * <li> If the function returns a vector, then the vector
- * entry at position <i>i</i> will be the integrated product of the
- * given function <i>u</i> with the test function <i>v<sub>i</sub></i>.</li>
- * <li> If the function returns a number, then this number is the
- * integral of the two given functions <i>u</i> and <i>v</i>.
+ * <li> If the function returns a matrix, the entry at position <i>(i,j)</i>
+ * will be the integrated product of test function <i>v<sub>i</sub></i> and
+ * trial function <i>u<sub>j</sub></i> (note the reversion of indices)</li>
+ * <li> If the function returns a vector, then the vector entry at position
+ * <i>i</i> will be the integrated product of the given function <i>u</i> with
+ * the test function <i>v<sub>i</sub></i>.</li>
+ * <li> If the function returns a number, then this number is the integral of
+ * the two given functions <i>u</i> and <i>v</i>.
* </ul>
*
- * We will use regular cursive symbols $u$ for scalars and bold
- * symbols $\mathbf u$ for vectors. Test functions are always <i>v</i>
- * and trial functions are always <i>u</i>. Parameters are Greek and
- * the face normal vectors are $\mathbf n = \mathbf n_1 = -\mathbf
- * n_2$.
+ * We will use regular cursive symbols $u$ for scalars and bold symbols
+ * $\mathbf u$ for vectors. Test functions are always <i>v</i> and trial
+ * functions are always <i>u</i>. Parameters are Greek and the face normal
+ * vectors are $\mathbf n = \mathbf n_1 = -\mathbf n_2$.
*
* <h3>Signature of functions</h3>
*
- * Functions in this namespace follow a generic signature. In the
- * simplest case, you have two related functions
+ * Functions in this namespace follow a generic signature. In the simplest
+ * case, you have two related functions
* @code
* template <int dim>
* void
* const double factor = 1.);
* @endcode
*
- * There is typically a pair of functions for the same operator, the
- * function <tt>cell_residual</tt> implementing the mapping of the
- * operator from the finite element space into its dual, and the
- * function <tt>cell_matrix</tt> generating the bilinear form
- * corresponding to the Frechet derivative of <tt>cell_residual</tt>.
+ * There is typically a pair of functions for the same operator, the function
+ * <tt>cell_residual</tt> implementing the mapping of the operator from the
+ * finite element space into its dual, and the function <tt>cell_matrix</tt>
+ * generating the bilinear form corresponding to the Frechet derivative of
+ * <tt>cell_residual</tt>.
*
* The first argument of these functions is the return type, which is
* <ul>
* <li> BlockVector<double> for vectors
* </ul>
*
- * The next argument is the FEValuesBase object representing the
- * finite element for integration. If the integrated operator maps
- * from one finite element space into the dual of another (for
- * instance an off-diagonal matrix in a block system), then first the
- * FEValuesBase for the trial space and after this the one for the
- * test space are specified.
+ * The next argument is the FEValuesBase object representing the finite
+ * element for integration. If the integrated operator maps from one finite
+ * element space into the dual of another (for instance an off-diagonal matrix
+ * in a block system), then first the FEValuesBase for the trial space and
+ * after this the one for the test space are specified.
*
* This list is followed by the set of required data in the order
* <ol>
*
* <h3>Usage</h3>
*
- * The local integrators can be used wherever a local integration loop
- * would have been implemented instead. The following example is from
- * the implementation of a Stokes solver, using
+ * The local integrators can be used wherever a local integration loop would
+ * have been implemented instead. The following example is from the
+ * implementation of a Stokes solver, using
* MeshWorker::Assembler::LocalBlocksToGlobalBlocks. The matrices are
* <ul>
- * <li> 0: The vector Laplacian for the velocity (here with a vector valued element)
+ * <li> 0: The vector Laplacian for the velocity (here with a vector valued
+ * element)
* <li> 1: The divergence matrix
* <li> 2: The pressure mass matrix used in the preconditioner
* </ul>
*
- * With these matrices, the function called by MeshWorker::loop()
- * could be written like
+ * With these matrices, the function called by MeshWorker::loop() could be
+ * written like
* @code
-using namespace ::dealii:: LocalIntegrators;
-
-template <int dim>
-void MatrixIntegrator<dim>::cell(
- MeshWorker::DoFInfo<dim>& dinfo,
- typename MeshWorker::IntegrationInfo<dim>& info)
-{
- Laplace::cell_matrix(dinfo.matrix(0,false).matrix, info.fe_values(0));
- Divergence::cell_matrix(dinfo.matrix(1,false).matrix, info.fe_values(0), info.fe_values(1));
- L2::cell_matrix(dinfo.matrix(2,false).matrix, info.fe_values(1));
-}
+ * using namespace ::dealii:: LocalIntegrators;
+ *
+ * template <int dim>
+ * void MatrixIntegrator<dim>::cell(
+ * MeshWorker::DoFInfo<dim>& dinfo,
+ * typename MeshWorker::IntegrationInfo<dim>& info)
+ * {
+ * Laplace::cell_matrix(dinfo.matrix(0,false).matrix, info.fe_values(0));
+ * Divergence::cell_matrix(dinfo.matrix(1,false).matrix, info.fe_values(0), info.fe_values(1));
+ * L2::cell_matrix(dinfo.matrix(2,false).matrix, info.fe_values(1));
+ * }
* @endcode
* See step-39 for a worked out example of this code.
*
namespace LocalIntegrators
{
/**
- * @brief Local integrators related to curl operators and their
- * traces.
+ * @brief Local integrators related to curl operators and their traces.
*
- * We use the following conventions for curl
- * operators. First, in three space dimensions
+ * We use the following conventions for curl operators. First, in three
+ * space dimensions
*
* @f[
* \nabla\times \mathbf u = \begin{pmatrix}
*
* In two space dimensions, the curl is obtained by extending a vector
* <b>u</b> to $(u_1, u_2, 0)^T$ and a scalar <i>p</i> to $(0,0,p)^T$.
- * Computing the nonzero components, we obtain the scalar
- * curl of a vector function and the vector curl of a scalar
- * function. The current implementation exchanges the sign and we have:
+ * Computing the nonzero components, we obtain the scalar curl of a vector
+ * function and the vector curl of a scalar function. The current
+ * implementation exchanges the sign and we have:
* @f[
* \nabla \times \mathbf u = \partial_1 u_2 - \partial 2 u_1,
* \qquad
namespace Maxwell
{
/**
- * Auxiliary function. Given the tensors of <tt>dim</tt> second derivatives,
- * compute the curl of the curl of a vector function. The result in
- * two and three dimensions is:
+ * Auxiliary function. Given the tensors of <tt>dim</tt> second
+ * derivatives, compute the curl of the curl of a vector function. The
+ * result in two and three dimensions is:
* @f[
* \nabla\times\nabla\times \mathbf u = \begin{pmatrix}
* \partial_1\partial_2 u_2 - \partial_2^2 u_1 \\
* \end{pmatrix}
* @f]
*
- * @note The third tensor argument is not used in two dimensions and
- * can for instance duplicate one of the previous.
+ * @note The third tensor argument is not used in two dimensions and can
+ * for instance duplicate one of the previous.
*
* @author Guido Kanschat
* @date 2011
}
/**
- * Auxiliary function. Given <tt>dim</tt> tensors of first
- * derivatives and a normal vector, compute the tangential curl
+ * Auxiliary function. Given <tt>dim</tt> tensors of first derivatives and
+ * a normal vector, compute the tangential curl
* @f[
* \mathbf n \times \nabla \times u.
* @f]
*
- * @note The third tensor argument is not used in two dimensions and
- * can for instance duplicate one of the previous.
+ * @note The third tensor argument is not used in two dimensions and can
+ * for instance duplicate one of the previous.
*
* @author Guido Kanschat
* @date 2011
* \int_Z \nabla\!\times\! u \cdot v \,dx.
* @f]
*
- * This is the standard curl operator in 3D and the scalar curl in
- * 2D. The vector curl operator can be obtained by exchanging test and
- * trial functions.
+ * This is the standard curl operator in 3D and the scalar curl in 2D. The
+ * vector curl operator can be obtained by exchanging test and trial
+ * functions.
*
* @author Guido Kanschat
* @date 2011
- */
+ */
template <int dim>
void curl_matrix (
FullMatrix<double> &M,
}
/**
- * The matrix for weak boundary
- * condition of Nitsche type for
- * the tangential component in
- * Maxwell systems.
+ * The matrix for weak boundary condition of Nitsche type for the
+ * tangential component in Maxwell systems.
*
* @f[
* \int_F \biggl( 2\gamma
}
}
/**
- * The product of two tangential
- * traces,
+ * The product of two tangential traces,
* @f[
* \int_F (u\times n)(v\times n)
* \, ds.
}
/**
- * The interior penalty fluxes
- * for Maxwell systems.
+ * The interior penalty fluxes for Maxwell systems.
*
* @f[
* \int_F \biggl( \gamma
* n\}\{\nu \nabla\times u\}
* \biggr)\;dx
* @f]
- *
- * @author Guido Kanschat
- * @date 2011
+ *
+ * @author Guido Kanschat
+ * @date 2011
*/
template <int dim>
inline void ip_curl_matrix (
* eigenvectors of a general n by n matrix A. It is most appropriate for large
* sparse matrices A.
*
- * In this class we make use of the method applied to the
- * generalized eigenspectrum problem $(A-\lambda B)x=0$, for
- * $x\neq0$; where $A$ is a system matrix, $B$ is a mass matrix,
- * and $\lambda, x$ are a set of eigenvalues and eigenvectors
- * respectively.
+ * In this class we make use of the method applied to the generalized
+ * eigenspectrum problem $(A-\lambda B)x=0$, for $x\neq0$; where $A$ is a
+ * system matrix, $B$ is a mass matrix, and $\lambda, x$ are a set of
+ * eigenvalues and eigenvectors respectively.
*
- * The ArpackSolver can be used in application codes
- * with serial objects in the following way:
- @code
- SolverControl solver_control (1000, 1e-9);
- ArpackSolver (solver_control);
- system.solve (A, B, OP, lambda, x, size_of_spectrum);
- @endcode
- * for the generalized eigenvalue problem $Ax=B\lambda x$, where
- * the variable <code>size_of_spectrum</code>
- * tells ARPACK the number of eigenvector/eigenvalue pairs to
- * solve for. Here, <code>lambda</code> is a vector that will contain
- * the eigenvalues computed, <code>x</code> a vector that will
- * contain the eigenvectors computed, and <code>OP</code> is
- * an inverse operation for the matrix <code>A</code>.
- * Shift and invert transformation around zero is applied.
+ * The ArpackSolver can be used in application codes with serial objects in
+ * the following way:
+ * @code
+ * SolverControl solver_control (1000, 1e-9);
+ * ArpackSolver (solver_control);
+ * system.solve (A, B, OP, lambda, x, size_of_spectrum);
+ * @endcode
+ * for the generalized eigenvalue problem $Ax=B\lambda x$, where the variable
+ * <code>size_of_spectrum</code> tells ARPACK the number of
+ * eigenvector/eigenvalue pairs to solve for. Here, <code>lambda</code> is a
+ * vector that will contain the eigenvalues computed, <code>x</code> a vector
+ * that will contain the eigenvectors computed, and <code>OP</code> is an
+ * inverse operation for the matrix <code>A</code>. Shift and invert
+ * transformation around zero is applied.
*
- * Through the AdditionalData the user can specify some of the
- * parameters to be set.
+ * Through the AdditionalData the user can specify some of the parameters to
+ * be set.
*
* For further information on how the ARPACK routines <code>dneupd</code> and
* <code>dnaupd</code> work and also how to set the parameters appropriately
/**
- * An enum that lists the possible
- * choices for which eigenvalues to
- * compute in the solve() function.
+ * An enum that lists the possible choices for which eigenvalues to compute
+ * in the solve() function.
*/
enum WhichEigenvalues
{
};
/**
- * Standardized data struct to pipe
- * additional data to the solver,
- * should it be needed.
+ * Standardized data struct to pipe additional data to the solver, should it
+ * be needed.
*/
struct AdditionalData
{
};
/**
- * Access to the object that
- * controls convergence.
+ * Access to the object that controls convergence.
*/
SolverControl &control () const;
const AdditionalData &data = AdditionalData());
/**
- * Solve the generalized eigensprectrum
- * problem $A x=\lambda B x$ by calling
- * the <code>dneupd</code> and <code>dnaupd</code>
- * functions of ARPACK.
+ * Solve the generalized eigensprectrum problem $A x=\lambda B x$ by calling
+ * the <code>dneupd</code> and <code>dnaupd</code> functions of ARPACK.
*/
template <typename VECTOR, typename MATRIX1,
typename MATRIX2, typename INVERSE>
protected:
/**
- * Reference to the object that
- * controls convergence of the
- * iterative solver.
+ * Reference to the object that controls convergence of the iterative
+ * solver.
*/
SolverControl &solver_control;
/**
- * Store a copy of the flags for
- * this particular solver.
+ * Store a copy of the flags for this particular solver.
*/
const AdditionalData additional_data;
int ido = 0;
/**
- * 'G' generalized eigenvalue problem
- * 'I' standard eigenvalue problem
+ * 'G' generalized eigenvalue problem 'I' standard eigenvalue problem
*/
char bmat[2] = "G";
- /** Specify the eigenvalues of interest,
- * possible parameters
- * "LA" algebraically largest
- * "SA" algebraically smallest
- * "LM" largest magnitude
- * "SM" smallest magnitude
- * "LR" largest real part
- * "SR" smallest real part
- * "LI" largest imaginary part
- * "SI" smallest imaginary part
- * "BE" both ends of spectrum simultaneous
+ /**
+ * Specify the eigenvalues of interest, possible parameters "LA"
+ * algebraically largest "SA" algebraically smallest "LM" largest magnitude
+ * "SM" smallest magnitude "LR" largest real part "SR" smallest real part
+ * "LI" largest imaginary part "SI" smallest imaginary part "BE" both ends
+ * of spectrum simultaneous
*/
char which[3];
switch (additional_data.eigenvalue_of_interest)
// maximum number of iterations
iparam[2] = control().max_steps();
- /** Sets the mode of dsaupd.
- * 1 is exact shifting,
- * 2 is user-supplied shifts,
- * 3 is shift-invert mode,
- * 4 is buckling mode,
- * 5 is Cayley mode.
+ /**
+ * Sets the mode of dsaupd. 1 is exact shifting, 2 is user-supplied shifts,
+ * 3 is shift-invert mode, 4 is buckling mode, 5 is Cayley mode.
*/
iparam[6] = mode;
}
else
{
- /** 1 - compute eigenvectors,
- * 0 - only eigenvalues
+ /**
+ * 1 - compute eigenvectors, 0 - only eigenvalues
*/
int rvec = 1;
* @brief Auxiliary class aiding in the handling of block structures like in
* BlockVector or FESystem.
*
- * The information obtained from this class falls into two
- * groups. First, it is possible to obtain the number of blocks,
- * namely size(), the block_size() for each block and the total_size()
- * of the object described by the block indices, namely the length of
- * the whole index set. These functions do not make any assumption on
- * the ordering of the index set.
+ * The information obtained from this class falls into two groups. First, it
+ * is possible to obtain the number of blocks, namely size(), the block_size()
+ * for each block and the total_size() of the object described by the block
+ * indices, namely the length of the whole index set. These functions do not
+ * make any assumption on the ordering of the index set.
*
- * If on the other hand the index set is ordered "by blocks", such
- * that each block forms a consecutive set of indices, this
- * class that manages the conversion of global indices into a block vector or
- * matrix to the local indices within this block. This is required, for
- * example, when you address a global element in a block vector and want to
- * know which element within which block this is. It is also useful if a
- * matrix is composed of several blocks, where you have to translate global
- * row and column indices to local ones.
+ * If on the other hand the index set is ordered "by blocks", such that each
+ * block forms a consecutive set of indices, this class that manages the
+ * conversion of global indices into a block vector or matrix to the local
+ * indices within this block. This is required, for example, when you address
+ * a global element in a block vector and want to know which element within
+ * which block this is. It is also useful if a matrix is composed of several
+ * blocks, where you have to translate global row and column indices to local
+ * ones.
*
- * @ingroup data
- * @see @ref GlossBlockLA "Block (linear algebra)"
+ * @ingroup data @see @ref GlossBlockLA "Block (linear algebra)"
* @author Wolfgang Bangerth, Guido Kanschat, 2000, 2007, 2011
*/
class BlockIndices : public Subscriptor
typedef types::global_dof_index size_type;
/**
- * Default
- * constructor. Initialize for
- * zero blocks.
+ * Default constructor. Initialize for zero blocks.
*/
BlockIndices ();
/**
- * Constructor. Initialize the
- * number of entries in each
- * block @p i as <tt>n[i]</tt>. The
- * number of blocks will be the
- * size of the vector
+ * Constructor. Initialize the number of entries in each block @p i as
+ * <tt>n[i]</tt>. The number of blocks will be the size of the vector
*/
BlockIndices (const std::vector<size_type> &n);
/**
- * Specialized constructor for a
- * structure with blocks of equal size.
+ * Specialized constructor for a structure with blocks of equal size.
*/
explicit BlockIndices(const unsigned int n_blocks, const size_type block_size = 0);
/**
- * Reinitialize the number of
- * blocks and assign each block
- * the same number of elements.
+ * Reinitialize the number of blocks and assign each block the same number
+ * of elements.
*/
void reinit (const unsigned int n_blocks,
const size_type n_elements_per_block);
/**
- * Reinitialize the number of
- * indices within each block from
- * the given argument. The number
- * of blocks will be adjusted to
- * the size of @p n and the size
- * of block @p i is set to
- * <tt>n[i]</tt>.
+ * Reinitialize the number of indices within each block from the given
+ * argument. The number of blocks will be adjusted to the size of @p n and
+ * the size of block @p i is set to <tt>n[i]</tt>.
*/
void reinit (const std::vector<size_type> &n);
/**
- * Add another block of given
- * size to the end of the block
- * structure.
+ * Add another block of given size to the end of the block structure.
*/
void push_back(const size_type size);
unsigned int size () const;
/**
- * Return the total number of
- * indices accumulated over all
- * blocks, that is, the dimension
- * of the vector space of the
- * block vector.
+ * Return the total number of indices accumulated over all blocks, that is,
+ * the dimension of the vector space of the block vector.
*/
size_type total_size () const;
/**
* @name Index conversion
*
- * Functions in this group
- * assume an object, which
- * was created after sorting by
- * block, such that each block
- * forms a set of consecutive
- * indices in the object.
- * If applied to other objects,
- * the numbers obtained from
- * these functions are meaningless.
+ * Functions in this group assume an object, which was created after sorting
+ * by block, such that each block forms a set of consecutive indices in the
+ * object. If applied to other objects, the numbers obtained from these
+ * functions are meaningless.
*/
//@{
/**
- * Return the block and the
- * index within that block
- * for the global index @p i. The
- * first element of the pair is
- * the block, the second the
- * index within it.
+ * Return the block and the index within that block for the global index @p
+ * i. The first element of the pair is the block, the second the index
+ * within it.
*/
std::pair<unsigned int,size_type>
global_to_local (const size_type i) const;
/**
- * Return the global index of
- * @p index in block @p block.
+ * Return the global index of @p index in block @p block.
*/
size_type local_to_global (const unsigned int block,
const size_type index) const;
BlockIndices &operator = (const BlockIndices &b);
/**
- * Compare whether two objects
- * are the same, i.e. whether the
- * number of blocks and the sizes
- * of all blocks are equal.
+ * Compare whether two objects are the same, i.e. whether the number of
+ * blocks and the sizes of all blocks are equal.
*/
bool operator == (const BlockIndices &b) const;
/**
- * Swap the contents of these two
- * objects.
+ * Swap the contents of these two objects.
*/
void swap (BlockIndices &b);
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
private:
/**
- * Number of blocks. While this
- * value could be obtained
- * through
- * <tt>start_indices.size()-1</tt>,
- * we cache this value for faster
- * access.
+ * Number of blocks. While this value could be obtained through
+ * <tt>start_indices.size()-1</tt>, we cache this value for faster access.
*/
unsigned int n_blocks;
/**
- * Global starting index of each
- * vector. The last and redundant
- * value is the total number of
- * entries.
+ * Global starting index of each vector. The last and redundant value is the
+ * total number of entries.
*/
std::vector<size_type> start_indices;
};
/**
- * Operator for logging BlockIndices. Writes the number of blocks, the
- * size of each block and the total size of the index field.
+ * Operator for logging BlockIndices. Writes the number of blocks, the size of
+ * each block and the total size of the index field.
*
* @ref BlockIndices
* @author Guido Kanschat
* @code
* IsBlockMatrix<BlockSparseMatrix<double> >::value
* @endcode
- * is true. This is sometimes useful in template contexts where we may
- * want to do things differently depending on whether a template type
- * denotes a regular or a block matrix type.
+ * is true. This is sometimes useful in template contexts where we may want to
+ * do things differently depending on whether a template type denotes a
+ * regular or a block matrix type.
*
* @see @ref GlossBlockLA "Block (linear algebra)"
* @author Wolfgang Bangerth, 2009
};
/**
- * Overload returning true if the class
- * is derived from BlockMatrixBase,
- * which is what block matrices do
- * (with the exception of
+ * Overload returning true if the class is derived from BlockMatrixBase,
+ * which is what block matrices do (with the exception of
* BlockSparseMatrixEZ).
*/
template <typename T>
static yes_type check_for_block_matrix (const BlockMatrixBase<T> *);
/**
- * Overload returning true if the class
- * is derived from
- * BlockSparsityPatternBase, which is
- * what block sparsity patterns do.
+ * Overload returning true if the class is derived from
+ * BlockSparsityPatternBase, which is what block sparsity patterns do.
*/
template <typename T>
static yes_type check_for_block_matrix (const BlockSparsityPatternBase<T> *);
/**
- * Overload for BlockSparseMatrixEZ,
- * which is the only block matrix not
- * derived from BlockMatrixBase at the
- * time of writing this class.
+ * Overload for BlockSparseMatrixEZ, which is the only block matrix not
+ * derived from BlockMatrixBase at the time of writing this class.
*/
template <typename T>
static yes_type check_for_block_matrix (const BlockSparseMatrixEZ<T> *);
/**
- * Catch all for all other potential
- * matrix types that are not block
+ * Catch all for all other potential matrix types that are not block
* matrices.
*/
static no_type check_for_block_matrix (...);
public:
/**
- * A statically computable value that
- * indicates whether the template
- * argument to this class is a block
- * matrix (in fact whether the type is
+ * A statically computable value that indicates whether the template
+ * argument to this class is a block matrix (in fact whether the type is
* derived from BlockMatrixBase<T>).
*/
static const bool value = (sizeof(check_for_block_matrix
/**
- * Global function @p swap which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two objects.
+ * Global function @p swap which overloads the default implementation of the
+ * C++ standard library which uses a temporary object. The function simply
+ * exchanges the data of the two objects.
*
* @relates BlockIndices
* @author Wolfgang Bangerth, 2000
DEAL_II_NAMESPACE_OPEN
/**
- * @deprecated This class is experimental and will be
- * removed in a future release.
+ * @deprecated This class is experimental and will be removed in a future
+ * release.
*
- * A vector of index sets listing the indices of small blocks of a
- * linear system. For each block, the indices in that block are
- * listed.
+ * A vector of index sets listing the indices of small blocks of a linear
+ * system. For each block, the indices in that block are listed.
*
- * The focus of this class is on small blocks of degrees of freedom
- * associated with a single mesh cell or a small patch. These indices
- * may be contiguous or not and we do not optimize for the case they
- * are. For larger sets, the use of a vector of IndexSet objects might
- * be advisable.
+ * The focus of this class is on small blocks of degrees of freedom associated
+ * with a single mesh cell or a small patch. These indices may be contiguous
+ * or not and we do not optimize for the case they are. For larger sets, the
+ * use of a vector of IndexSet objects might be advisable.
*
- * BlockList objects can conveniently be initialized with iterator
- * ranges from DoFHandler or MGDoFHandler, using either their cell or
- * multigrid indices. Other initializations are possible to be
- * implemented.
+ * BlockList objects can conveniently be initialized with iterator ranges from
+ * DoFHandler or MGDoFHandler, using either their cell or multigrid indices.
+ * Other initializations are possible to be implemented.
*
* @author Guido Kanschat
* @date 2010
typedef block_container::const_iterator const_iterator;
/**
- * Since SparsityPattern can
- * handle the tasks of BlockList,
- * this function allows us to
- * create one from an already
- * filled BlockList. A first step
- * to make BlockList obsolete.
+ * Since SparsityPattern can handle the tasks of BlockList, this function
+ * allows us to create one from an already filled BlockList. A first step to
+ * make BlockList obsolete.
*
- * The additional integer
- * argument is the dimension of
- * the vector space.
+ * The additional integer argument is the dimension of the vector space.
*/
void create_sparsity_pattern(SparsityPattern &sparsity, size_type n) const;
/**
- * Add the indices in
- * <tt>indices</tt> to block
- * <tt>block</tt>, eliminating
+ * Add the indices in <tt>indices</tt> to block <tt>block</tt>, eliminating
* repeated indices.
*/
void add(size_type block, const std::vector<size_type> &indices);
/**
- * Add the indices in
- * <tt>indices</tt> to block
- * <tt>block</tt>, eliminating
- * repeated indices. Only add
- * those indices for which
+ * Add the indices in <tt>indices</tt> to block <tt>block</tt>, eliminating
+ * repeated indices. Only add those indices for which
* <tt>selected_indices</tt> is true.
*/
void add(size_type block,
size_type offset = 0);
/**
- * Just set up the correct size
- * and assign indices to blocks later.
+ * Just set up the correct size and assign indices to blocks later.
*/
void initialize(size_type n_blocks);
/**
- * Set up all index sets using an
- * DoF iterator range. This
- * function will call
- * <tt>begin->get_dof_indices()</tt>
- * with a signature like
- * DoFCellAccessor::get_dof_indices().
- * Typically, the iterators will
- * loop over active cells of a
- * triangulation.
+ * Set up all index sets using an DoF iterator range. This function will
+ * call <tt>begin->get_dof_indices()</tt> with a signature like
+ * DoFCellAccessor::get_dof_indices(). Typically, the iterators will loop
+ * over active cells of a triangulation.
*
- * In addition, the function
- * needs the total number of
- * blocks as its first argument.
+ * In addition, the function needs the total number of blocks as its first
+ * argument.
*/
template <typename ITERATOR>
void initialize(size_type n_blocks,
const typename identity<ITERATOR>::type end);
/**
- * @deprecated This function will
- * move to DoFTools.
+ * @deprecated This function will move to DoFTools.
*
- * Set up all index sets using an
- * DoF iterator range. This
- * function will call
- * <tt>begin->get_mg_dof_indices()</tt>
- * with a signature like
- * MGDoFCellAccessor::get_mg_dof_indices().
- * Typically, the iterators loop
- * over the cells of a single
- * level or a Triangulation.
+ * Set up all index sets using an DoF iterator range. This function will
+ * call <tt>begin->get_mg_dof_indices()</tt> with a signature like
+ * MGDoFCellAccessor::get_mg_dof_indices(). Typically, the iterators loop
+ * over the cells of a single level or a Triangulation.
*
- * In addition, the function
- * needs the total number of
- * blocks as its first argument.
+ * In addition, the function needs the total number of blocks as its first
+ * argument.
*/
template <typename ITERATOR>
void initialize_mg(size_type n_blocks,
const typename identity<ITERATOR>::type end) DEAL_II_DEPRECATED;
/**
- * @deprecated This function will
- * move to DoFTools.
+ * @deprecated This function will move to DoFTools.
*
- * Set up all index sets using an
- * DoF iterator range. This
- * function will call
- * <tt>begin->get_dof_indices()</tt>
- * with a signature like
- * DoFCellAccessor::get_dof_indices().
- * Typically, the iterators will
- * loop over active cells of a
- * triangulation.
+ * Set up all index sets using an DoF iterator range. This function will
+ * call <tt>begin->get_dof_indices()</tt> with a signature like
+ * DoFCellAccessor::get_dof_indices(). Typically, the iterators will loop
+ * over active cells of a triangulation.
*
- * The argument vector
- * <tt>selected_dofs</tt> should
- * have the length of dofs per
- * cell (thus, this function is
- * not suitable for hp), and a
- * true value for each degree of
- * freedom which should be added
- * to the index set of this
- * cell. If you are working on a
- * single block of a block
- * system, the <tt>offset</tt> is
- * the start index of this block.
+ * The argument vector <tt>selected_dofs</tt> should have the length of
+ * dofs per cell (thus, this function is not suitable for hp), and a true
+ * value for each degree of freedom which should be added to the index set
+ * of this cell. If you are working on a single block of a block system, the
+ * <tt>offset</tt> is the start index of this block.
*
- * In addition, the function
- * needs the total number of
- * blocks as its first argument.
+ * In addition, the function needs the total number of blocks as its first
+ * argument.
*/
template <typename ITERATOR>
void initialize(size_type n_blocks,
const std::vector<bool> &selected_dofs,
size_type offset = 0) DEAL_II_DEPRECATED;
/**
- * @deprecated This function will
- * move to DoFTools.
+ * @deprecated This function will move to DoFTools.
*
- * Set up all index sets using an
- * DoF iterator range. This
- * function will call
- * <tt>begin->get_mg_dof_indices()</tt>
- * with a signature like
- * MGDoFCellAccessor::get_mg_dof_indices().
- * Typically, the iterators will
- * loop over cells on a single
- * level of a triangulation.
+ * Set up all index sets using an DoF iterator range. This function will
+ * call <tt>begin->get_mg_dof_indices()</tt> with a signature like
+ * MGDoFCellAccessor::get_mg_dof_indices(). Typically, the iterators will
+ * loop over cells on a single level of a triangulation.
*
- * The argument vector
- * <tt>selected_dofs</tt> should
- * have the length of dofs per
- * cell (thus, this function is
- * not suitable for hp), and a
- * true value for each degree of
- * freedom which should be added
- * to the index set of this
- * cell. If you are working on a
- * single block of a block
- * system, the <tt>offset</tt> is
- * the start index of this block.
+ * The argument vector <tt>selected_dofs</tt> should have the length of
+ * dofs per cell (thus, this function is not suitable for hp), and a true
+ * value for each degree of freedom which should be added to the index set
+ * of this cell. If you are working on a single block of a block system, the
+ * <tt>offset</tt> is the start index of this block.
*
- * In addition, the function
- * needs the total number of
- * blocks as its first argument.
+ * In addition, the function needs the total number of blocks as its first
+ * argument.
*/
template <typename ITERATOR>
void initialize_mg(size_type n_blocks,
size_type offset = 0) DEAL_II_DEPRECATED;
/**
- * @deprecated This function will
- * move to DoFTools.
+ * @deprecated This function will move to DoFTools.
*
- * Same as initialize_mg(), but
- * instead of gathering the
- * degrees of freedom of a single
- * cell into a block, gather all
- * degrees of freedom of a patch
+ * Same as initialize_mg(), but instead of gathering the degrees of freedom
+ * of a single cell into a block, gather all degrees of freedom of a patch
* around a vertex.
*/
template <int dim, typename ITERATOR>
size_type offset = 0) DEAL_II_DEPRECATED;
/**
- * @deprecated This function will
- * move to DoFTools.
+ * @deprecated This function will move to DoFTools.
*
- * Auxiliary function, counting
- * the patches around vertices.
+ * Auxiliary function, counting the patches around vertices.
*/
template <int dim, typename ITERATOR>
unsigned int count_vertex_patches(
bool same_level_only) const DEAL_II_DEPRECATED;
/**
- * @deprecated This function will
- * move to DoFTools.
+ * @deprecated This function will move to DoFTools.
*
*/
template <int dim, typename ITERATOR>
*/
const_iterator end(size_type block) const;
/**
- * Return the position of
- * <tt>index</tt> in
- * <tt>block</tt>, or
- * numbers::invalid_size_type,
- * if the index is not in the block.
+ * Return the position of <tt>index</tt> in <tt>block</tt>, or
+ * numbers::invalid_size_type, if the index is not in the block.
*/
size_type local_index(size_type block, size_type index) const;
/**
* A matrix with several copies of the same block on the diagonal.
*
- * This matrix implements an @p m by @p m block matrix. Each
- * diagonal block consists of the same (non-block) matrix, while
- * off-diagonal blocks are void.
+ * This matrix implements an @p m by @p m block matrix. Each diagonal block
+ * consists of the same (non-block) matrix, while off-diagonal blocks are
+ * void.
*
- * One special application is a one by one block matrix, allowing to
- * apply the @p vmult of the original matrix (or preconditioner) to a
- * block vector.
+ * One special application is a one by one block matrix, allowing to apply the
+ * @p vmult of the original matrix (or preconditioner) to a block vector.
*
* @see @ref GlossBlockLA "Block (linear algebra)"
* @author Guido Kanschat, 2000
{
public:
/**
- * Constructor for an @p n_blocks
- * by @p n_blocks matrix with
- * diagonal blocks @p M.
+ * Constructor for an @p n_blocks by @p n_blocks matrix with diagonal blocks
+ * @p M.
*/
BlockDiagonalMatrix (const MATRIX &M,
const unsigned int n_blocks);
/**
- * Block matrix composed of different single matrices; these matrices
- * may even be of different types.
+ * Block matrix composed of different single matrices; these matrices may even
+ * be of different types.
*
* Given a set of arbitrary matrices <i>A<sub>i</sub></i>, this class
- * implements a block matrix with block entries of the form
- * <i>M<sub>jk</sub> = s<sub>jk</sub>A<sub>i</sub></i>. Each
- * <i>A<sub>i</sub></i> may be used several times with different
- * prefix. The matrices are not copied into the BlockMatrixArray
- * object, but rather a PointerMatrix referencing each of them will be
- * stored along with factors and transposition flags.
+ * implements a block matrix with block entries of the form <i>M<sub>jk</sub>
+ * = s<sub>jk</sub>A<sub>i</sub></i>. Each <i>A<sub>i</sub></i> may be used
+ * several times with different prefix. The matrices are not copied into the
+ * BlockMatrixArray object, but rather a PointerMatrix referencing each of
+ * them will be stored along with factors and transposition flags.
*
- * Non-zero entries are registered by the function enter(), zero
- * entries are not stored at all. Using enter() with the same location
- * <tt>(i,j)</tt> several times will add the corresponding matrices in
- * matrix-vector multiplications. These matrices will not be actually
- * added, but the multiplications with them will be summed up.
+ * Non-zero entries are registered by the function enter(), zero entries are
+ * not stored at all. Using enter() with the same location <tt>(i,j)</tt>
+ * several times will add the corresponding matrices in matrix-vector
+ * multiplications. These matrices will not be actually added, but the
+ * multiplications with them will be summed up.
*
- * @note This mechanism makes it impossible to access single entries
- * of BlockMatrixArray. In particular, (block) relaxation
- * preconditioners based on PreconditionRelaxation or
- * PreconditionBlock <b>cannot</b> be used with this class. If you
- * need a preconditioner for a BlockMatrixArray object, use
+ * @note This mechanism makes it impossible to access single entries of
+ * BlockMatrixArray. In particular, (block) relaxation preconditioners based
+ * on PreconditionRelaxation or PreconditionBlock <b>cannot</b> be used with
+ * this class. If you need a preconditioner for a BlockMatrixArray object, use
* BlockTrianglePrecondition.
*
* <h3>Requirements on MATRIX</h3>
*
- * The template argument <tt>MATRIX</tt> is a class providing the
- * matrix-vector multiplication functions vmult(), Tvmult(),
- * vmult_add() and Tvmult_add() used in this class, but with arguments
- * of type Vector<number> instead of
- * BlockVector<number>. Every matrix which can be used by
- * PointerMatrix is allowed, in particular SparseMatrix is a possible
- * entry type.
+ * The template argument <tt>MATRIX</tt> is a class providing the matrix-
+ * vector multiplication functions vmult(), Tvmult(), vmult_add() and
+ * Tvmult_add() used in this class, but with arguments of type
+ * Vector<number> instead of BlockVector<number>. Every matrix
+ * which can be used by PointerMatrix is allowed, in particular SparseMatrix
+ * is a possible entry type.
*
- * <h3>Example program</h3>
- * We document the relevant parts of <tt>examples/doxygen/block_matrix_array.cc</tt>.
+ * <h3>Example program</h3> We document the relevant parts of
+ * <tt>examples/doxygen/block_matrix_array.cc</tt>.
*
* @dontinclude block_matrix_array.cc
*
- * Obviously, we have to include the header file containing the definition
- * of BlockMatrixArray:
- * @skipline block_matrix_array.h
+ * Obviously, we have to include the header file containing the definition of
+ * BlockMatrixArray: @skipline block_matrix_array.h
*
- * First, we set up some matrices to be entered into the blocks.
- * @skip main
+ * First, we set up some matrices to be entered into the blocks. @skip main
* @until C.fill
*
- * The BlockMatrixArray needs a VectorMemory<Vector<number>
- * > object to allocate auxiliary vectors. <tt>number</tt> must
- * equal the second template argument of BlockMatrixArray and also the
- * number type of the BlockVector used later. We use the
- * GrowingVectorMemory type, since it remembers the vector and avoids
- * reallocating.
+ * The BlockMatrixArray needs a VectorMemory<Vector<number> >
+ * object to allocate auxiliary vectors. <tt>number</tt> must equal the second
+ * template argument of BlockMatrixArray and also the number type of the
+ * BlockVector used later. We use the GrowingVectorMemory type, since it
+ * remembers the vector and avoids reallocating.
*
* @line Growing
*
- * Now, we are ready to build a <i>2x2</i> BlockMatrixArray.
- * @line Block
- * First, we enter the matrix <tt>A</tt> multiplied by 2 in the upper left block
- * @line enter
- * Now -1 times <tt>B1</tt> in the upper right block.
- * @line enter
- * We add the transpose of <tt>B2</tt> to the upper right block and
- * continue in a similar fashion. In the end, the block matrix
- * structure is printed into an LaTeX table.
- * @until latex
+ * Now, we are ready to build a <i>2x2</i> BlockMatrixArray. @line Block
+ * First, we enter the matrix <tt>A</tt> multiplied by 2 in the upper left
+ * block @line enter Now -1 times <tt>B1</tt> in the upper right block. @line
+ * enter We add the transpose of <tt>B2</tt> to the upper right block and
+ * continue in a similar fashion. In the end, the block matrix structure is
+ * printed into an LaTeX table. @until latex
*
* Now, we set up vectors to be multiplied with this matrix and do a
- * multiplication.
- * @until vmult
+ * multiplication. @until vmult
*
* Finally, we solve a linear system with BlockMatrixArray, using no
- * preconditioning and the conjugate gradient method.
- * @until Error
+ * preconditioning and the conjugate gradient method. @until Error
*
- * The remaining code of this sample program concerns preconditioning
- * and is described in the documentation of
- * BlockTrianglePrecondition.
+ * The remaining code of this sample program concerns preconditioning and is
+ * described in the documentation of BlockTrianglePrecondition.
*
* @see @ref GlossBlockLA "Block (linear algebra)"
* @author Guido Kanschat
typedef types::global_dof_index size_type;
/**
- * Default constructor creating a
- * useless object. initialize()
- * must be called before using
- * it.
+ * Default constructor creating a useless object. initialize() must be
+ * called before using it.
*/
BlockMatrixArray ();
/**
- * Constructor fixing the
- * dimensions.
+ * Constructor fixing the dimensions.
*/
BlockMatrixArray (const unsigned int n_block_rows,
const unsigned int n_block_cols);
/**
- * Initialize object
- * completely. This is the
- * function to call for an object
- * created by the default
- * constructor.
+ * Initialize object completely. This is the function to call for an object
+ * created by the default constructor.
*/
void initialize (const unsigned int n_block_rows,
const unsigned int n_block_cols);
/**
- * Constructor fixing the
- * dimensions.
+ * Constructor fixing the dimensions.
*
* @deprecated The last argument is ignored. Use the constructor with only
* the first two arguments.
VectorMemory<Vector<number> > &mem) DEAL_II_DEPRECATED;
/**
- * Initialize object
- * completely. This is the
- * function to call for an object
- * created by the default
- * constructor.
+ * Initialize object completely. This is the function to call for an object
+ * created by the default constructor.
*
* @deprecated The last argument is ignored. Use the function with same name
* but only the first two arguments.
VectorMemory<Vector<number> > &mem) DEAL_II_DEPRECATED;
/**
- * Adjust the matrix to a new
- * size and delete all blocks.
+ * Adjust the matrix to a new size and delete all blocks.
*/
void reinit (const unsigned int n_block_rows,
const unsigned int n_block_cols);
/**
- * Add a block matrix entry. The
- * <tt>matrix</tt> is entered
- * into a list of blocks for
- * multiplication, together with
- * its coordinates <tt>row</tt>
- * and <tt>col</tt> as well as
- * optional multiplication factor
- * <tt>prefix</tt> and transpose
- * flag <tt>transpose</tt>.
+ * Add a block matrix entry. The <tt>matrix</tt> is entered into a list of
+ * blocks for multiplication, together with its coordinates <tt>row</tt> and
+ * <tt>col</tt> as well as optional multiplication factor <tt>prefix</tt>
+ * and transpose flag <tt>transpose</tt>.
*
- * @note No check for consistency
- * of block sizes is
- * made. Therefore, entering a
- * block of wrong dimension here
- * will only lead to a
- * ExcDimensionMismatch in one of
- * the multiplication functions.
+ * @note No check for consistency of block sizes is made. Therefore,
+ * entering a block of wrong dimension here will only lead to a
+ * ExcDimensionMismatch in one of the multiplication functions.
*/
template <class MATRIX>
void enter (const MATRIX &matrix,
const bool transpose = false);
/**
- * Add an entry like with enter,
- * but use PointerMatrixAux for
- * matrices not having functions
- * vmult_add() and TVmult_add().
+ * Add an entry like with enter, but use PointerMatrixAux for matrices not
+ * having functions vmult_add() and TVmult_add().
*
- * @deprecated The first argument
- * is ignored. Use the function with same name
- * but without the first argument.
+ * @deprecated The first argument is ignored. Use the function with same
+ * name but without the first argument.
*/
template <class MATRIX>
void enter_aux (VectorMemory<Vector<number> > &mem,
/**
- * Delete all entries, i.e. reset
- * the matrix to an empty state.
+ * Delete all entries, i.e. reset the matrix to an empty state.
*/
void clear();
/**
- * Number of block-entries per
- * column.
+ * Number of block-entries per column.
*/
unsigned int n_block_rows () const;
/**
- * Number of block-entries per
- * row.
+ * Number of block-entries per row.
*/
unsigned int n_block_cols () const;
const BlockVector<number> &src) const;
/**
- * Matrix-vector multiplication
- * adding to <tt>dst</tt>.
+ * Matrix-vector multiplication adding to <tt>dst</tt>.
*/
void vmult_add (BlockVector<number> &dst,
const BlockVector<number> &src) const;
/**
- * Transposed matrix-vector
- * multiplication.
+ * Transposed matrix-vector multiplication.
*/
void Tvmult (BlockVector<number> &dst,
const BlockVector<number> &src) const;
/**
- * Transposed matrix-vector
- * multiplication adding to
- * <tt>dst</tt>.
+ * Transposed matrix-vector multiplication adding to <tt>dst</tt>.
*/
void Tvmult_add (BlockVector<number> &dst,
const BlockVector<number> &src) const;
/**
- * Matrix scalar product between
- * two vectors (at least for a
- * symmetric matrix).
+ * Matrix scalar product between two vectors (at least for a symmetric
+ * matrix).
*/
number matrix_scalar_product (const BlockVector<number> &u,
const BlockVector<number> &v) const;
/**
- * Compute $u^T M u$. This is the square
- * of the norm induced by the matrix
- * assuming the matrix is symmetric
- * positive definitive.
+ * Compute $u^T M u$. This is the square of the norm induced by the matrix
+ * assuming the matrix is symmetric positive definitive.
*/
number matrix_norm_square (const BlockVector<number> &u) const;
/**
- * Print the block structure as a
- * LaTeX-array. This output will
- * not be very intuitive, since
- * the current object lacks
- * knowledge about what the individual blocks represent or
- * how they should be named. Instead, what
- * you will see is an entry for each
- * block showing all the matrices
- * with their multiplication
- * factors and possibly transpose
- * marks. The matrices itself are
- * named successively as they are encountered. If the same
- * matrix is entered several
- * times, it will be listed with
- * different names.
+ * Print the block structure as a LaTeX-array. This output will not be very
+ * intuitive, since the current object lacks knowledge about what the
+ * individual blocks represent or how they should be named. Instead, what
+ * you will see is an entry for each block showing all the matrices with
+ * their multiplication factors and possibly transpose marks. The matrices
+ * itself are named successively as they are encountered. If the same matrix
+ * is entered several times, it will be listed with different names.
*
* As an example, consider the following code:
* @code
*
* block.print_latex(std::cout);
* @endcode
- * The current function will then produce output of the following
- * kind:
+ * The current function will then produce output of the following kind:
* @code
* \begin{array}{cc}
* M0+2xM1^T & -3xM2-3xM3^T\\
* & M4^T
* \end{array}
* @endcode
- * Note how the individual blocks here are just numbered successively
- * as <code>M0</code> to <code>M4</code> and that the output misses
- * the fact that <code>M2</code> and <code>M3</code> are, in fact,
- * the same matrix. Nevertheless, the output at least gives some
- * kind of idea of the block structure of this matrix.
+ * Note how the individual blocks here are just numbered successively as
+ * <code>M0</code> to <code>M4</code> and that the output misses the fact
+ * that <code>M2</code> and <code>M3</code> are, in fact, the same matrix.
+ * Nevertheless, the output at least gives some kind of idea of the block
+ * structure of this matrix.
*/
template <class STREAM>
void print_latex (STREAM &out) const;
/**
* Internal data structure.
*
- * For each entry of a
- * BlockMatrixArray, its
- * position, matrix, prefix and
- * optional transposition must be
- * stored. This structure
- * encapsulates all of them.
+ * For each entry of a BlockMatrixArray, its position, matrix, prefix and
+ * optional transposition must be stored. This structure encapsulates all of
+ * them.
*
* @author Guido Kanschat, 2000, 2001
*/
{
public:
/**
- * Constructor initializing
- * all data fields. A
- * PointerMatrix object is
- * generated for
- * <tt>matrix</tt>.
+ * Constructor initializing all data fields. A PointerMatrix object is
+ * generated for <tt>matrix</tt>.
*/
template<class MATRIX>
Entry (const MATRIX &matrix,
double prefix, bool transpose);
/**
- * Copy constructor
- * invalidating the old
- * object. Since it is only
- * used for entering
- * temporary objects into a
- * vector, this is ok.
+ * Copy constructor invalidating the old object. Since it is only used for
+ * entering temporary objects into a vector, this is ok.
*
- * For a deep copy, we would
- * need a reproduction
- * operator in
+ * For a deep copy, we would need a reproduction operator in
* PointerMatixBase.
*/
Entry(const Entry &);
/**
- * Destructor, where we
- * delete the PointerMatrix
- * created by the
+ * Destructor, where we delete the PointerMatrix created by the
* constructor.
*/
~Entry();
/**
- * Row number in the block
- * matrix.
+ * Row number in the block matrix.
*/
size_type row;
/**
- * Column number in the block
- * matrix.
+ * Column number in the block matrix.
*/
size_type col;
/**
- * Factor in front of the matrix
- * block.
+ * Factor in front of the matrix block.
*/
double prefix;
/**
- * Indicates that matrix block
- * must be transposed for
- * multiplication.
+ * Indicates that matrix block must be transposed for multiplication.
*/
bool transpose;
};
/**
- * Array of block entries in the
- * matrix.
+ * Array of block entries in the matrix.
*/
std::vector<Entry> entries;
/**
* Inversion of a block-triangular matrix.
*
- * In this block matrix, the inverses of the diagonal blocks are
- * stored together with the off-diagonal blocks of a block
- * matrix. Then, forward or backward insertion is performed
- * block-wise. The diagonal blocks are NOT inverted for this purpose!
+ * In this block matrix, the inverses of the diagonal blocks are stored
+ * together with the off-diagonal blocks of a block matrix. Then, forward or
+ * backward insertion is performed block-wise. The diagonal blocks are NOT
+ * inverted for this purpose!
*
- * Like for all preconditioners, the preconditioning operation is
- * performed by the vmult() member function.
+ * Like for all preconditioners, the preconditioning operation is performed by
+ * the vmult() member function.
*
- * @note While block indices may be duplicated (see BlockMatrixArray)
- * to add blocks, this has to be used with caution, since
- * summing up the inverse of two blocks does not yield the inverse of
- * the sum. While the latter would be desirable, we can only perform
- * the first.
+ * @note While block indices may be duplicated (see BlockMatrixArray) to add
+ * blocks, this has to be used with caution, since summing up the inverse of
+ * two blocks does not yield the inverse of the sum. While the latter would be
+ * desirable, we can only perform the first.
*
- * The implementation may be a little clumsy, but it should be
- * sufficient as long as the block sizes are much larger than the
- * number of blocks.
+ * The implementation may be a little clumsy, but it should be sufficient as
+ * long as the block sizes are much larger than the number of blocks.
*
- * <h3>Example</h3>
- * Here, we document the second part of
- * <tt>examples/doxygen/block_matrix_array.cc</tt>. For the beginning
- * of this file, see BlockMatrixArray.
+ * <h3>Example</h3> Here, we document the second part of
+ * <tt>examples/doxygen/block_matrix_array.cc</tt>. For the beginning of this
+ * file, see BlockMatrixArray.
*
- * In order to set up the preconditioner, we have to compute the
- * inverses of the diagonal blocks ourselves. Since we used FullMatrix
- * objects, this is fairly easy.
- * @dontinclude block_matrix_array.cc
- * @skip Error
- * @until Cinv.invert
+ * In order to set up the preconditioner, we have to compute the inverses of
+ * the diagonal blocks ourselves. Since we used FullMatrix objects, this is
+ * fairly easy. @dontinclude block_matrix_array.cc @skip Error @until
+ * Cinv.invert
*
- * After creating a <i>2x2</i> BlockTrianglePrecondition object, we
- * only fill its diagonals. The scaling factor <i>1/2</i> used for
- * <tt>A</tt> is the reciprocal of the scaling factor used for the
- * <tt>matrix</tt> itself. Remember, this preconditioner actually
- * <b>multiplies</b> with the diagonal blocks.
- * @until Cinv
+ * After creating a <i>2x2</i> BlockTrianglePrecondition object, we only fill
+ * its diagonals. The scaling factor <i>1/2</i> used for <tt>A</tt> is the
+ * reciprocal of the scaling factor used for the <tt>matrix</tt> itself.
+ * Remember, this preconditioner actually <b>multiplies</b> with the diagonal
+ * blocks. @until Cinv
*
- * Now, we have a block Jacobi preconditioner, which is still
- * symmetric, since the blocks are symmetric. Therefore, we can still
- * use the preconditioned conjugate gradient method.
- * @until Error
+ * Now, we have a block Jacobi preconditioner, which is still symmetric, since
+ * the blocks are symmetric. Therefore, we can still use the preconditioned
+ * conjugate gradient method. @until Error
*
* Now, we enter the subdiagonal block. This is the same as in
- * <tt>matrix</tt>.
- * @until B2
+ * <tt>matrix</tt>. @until B2
*
- * Since the preconditioner is not symmetric anymore, we use the GMRES
- * method for solving.
- * @until Error
+ * Since the preconditioner is not symmetric anymore, we use the GMRES method
+ * for solving. @until Error
*
*
* @ingroup Preconditioners
typedef types::global_dof_index size_type;
/**
- * Default constructor creating a
- * useless object. initialize()
- * must be called before using
- * it.
+ * Default constructor creating a useless object. initialize() must be
+ * called before using it.
*/
BlockTrianglePrecondition ();
/**
- * Constructor. This matrix must be
- * block-quadratic, and
- * <tt>n_blocks</tt> is the
- * number of blocks in each direction.
+ * Constructor. This matrix must be block-quadratic, and <tt>n_blocks</tt>
+ * is the number of blocks in each direction.
*/
BlockTrianglePrecondition (const unsigned int n_blocks);
/**
- * Constructor. This matrix must be
- * block-quadratic. The additional
- * parameter allows for backward
- * insertion instead of forward.
+ * Constructor. This matrix must be block-quadratic. The additional
+ * parameter allows for backward insertion instead of forward.
*
* @deprecated The second argument is ignored. Use the constructor with only
* the first and third argument.
const bool backward = false) DEAL_II_DEPRECATED;
/**
- * Initialize object
- * completely. This is the
- * function to call for an object
- * created by the default
- * constructor.
+ * Initialize object completely. This is the function to call for an object
+ * created by the default constructor.
*
- * @deprecated The second argument
- * is ignored. Use the function without that argument.
+ * @deprecated The second argument is ignored. Use the function without that
+ * argument.
*/
void initialize (const unsigned int n_block_rows,
VectorMemory<Vector<number> > &mem,
const bool backward = false) DEAL_II_DEPRECATED;
/**
- * Resize preconditioner to a new
- * size and clear all blocks.
+ * Resize preconditioner to a new size and clear all blocks.
*/
void reinit (const unsigned int n_block_rows);
/**
- * Enter a block. This calls
- * BlockMatrixArray::enter(). Remember
- * that the diagonal blocks
- * should actually be inverse
- * matrices or preconditioners.
+ * Enter a block. This calls BlockMatrixArray::enter(). Remember that the
+ * diagonal blocks should actually be inverse matrices or preconditioners.
*/
template <class MATRIX>
void enter (const MATRIX &matrix,
const bool transpose = false);
/**
- * Enter a block. This calls
- * BlockMatrixArray::enter_aux(). Remember
- * that the diagonal blocks
- * should actually be inverse
- * matrices or preconditioners.
+ * Enter a block. This calls BlockMatrixArray::enter_aux(). Remember that
+ * the diagonal blocks should actually be inverse matrices or
+ * preconditioners.
*
- * @deprecated The first
- * argument is ignored. Use
- * enter() instead.
+ * @deprecated The first argument is ignored. Use enter() instead.
*/
template <class MATRIX>
void enter_aux (VectorMemory<Vector<double> > &mem,
const BlockVector<number> &src) const;
/**
- * Preconditioning
- * adding to <tt>dst</tt>.
+ * Preconditioning adding to <tt>dst</tt>.
*/
void vmult_add (BlockVector<number> &dst,
const BlockVector<number> &src) const;
const BlockVector<number> &src) const;
/**
- * Transposed preconditioning
- * adding to <tt>dst</tt>.
+ * Transposed preconditioning adding to <tt>dst</tt>.
*/
void Tvmult_add (BlockVector<number> &dst,
const BlockVector<number> &src) const;
using BlockMatrixArray<number>::Subscriptor::subscribe;
using BlockMatrixArray<number>::Subscriptor::unsubscribe;
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
- * Each diagonal block must
- * contain one and only one
- * matrix. If this exception is
- * thrown, you did not enter a
- * matrix here.
+ * Each diagonal block must contain one and only one matrix. If this
+ * exception is thrown, you did not enter a matrix here.
*/
DeclException1(ExcNoDiagonal,
size_type,
<< "No diagonal entry was added for block " << arg1);
/**
- * Each diagonal block must
- * contain one and only one
- * matrix. If this exception is
- * thrown, you entered a second
- * matrix here.
+ * Each diagonal block must contain one and only one matrix. If this
+ * exception is thrown, you entered a second matrix here.
*/
DeclException1(ExcMultipleDiagonal,
size_type,
//@}
private:
/**
- * Add all off-diagonal
- * contributions and return the
- * entry of the diagonal element
- * for one row.
+ * Add all off-diagonal contributions and return the entry of the diagonal
+ * element for one row.
*/
void do_row (BlockVector<number> &dst,
size_type row_num) const;
namespace BlockMatrixIterators
{
/**
- * Base class for block matrix
- * accessors, implementing the
- * stepping through a matrix.
+ * Base class for block matrix accessors, implementing the stepping through
+ * a matrix.
*/
template <class BlockMatrix>
class AccessorBase
typedef types::global_dof_index size_type;
/**
- * Typedef the value type of the
- * matrix we point into.
+ * Typedef the value type of the matrix we point into.
*/
typedef typename BlockMatrix::value_type value_type;
/**
- * Initialize data fields to
- * default values.
+ * Initialize data fields to default values.
*/
AccessorBase ();
/**
- * Block row of the
- * element represented by
- * this object.
+ * Block row of the element represented by this object.
*/
unsigned int block_row() const;
/**
- * Block column of the
- * element represented by
- * this object.
+ * Block column of the element represented by this object.
*/
unsigned int block_column() const;
protected:
/**
- * Block row into which we presently
- * point.
+ * Block row into which we presently point.
*/
unsigned int row_block;
/**
- * Block column into which we
- * presently point.
+ * Block column into which we presently point.
*/
unsigned int col_block;
/**
- * Let the iterator class be a
- * friend.
+ * Let the iterator class be a friend.
*/
template <typename>
friend class MatrixIterator;
/**
- * Accessor classes in
- * block matrices.
+ * Accessor classes in block matrices.
*/
template <class BlockMatrix, bool ConstNess>
class Accessor;
/**
- * Block matrix accessor for non
- * const matrices.
+ * Block matrix accessor for non const matrices.
*/
template <class BlockMatrix>
class Accessor<BlockMatrix, false>
typedef types::global_dof_index size_type;
/**
- * Type of the matrix used in
- * this accessor.
+ * Type of the matrix used in this accessor.
*/
typedef BlockMatrix MatrixType;
/**
- * Typedef the value type of the
- * matrix we point into.
+ * Typedef the value type of the matrix we point into.
*/
typedef typename BlockMatrix::value_type value_type;
/**
- * Constructor. Since we use
- * accessors only for read
- * access, a const matrix
- * pointer is sufficient.
+ * Constructor. Since we use accessors only for read access, a const
+ * matrix pointer is sufficient.
*
- * Place the iterator at the
- * beginning of the given row of the
- * matrix, or create the end pointer
- * if @p row equals the total number
- * of rows in the matrix.
+ * Place the iterator at the beginning of the given row of the matrix, or
+ * create the end pointer if @p row equals the total number of rows in the
+ * matrix.
*/
Accessor (BlockMatrix *m,
const size_type row,
const size_type col);
/**
- * Row number of the element
- * represented by this
- * object.
+ * Row number of the element represented by this object.
*/
size_type row() const;
/**
- * Column number of the
- * element represented by
- * this object.
+ * Column number of the element represented by this object.
*/
size_type column() const;
/**
- * Value of the entry at the
- * current position.
+ * Value of the entry at the current position.
*/
value_type value() const;
BlockMatrix *matrix;
/**
- * Iterator of the underlying matrix
- * class.
+ * Iterator of the underlying matrix class.
*/
typename BlockMatrix::BlockType::iterator base_iterator;
void advance ();
/**
- * Compare this accessor with another
- * one for equality.
+ * Compare this accessor with another one for equality.
*/
bool operator == (const Accessor &a) const;
};
/**
- * Block matrix accessor for
- * constant matrices, implementing
- * the stepping through a matrix.
+ * Block matrix accessor for constant matrices, implementing the stepping
+ * through a matrix.
*/
template <class BlockMatrix>
class Accessor<BlockMatrix, true>
typedef types::global_dof_index size_type;
/**
- * Type of the matrix used in
- * this accessor.
+ * Type of the matrix used in this accessor.
*/
typedef const BlockMatrix MatrixType;
/**
- * Typedef the value type of the
- * matrix we point into.
+ * Typedef the value type of the matrix we point into.
*/
typedef typename BlockMatrix::value_type value_type;
/**
- * Constructor. Since we use
- * accessors only for read
- * access, a const matrix
- * pointer is sufficient.
+ * Constructor. Since we use accessors only for read access, a const
+ * matrix pointer is sufficient.
*
- * Place the iterator at the
- * beginning of the given row of the
- * matrix, or create the end pointer
- * if @p row equals the total number
- * of rows in the matrix.
+ * Place the iterator at the beginning of the given row of the matrix, or
+ * create the end pointer if @p row equals the total number of rows in the
+ * matrix.
*/
Accessor (const BlockMatrix *m,
const size_type row,
const size_type col);
/**
- * Initalize const accessor
- * from non const accessor.
+ * Initalize const accessor from non const accessor.
*/
Accessor(const Accessor<BlockMatrix, false> &);
/**
- * Row number of the element
- * represented by this
- * object.
+ * Row number of the element represented by this object.
*/
size_type row() const;
/**
- * Column number of the
- * element represented by
- * this object.
+ * Column number of the element represented by this object.
*/
size_type column() const;
/**
- * Value of the entry at the
- * current position.
+ * Value of the entry at the current position.
*/
value_type value() const;
protected:
const BlockMatrix *matrix;
/**
- * Iterator of the underlying matrix
- * class.
+ * Iterator of the underlying matrix class.
*/
typename BlockMatrix::BlockType::const_iterator base_iterator;
void advance ();
/**
- * Compare this accessor with another
- * one for equality.
+ * Compare this accessor with another one for equality.
*/
bool operator == (const Accessor &a) const;
/**
- * Let the iterator class be a
- * friend.
+ * Let the iterator class be a friend.
*/
template <typename>
friend class dealii::MatrixIterator;
* blocks of this matrix is the type of the template argument, and can, for
* example be the usual SparseMatrix or PETScWrappers::SparseMatrix.
*
- * In addition to the usual matrix access and linear algebra
- * functions, there are functions block() which allow access to the
- * different blocks of the matrix. This may, for example, be of help
- * when you want to implement Schur complement methods, or block
- * preconditioners, where each block belongs to a specific component
- * of the equation you are presently discretizing.
+ * In addition to the usual matrix access and linear algebra functions, there
+ * are functions block() which allow access to the different blocks of the
+ * matrix. This may, for example, be of help when you want to implement Schur
+ * complement methods, or block preconditioners, where each block belongs to a
+ * specific component of the equation you are presently discretizing.
*
- * Note that the numbers of blocks and rows are implicitly determined
- * by the sparsity pattern objects used.
+ * Note that the numbers of blocks and rows are implicitly determined by the
+ * sparsity pattern objects used.
*
* Objects of this type are frequently used when a system of differential
- * equations has solutions with variables that fall into different
- * classes. For example, solutions of the Stokes or Navier-Stokes equations
- * have @p dim velocity components and one pressure component. In this case,
- * it may make sense to consider the linear system of equations as a system of
- * 2x2 blocks, and one can construct preconditioners or solvers based on this
- * 2x2 block structure. This class can help you in these cases, as it allows
- * to view the matrix alternatively as one big matrix, or as a number of
- * individual blocks.
+ * equations has solutions with variables that fall into different classes.
+ * For example, solutions of the Stokes or Navier-Stokes equations have @p dim
+ * velocity components and one pressure component. In this case, it may make
+ * sense to consider the linear system of equations as a system of 2x2 blocks,
+ * and one can construct preconditioners or solvers based on this 2x2 block
+ * structure. This class can help you in these cases, as it allows to view the
+ * matrix alternatively as one big matrix, or as a number of individual
+ * blocks.
*
*
* <h3>Inheriting from this class</h3>
*
*
* Most of the functions take a vector or block vector argument. These
- * functions can, in general, only successfully be compiled if the
- * individual blocks of this matrix implement the respective functions
- * operating on the vector type in question. For example, if you have
- * a block sparse matrix over deal.II SparseMatrix objects, then you
- * will likely not be able to form the matrix-vector multiplication
- * with a block vector over PETScWrappers::SparseMatrix objects. If
- * you attempt anyway, you will likely get a number of compiler
- * errors.
+ * functions can, in general, only successfully be compiled if the individual
+ * blocks of this matrix implement the respective functions operating on the
+ * vector type in question. For example, if you have a block sparse matrix
+ * over deal.II SparseMatrix objects, then you will likely not be able to form
+ * the matrix-vector multiplication with a block vector over
+ * PETScWrappers::SparseMatrix objects. If you attempt anyway, you will likely
+ * get a number of compiler errors.
*
* @note Instantiations for this template are provided for <tt>@<float@> and
* @<double@></tt>; others can be generated in application programs (see the
{
public:
/**
- * Typedef the type of the underlying
- * matrix.
+ * Typedef the type of the underlying matrix.
*/
typedef MatrixType BlockType;
/**
- * Type of matrix entries. In analogy to
- * the STL container classes.
+ * Type of matrix entries. In analogy to the STL container classes.
*/
typedef typename BlockType::value_type value_type;
typedef value_type *pointer;
~BlockMatrixBase ();
/**
- * Copy the given matrix to this
- * one. The operation throws an
- * error if the sparsity patterns
- * of the two involved matrices
- * do not point to the same
- * object, since in this case the
- * copy operation is
- * cheaper. Since this operation
- * is notheless not for free, we
- * do not make it available
- * through operator=(), since
- * this may lead to unwanted
- * usage, e.g. in copy arguments
- * to functions, which should
- * really be arguments by
- * reference.
+ * Copy the given matrix to this one. The operation throws an error if the
+ * sparsity patterns of the two involved matrices do not point to the same
+ * object, since in this case the copy operation is cheaper. Since this
+ * operation is notheless not for free, we do not make it available through
+ * operator=(), since this may lead to unwanted usage, e.g. in copy
+ * arguments to functions, which should really be arguments by reference.
*
- * The source matrix may be a
- * matrix of arbitrary type, as
- * long as its data type is
- * convertible to the data type
- * of this matrix.
+ * The source matrix may be a matrix of arbitrary type, as long as its data
+ * type is convertible to the data type of this matrix.
*
- * The function returns a
- * reference to <tt>this</tt>.
+ * The function returns a reference to <tt>this</tt>.
*/
template <class BlockMatrixType>
BlockMatrixBase &
copy_from (const BlockMatrixType &source);
/**
- * Access the block with the
- * given coordinates.
+ * Access the block with the given coordinates.
*/
BlockType &
block (const unsigned int row,
/**
- * Access the block with the
- * given coordinates. Version for
- * constant objects.
+ * Access the block with the given coordinates. Version for constant
+ * objects.
*/
const BlockType &
block (const unsigned int row,
const unsigned int column) const;
/**
- * Return the dimension of the
- * image space. To remember: the
- * matrix is of dimension
- * $m \times n$.
+ * Return the dimension of the image space. To remember: the matrix is of
+ * dimension $m \times n$.
*/
size_type m () const;
/**
- * Return the dimension of the
- * range space. To remember: the
- * matrix is of dimension
- * $m \times n$.
+ * Return the dimension of the range space. To remember: the matrix is of
+ * dimension $m \times n$.
*/
size_type n () const;
/**
- * Return the number of blocks in
- * a column. Returns zero if no
- * sparsity pattern is presently
- * associated to this matrix.
+ * Return the number of blocks in a column. Returns zero if no sparsity
+ * pattern is presently associated to this matrix.
*/
unsigned int n_block_rows () const;
/**
- * Return the number of blocks in
- * a row. Returns zero if no
- * sparsity pattern is presently
- * associated to this matrix.
+ * Return the number of blocks in a row. Returns zero if no sparsity pattern
+ * is presently associated to this matrix.
*/
unsigned int n_block_cols () const;
/**
- * Set the element <tt>(i,j)</tt>
- * to <tt>value</tt>. Throws an
- * error if the entry does not
- * exist or if <tt>value</tt> is
- * not a finite number. Still, it
- * is allowed to store zero
- * values in non-existent fields.
+ * Set the element <tt>(i,j)</tt> to <tt>value</tt>. Throws an error if the
+ * entry does not exist or if <tt>value</tt> is not a finite number. Still,
+ * it is allowed to store zero values in non-existent fields.
*/
void set (const size_type i,
const size_type j,
const value_type value);
/**
- * Set all elements given in a
- * FullMatrix into the sparse matrix
- * locations given by
- * <tt>indices</tt>. In other words,
- * this function writes the elements
- * in <tt>full_matrix</tt> into the
- * calling matrix, using the
- * local-to-global indexing specified
- * by <tt>indices</tt> for both the
- * rows and the columns of the
- * matrix. This function assumes a
- * quadratic sparse matrix and a
- * quadratic full_matrix, the usual
- * situation in FE calculations.
+ * Set all elements given in a FullMatrix into the sparse matrix locations
+ * given by <tt>indices</tt>. In other words, this function writes the
+ * elements in <tt>full_matrix</tt> into the calling matrix, using the
+ * local-to-global indexing specified by <tt>indices</tt> for both the rows
+ * and the columns of the matrix. This function assumes a quadratic sparse
+ * matrix and a quadratic full_matrix, the usual situation in FE
+ * calculations.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> can be
- * used to specify whether zero
- * values should be set anyway or
- * they should be filtered away (and
- * not change the previous content in
- * the respective element if it
- * exists). The default value is
- * <tt>false</tt>, i.e., even zero
- * values are treated.
+ * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+ * whether zero values should be set anyway or they should be filtered away
+ * (and not change the previous content in the respective element if it
+ * exists). The default value is <tt>false</tt>, i.e., even zero values are
+ * treated.
*/
template <typename number>
void set (const std::vector<size_type> &indices,
const bool elide_zero_values = false);
/**
- * Same function as before, but now
- * including the possibility to use
- * rectangular full_matrices and
- * different local-to-global indexing
- * on rows and columns, respectively.
+ * Same function as before, but now including the possibility to use
+ * rectangular full_matrices and different local-to-global indexing on rows
+ * and columns, respectively.
*/
template <typename number>
void set (const std::vector<size_type> &row_indices,
const bool elide_zero_values = false);
/**
- * Set several elements in the
- * specified row of the matrix with
- * column indices as given by
- * <tt>col_indices</tt> to the
- * respective value.
+ * Set several elements in the specified row of the matrix with column
+ * indices as given by <tt>col_indices</tt> to the respective value.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> can be
- * used to specify whether zero
- * values should be set anyway or
- * they should be filtered away (and
- * not change the previous content in
- * the respective element if it
- * exists). The default value is
- * <tt>false</tt>, i.e., even zero
- * values are treated.
+ * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+ * whether zero values should be set anyway or they should be filtered away
+ * (and not change the previous content in the respective element if it
+ * exists). The default value is <tt>false</tt>, i.e., even zero values are
+ * treated.
*/
template <typename number>
void set (const size_type row,
const bool elide_zero_values = false);
/**
- * Set several elements to values
- * given by <tt>values</tt> in a
- * given row in columns given by
- * col_indices into the sparse
- * matrix.
+ * Set several elements to values given by <tt>values</tt> in a given row in
+ * columns given by col_indices into the sparse matrix.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> can be
- * used to specify whether zero
- * values should be inserted anyway
- * or they should be filtered
- * away. The default value is
- * <tt>false</tt>, i.e., even zero
- * values are inserted/replaced.
+ * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+ * whether zero values should be inserted anyway or they should be filtered
+ * away. The default value is <tt>false</tt>, i.e., even zero values are
+ * inserted/replaced.
*/
template <typename number>
void set (const size_type row,
const bool elide_zero_values = false);
/**
- * Add <tt>value</tt> to the
- * element (<i>i,j</i>). Throws
- * an error if the entry does not
- * exist or if <tt>value</tt> is
- * not a finite number. Still, it
- * is allowed to store zero
- * values in non-existent fields.
+ * Add <tt>value</tt> to the element (<i>i,j</i>). Throws an error if the
+ * entry does not exist or if <tt>value</tt> is not a finite number. Still,
+ * it is allowed to store zero values in non-existent fields.
*/
void add (const size_type i,
const size_type j,
const value_type value);
/**
- * Add all elements given in a
- * FullMatrix<double> into sparse
- * matrix locations given by
- * <tt>indices</tt>. In other words,
- * this function adds the elements in
- * <tt>full_matrix</tt> to the
- * respective entries in calling
- * matrix, using the local-to-global
- * indexing specified by
- * <tt>indices</tt> for both the rows
- * and the columns of the
- * matrix. This function assumes a
- * quadratic sparse matrix and a
- * quadratic full_matrix, the usual
- * situation in FE calculations.
+ * Add all elements given in a FullMatrix<double> into sparse matrix
+ * locations given by <tt>indices</tt>. In other words, this function adds
+ * the elements in <tt>full_matrix</tt> to the respective entries in calling
+ * matrix, using the local-to-global indexing specified by <tt>indices</tt>
+ * for both the rows and the columns of the matrix. This function assumes a
+ * quadratic sparse matrix and a quadratic full_matrix, the usual situation
+ * in FE calculations.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> can be
- * used to specify whether zero
- * values should be added anyway or
- * these should be filtered away and
- * only non-zero data is added. The
- * default value is <tt>true</tt>,
- * i.e., zero values won't be added
- * into the matrix.
+ * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+ * whether zero values should be added anyway or these should be filtered
+ * away and only non-zero data is added. The default value is <tt>true</tt>,
+ * i.e., zero values won't be added into the matrix.
*/
template <typename number>
void add (const std::vector<size_type> &indices,
const bool elide_zero_values = true);
/**
- * Same function as before, but now
- * including the possibility to use
- * rectangular full_matrices and
- * different local-to-global indexing
- * on rows and columns, respectively.
+ * Same function as before, but now including the possibility to use
+ * rectangular full_matrices and different local-to-global indexing on rows
+ * and columns, respectively.
*/
template <typename number>
void add (const std::vector<size_type> &row_indices,
const bool elide_zero_values = true);
/**
- * Set several elements in the
- * specified row of the matrix with
- * column indices as given by
- * <tt>col_indices</tt> to the
- * respective value.
+ * Set several elements in the specified row of the matrix with column
+ * indices as given by <tt>col_indices</tt> to the respective value.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> can be
- * used to specify whether zero
- * values should be added anyway or
- * these should be filtered away and
- * only non-zero data is added. The
- * default value is <tt>true</tt>,
- * i.e., zero values won't be added
- * into the matrix.
+ * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+ * whether zero values should be added anyway or these should be filtered
+ * away and only non-zero data is added. The default value is <tt>true</tt>,
+ * i.e., zero values won't be added into the matrix.
*/
template <typename number>
void add (const size_type row,
const bool elide_zero_values = true);
/**
- * Add an array of values given by
- * <tt>values</tt> in the given
- * global matrix row at columns
- * specified by col_indices in the
- * sparse matrix.
+ * Add an array of values given by <tt>values</tt> in the given global
+ * matrix row at columns specified by col_indices in the sparse matrix.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> can be
- * used to specify whether zero
- * values should be added anyway or
- * these should be filtered away and
- * only non-zero data is added. The
- * default value is <tt>true</tt>,
- * i.e., zero values won't be added
- * into the matrix.
+ * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+ * whether zero values should be added anyway or these should be filtered
+ * away and only non-zero data is added. The default value is <tt>true</tt>,
+ * i.e., zero values won't be added into the matrix.
*/
template <typename number>
void add (const size_type row,
const bool col_indices_are_sorted = false);
/**
- * Add <tt>matrix</tt> scaled by
- * <tt>factor</tt> to this matrix,
- * i.e. the matrix
- * <tt>factor*matrix</tt> is added to
- * <tt>this</tt>. If the sparsity
- * pattern of the calling matrix does
- * not contain all the elements in
- * the sparsity pattern of the input
- * matrix, this function will throw
- * an exception.
+ * Add <tt>matrix</tt> scaled by <tt>factor</tt> to this matrix, i.e. the
+ * matrix <tt>factor*matrix</tt> is added to <tt>this</tt>. If the sparsity
+ * pattern of the calling matrix does not contain all the elements in the
+ * sparsity pattern of the input matrix, this function will throw an
+ * exception.
*/
void add (const value_type factor,
const BlockMatrixBase<MatrixType> &matrix);
/**
- * Return the value of the entry
- * (i,j). This may be an
- * expensive operation and you
- * should always take care where
- * to call this function. In
- * order to avoid abuse, this
- * function throws an exception
- * if the wanted element does not
- * exist in the matrix.
+ * Return the value of the entry (i,j). This may be an expensive operation
+ * and you should always take care where to call this function. In order to
+ * avoid abuse, this function throws an exception if the wanted element does
+ * not exist in the matrix.
*/
value_type operator () (const size_type i,
const size_type j) const;
/**
- * This function is mostly like
- * operator()() in that it
- * returns the value of the
- * matrix entry <tt>(i,j)</tt>. The only
- * difference is that if this
- * entry does not exist in the
- * sparsity pattern, then instead
- * of raising an exception, zero
- * is returned. While this may be
- * convenient in some cases, note
- * that it is simple to write
- * algorithms that are slow
- * compared to an optimal
- * solution, since the sparsity
- * of the matrix is not used.
+ * This function is mostly like operator()() in that it returns the value of
+ * the matrix entry <tt>(i,j)</tt>. The only difference is that if this
+ * entry does not exist in the sparsity pattern, then instead of raising an
+ * exception, zero is returned. While this may be convenient in some cases,
+ * note that it is simple to write algorithms that are slow compared to an
+ * optimal solution, since the sparsity of the matrix is not used.
*/
value_type el (const size_type i,
const size_type j) const;
/**
- * Return the main diagonal element in
- * the <i>i</i>th row. This function
- * throws an error if the matrix is not
- * quadratic and also if the diagonal
- * blocks of the matrix are not
- * quadratic.
+ * Return the main diagonal element in the <i>i</i>th row. This function
+ * throws an error if the matrix is not quadratic and also if the diagonal
+ * blocks of the matrix are not quadratic.
*
- * This function is considerably
- * faster than the operator()(),
- * since for quadratic matrices, the
- * diagonal entry may be the
- * first to be stored in each row
- * and access therefore does not
- * involve searching for the
- * right column number.
+ * This function is considerably faster than the operator()(), since for
+ * quadratic matrices, the diagonal entry may be the first to be stored in
+ * each row and access therefore does not involve searching for the right
+ * column number.
*/
value_type diag_element (const size_type i) const;
/**
- * Call the compress() function on all
- * the subblocks of the matrix.
- *
- *
- * See @ref GlossCompress "Compressing
- * distributed objects" for more
- * information.
+ * Call the compress() function on all the subblocks of the matrix.
+ *
+ *
+ * See @ref GlossCompress "Compressing distributed objects" for more
+ * information.
*/
void compress (::dealii::VectorOperation::values operation);
void compress () DEAL_II_DEPRECATED;
/**
- * Multiply the entire matrix by a
- * fixed factor.
+ * Multiply the entire matrix by a fixed factor.
*/
BlockMatrixBase &operator *= (const value_type factor);
/**
- * Divide the entire matrix by a
- * fixed factor.
+ * Divide the entire matrix by a fixed factor.
*/
BlockMatrixBase &operator /= (const value_type factor);
/**
- * Adding Matrix-vector
- * multiplication. Add $M*src$ on
- * $dst$ with $M$ being this
- * matrix.
+ * Adding Matrix-vector multiplication. Add $M*src$ on $dst$ with $M$ being
+ * this matrix.
*/
template <class BlockVectorType>
void vmult_add (BlockVectorType &dst,
const BlockVectorType &src) const;
/**
- * Adding Matrix-vector
- * multiplication. Add
- * <i>M<sup>T</sup>src</i> to
- * <i>dst</i> with <i>M</i> being
- * this matrix. This function
- * does the same as vmult_add()
- * but takes the transposed
- * matrix.
+ * Adding Matrix-vector multiplication. Add <i>M<sup>T</sup>src</i> to
+ * <i>dst</i> with <i>M</i> being this matrix. This function does the same
+ * as vmult_add() but takes the transposed matrix.
*/
template <class BlockVectorType>
void Tvmult_add (BlockVectorType &dst,
const BlockVectorType &src) const;
/**
- * Return the norm of the vector
- * <i>v</i> with respect to the
- * norm induced by this matrix,
- * i.e. <i>v<sup>T</sup>Mv)</i>. This
- * is useful, e.g. in the finite
- * element context, where the
- * <i>L<sup>T</sup></i>-norm of a
- * function equals the matrix
- * norm with respect to the mass
- * matrix of the vector
- * representing the nodal values
- * of the finite element
- * function. Note that even
- * though the function's name
- * might suggest something
- * different, for historic
- * reasons not the norm but its
- * square is returned, as defined
+ * Return the norm of the vector <i>v</i> with respect to the norm induced
+ * by this matrix, i.e. <i>v<sup>T</sup>Mv)</i>. This is useful, e.g. in the
+ * finite element context, where the <i>L<sup>T</sup></i>-norm of a function
+ * equals the matrix norm with respect to the mass matrix of the vector
+ * representing the nodal values of the finite element function. Note that
+ * even though the function's name might suggest something different, for
+ * historic reasons not the norm but its square is returned, as defined
* above by the scalar product.
*
- * Obviously, the matrix needs to
- * be square for this operation.
+ * Obviously, the matrix needs to be square for this operation.
*/
template <class BlockVectorType>
value_type
matrix_norm_square (const BlockVectorType &v) const;
/**
- * Compute the matrix scalar
- * product $\left(u,Mv\right)$.
+ * Compute the matrix scalar product $\left(u,Mv\right)$.
*/
template <class BlockVectorType>
value_type
const BlockVectorType &v) const;
/**
- * Compute the residual
- * <i>r=b-Ax</i>. Write the
- * residual into <tt>dst</tt>.
+ * Compute the residual <i>r=b-Ax</i>. Write the residual into <tt>dst</tt>.
*/
template <class BlockVectorType>
value_type residual (BlockVectorType &dst,
const BlockVectorType &b) const;
/**
- * Print the matrix to the given
- * stream, using the format
- * <tt>(line,col) value</tt>, i.e. one
- * nonzero entry of the matrix per
- * line. The optional flag outputs the
- * sparsity pattern in a different style
- * according to the underlying
- * sparsematrix type.
+ * Print the matrix to the given stream, using the format <tt>(line,col)
+ * value</tt>, i.e. one nonzero entry of the matrix per line. The optional
+ * flag outputs the sparsity pattern in a different style according to the
+ * underlying sparsematrix type.
*/
void print (std::ostream &out,
const bool alternative_output = false) const;
/**
- * STL-like iterator with the
- * first entry.
+ * STL-like iterator with the first entry.
*/
iterator begin ();
iterator end ();
/**
- * STL-like iterator with the
- * first entry of row <tt>r</tt>.
+ * STL-like iterator with the first entry of row <tt>r</tt>.
*/
iterator begin (const size_type r);
*/
iterator end (const size_type r);
/**
- * STL-like iterator with the
- * first entry.
+ * STL-like iterator with the first entry.
*/
const_iterator begin () const;
const_iterator end () const;
/**
- * STL-like iterator with the
- * first entry of row <tt>r</tt>.
+ * STL-like iterator with the first entry of row <tt>r</tt>.
*/
const_iterator begin (const size_type r) const;
const_iterator end (const size_type r) const;
/**
- * Return a reference to the underlying
- * BlockIndices data of the rows.
+ * Return a reference to the underlying BlockIndices data of the rows.
*/
const BlockIndices &get_row_indices () const;
/**
- * Return a reference to the underlying
- * BlockIndices data of the columns.
+ * Return a reference to the underlying BlockIndices data of the columns.
*/
const BlockIndices &get_column_indices () const;
/**
- * Determine an estimate for the memory
- * consumption (in bytes) of this
- * object. Note that only the memory
- * reserved on the current processor is
- * returned in case this is called in
- * an MPI-based program.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object. Note that only the memory reserved on the current processor is
+ * returned in case this is called in an MPI-based program.
*/
std::size_t memory_consumption () const;
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
//@}
protected:
/**
- * Release all memory and return
- * to a state just like after
- * having called the default
- * constructor. It also forgets
- * the sparsity pattern it was
+ * Release all memory and return to a state just like after having called
+ * the default constructor. It also forgets the sparsity pattern it was
* previously tied to.
*
- * This calls clear for all
- * sub-matrices and then resets this
- * object to have no blocks at all.
+ * This calls clear for all sub-matrices and then resets this object to have
+ * no blocks at all.
*
- * This function is protected
- * since it may be necessary to
- * release additional structures.
- * A derived class can make it
- * public again, if it is
+ * This function is protected since it may be necessary to release
+ * additional structures. A derived class can make it public again, if it is
* sufficient.
*/
void clear ();
Table<2,SmartPointer<BlockType, BlockMatrixBase<MatrixType> > > sub_objects;
/**
- * This function collects the
- * sizes of the sub-objects and
- * stores them in internal
- * arrays, in order to be able to
- * relay global indices into the
- * matrix to indices into the
- * subobjects. You *must* call
- * this function each time after
- * you have changed the size of
- * the sub-objects.
+ * This function collects the sizes of the sub-objects and stores them in
+ * internal arrays, in order to be able to relay global indices into the
+ * matrix to indices into the subobjects. You *must* call this function each
+ * time after you have changed the size of the sub-objects.
*
- * Derived classes should call this
- * function whenever the size of the
- * sub-objects has changed and the @p
- * X_block_indices arrays need to be
- * updated.
+ * Derived classes should call this function whenever the size of the sub-
+ * objects has changed and the @p X_block_indices arrays need to be updated.
*
- * Note that this function is not public
- * since not all derived classes need to
- * export its interface. For example, for
- * the usual deal.II SparseMatrix class,
- * the sizes are implicitly determined
- * whenever reinit() is called, and
- * individual blocks cannot be
- * resized. For that class, this function
- * therefore does not have to be
- * public. On the other hand, for the
- * PETSc classes, there is no associated
- * sparsity pattern object that
- * determines the block sizes, and for
- * these the function needs to be
- * publicly available. These classes
- * therefore export this function.
+ * Note that this function is not public since not all derived classes need
+ * to export its interface. For example, for the usual deal.II SparseMatrix
+ * class, the sizes are implicitly determined whenever reinit() is called,
+ * and individual blocks cannot be resized. For that class, this function
+ * therefore does not have to be public. On the other hand, for the PETSc
+ * classes, there is no associated sparsity pattern object that determines
+ * the block sizes, and for these the function needs to be publicly
+ * available. These classes therefore export this function.
*/
void collect_sizes ();
/**
- * Matrix-vector multiplication:
- * let $dst = M*src$ with $M$
- * being this matrix.
+ * Matrix-vector multiplication: let $dst = M*src$ with $M$ being this
+ * matrix.
*
- * Due to problems with deriving template
- * arguments between the block and
- * non-block versions of the vmult/Tvmult
- * functions, the actual functions are
- * implemented in derived classes, with
- * implementations forwarding the calls
- * to the implementations provided here
- * under a unique name for which template
- * arguments can be derived by the
- * compiler.
+ * Due to problems with deriving template arguments between the block and
+ * non-block versions of the vmult/Tvmult functions, the actual functions
+ * are implemented in derived classes, with implementations forwarding the
+ * calls to the implementations provided here under a unique name for which
+ * template arguments can be derived by the compiler.
*/
template <class BlockVectorType>
void vmult_block_block (BlockVectorType &dst,
const BlockVectorType &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block column.
+ * Matrix-vector multiplication. Just like the previous function, but only
+ * applicable if the matrix has only one block column.
*
- * Due to problems with deriving template
- * arguments between the block and
- * non-block versions of the vmult/Tvmult
- * functions, the actual functions are
- * implemented in derived classes, with
- * implementations forwarding the calls
- * to the implementations provided here
- * under a unique name for which template
- * arguments can be derived by the
- * compiler.
+ * Due to problems with deriving template arguments between the block and
+ * non-block versions of the vmult/Tvmult functions, the actual functions
+ * are implemented in derived classes, with implementations forwarding the
+ * calls to the implementations provided here under a unique name for which
+ * template arguments can be derived by the compiler.
*/
template <class BlockVectorType,
class VectorType>
const VectorType &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block row.
+ * Matrix-vector multiplication. Just like the previous function, but only
+ * applicable if the matrix has only one block row.
*
- * Due to problems with deriving template
- * arguments between the block and
- * non-block versions of the vmult/Tvmult
- * functions, the actual functions are
- * implemented in derived classes, with
- * implementations forwarding the calls
- * to the implementations provided here
- * under a unique name for which template
- * arguments can be derived by the
- * compiler.
+ * Due to problems with deriving template arguments between the block and
+ * non-block versions of the vmult/Tvmult functions, the actual functions
+ * are implemented in derived classes, with implementations forwarding the
+ * calls to the implementations provided here under a unique name for which
+ * template arguments can be derived by the compiler.
*/
template <class BlockVectorType,
class VectorType>
const BlockVectorType &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block.
+ * Matrix-vector multiplication. Just like the previous function, but only
+ * applicable if the matrix has only one block.
*
- * Due to problems with deriving template
- * arguments between the block and
- * non-block versions of the vmult/Tvmult
- * functions, the actual functions are
- * implemented in derived classes, with
- * implementations forwarding the calls
- * to the implementations provided here
- * under a unique name for which template
- * arguments can be derived by the
- * compiler.
+ * Due to problems with deriving template arguments between the block and
+ * non-block versions of the vmult/Tvmult functions, the actual functions
+ * are implemented in derived classes, with implementations forwarding the
+ * calls to the implementations provided here under a unique name for which
+ * template arguments can be derived by the compiler.
*/
template <class VectorType>
void vmult_nonblock_nonblock (VectorType &dst,
const VectorType &src) const;
/**
- * Matrix-vector multiplication:
- * let $dst = M^T*src$ with $M$
- * being this matrix. This
- * function does the same as
- * vmult() but takes the
- * transposed matrix.
+ * Matrix-vector multiplication: let $dst = M^T*src$ with $M$ being this
+ * matrix. This function does the same as vmult() but takes the transposed
+ * matrix.
*
- * Due to problems with deriving template
- * arguments between the block and
- * non-block versions of the vmult/Tvmult
- * functions, the actual functions are
- * implemented in derived classes, with
- * implementations forwarding the calls
- * to the implementations provided here
- * under a unique name for which template
- * arguments can be derived by the
- * compiler.
+ * Due to problems with deriving template arguments between the block and
+ * non-block versions of the vmult/Tvmult functions, the actual functions
+ * are implemented in derived classes, with implementations forwarding the
+ * calls to the implementations provided here under a unique name for which
+ * template arguments can be derived by the compiler.
*/
template <class BlockVectorType>
void Tvmult_block_block (BlockVectorType &dst,
const BlockVectorType &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block row.
+ * Matrix-vector multiplication. Just like the previous function, but only
+ * applicable if the matrix has only one block row.
*
- * Due to problems with deriving template
- * arguments between the block and
- * non-block versions of the vmult/Tvmult
- * functions, the actual functions are
- * implemented in derived classes, with
- * implementations forwarding the calls
- * to the implementations provided here
- * under a unique name for which template
- * arguments can be derived by the
- * compiler.
+ * Due to problems with deriving template arguments between the block and
+ * non-block versions of the vmult/Tvmult functions, the actual functions
+ * are implemented in derived classes, with implementations forwarding the
+ * calls to the implementations provided here under a unique name for which
+ * template arguments can be derived by the compiler.
*/
template <class BlockVectorType,
class VectorType>
const VectorType &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block column.
+ * Matrix-vector multiplication. Just like the previous function, but only
+ * applicable if the matrix has only one block column.
*
- * Due to problems with deriving template
- * arguments between the block and
- * non-block versions of the vmult/Tvmult
- * functions, the actual functions are
- * implemented in derived classes, with
- * implementations forwarding the calls
- * to the implementations provided here
- * under a unique name for which template
- * arguments can be derived by the
- * compiler.
+ * Due to problems with deriving template arguments between the block and
+ * non-block versions of the vmult/Tvmult functions, the actual functions
+ * are implemented in derived classes, with implementations forwarding the
+ * calls to the implementations provided here under a unique name for which
+ * template arguments can be derived by the compiler.
*/
template <class BlockVectorType,
class VectorType>
const BlockVectorType &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block.
+ * Matrix-vector multiplication. Just like the previous function, but only
+ * applicable if the matrix has only one block.
*
- * Due to problems with deriving template
- * arguments between the block and
- * non-block versions of the vmult/Tvmult
- * functions, the actual functions are
- * implemented in derived classes, with
- * implementations forwarding the calls
- * to the implementations provided here
- * under a unique name for which template
- * arguments can be derived by the
- * compiler.
+ * Due to problems with deriving template arguments between the block and
+ * non-block versions of the vmult/Tvmult functions, the actual functions
+ * are implemented in derived classes, with implementations forwarding the
+ * calls to the implementations provided here under a unique name for which
+ * template arguments can be derived by the compiler.
*/
template <class VectorType>
void Tvmult_nonblock_nonblock (VectorType &dst,
protected:
/**
- * Some matrix types, in particular PETSc,
- * need to synchronize set and add
- * operations. This has to be done for all
- * matrices in the BlockMatrix.
- * This routine prepares adding of elements
- * by notifying all blocks. Called by all
- * internal routines before adding
- * elements.
+ * Some matrix types, in particular PETSc, need to synchronize set and add
+ * operations. This has to be done for all matrices in the BlockMatrix. This
+ * routine prepares adding of elements by notifying all blocks. Called by
+ * all internal routines before adding elements.
*/
void prepare_add_operation();
/**
- * Notifies all blocks to let them prepare
- * for setting elements, see
+ * Notifies all blocks to let them prepare for setting elements, see
* prepare_add_operation().
*/
void prepare_set_operation();
private:
/**
- * A structure containing some fields used by the
- * set() and add() functions that is used to pre-sort
- * the input fields. Since one can reasonably expect
- * to call set() and add() from multiple threads at once
- * as long as the matrix indices that are touched are
- * disjoint, these temporary data fields need to be
- * guarded by a mutex; the structure therefore contains such
- * a mutex as a member variable.
+ * A structure containing some fields used by the set() and add() functions
+ * that is used to pre-sort the input fields. Since one can reasonably
+ * expect to call set() and add() from multiple threads at once as long as
+ * the matrix indices that are touched are disjoint, these temporary data
+ * fields need to be guarded by a mutex; the structure therefore contains
+ * such a mutex as a member variable.
*/
struct TemporaryData
{
/**
- * Temporary vector for counting the
- * elements written into the
- * individual blocks when doing a
- * collective add or set.
+ * Temporary vector for counting the elements written into the individual
+ * blocks when doing a collective add or set.
*/
std::vector<size_type> counter_within_block;
/**
- * Temporary vector for column
- * indices on each block when writing
- * local to global data on each
- * sparse matrix.
+ * Temporary vector for column indices on each block when writing local to
+ * global data on each sparse matrix.
*/
std::vector<std::vector<size_type> > column_indices;
/**
- * Temporary vector for storing the
- * local values (they need to be
- * reordered when writing local to
- * global).
+ * Temporary vector for storing the local values (they need to be
+ * reordered when writing local to global).
*/
std::vector<std::vector<double> > column_values;
/**
- * A mutex variable used to guard access to the member
- * variables of this structure;
+ * A mutex variable used to guard access to the member variables of this
+ * structure;
*/
Threads::Mutex mutex;
/**
- * Copy operator. This is needed because the default copy
- * operator of this class is deleted (since Threads::Mutex is
- * not copyable) and hence the default copy operator of the
- * enclosing class is also deleted.
+ * Copy operator. This is needed because the default copy operator of this
+ * class is deleted (since Threads::Mutex is not copyable) and hence the
+ * default copy operator of the enclosing class is also deleted.
*
- * The implementation here simply does nothing -- TemporaryData
- * objects are just scratch objects that are resized at the
- * beginning of their use, so there is no point actually copying
- * anything.
+ * The implementation here simply does nothing -- TemporaryData objects
+ * are just scratch objects that are resized at the beginning of their
+ * use, so there is no point actually copying anything.
*/
TemporaryData &operator = (const TemporaryData &)
{
};
/**
- * A set of scratch arrays that can be used by the add()
- * and set() functions that take pointers to data to
- * pre-sort indices before use. Access from multiple threads
- * is synchronized via the mutex variable that is part of the
- * structure.
+ * A set of scratch arrays that can be used by the add() and set() functions
+ * that take pointers to data to pre-sort indices before use. Access from
+ * multiple threads is synchronized via the mutex variable that is part of
+ * the structure.
*/
TemporaryData temporary_data;
/**
- * Make the iterator class a
- * friend. We have to work around
- * a compiler bug here again.
+ * Make the iterator class a friend. We have to work around a compiler bug
+ * here again.
*/
template <typename, bool>
friend class BlockMatrixIterators::Accessor;
{
public:
/**
- * Typedef the base class for simpler
- * access to its own typedefs.
+ * Typedef the base class for simpler access to its own typedefs.
*/
typedef BlockMatrixBase<SparseMatrix<number> > BaseClass;
/**
- * Typedef the type of the underlying
- * matrix.
+ * Typedef the type of the underlying matrix.
*/
typedef typename BaseClass::BlockType BlockType;
/**
- * Import the typedefs from the base
- * class.
+ * Import the typedefs from the base class.
*/
typedef typename BaseClass::value_type value_type;
typedef typename BaseClass::pointer pointer;
*/
//@{
/**
- * Constructor; initializes the
- * matrix to be empty, without
- * any structure, i.e. the
- * matrix is not usable at
- * all. This constructor is
- * therefore only useful for
- * matrices which are members of
- * a class. All other matrices
- * should be created at a point
- * in the data flow where all
- * necessary information is
- * available.
+ * Constructor; initializes the matrix to be empty, without any structure,
+ * i.e. the matrix is not usable at all. This constructor is therefore only
+ * useful for matrices which are members of a class. All other matrices
+ * should be created at a point in the data flow where all necessary
+ * information is available.
*
- * You have to initialize the
- * matrix before usage with
- * reinit(BlockSparsityPattern). The
- * number of blocks per row and
- * column are then determined by
- * that function.
+ * You have to initialize the matrix before usage with
+ * reinit(BlockSparsityPattern). The number of blocks per row and column are
+ * then determined by that function.
*/
BlockSparseMatrix ();
/**
- * Constructor. Takes the given
- * matrix sparsity structure to
- * represent the sparsity pattern
- * of this matrix. You can change
- * the sparsity pattern later on
- * by calling the reinit()
- * function.
+ * Constructor. Takes the given matrix sparsity structure to represent the
+ * sparsity pattern of this matrix. You can change the sparsity pattern
+ * later on by calling the reinit() function.
*
- * This constructor initializes
- * all sub-matrices with the
- * sub-sparsity pattern within
- * the argument.
+ * This constructor initializes all sub-matrices with the sub-sparsity
+ * pattern within the argument.
*
- * You have to make sure that the
- * lifetime of the sparsity
- * structure is at least as long
- * as that of this matrix or as
- * long as reinit() is not called
+ * You have to make sure that the lifetime of the sparsity structure is at
+ * least as long as that of this matrix or as long as reinit() is not called
* with a new sparsity structure.
*/
BlockSparseMatrix (const BlockSparsityPattern &sparsity);
/**
- * Pseudo copy operator only copying
- * empty objects. The sizes of the block
+ * Pseudo copy operator only copying empty objects. The sizes of the block
* matrices need to be the same.
*/
BlockSparseMatrix &
operator = (const BlockSparseMatrix &);
/**
- * This operator assigns a scalar to a
- * matrix. Since this does usually not
- * make much sense (should we set all
- * matrix entries to this value? Only
- * the nonzero entries of the sparsity
- * pattern?), this operation is only
- * allowed if the actual value to be
- * assigned is zero. This operator only
- * exists to allow for the obvious
- * notation <tt>matrix=0</tt>, which
- * sets all elements of the matrix to
- * zero, but keep the sparsity pattern
- * previously used.
+ * This operator assigns a scalar to a matrix. Since this does usually not
+ * make much sense (should we set all matrix entries to this value? Only the
+ * nonzero entries of the sparsity pattern?), this operation is only allowed
+ * if the actual value to be assigned is zero. This operator only exists to
+ * allow for the obvious notation <tt>matrix=0</tt>, which sets all elements
+ * of the matrix to zero, but keep the sparsity pattern previously used.
*/
BlockSparseMatrix &
operator = (const double d);
/**
- * Release all memory and return
- * to a state just like after
- * having called the default
- * constructor. It also forgets
- * the sparsity pattern it was
+ * Release all memory and return to a state just like after having called
+ * the default constructor. It also forgets the sparsity pattern it was
* previously tied to.
*
- * This calls SparseMatrix::clear on all
- * sub-matrices and then resets this
+ * This calls SparseMatrix::clear on all sub-matrices and then resets this
* object to have no blocks at all.
*/
void clear ();
/**
- * Reinitialize the sparse matrix
- * with the given sparsity
- * pattern. The latter tells the
- * matrix how many nonzero
- * elements there need to be
+ * Reinitialize the sparse matrix with the given sparsity pattern. The
+ * latter tells the matrix how many nonzero elements there need to be
* reserved.
*
- * Basically, this function only
- * calls SparseMatrix::reinit() of the
- * sub-matrices with the block
- * sparsity patterns of the
- * parameter.
+ * Basically, this function only calls SparseMatrix::reinit() of the sub-
+ * matrices with the block sparsity patterns of the parameter.
*
* You have to make sure that the lifetime of the sparsity structure is at
* least as long as that of this matrix or as long as reinit(const
*/
//@{
/**
- * Return whether the object is
- * empty. It is empty if either
- * both dimensions are zero or no
- * BlockSparsityPattern is
- * associated.
+ * Return whether the object is empty. It is empty if either both dimensions
+ * are zero or no BlockSparsityPattern is associated.
*/
bool empty () const;
/**
- * Return the number of entries
- * in a specific row.
+ * Return the number of entries in a specific row.
*/
size_type get_row_length (const size_type row) const;
/**
- * Return the number of nonzero
- * elements of this
- * matrix. Actually, it returns
- * the number of entries in the
- * sparsity pattern; if any of
- * the entries should happen to
- * be zero, it is counted anyway.
+ * Return the number of nonzero elements of this matrix. Actually, it
+ * returns the number of entries in the sparsity pattern; if any of the
+ * entries should happen to be zero, it is counted anyway.
*/
size_type n_nonzero_elements () const;
/**
- * Return the number of actually
- * nonzero elements. Just counts the
- * number of actually nonzero elements
- * (with absolute value larger than
- * threshold) of all the blocks.
+ * Return the number of actually nonzero elements. Just counts the number of
+ * actually nonzero elements (with absolute value larger than threshold) of
+ * all the blocks.
*/
size_type n_actually_nonzero_elements (const double threshold = 0.0) const;
/**
- * Return a (constant) reference
- * to the underlying sparsity
- * pattern of this matrix.
+ * Return a (constant) reference to the underlying sparsity pattern of this
+ * matrix.
*
- * Though the return value is
- * declared <tt>const</tt>, you
- * should be aware that it may
- * change if you call any
- * nonconstant function of
- * objects which operate on it.
+ * Though the return value is declared <tt>const</tt>, you should be aware
+ * that it may change if you call any nonconstant function of objects which
+ * operate on it.
*/
const BlockSparsityPattern &
get_sparsity_pattern () const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
//@}
*/
//@{
/**
- * Matrix-vector multiplication:
- * let $dst = M*src$ with $M$
- * being this matrix.
+ * Matrix-vector multiplication: let $dst = M*src$ with $M$ being this
+ * matrix.
*/
template <typename block_number>
void vmult (BlockVector<block_number> &dst,
const BlockVector<block_number> &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block column.
+ * Matrix-vector multiplication. Just like the previous function, but only
+ * applicable if the matrix has only one block column.
*/
template <typename block_number,
typename nonblock_number>
const Vector<nonblock_number> &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block row.
+ * Matrix-vector multiplication. Just like the previous function, but only
+ * applicable if the matrix has only one block row.
*/
template <typename block_number,
typename nonblock_number>
const BlockVector<block_number> &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block.
+ * Matrix-vector multiplication. Just like the previous function, but only
+ * applicable if the matrix has only one block.
*/
template <typename nonblock_number>
void vmult (Vector<nonblock_number> &dst,
const Vector<nonblock_number> &src) const;
/**
- * Matrix-vector multiplication:
- * let $dst = M^T*src$ with $M$
- * being this matrix. This
- * function does the same as
- * vmult() but takes the
- * transposed matrix.
+ * Matrix-vector multiplication: let $dst = M^T*src$ with $M$ being this
+ * matrix. This function does the same as vmult() but takes the transposed
+ * matrix.
*/
template <typename block_number>
void Tvmult (BlockVector<block_number> &dst,
const BlockVector<block_number> &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block row.
+ * Matrix-vector multiplication. Just like the previous function, but only
+ * applicable if the matrix has only one block row.
*/
template <typename block_number,
typename nonblock_number>
const Vector<nonblock_number> &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block column.
+ * Matrix-vector multiplication. Just like the previous function, but only
+ * applicable if the matrix has only one block column.
*/
template <typename block_number,
typename nonblock_number>
const BlockVector<block_number> &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block.
+ * Matrix-vector multiplication. Just like the previous function, but only
+ * applicable if the matrix has only one block.
*/
template <typename nonblock_number>
void Tvmult (Vector<nonblock_number> &dst,
*/
//@{
/**
- * Apply the Jacobi
- * preconditioner, which
- * multiplies every element of
- * the <tt>src</tt> vector by the
- * inverse of the respective
- * diagonal element and
- * multiplies the result with the
- * relaxation parameter
- * <tt>omega</tt>.
+ * Apply the Jacobi preconditioner, which multiplies every element of the
+ * <tt>src</tt> vector by the inverse of the respective diagonal element and
+ * multiplies the result with the relaxation parameter <tt>omega</tt>.
*
- * All diagonal blocks must be
- * square matrices for this
- * operation.
+ * All diagonal blocks must be square matrices for this operation.
*/
template <class BlockVectorType>
void precondition_Jacobi (BlockVectorType &dst,
const number omega = 1.) const;
/**
- * Apply the Jacobi
- * preconditioner to a simple vector.
+ * Apply the Jacobi preconditioner to a simple vector.
*
- * The matrix must be a single
- * square block for this.
+ * The matrix must be a single square block for this.
*/
template <typename number2>
void precondition_Jacobi (Vector<number2> &dst,
*/
//@{
/**
- * Print the matrix in the usual
- * format, i.e. as a matrix and
- * not as a list of nonzero
- * elements. For better
- * readability, elements not in
- * the matrix are displayed as
- * empty space, while matrix
- * elements which are explicitly
- * set to zero are displayed as
- * such.
+ * Print the matrix in the usual format, i.e. as a matrix and not as a list
+ * of nonzero elements. For better readability, elements not in the matrix
+ * are displayed as empty space, while matrix elements which are explicitly
+ * set to zero are displayed as such.
*
- * The parameters allow for a
- * flexible setting of the output
- * format: <tt>precision</tt> and
- * <tt>scientific</tt> are used
- * to determine the number
- * format, where <tt>scientific =
- * false</tt> means fixed point
- * notation. A zero entry for
- * <tt>width</tt> makes the
- * function compute a width, but
- * it may be changed to a
- * positive value, if output is
- * crude.
+ * The parameters allow for a flexible setting of the output format:
+ * <tt>precision</tt> and <tt>scientific</tt> are used to determine the
+ * number format, where <tt>scientific = false</tt> means fixed point
+ * notation. A zero entry for <tt>width</tt> makes the function compute a
+ * width, but it may be changed to a positive value, if output is crude.
*
- * Additionally, a character for
- * an empty value may be
- * specified.
+ * Additionally, a character for an empty value may be specified.
*
- * Finally, the whole matrix can
- * be multiplied with a common
- * denominator to produce more
- * readable output, even
- * integers.
+ * Finally, the whole matrix can be multiplied with a common denominator to
+ * produce more readable output, even integers.
*
- * @attention This function may
- * produce <b>large</b> amounts
- * of output if applied to a
- * large matrix!
+ * @attention This function may produce <b>large</b> amounts of output if
+ * applied to a large matrix!
*/
void print_formatted (std::ostream &out,
const unsigned int precision = 3,
const char *zero_string = " ",
const double denominator = 1.) const;
//@}
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
private:
/**
- * Pointer to the block sparsity
- * pattern used for this
- * matrix. In order to guarantee
- * that it is not deleted while
- * still in use, we subscribe to
- * it using the SmartPointer
- * class.
+ * Pointer to the block sparsity pattern used for this matrix. In order to
+ * guarantee that it is not deleted while still in use, we subscribe to it
+ * using the SmartPointer class.
*/
SmartPointer<const BlockSparsityPattern,BlockSparseMatrix<number> > sparsity_pattern;
};
* A block matrix consisting of blocks of type SparseMatrixEZ.
*
* Like the other Block-objects, this matrix can be used like a
- * SparseMatrixEZ, when it comes to access to entries. Then, there
- * are functions for the multiplication with BlockVector and
- * access to the individual blocks.
+ * SparseMatrixEZ, when it comes to access to entries. Then, there are
+ * functions for the multiplication with BlockVector and access to the
+ * individual blocks.
*
* @see @ref GlossBlockLA "Block (linear algebra)"
* @author Guido Kanschat, 2002, 2003
typedef types::global_dof_index size_type;
/**
- * Default constructor. The
- * result is an empty object with
- * zero dimensions.
+ * Default constructor. The result is an empty object with zero dimensions.
*/
BlockSparseMatrixEZ ();
/**
- * Constructor setting up an
- * object with given unmber of
- * block rows and columns. The
- * blocks themselves still have
- * zero dimension.
+ * Constructor setting up an object with given unmber of block rows and
+ * columns. The blocks themselves still have zero dimension.
*/
BlockSparseMatrixEZ (const unsigned int block_rows,
const unsigned int block_cols);
/**
- * Copy constructor. This is
- * needed for some container
- * classes. It creates an object
- * of the same number of block
- * rows and columns. Since it
- * calls the copy constructor of
- * SparseMatrixEZ, the
- * block s must be empty.
+ * Copy constructor. This is needed for some container classes. It creates
+ * an object of the same number of block rows and columns. Since it calls
+ * the copy constructor of SparseMatrixEZ, the block s must be empty.
*/
BlockSparseMatrixEZ (const BlockSparseMatrixEZ<Number> &);
/**
- * Copy operator. Like the copy
- * constructor, this may be
- * called for objects with empty
- * blocks only.
+ * Copy operator. Like the copy constructor, this may be called for objects
+ * with empty blocks only.
*/
BlockSparseMatrixEZ &operator = (const BlockSparseMatrixEZ<Number> &);
/**
- * This operator assigns a scalar to
- * a matrix. Since this does usually
- * not make much sense (should we set
- * all matrix entries to this value?
- * Only the nonzero entries of the
- * sparsity pattern?), this operation
- * is only allowed if the actual
- * value to be assigned is zero. This
- * operator only exists to allow for
- * the obvious notation
- * <tt>matrix=0</tt>, which sets all
- * elements of the matrix to zero,
- * but keep the sparsity pattern
- * previously used.
+ * This operator assigns a scalar to a matrix. Since this does usually not
+ * make much sense (should we set all matrix entries to this value? Only the
+ * nonzero entries of the sparsity pattern?), this operation is only allowed
+ * if the actual value to be assigned is zero. This operator only exists to
+ * allow for the obvious notation <tt>matrix=0</tt>, which sets all elements
+ * of the matrix to zero, but keep the sparsity pattern previously used.
*/
BlockSparseMatrixEZ &operator = (const double d);
/**
- * Set matrix to zero dimensions
- * and release memory.
+ * Set matrix to zero dimensions and release memory.
*/
void clear ();
/**
- * Initialize to given block
- * numbers. After this
- * operation, the matrix will
- * have the block dimensions
- * provided. Each block will have
- * zero dimensions and must be
- * initialized
- * subsequently. After setting
- * the sizes of the blocks,
- * collect_sizes() must be
- * called to update internal data
+ * Initialize to given block numbers. After this operation, the matrix will
+ * have the block dimensions provided. Each block will have zero dimensions
+ * and must be initialized subsequently. After setting the sizes of the
+ * blocks, collect_sizes() must be called to update internal data
* structures.
*/
void reinit (const unsigned int n_block_rows,
const unsigned int n_block_cols);
/**
- * This function collects the
- * sizes of the sub-objects and
- * stores them in internal
- * arrays, in order to be able to
- * relay global indices into the
- * matrix to indices into the
- * subobjects. You *must* call
- * this function each time after
- * you have changed the size of
- * the sub-objects.
+ * This function collects the sizes of the sub-objects and stores them in
+ * internal arrays, in order to be able to relay global indices into the
+ * matrix to indices into the subobjects. You *must* call this function each
+ * time after you have changed the size of the sub-objects.
*/
void collect_sizes ();
/**
- * Access the block with the
- * given coordinates.
+ * Access the block with the given coordinates.
*/
SparseMatrixEZ<Number> &
block (const unsigned int row,
/**
- * Access the block with the
- * given coordinates. Version for
- * constant objects.
+ * Access the block with the given coordinates. Version for constant
+ * objects.
*/
const SparseMatrixEZ<Number> &
block (const unsigned int row,
const unsigned int column) const;
/**
- * Return the number of blocks in a
- * column.
+ * Return the number of blocks in a column.
*/
unsigned int n_block_rows () const;
/**
- * Return the number of blocks in a
- * row.
+ * Return the number of blocks in a row.
*/
unsigned int n_block_cols () const;
/**
- * Return whether the object is
- * empty. It is empty if no
- * memory is allocated, which is
- * the same as that both
- * dimensions are zero. This
- * function is just the
- * concatenation of the
- * respective call to all
- * sub-matrices.
+ * Return whether the object is empty. It is empty if no memory is
+ * allocated, which is the same as that both dimensions are zero. This
+ * function is just the concatenation of the respective call to all sub-
+ * matrices.
*/
bool empty () const;
/**
- * Return number of rows of this
- * matrix, which equals the
- * dimension of the image
- * space. It is the sum of rows
- * of the rows of sub-matrices.
+ * Return number of rows of this matrix, which equals the dimension of the
+ * image space. It is the sum of rows of the rows of sub-matrices.
*/
size_type n_rows () const;
/**
- * Return number of columns of
- * this matrix, which equals the
- * dimension of the range
- * space. It is the sum of
- * columns of the columns of
- * sub-matrices.
+ * Return number of columns of this matrix, which equals the dimension of
+ * the range space. It is the sum of columns of the columns of sub-matrices.
*/
size_type n_cols () const;
/**
- * Return the dimension of the
- * image space. To remember: the
- * matrix is of dimension
- * $m \times n$.
+ * Return the dimension of the image space. To remember: the matrix is of
+ * dimension $m \times n$.
*/
size_type m () const;
/**
- * Return the dimension of the
- * range space. To remember: the
- * matrix is of dimension
- * $m \times n$.
+ * Return the dimension of the range space. To remember: the matrix is of
+ * dimension $m \times n$.
*/
size_type n () const;
/**
- * Set the element <tt>(i,j)</tt>
- * to @p value. Throws an error
- * if the entry does not exist or
- * if <tt>value</tt> is not a
- * finite number. Still, it is
- * allowed to store zero values
- * in non-existent fields.
+ * Set the element <tt>(i,j)</tt> to @p value. Throws an error if the entry
+ * does not exist or if <tt>value</tt> is not a finite number. Still, it is
+ * allowed to store zero values in non-existent fields.
*/
void set (const size_type i,
const size_type j,
const Number value);
/**
- * Add @p value to the element
- * <tt>(i,j)</tt>. Throws an
- * error if the entry does not
- * exist or if <tt>value</tt> is
- * not a finite number. Still, it
- * is allowed to store zero
- * values in non-existent fields.
+ * Add @p value to the element <tt>(i,j)</tt>. Throws an error if the entry
+ * does not exist or if <tt>value</tt> is not a finite number. Still, it is
+ * allowed to store zero values in non-existent fields.
*/
void add (const size_type i, const size_type j,
const Number value);
/**
- * Matrix-vector multiplication:
- * let $dst = M*src$ with $M$
- * being this matrix.
+ * Matrix-vector multiplication: let $dst = M*src$ with $M$ being this
+ * matrix.
*/
template <typename somenumber>
void vmult (BlockVector<somenumber> &dst,
const BlockVector<somenumber> &src) const;
/**
- * Matrix-vector multiplication:
- * let $dst = M^T*src$ with $M$
- * being this matrix. This
- * function does the same as
- * vmult() but takes the
- * transposed matrix.
+ * Matrix-vector multiplication: let $dst = M^T*src$ with $M$ being this
+ * matrix. This function does the same as vmult() but takes the transposed
+ * matrix.
*/
template <typename somenumber>
void Tvmult (BlockVector<somenumber> &dst,
const BlockVector<somenumber> &src) const;
/**
- * Adding Matrix-vector
- * multiplication. Add $M*src$ on
- * $dst$ with $M$ being this
- * matrix.
+ * Adding Matrix-vector multiplication. Add $M*src$ on $dst$ with $M$ being
+ * this matrix.
*/
template <typename somenumber>
void vmult_add (BlockVector<somenumber> &dst,
const BlockVector<somenumber> &src) const;
/**
- * Adding Matrix-vector
- * multiplication. Add $M^T*src$
- * to $dst$ with $M$ being this
- * matrix. This function does the
- * same as vmult_add() but takes
+ * Adding Matrix-vector multiplication. Add $M^T*src$ to $dst$ with $M$
+ * being this matrix. This function does the same as vmult_add() but takes
* the transposed matrix.
*/
template <typename somenumber>
/**
- * Print statistics. If @p full
- * is @p true, prints a
- * histogram of all existing row
- * lengths and allocated row
- * lengths. Otherwise, just the
- * relation of allocated and used
- * entries is shown.
+ * Print statistics. If @p full is @p true, prints a histogram of all
+ * existing row lengths and allocated row lengths. Otherwise, just the
+ * relation of allocated and used entries is shown.
*/
template <class STREAM>
void print_statistics (STREAM &s, bool full = false);
private:
/**
- * Object storing and managing
- * the transformation of row
- * indices to indices of the
- * sub-objects.
+ * Object storing and managing the transformation of row indices to indices
+ * of the sub-objects.
*/
BlockIndices row_indices;
/**
- * Object storing and managing
- * the transformation of column
- * indices to indices of the
- * sub-objects.
+ * Object storing and managing the transformation of column indices to
+ * indices of the sub-objects.
*/
BlockIndices column_indices;
* member functions of the member sparsity patterns.
*
* The largest difference between the SparsityPattern and
- * CompressedSparsityPattern classes and this class is that
- * mostly, the matrices have different properties and you will want to
- * work on the blocks making up the matrix rather than the whole
- * matrix. You can access the different blocks using the
- * <tt>block(row,col)</tt> function.
+ * CompressedSparsityPattern classes and this class is that mostly, the
+ * matrices have different properties and you will want to work on the blocks
+ * making up the matrix rather than the whole matrix. You can access the
+ * different blocks using the <tt>block(row,col)</tt> function.
*
- * Attention: this object is not automatically notified if the size of
- * one of its subobjects' size is changed. After you initialize the
- * sizes of the subobjects, you will therefore have to call the
- * <tt>collect_sizes()</tt> function of this class! Note that, of course, all
- * sub-matrices in a (block-)row have to have the same number of rows, and
- * that all sub-matrices in a (block-)column have to have the same number of
- * columns.
+ * Attention: this object is not automatically notified if the size of one of
+ * its subobjects' size is changed. After you initialize the sizes of the
+ * subobjects, you will therefore have to call the <tt>collect_sizes()</tt>
+ * function of this class! Note that, of course, all sub-matrices in a
+ * (block-)row have to have the same number of rows, and that all sub-matrices
+ * in a (block-)column have to have the same number of columns.
*
- * You will in general not want to use this class, but one of the
- * derived classes.
+ * You will in general not want to use this class, but one of the derived
+ * classes.
*
* @todo Handle optimization of diagonal elements of the underlying
* SparsityPattern correctly.
typedef types::global_dof_index size_type;
/**
- * Define a value which is used
- * to indicate that a certain
- * value in the @p colnums array
- * is unused, i.e. does not
- * represent a certain column
- * number index.
+ * Define a value which is used to indicate that a certain value in the @p
+ * colnums array is unused, i.e. does not represent a certain column number
+ * index.
*
- * This value is only an alias to
- * the respective value of the
+ * This value is only an alias to the respective value of the
* SparsityPattern class.
*/
static const size_type invalid_entry = SparsityPattern::invalid_entry;
/**
- * Initialize the matrix empty,
- * that is with no memory
- * allocated. This is useful if
- * you want such objects as
- * member variables in other
- * classes. You can make the
- * structure usable by calling
- * the reinit() function.
+ * Initialize the matrix empty, that is with no memory allocated. This is
+ * useful if you want such objects as member variables in other classes. You
+ * can make the structure usable by calling the reinit() function.
*/
BlockSparsityPatternBase ();
/**
- * Initialize the matrix with the
- * given number of block rows and
- * columns. The blocks themselves
- * are still empty, and you have
- * to call collect_sizes() after
- * you assign them sizes.
+ * Initialize the matrix with the given number of block rows and columns.
+ * The blocks themselves are still empty, and you have to call
+ * collect_sizes() after you assign them sizes.
*/
BlockSparsityPatternBase (const size_type n_block_rows,
const size_type n_block_columns);
/**
- * Copy constructor. This
- * constructor is only allowed to
- * be called if the sparsity pattern to be
- * copied is empty, i.e. there
- * are no block allocated at
- * present. This is for the same
- * reason as for the
- * SparsityPattern, see there
- * for the details.
+ * Copy constructor. This constructor is only allowed to be called if the
+ * sparsity pattern to be copied is empty, i.e. there are no block allocated
+ * at present. This is for the same reason as for the SparsityPattern, see
+ * there for the details.
*/
BlockSparsityPatternBase (const BlockSparsityPatternBase &bsp);
~BlockSparsityPatternBase ();
/**
- * Resize the matrix, by setting
- * the number of block rows and
- * columns. This deletes all
- * blocks and replaces them by
- * unitialized ones, i.e. ones
- * for which also the sizes are
- * not yet set. You have to do
- * that by calling the reinit()
- * functions of the blocks
- * themselves. Do not forget to
- * call collect_sizes() after
- * that on this object.
+ * Resize the matrix, by setting the number of block rows and columns. This
+ * deletes all blocks and replaces them by unitialized ones, i.e. ones for
+ * which also the sizes are not yet set. You have to do that by calling the
+ * reinit() functions of the blocks themselves. Do not forget to call
+ * collect_sizes() after that on this object.
*
- * The reason that you have to
- * set sizes of the blocks
- * yourself is that the sizes may
- * be varying, the maximum number
- * of elements per row may be
- * varying, etc. It is simpler
- * not to reproduce the interface
- * of the SparsityPattern
- * class here but rather let the
- * user call whatever function
+ * The reason that you have to set sizes of the blocks yourself is that the
+ * sizes may be varying, the maximum number of elements per row may be
+ * varying, etc. It is simpler not to reproduce the interface of the
+ * SparsityPattern class here but rather let the user call whatever function
* she desires.
*/
void reinit (const size_type n_block_rows,
const size_type n_block_columns);
/**
- * Copy operator. For this the
- * same holds as for the copy
- * constructor: it is declared,
- * defined and fine to be called,
- * but the latter only for empty
+ * Copy operator. For this the same holds as for the copy constructor: it is
+ * declared, defined and fine to be called, but the latter only for empty
* objects.
*/
BlockSparsityPatternBase &operator = (const BlockSparsityPatternBase &);
/**
- * This function collects the
- * sizes of the sub-objects and
- * stores them in internal
- * arrays, in order to be able to
- * relay global indices into the
- * matrix to indices into the
- * subobjects. You *must* call
- * this function each time after
- * you have changed the size of
- * the sub-objects.
+ * This function collects the sizes of the sub-objects and stores them in
+ * internal arrays, in order to be able to relay global indices into the
+ * matrix to indices into the subobjects. You *must* call this function each
+ * time after you have changed the size of the sub-objects.
*/
void collect_sizes ();
/**
- * Access the block with the
- * given coordinates.
+ * Access the block with the given coordinates.
*/
SparsityPatternBase &
block (const size_type row,
/**
- * Access the block with the
- * given coordinates. Version for
- * constant objects.
+ * Access the block with the given coordinates. Version for constant
+ * objects.
*/
const SparsityPatternBase &
block (const size_type row,
const size_type column) const;
/**
- * Grant access to the object
- * describing the distribution of
- * row indices to the individual
- * blocks.
+ * Grant access to the object describing the distribution of row indices to
+ * the individual blocks.
*/
const BlockIndices &
get_row_indices () const;
/**
- * Grant access to the object
- * describing the distribution of
- * column indices to the individual
- * blocks.
+ * Grant access to the object describing the distribution of column indices
+ * to the individual blocks.
*/
const BlockIndices &
get_column_indices () const;
/**
- * This function compresses the
- * sparsity structures that this
- * object represents. It simply
- * calls @p compress for all
- * sub-objects.
+ * This function compresses the sparsity structures that this object
+ * represents. It simply calls @p compress for all sub-objects.
*/
void compress ();
/**
- * Return the number of blocks in a
- * column.
+ * Return the number of blocks in a column.
*/
size_type n_block_rows () const;
/**
- * Return the number of blocks in a
- * row.
+ * Return the number of blocks in a row.
*/
size_type n_block_cols () const;
/**
- * Return whether the object is
- * empty. It is empty if no
- * memory is allocated, which is
- * the same as that both
- * dimensions are zero. This
- * function is just the
- * concatenation of the
- * respective call to all
- * sub-matrices.
+ * Return whether the object is empty. It is empty if no memory is
+ * allocated, which is the same as that both dimensions are zero. This
+ * function is just the concatenation of the respective call to all sub-
+ * matrices.
*/
bool empty () const;
/**
- * Return the maximum number of
- * entries per row. It returns
- * the maximal number of entries
- * per row accumulated over all
- * blocks in a row, and the
+ * Return the maximum number of entries per row. It returns the maximal
+ * number of entries per row accumulated over all blocks in a row, and the
* maximum over all rows.
*/
size_type max_entries_per_row () const;
/**
- * Add a nonzero entry to the matrix.
- * This function may only be called
- * for non-compressed sparsity patterns.
+ * Add a nonzero entry to the matrix. This function may only be called for
+ * non-compressed sparsity patterns.
*
- * If the entry already exists, nothing
- * bad happens.
+ * If the entry already exists, nothing bad happens.
*
- * This function simply finds out
- * to which block <tt>(i,j)</tt> belongs
- * and then relays to that block.
+ * This function simply finds out to which block <tt>(i,j)</tt> belongs and
+ * then relays to that block.
*/
void add (const size_type i, const size_type j);
/**
- * Add several nonzero entries to the
- * specified matrix row. This function
- * may only be called for
- * non-compressed sparsity patterns.
+ * Add several nonzero entries to the specified matrix row. This function
+ * may only be called for non-compressed sparsity patterns.
*
- * If some of the entries already
- * exist, nothing bad happens.
+ * If some of the entries already exist, nothing bad happens.
*
- * This function simply finds out to
- * which blocks <tt>(row,col)</tt> for
- * <tt>col</tt> in the iterator range
- * belong and then relays to those
+ * This function simply finds out to which blocks <tt>(row,col)</tt> for
+ * <tt>col</tt> in the iterator range belong and then relays to those
* blocks.
*/
template <typename ForwardIterator>
const bool indices_are_sorted = false);
/**
- * Return number of rows of this
- * matrix, which equals the
- * dimension of the image
- * space. It is the sum of rows
- * of the (block-)rows of
- * sub-matrices.
+ * Return number of rows of this matrix, which equals the dimension of the
+ * image space. It is the sum of rows of the (block-)rows of sub-matrices.
*/
size_type n_rows () const;
/**
- * Return number of columns of
- * this matrix, which equals the
- * dimension of the range
- * space. It is the sum of
- * columns of the (block-)columns
- * of sub-matrices.
+ * Return number of columns of this matrix, which equals the dimension of
+ * the range space. It is the sum of columns of the (block-)columns of sub-
+ * matrices.
*/
size_type n_cols () const;
/**
- * Check if a value at a certain
- * position may be non-zero.
+ * Check if a value at a certain position may be non-zero.
*/
bool exists (const size_type i, const size_type j) const;
/**
- * Number of entries in a
- * specific row, added up over
- * all the blocks that form this
- * row.
+ * Number of entries in a specific row, added up over all the blocks that
+ * form this row.
*/
unsigned int row_length (const size_type row) const;
/**
- * Return the number of nonzero
- * elements of this
- * matrix. Actually, it returns
- * the number of entries in the
- * sparsity pattern; if any of
- * the entries should happen to
- * be zero, it is counted anyway.
+ * Return the number of nonzero elements of this matrix. Actually, it
+ * returns the number of entries in the sparsity pattern; if any of the
+ * entries should happen to be zero, it is counted anyway.
*
- * This function may only be
- * called if the matrix struct is
- * compressed. It does not make
- * too much sense otherwise
- * anyway.
+ * This function may only be called if the matrix struct is compressed. It
+ * does not make too much sense otherwise anyway.
*
- * In the present context, it is
- * the sum of the values as
- * returned by the sub-objects.
+ * In the present context, it is the sum of the values as returned by the
+ * sub-objects.
*/
size_type n_nonzero_elements () const;
/**
- * Print the sparsity of the
- * matrix. The output consists of
- * one line per row of the format
- * <tt>[i,j1,j2,j3,...]</tt>. <i>i</i>
- * is the row number and
- * <i>jn</i> are the allocated
- * columns in this row.
+ * Print the sparsity of the matrix. The output consists of one line per row
+ * of the format <tt>[i,j1,j2,j3,...]</tt>. <i>i</i> is the row number and
+ * <i>jn</i> are the allocated columns in this row.
*/
void print (std::ostream &out) const;
/**
- * Print the sparsity of the matrix
- * in a format that <tt>gnuplot</tt> understands
- * and which can be used to plot the
- * sparsity pattern in a graphical
- * way. This is the same functionality
- * implemented for usual sparsity
- * patterns, see @ref SparsityPattern.
+ * Print the sparsity of the matrix in a format that <tt>gnuplot</tt>
+ * understands and which can be used to plot the sparsity pattern in a
+ * graphical way. This is the same functionality implemented for usual
+ * sparsity patterns, see @ref SparsityPattern.
*/
void print_gnuplot (std::ostream &out) const;
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
Table<2,SmartPointer<SparsityPatternBase, BlockSparsityPatternBase<SparsityPatternBase> > > sub_objects;
/**
- * Object storing and managing
- * the transformation of row
- * indices to indices of the
- * sub-objects.
+ * Object storing and managing the transformation of row indices to indices
+ * of the sub-objects.
*/
BlockIndices row_indices;
/**
- * Object storing and managing
- * the transformation of column
- * indices to indices of the
- * sub-objects.
+ * Object storing and managing the transformation of column indices to
+ * indices of the sub-objects.
*/
BlockIndices column_indices;
private:
/**
- * Temporary vector for counting the
- * elements written into the
- * individual blocks when doing a
- * collective add or set.
+ * Temporary vector for counting the elements written into the individual
+ * blocks when doing a collective add or set.
*/
std::vector<size_type > counter_within_block;
/**
- * Temporary vector for column
- * indices on each block when writing
- * local to global data on each
- * sparse matrix.
+ * Temporary vector for column indices on each block when writing local to
+ * global data on each sparse matrix.
*/
std::vector<std::vector<size_type > > block_column_indices;
/**
- * Make the block sparse matrix a
- * friend, so that it can use our
- * #row_indices and
- * #column_indices objects.
+ * Make the block sparse matrix a friend, so that it can use our
+ * #row_indices and #column_indices objects.
*/
template <typename number>
friend class BlockSparseMatrix;
/**
* This class extends the base class to implement an array of sparsity
- * patterns that can be used by block sparse matrix objects. It only
- * adds a few additional member functions, but the main interface
- * stems from the base class, see there for more information.
+ * patterns that can be used by block sparse matrix objects. It only adds a
+ * few additional member functions, but the main interface stems from the base
+ * class, see there for more information.
*
* This class is an example of the "static" type of @ref Sparsity.
*
public:
/**
- * Initialize the matrix empty,
- * that is with no memory
- * allocated. This is useful if
- * you want such objects as
- * member variables in other
- * classes. You can make the
- * structure usable by calling
- * the reinit() function.
+ * Initialize the matrix empty, that is with no memory allocated. This is
+ * useful if you want such objects as member variables in other classes. You
+ * can make the structure usable by calling the reinit() function.
*/
BlockSparsityPattern ();
/**
- * Initialize the matrix with the
- * given number of block rows and
- * columns. The blocks themselves
- * are still empty, and you have
- * to call collect_sizes() after
- * you assign them sizes.
+ * Initialize the matrix with the given number of block rows and columns.
+ * The blocks themselves are still empty, and you have to call
+ * collect_sizes() after you assign them sizes.
*/
BlockSparsityPattern (const size_type n_rows,
const size_type n_columns);
/**
- * Forwarding to
- * BlockSparsityPatternBase::reinit().
+ * Forwarding to BlockSparsityPatternBase::reinit().
*/
void reinit (const size_type n_block_rows,
const size_type n_block_columns);
/**
- * Initialize the pattern with
- * two BlockIndices for the block
- * structures of matrix rows and
- * columns as well as a row
- * length vector.
+ * Initialize the pattern with two BlockIndices for the block structures of
+ * matrix rows and columns as well as a row length vector.
*
- * The row length vector should
- * be in the format produced by
- * DoFTools. Alternatively, there
- * is a simplified version,
- * where each of the inner
- * vectors has length one. Then,
- * the corresponding entry is
- * used as the maximal row length.
+ * The row length vector should be in the format produced by DoFTools.
+ * Alternatively, there is a simplified version, where each of the inner
+ * vectors has length one. Then, the corresponding entry is used as the
+ * maximal row length.
*
- * For the diagonal blocks, the
- * inner SparsityPattern is
- * initialized with optimized
- * diagonals, while this is not
- * done for the off-diagonal blocks.
+ * For the diagonal blocks, the inner SparsityPattern is initialized with
+ * optimized diagonals, while this is not done for the off-diagonal blocks.
*/
void reinit (const BlockIndices &row_indices,
const BlockIndices &col_indices,
/**
- * Return whether the structure
- * is compressed or not,
- * i.e. whether all sub-matrices
- * are compressed.
+ * Return whether the structure is compressed or not, i.e. whether all sub-
+ * matrices are compressed.
*/
bool is_compressed () const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
/**
- * Copy data from an object of
- * type
- * BlockCompressedSparsityPattern,
- * i.e. resize this object to the
- * size of the given argument,
- * and copy over the contents of
- * each of the
- * subobjects. Previous content
- * of this object is lost.
+ * Copy data from an object of type BlockCompressedSparsityPattern, i.e.
+ * resize this object to the size of the given argument, and copy over the
+ * contents of each of the subobjects. Previous content of this object is
+ * lost.
*/
void copy_from (const BlockCompressedSparsityPattern &csp);
/**
- * Copy data from an object of
- * type
- * BlockCompressedSetSparsityPattern,
- * i.e. resize this object to the
- * size of the given argument,
- * and copy over the contents of
- * each of the
- * subobjects. Previous content
- * of this object is lost.
+ * Copy data from an object of type BlockCompressedSetSparsityPattern, i.e.
+ * resize this object to the size of the given argument, and copy over the
+ * contents of each of the subobjects. Previous content of this object is
+ * lost.
*/
void copy_from (const BlockCompressedSetSparsityPattern &csp);
/**
- * Copy data from an object of
- * type
- * BlockCompressedSimpleSparsityPattern,
- * i.e. resize this object to the
- * size of the given argument,
- * and copy over the contents of
- * each of the
- * subobjects. Previous content
- * of this object is lost.
+ * Copy data from an object of type BlockCompressedSimpleSparsityPattern,
+ * i.e. resize this object to the size of the given argument, and copy over
+ * the contents of each of the subobjects. Previous content of this object
+ * is lost.
*/
void copy_from (const BlockCompressedSimpleSparsityPattern &csp);
*
* This class is an example of the "dynamic" type of @ref Sparsity.
*
- * <b>Note:</b>
- * There are several, exchangeable variations of this class, see @ref Sparsity,
- * section 'Dynamic block sparsity patterns' for more information.
+ * <b>Note:</b> There are several, exchangeable variations of this class, see
+ * @ref Sparsity, section 'Dynamic block sparsity patterns' for more
+ * information.
*
- * <b>Note:</b> This class used to be called
- * CompressedBlockSparsityPattern. However, since it's a block wrapper around
- * the CompressedSparsityPattern class, this is a misnomer and the class has
- * been renamed.
+ * <b>Note:</b> This class used to be called CompressedBlockSparsityPattern.
+ * However, since it's a block wrapper around the CompressedSparsityPattern
+ * class, this is a misnomer and the class has been renamed.
*
* <h3>Example</h3>
*
- * Usage of this class is very similar to CompressedSparsityPattern,
- * but since the use of block indices causes some additional
- * complications, we give a short example.
+ * Usage of this class is very similar to CompressedSparsityPattern, but since
+ * the use of block indices causes some additional complications, we give a
+ * short example.
*
* @dontinclude compressed_block_sparsity_pattern.cc
*
* After the the DoFHandler <tt>dof</tt> and the ConstraintMatrix
- * <tt>constraints</tt> have been set up with a system element, we
- * must count the degrees of freedom in each matrix block:
+ * <tt>constraints</tt> have been set up with a system element, we must count
+ * the degrees of freedom in each matrix block:
*
- * @skipline dofs_per_block
- * @until count
+ * @skipline dofs_per_block @until count
*
* Now, we are ready to set up the BlockCompressedSparsityPattern.
*
*
* @until condense
*
- * In the end, it is copied to a normal BlockSparsityPattern for later
- * use.
+ * In the end, it is copied to a normal BlockSparsityPattern for later use.
*
* @until copy
*
public:
/**
- * Initialize the matrix empty,
- * that is with no memory
- * allocated. This is useful if
- * you want such objects as
- * member variables in other
- * classes. You can make the
- * structure usable by calling
- * the reinit() function.
+ * Initialize the matrix empty, that is with no memory allocated. This is
+ * useful if you want such objects as member variables in other classes. You
+ * can make the structure usable by calling the reinit() function.
*/
BlockCompressedSparsityPattern ();
/**
- * Initialize the matrix with the
- * given number of block rows and
- * columns. The blocks themselves
- * are still empty, and you have
- * to call collect_sizes() after
- * you assign them sizes.
+ * Initialize the matrix with the given number of block rows and columns.
+ * The blocks themselves are still empty, and you have to call
+ * collect_sizes() after you assign them sizes.
*/
BlockCompressedSparsityPattern (const size_type n_rows,
const size_type n_columns);
/**
- * Initialize the pattern with
- * two BlockIndices for the block
- * structures of matrix rows and
- * columns. This function is
- * equivalent to calling the
- * previous constructor with the
- * length of the two index vector
- * and then entering the index
- * values.
+ * Initialize the pattern with two BlockIndices for the block structures of
+ * matrix rows and columns. This function is equivalent to calling the
+ * previous constructor with the length of the two index vector and then
+ * entering the index values.
*/
BlockCompressedSparsityPattern (const std::vector<size_type> &row_block_sizes,
const std::vector<size_type> &col_block_sizes);
/**
- * Initialize the pattern with
- * two BlockIndices for the block
- * structures of matrix rows and
- * columns.
+ * Initialize the pattern with two BlockIndices for the block structures of
+ * matrix rows and columns.
*/
BlockCompressedSparsityPattern (const BlockIndices &row_indices,
const BlockIndices &col_indices);
/**
- * Resize the matrix to a tensor
- * product of matrices with
- * dimensions defined by the
- * arguments.
+ * Resize the matrix to a tensor product of matrices with dimensions defined
+ * by the arguments.
*
- * The matrix will have as many
- * block rows and columns as
- * there are entries in the two
- * arguments. The block at
- * position (<i>i,j</i>) will
- * have the dimensions
- * <tt>row_block_sizes[i]</tt>
- * times <tt>col_block_sizes[j]</tt>.
+ * The matrix will have as many block rows and columns as there are entries
+ * in the two arguments. The block at position (<i>i,j</i>) will have the
+ * dimensions <tt>row_block_sizes[i]</tt> times <tt>col_block_sizes[j]</tt>.
*/
void reinit (const std::vector<size_type> &row_block_sizes,
const std::vector<size_type> &col_block_sizes);
/**
- * Resize the matrix to a tensor
- * product of matrices with
- * dimensions defined by the
- * arguments. The two
- * BlockIndices objects must be
- * initialized and the sparsity
- * pattern will have the
- * same block structure afterwards.
+ * Resize the matrix to a tensor product of matrices with dimensions defined
+ * by the arguments. The two BlockIndices objects must be initialized and
+ * the sparsity pattern will have the same block structure afterwards.
*/
void reinit (const BlockIndices &row_indices, const BlockIndices &col_indices);
/**
- * Allow the use of the reinit
- * functions of the base class as
- * well.
+ * Allow the use of the reinit functions of the base class as well.
*/
using BlockSparsityPatternBase<CompressedSparsityPattern>::reinit;
};
*
* This class is an example of the "dynamic" type of @ref Sparsity.
*
- * <b>Note:</b>
- * There are several, exchangeable variations of this class, see @ref Sparsity,
- * section 'Dynamic block sparsity patterns' for more information.
+ * <b>Note:</b> There are several, exchangeable variations of this class, see
+ * @ref Sparsity, section 'Dynamic block sparsity patterns' for more
+ * information.
*
* @author Wolfgang Bangerth, 2007
*/
public:
/**
- * Initialize the matrix empty,
- * that is with no memory
- * allocated. This is useful if
- * you want such objects as
- * member variables in other
- * classes. You can make the
- * structure usable by calling
- * the reinit() function.
+ * Initialize the matrix empty, that is with no memory allocated. This is
+ * useful if you want such objects as member variables in other classes. You
+ * can make the structure usable by calling the reinit() function.
*/
BlockCompressedSetSparsityPattern ();
/**
- * Initialize the matrix with the
- * given number of block rows and
- * columns. The blocks themselves
- * are still empty, and you have
- * to call collect_sizes() after
- * you assign them sizes.
+ * Initialize the matrix with the given number of block rows and columns.
+ * The blocks themselves are still empty, and you have to call
+ * collect_sizes() after you assign them sizes.
*/
BlockCompressedSetSparsityPattern (const size_type n_rows,
const size_type n_columns);
/**
- * Initialize the pattern with
- * two BlockIndices for the block
- * structures of matrix rows and
- * columns. This function is
- * equivalent to calling the
- * previous constructor with the
- * length of the two index vector
- * and then entering the index
- * values.
+ * Initialize the pattern with two BlockIndices for the block structures of
+ * matrix rows and columns. This function is equivalent to calling the
+ * previous constructor with the length of the two index vector and then
+ * entering the index values.
*/
BlockCompressedSetSparsityPattern (const std::vector<size_type> &row_block_sizes,
const std::vector<size_type> &col_block_sizes);
/**
- * Initialize the pattern with
- * two BlockIndices for the block
- * structures of matrix rows and
- * columns.
+ * Initialize the pattern with two BlockIndices for the block structures of
+ * matrix rows and columns.
*/
BlockCompressedSetSparsityPattern (const BlockIndices &row_indices,
const BlockIndices &col_indices);
/**
- * Resize the matrix to a tensor
- * product of matrices with
- * dimensions defined by the
- * arguments.
+ * Resize the matrix to a tensor product of matrices with dimensions defined
+ * by the arguments.
*
- * The matrix will have as many
- * block rows and columns as
- * there are entries in the two
- * arguments. The block at
- * position (<i>i,j</i>) will
- * have the dimensions
- * <tt>row_block_sizes[i]</tt>
- * times <tt>col_block_sizes[j]</tt>.
+ * The matrix will have as many block rows and columns as there are entries
+ * in the two arguments. The block at position (<i>i,j</i>) will have the
+ * dimensions <tt>row_block_sizes[i]</tt> times <tt>col_block_sizes[j]</tt>.
*/
void reinit (const std::vector<size_type> &row_block_sizes,
const std::vector<size_type> &col_block_sizes);
/**
- * Resize the matrix to a tensor
- * product of matrices with
- * dimensions defined by the
- * arguments. The two
- * BlockIndices objects must be
- * initialized and the sparsity
- * pattern will have the
- * same block structure afterwards.
+ * Resize the matrix to a tensor product of matrices with dimensions defined
+ * by the arguments. The two BlockIndices objects must be initialized and
+ * the sparsity pattern will have the same block structure afterwards.
*/
void reinit (const BlockIndices &row_indices, const BlockIndices &col_indices);
/**
- * Allow the use of the reinit
- * functions of the base class as
- * well.
+ * Allow the use of the reinit functions of the base class as well.
*/
using BlockSparsityPatternBase<CompressedSetSparsityPattern>::reinit;
};
* sparsity patterns that can be used to initialize objects of type
* BlockSparsityPattern. It is used in the same way as the
* BlockCompressedSparsityPattern except that it builds upon the
- * CompressedSimpleSparsityPattern instead of the CompressedSparsityPattern. See
- * the documentation of the BlockCompressedSparsityPattern for examples.
+ * CompressedSimpleSparsityPattern instead of the CompressedSparsityPattern.
+ * See the documentation of the BlockCompressedSparsityPattern for examples.
*
* This class is an example of the "dynamic" type of @ref Sparsity.
*
- * <b>Note:</b>
- * There are several, exchangeable variations of this class, see @ref Sparsity,
- * section 'Dynamic block sparsity patterns' for more information.
+ * <b>Note:</b> There are several, exchangeable variations of this class, see
+ * @ref Sparsity, section 'Dynamic block sparsity patterns' for more
+ * information.
*
* This class is used in step-22 and step-31.
*
public:
/**
- * Initialize the matrix empty,
- * that is with no memory
- * allocated. This is useful if
- * you want such objects as
- * member variables in other
- * classes. You can make the
- * structure usable by calling
- * the reinit() function.
+ * Initialize the matrix empty, that is with no memory allocated. This is
+ * useful if you want such objects as member variables in other classes. You
+ * can make the structure usable by calling the reinit() function.
*/
BlockCompressedSimpleSparsityPattern ();
/**
- * Initialize the matrix with the
- * given number of block rows and
- * columns. The blocks themselves
- * are still empty, and you have
- * to call collect_sizes() after
- * you assign them sizes.
+ * Initialize the matrix with the given number of block rows and columns.
+ * The blocks themselves are still empty, and you have to call
+ * collect_sizes() after you assign them sizes.
*/
BlockCompressedSimpleSparsityPattern (const size_type n_rows,
const size_type n_columns);
/**
- * Initialize the pattern with
- * two BlockIndices for the block
- * structures of matrix rows and
- * columns. This function is
- * equivalent to calling the
- * previous constructor with the
- * length of the two index vector
- * and then entering the index
- * values.
+ * Initialize the pattern with two BlockIndices for the block structures of
+ * matrix rows and columns. This function is equivalent to calling the
+ * previous constructor with the length of the two index vector and then
+ * entering the index values.
*/
BlockCompressedSimpleSparsityPattern (const std::vector<size_type> &row_block_sizes,
const std::vector<size_type> &col_block_sizes);
/**
- * Initialize the pattern with symmetric
- * blocks. The number of IndexSets in the
- * vector determine the number of rows
- * and columns of blocks. The size of
- * each block is determined by the size()
- * of the respective IndexSet. Each block
- * only stores the rows given by the
- * values in the IndexSet, which is
- * useful for distributed memory parallel
- * computations and usually corresponds
- * to the locally owned DoFs.
+ * Initialize the pattern with symmetric blocks. The number of IndexSets in
+ * the vector determine the number of rows and columns of blocks. The size
+ * of each block is determined by the size() of the respective IndexSet.
+ * Each block only stores the rows given by the values in the IndexSet,
+ * which is useful for distributed memory parallel computations and usually
+ * corresponds to the locally owned DoFs.
*/
BlockCompressedSimpleSparsityPattern (const std::vector<IndexSet> &partitioning);
/**
- * Resize the pattern to a tensor product
- * of matrices with dimensions defined by
- * the arguments.
+ * Resize the pattern to a tensor product of matrices with dimensions
+ * defined by the arguments.
*
- * The matrix will have as many
- * block rows and columns as
- * there are entries in the two
- * arguments. The block at
- * position (<i>i,j</i>) will
- * have the dimensions
- * <tt>row_block_sizes[i]</tt>
- * times <tt>col_block_sizes[j]</tt>.
+ * The matrix will have as many block rows and columns as there are entries
+ * in the two arguments. The block at position (<i>i,j</i>) will have the
+ * dimensions <tt>row_block_sizes[i]</tt> times <tt>col_block_sizes[j]</tt>.
*/
void reinit (const std::vector<size_type> &row_block_sizes,
const std::vector<size_type> &col_block_sizes);
/**
- * Resize the pattern with symmetric
- * blocks determined by the size() of
- * each IndexSet. See the constructor
- * taking a vector of IndexSets for
- * details.
+ * Resize the pattern with symmetric blocks determined by the size() of each
+ * IndexSet. See the constructor taking a vector of IndexSets for details.
*/
void reinit(const std::vector<IndexSet> &partitioning);
/**
- * Access to column number field.
- * Return the column number of
- * the @p index th entry in row @p row.
+ * Access to column number field. Return the column number of the @p index
+ * th entry in row @p row.
*/
size_type column_number (const size_type row,
const unsigned int index) const;
/**
- * Allow the use of the reinit
- * functions of the base class as
- * well.
+ * Allow the use of the reinit functions of the base class as well.
*/
using BlockSparsityPatternBase<CompressedSimpleSparsityPattern>::reinit;
};
/**
* This class extends the base class to implement an array of Trilinos
* sparsity patterns that can be used to initialize Trilinos block sparse
- * matrices that can be distributed among different processors. It is used
- * in the same way as the BlockSparsityPattern except that it builds upon
- * the TrilinosWrappers::SparsityPattern instead of the
- * dealii::SparsityPattern. See the documentation of the
- * BlockSparsityPattern for examples.
+ * matrices that can be distributed among different processors. It is used in
+ * the same way as the BlockSparsityPattern except that it builds upon the
+ * TrilinosWrappers::SparsityPattern instead of the dealii::SparsityPattern.
+ * See the documentation of the BlockSparsityPattern for examples.
*
- * This class is has properties of the "dynamic" type of @ref Sparsity (in
- * the sense that it can extend the memory if too little elements were
- * allocated), but otherwise is more like the basic deal.II SparsityPattern
- * (in the sense that the method compress() needs to be called before the
- * pattern can be used).
+ * This class is has properties of the "dynamic" type of @ref Sparsity (in the
+ * sense that it can extend the memory if too little elements were allocated),
+ * but otherwise is more like the basic deal.II SparsityPattern (in the sense
+ * that the method compress() needs to be called before the pattern can be
+ * used).
*
* This class is used in step-32.
*
/**
* Initialize the matrix empty, that is with no memory allocated. This is
- * useful if you want such objects as member variables in other
- * classes. You can make the structure usable by calling the reinit()
- * function.
+ * useful if you want such objects as member variables in other classes.
+ * You can make the structure usable by calling the reinit() function.
*/
BlockSparsityPattern ();
/**
- * Initialize the matrix with the given number of block rows and
- * columns. The blocks themselves are still empty, and you have to call
+ * Initialize the matrix with the given number of block rows and columns.
+ * The blocks themselves are still empty, and you have to call
* collect_sizes() after you assign them sizes.
*/
BlockSparsityPattern (const size_type n_rows,
* and columns of the matrix, where the size() of the IndexSets specifies
* the size of the blocks and the values in each IndexSet denotes the rows
* that are going to be saved in each block. The additional index set
- * writable_rows is used to set all rows that we allow to write
- * locally. This constructor is used to create matrices that allow several
- * threads to write simultaneously into the matrix (to different rows, of
- * course), see the method TrilinosWrappers::SparsityPattern::reinit
- * method with three index set arguments for more details.
+ * writable_rows is used to set all rows that we allow to write locally.
+ * This constructor is used to create matrices that allow several threads
+ * to write simultaneously into the matrix (to different rows, of course),
+ * see the method TrilinosWrappers::SparsityPattern::reinit method with
+ * three index set arguments for more details.
*/
BlockSparsityPattern (const std::vector<IndexSet> &row_parallel_partitioning,
const std::vector<IndexSet> &column_parallel_partitioning,
{
public:
/**
- * Typedef the base class for simpler
- * access to its own typedefs.
+ * Typedef the base class for simpler access to its own typedefs.
*/
typedef BlockVectorBase<Vector<Number> > BaseClass;
/**
- * Typedef the type of the underlying
- * vector.
+ * Typedef the type of the underlying vector.
*/
typedef typename BaseClass::BlockType BlockType;
/**
- * Import the typedefs from the base
- * class.
+ * Import the typedefs from the base class.
*/
typedef typename BaseClass::value_type value_type;
typedef typename BaseClass::real_type real_type;
typedef typename BaseClass::const_iterator const_iterator;
/**
- * Constructor. There are three
- * ways to use this
- * constructor. First, without
- * any arguments, it generates
- * an object with no
- * blocks. Given one argument,
- * it initializes <tt>num_blocks</tt>
- * blocks, but these blocks have
- * size zero. The third variant
- * finally initializes all
- * blocks to the same size
- * <tt>block_size</tt>.
+ * Constructor. There are three ways to use this constructor. First, without
+ * any arguments, it generates an object with no blocks. Given one argument,
+ * it initializes <tt>num_blocks</tt> blocks, but these blocks have size
+ * zero. The third variant finally initializes all blocks to the same size
+ * <tt>block_size</tt>.
*
- * Confer the other constructor
- * further down if you intend to
- * use blocks of different
- * sizes.
+ * Confer the other constructor further down if you intend to use blocks of
+ * different sizes.
*/
explicit BlockVector (const unsigned int num_blocks = 0,
const size_type block_size = 0);
/**
- * Copy-Constructor. Dimension set to
- * that of V, all components are copied
+ * Copy-Constructor. Dimension set to that of V, all components are copied
* from V
*/
BlockVector (const BlockVector<Number> &V);
#ifndef DEAL_II_EXPLICIT_CONSTRUCTOR_BUG
/**
- * Copy constructor taking a BlockVector of
- * another data type. This will fail if
- * there is no conversion path from
- * <tt>OtherNumber</tt> to <tt>Number</tt>. Note that
- * you may lose accuracy when copying
- * to a BlockVector with data elements with
- * less accuracy.
+ * Copy constructor taking a BlockVector of another data type. This will
+ * fail if there is no conversion path from <tt>OtherNumber</tt> to
+ * <tt>Number</tt>. Note that you may lose accuracy when copying to a
+ * BlockVector with data elements with less accuracy.
*
- * Older versions of gcc did not honor
- * the @p explicit keyword on template
- * constructors. In such cases, it is
- * easy to accidentally write code that
- * can be very inefficient, since the
- * compiler starts performing hidden
- * conversions. To avoid this, this
- * function is disabled if we have
- * detected a broken compiler during
- * configuration.
+ * Older versions of gcc did not honor the @p explicit keyword on template
+ * constructors. In such cases, it is easy to accidentally write code that
+ * can be very inefficient, since the compiler starts performing hidden
+ * conversions. To avoid this, this function is disabled if we have detected
+ * a broken compiler during configuration.
*/
template <typename OtherNumber>
explicit
#ifdef DEAL_II_WITH_TRILINOS
/**
- * A copy constructor taking a
- * (parallel) Trilinos block
- * vector and copying it into
- * the deal.II own format.
+ * A copy constructor taking a (parallel) Trilinos block vector and copying
+ * it into the deal.II own format.
*/
BlockVector (const TrilinosWrappers::BlockVector &v);
#endif
/**
- * Constructor. Set the number of
- * blocks to
- * <tt>block_sizes.size()</tt> and
- * initialize each block with
- * <tt>block_sizes[i]</tt> zero
- * elements.
+ * Constructor. Set the number of blocks to <tt>block_sizes.size()</tt> and
+ * initialize each block with <tt>block_sizes[i]</tt> zero elements.
*/
BlockVector (const std::vector<size_type> &block_sizes);
/**
- * Constructor. Initialize vector
- * to the structure found in the
- * BlockIndices argument.
+ * Constructor. Initialize vector to the structure found in the BlockIndices
+ * argument.
*/
BlockVector (const BlockIndices &block_indices);
/**
- * Constructor. Set the number of
- * blocks to
- * <tt>n.size()</tt>. Initialize the
- * vector with the elements
- * pointed to by the range of
- * iterators given as second and
- * third argument. Apart from the
- * first argument, this
- * constructor is in complete
- * analogy to the respective
- * constructor of the
- * <tt>std::vector</tt> class, but the
- * first argument is needed in
- * order to know how to subdivide
- * the block vector into
- * different blocks.
+ * Constructor. Set the number of blocks to <tt>n.size()</tt>. Initialize
+ * the vector with the elements pointed to by the range of iterators given
+ * as second and third argument. Apart from the first argument, this
+ * constructor is in complete analogy to the respective constructor of the
+ * <tt>std::vector</tt> class, but the first argument is needed in order to
+ * know how to subdivide the block vector into different blocks.
*/
template <typename InputIterator>
BlockVector (const std::vector<size_type> &n,
~BlockVector ();
/**
- * Call the compress() function on all
- * the subblocks.
- *
- * This functionality only needs to be
- * called if using MPI based vectors and
- * exists in other objects for
- * compatibility.
- *
- * See @ref GlossCompress "Compressing
- * distributed objects" for more
- * information.
+ * Call the compress() function on all the subblocks.
+ *
+ * This functionality only needs to be called if using MPI based vectors and
+ * exists in other objects for compatibility.
+ *
+ * See @ref GlossCompress "Compressing distributed objects" for more
+ * information.
*/
void compress (::dealii::VectorOperation::values operation
=::dealii::VectorOperation::unknown);
/**
- * Copy operator: fill all components of
- * the vector with the given scalar
+ * Copy operator: fill all components of the vector with the given scalar
* value.
*/
BlockVector &operator = (const value_type s);
/**
- * Copy operator for arguments of the
- * same type. Resize the
- * present vector if necessary.
+ * Copy operator for arguments of the same type. Resize the present vector
+ * if necessary.
*/
BlockVector &
operator= (const BlockVector &V);
/**
- * Copy operator for template arguments
- * of different types. Resize the
+ * Copy operator for template arguments of different types. Resize the
* present vector if necessary.
*/
template <class Number2>
operator= (const BlockVector<Number2> &V);
/**
- * Copy a regular vector into a
- * block vector.
+ * Copy a regular vector into a block vector.
*/
BlockVector &
operator= (const Vector<Number> &V);
#ifdef DEAL_II_WITH_TRILINOS
/**
- * A copy constructor from a
- * Trilinos block vector to a
- * deal.II block vector.
+ * A copy constructor from a Trilinos block vector to a deal.II block
+ * vector.
*/
BlockVector &
operator= (const TrilinosWrappers::BlockVector &V);
#endif
/**
- * Reinitialize the BlockVector to
- * contain <tt>num_blocks</tt> blocks of
+ * Reinitialize the BlockVector to contain <tt>num_blocks</tt> blocks of
* size <tt>block_size</tt> each.
*
- * If the second argument is left
- * at its default value, then the
- * block vector allocates the
- * specified number of blocks but
- * leaves them at zero size. You
- * then need to later
- * reinitialize the individual
- * blocks, and call
- * collect_sizes() to update the
- * block system's knowledge of
- * its individual block's sizes.
+ * If the second argument is left at its default value, then the block
+ * vector allocates the specified number of blocks but leaves them at zero
+ * size. You then need to later reinitialize the individual blocks, and call
+ * collect_sizes() to update the block system's knowledge of its individual
+ * block's sizes.
*
- * If <tt>fast==false</tt>, the vector
- * is filled with zeros.
+ * If <tt>fast==false</tt>, the vector is filled with zeros.
*/
void reinit (const unsigned int num_blocks,
const size_type block_size = 0,
const bool fast = false);
/**
- * Reinitialize the BlockVector such that
- * it contains
- * <tt>block_sizes.size()</tt>
- * blocks. Each block is reinitialized to
+ * Reinitialize the BlockVector such that it contains
+ * <tt>block_sizes.size()</tt> blocks. Each block is reinitialized to
* dimension <tt>block_sizes[i]</tt>.
*
- * If the number of blocks is the
- * same as before this function
- * was called, all vectors remain
- * the same and reinit() is
- * called for each vector.
+ * If the number of blocks is the same as before this function was called,
+ * all vectors remain the same and reinit() is called for each vector.
*
- * If <tt>fast==false</tt>, the vector
- * is filled with zeros.
+ * If <tt>fast==false</tt>, the vector is filled with zeros.
*
- * Note that you must call this
- * (or the other reinit()
- * functions) function, rather
- * than calling the reinit()
- * functions of an individual
- * block, to allow the block
- * vector to update its caches of
- * vector sizes. If you call
- * reinit() on one of the
- * blocks, then subsequent
- * actions on this object may
- * yield unpredictable results
- * since they may be routed to
- * the wrong block.
+ * Note that you must call this (or the other reinit() functions) function,
+ * rather than calling the reinit() functions of an individual block, to
+ * allow the block vector to update its caches of vector sizes. If you call
+ * reinit() on one of the blocks, then subsequent actions on this object may
+ * yield unpredictable results since they may be routed to the wrong block.
*/
void reinit (const std::vector<size_type> &N,
const bool fast=false);
/**
- * Reinitialize the BlockVector
- * to reflect the structure found
- * in BlockIndices.
+ * Reinitialize the BlockVector to reflect the structure found in
+ * BlockIndices.
*
- * If the number of blocks is the
- * same as before this function
- * was called, all vectors remain
- * the same and reinit() is
- * called for each vector.
+ * If the number of blocks is the same as before this function was called,
+ * all vectors remain the same and reinit() is called for each vector.
*
- * If <tt>fast==false</tt>, the vector
- * is filled with zeros.
+ * If <tt>fast==false</tt>, the vector is filled with zeros.
*/
void reinit (const BlockIndices &block_indices,
const bool fast=false);
/**
- * Change the dimension to that
- * of the vector <tt>V</tt>. The same
- * applies as for the other
- * reinit() function.
+ * Change the dimension to that of the vector <tt>V</tt>. The same applies
+ * as for the other reinit() function.
*
- * The elements of <tt>V</tt> are not
- * copied, i.e. this function is
- * the same as calling <tt>reinit
- * (V.size(), fast)</tt>.
+ * The elements of <tt>V</tt> are not copied, i.e. this function is the
+ * same as calling <tt>reinit (V.size(), fast)</tt>.
*
- * Note that you must call this
- * (or the other reinit()
- * functions) function, rather
- * than calling the reinit()
- * functions of an individual
- * block, to allow the block
- * vector to update its caches of
- * vector sizes. If you call
- * reinit() of one of the
- * blocks, then subsequent
- * actions of this object may
- * yield unpredictable results
- * since they may be routed to
- * the wrong block.
+ * Note that you must call this (or the other reinit() functions) function,
+ * rather than calling the reinit() functions of an individual block, to
+ * allow the block vector to update its caches of vector sizes. If you call
+ * reinit() of one of the blocks, then subsequent actions of this object may
+ * yield unpredictable results since they may be routed to the wrong block.
*/
template <typename Number2>
void reinit (const BlockVector<Number2> &V,
const bool fast=false);
/**
- * Scale each element of the
- * vector by the given factor.
+ * Scale each element of the vector by the given factor.
*
- * This function is deprecated
- * and will be removed in a
- * future version. Use
- * <tt>operator *=</tt> and
- * <tt>operator /=</tt> instead.
+ * This function is deprecated and will be removed in a future version. Use
+ * <tt>operator *=</tt> and <tt>operator /=</tt> instead.
*
- * @deprecated Use <tt>operator*=</tt>
- * instead.
+ * @deprecated Use <tt>operator*=</tt> instead.
*/
void scale (const value_type factor) DEAL_II_DEPRECATED;
/**
- * Multiply each element of this
- * vector by the corresponding
- * element of <tt>v</tt>.
+ * Multiply each element of this vector by the corresponding element of
+ * <tt>v</tt>.
*/
template <class BlockVector2>
void scale (const BlockVector2 &v);
/**
- * Swap the contents of this
- * vector and the other vector
- * <tt>v</tt>. One could do this
- * operation with a temporary
- * variable and copying over the
- * data elements, but this
- * function is significantly more
- * efficient since it only swaps
- * the pointers to the data of
- * the two vectors and therefore
- * does not need to allocate
- * temporary storage and move
- * data around.
+ * Swap the contents of this vector and the other vector <tt>v</tt>. One
+ * could do this operation with a temporary variable and copying over the
+ * data elements, but this function is significantly more efficient since it
+ * only swaps the pointers to the data of the two vectors and therefore does
+ * not need to allocate temporary storage and move data around.
*
- * Limitation: right now this
- * function only works if both
- * vectors have the same number
- * of blocks. If needed, the
- * numbers of blocks should be
+ * Limitation: right now this function only works if both vectors have the
+ * same number of blocks. If needed, the numbers of blocks should be
* exchanged, too.
*
- * This function is analog to the
- * the swap() function of all C++
- * standard containers. Also,
- * there is a global function
- * swap(u,v) that simply calls
- * <tt>u.swap(v)</tt>, again in analogy
- * to standard functions.
+ * This function is analog to the the swap() function of all C++ standard
+ * containers. Also, there is a global function swap(u,v) that simply calls
+ * <tt>u.swap(v)</tt>, again in analogy to standard functions.
*/
void swap (BlockVector<Number> &v);
/**
- * Output of vector in user-defined
- * format.
+ * Output of vector in user-defined format.
*/
void print (const char *format = 0) const;
const bool across = true) const;
/**
- * Write the vector en bloc to a
- * stream. This is done in a binary mode,
- * so the output is neither readable by
- * humans nor (probably) by other
- * computers using a different operating
- * system or number format.
+ * Write the vector en bloc to a stream. This is done in a binary mode, so
+ * the output is neither readable by humans nor (probably) by other
+ * computers using a different operating system or number format.
*/
void block_write (std::ostream &out) const;
/**
- * Read a vector en block from a
- * file. This is done using the inverse
- * operations to the above function, so
- * it is reasonably fast because the
+ * Read a vector en block from a file. This is done using the inverse
+ * operations to the above function, so it is reasonably fast because the
* bitstream is not interpreted.
*
* The vector is resized if necessary.
*
- * A primitive form of error checking is
- * performed which will recognize the
- * bluntest attempts to interpret some
- * data as a vector stored bitwise to a
+ * A primitive form of error checking is performed which will recognize the
+ * bluntest attempts to interpret some data as a vector stored bitwise to a
* file, but not more.
*/
void block_read (std::istream &in);
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
/**
- * Global function which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two vectors.
+ * Global function which overloads the default implementation of the C++
+ * standard library which uses a temporary object. The function simply
+ * exchanges the data of the two vectors.
*
* @relates BlockVector
* @author Wolfgang Bangerth, 2000
* @code
* IsBlockVector<BlockVector<double> >::value
* @endcode
- * is true. This is sometimes useful in template contexts where we may
- * want to do things differently depending on whether a template type
- * denotes a regular or a block vector type.
+ * is true. This is sometimes useful in template contexts where we may want to
+ * do things differently depending on whether a template type denotes a
+ * regular or a block vector type.
*
* @author Wolfgang Bangerth, 2010
*/
};
/**
- * Overload returning true if the class
- * is derived from BlockVectorBase,
+ * Overload returning true if the class is derived from BlockVectorBase,
* which is what block vectors do.
*/
template <typename T>
static yes_type check_for_block_vector (const BlockVectorBase<T> *);
/**
- * Catch all for all other potential
- * vector types that are not block
+ * Catch all for all other potential vector types that are not block
* matrices.
*/
static no_type check_for_block_vector (...);
public:
/**
- * A statically computable value that
- * indicates whether the template
- * argument to this class is a block
- * vector (in fact whether the type is
+ * A statically computable value that indicates whether the template
+ * argument to this class is a block vector (in fact whether the type is
* derived from BlockVectorBase<T>).
*/
static const bool value = (sizeof(check_for_block_vector
namespace BlockVectorIterators
{
/**
- * Declaration of the general
- * template of a structure which is
- * used to determine some types
- * based on the template arguments
- * of other classes.
+ * Declaration of the general template of a structure which is used to
+ * determine some types based on the template arguments of other classes.
*/
template <class BlockVectorType, bool constness>
struct Types
/**
- * Declaration of a specialized
- * template of a structure which is
- * used to determine some types
- * based on the template arguments
- * of other classes.
+ * Declaration of a specialized template of a structure which is used to
+ * determine some types based on the template arguments of other classes.
*
- * This is for the use of non-const
- * iterators.
+ * This is for the use of non-const iterators.
*/
template <class BlockVectorType>
struct Types<BlockVectorType,false>
{
/**
- * Type of the vector
- * underlying the block vector
- * used in non-const
- * iterators. There, the
- * vector must not be constant.
+ * Type of the vector underlying the block vector used in non-const
+ * iterators. There, the vector must not be constant.
*/
typedef typename BlockVectorType::BlockType Vector;
/**
- * Type of the block vector
- * used in non-const
- * iterators. There, the block
- * vector must not be constant.
+ * Type of the block vector used in non-const iterators. There, the
+ * block vector must not be constant.
*/
typedef BlockVectorType BlockVector;
/**
- * Type of the numbers we point
- * to. Here, they are not
- * constant.
+ * Type of the numbers we point to. Here, they are not constant.
*/
typedef typename BlockVector::value_type value_type;
/**
- * Typedef the result of a
- * dereferencing operation for an
- * iterator of the underlying
- * iterator.
+ * Typedef the result of a dereferencing operation for an iterator of
+ * the underlying iterator.
*/
typedef typename Vector::reference dereference_type;
};
/**
- * Declaration of a specialized
- * template of a structure which is
- * used to determine some types
- * based on the template arguments
- * of other classes.
+ * Declaration of a specialized template of a structure which is used to
+ * determine some types based on the template arguments of other classes.
*
- * This is for the use of
- * const_iterator.
+ * This is for the use of const_iterator.
*/
template <class BlockVectorType>
struct Types<BlockVectorType,true>
{
/**
- * Type of the vector
- * underlying the block vector
- * used in
- * const_iterator. There,
- * the vector must be
- * constant.
+ * Type of the vector underlying the block vector used in
+ * const_iterator. There, the vector must be constant.
*/
typedef const typename BlockVectorType::BlockType Vector;
/**
- * Type of the block vector
- * used in
- * const_iterator. There,
- * the block vector must be
- * constant.
+ * Type of the block vector used in const_iterator. There, the block
+ * vector must be constant.
*/
typedef const BlockVectorType BlockVector;
/**
- * Type of the numbers we point
- * to. Here, they are constant
- * since the block vector we
- * use is constant.
+ * Type of the numbers we point to. Here, they are constant since the
+ * block vector we use is constant.
*/
typedef const typename BlockVector::value_type value_type;
/**
- * Typedef the result of a
- * dereferencing operation for an
- * iterator of the underlying
- * iterator. Since this is for
- * constant iterators, we can only
- * return values, no actual
- * references.
+ * Typedef the result of a dereferencing operation for an iterator of
+ * the underlying iterator. Since this is for constant iterators, we can
+ * only return values, no actual references.
*/
typedef value_type dereference_type;
};
/**
- * General random-access iterator
- * class for block vectors. Since
- * we do not want to have two
- * classes for non-const
- * iterator and
- * const_iterator, we take a
- * second template argument which
- * denotes whether the vector we
- * point into is a constant object
- * or not. The first template
- * argument is always the number
- * type of the block vector in use.
+ * General random-access iterator class for block vectors. Since we do not
+ * want to have two classes for non-const iterator and const_iterator, we
+ * take a second template argument which denotes whether the vector we
+ * point into is a constant object or not. The first template argument is
+ * always the number type of the block vector in use.
*
- * This class satisfies all
- * requirements of random access
- * iterators defined in the C++
- * standard. Operations on these
- * iterators are constant in the
- * number of elements in the block
- * vector. However, they are
- * sometimes linear in the number
- * of blocks in the vector, but
- * since that does rarely change
- * dynamically within an
- * application, this is a constant
- * and we again have that the
- * iterator satisfies the
- * requirements of a random access
- * iterator.
+ * This class satisfies all requirements of random access iterators
+ * defined in the C++ standard. Operations on these iterators are constant
+ * in the number of elements in the block vector. However, they are
+ * sometimes linear in the number of blocks in the vector, but since that
+ * does rarely change dynamically within an application, this is a
+ * constant and we again have that the iterator satisfies the requirements
+ * of a random access iterator.
*
- * The implementation of this class
- * has to work around some problems
- * in compilers and standard
- * libraries. One of these requires
- * us to write all comparison
- * operators twice, once comparison
- * with iterators of the same type
- * and once with iterators pointing
- * to numbers of opposite constness
- * specification. The reason is
- * that if we would have written
- * the comparison operators as a
- * template on the constness of the
- * right hand side, then gcc2.95
- * signals an error that these
- * operators ambiguate operators
- * declared somewhere within the
- * standard library. Likewise, we
- * have to work around some
- * problems with granting other
- * iterators friendship. This makes
- * the implementation somewhat
- * non-optimal at places, but at
- * least everything works.
+ * The implementation of this class has to work around some problems in
+ * compilers and standard libraries. One of these requires us to write all
+ * comparison operators twice, once comparison with iterators of the same
+ * type and once with iterators pointing to numbers of opposite constness
+ * specification. The reason is that if we would have written the
+ * comparison operators as a template on the constness of the right hand
+ * side, then gcc2.95 signals an error that these operators ambiguate
+ * operators declared somewhere within the standard library. Likewise, we
+ * have to work around some problems with granting other iterators
+ * friendship. This makes the implementation somewhat non-optimal at
+ * places, but at least everything works.
*
* @author Wolfgang Bangerth, 2001
*/
{
private:
/**
- * Typedef an iterator with
- * opposite constness
- * requirements on the elements
- * it points to.
+ * Typedef an iterator with opposite constness requirements on the
+ * elements it points to.
*/
typedef Iterator<BlockVectorType,!constness> InverseConstnessIterator;
typedef types::global_dof_index size_type;
/**
- * Type of the number this
- * iterator points
- * to. Depending on the value
- * of the second template
- * parameter, this is either a
- * constant or non-const
+ * Type of the number this iterator points to. Depending on the value of
+ * the second template parameter, this is either a constant or non-const
* number.
*/
typedef
value_type;
/**
- * Declare some typedefs which
- * are standard for iterators
- * and are used by algorithms
- * to enquire about the
- * specifics of the iterators
- * they work on.
+ * Declare some typedefs which are standard for iterators and are used
+ * by algorithms to enquire about the specifics of the iterators they
+ * work on.
*/
typedef std::random_access_iterator_tag iterator_type;
typedef std::ptrdiff_t difference_type;
dereference_type;
/**
- * Typedef the type of the
- * block vector (which differs
- * in constness, depending on
- * the second template
- * parameter).
+ * Typedef the type of the block vector (which differs in constness,
+ * depending on the second template parameter).
*/
typedef
typename Types<BlockVectorType,constness>::BlockVector
BlockVector;
/**
- * Construct an iterator from
- * a vector to which we point
- * and the global index of
- * the element pointed to.
+ * Construct an iterator from a vector to which we point and the global
+ * index of the element pointed to.
*
- * Depending on the value of
- * the <tt>constness</tt> template
- * argument of this class,
- * the first argument of this
- * constructor is either is a
- * const or non-const
- * reference.
+ * Depending on the value of the <tt>constness</tt> template argument of
+ * this class, the first argument of this constructor is either is a
+ * const or non-const reference.
*/
Iterator (BlockVector &parent,
const size_type global_index);
Iterator (const Iterator<BlockVectorType,constness> &c);
/**
- * Copy constructor for
- * conversion between iterators
- * with different constness
- * requirements. This
- * constructor throws an error
- * if an attempt is made at
- * converting a constant to a
- * non-constant iterator.
+ * Copy constructor for conversion between iterators with different
+ * constness requirements. This constructor throws an error if an
+ * attempt is made at converting a constant to a non-constant iterator.
*/
Iterator (const InverseConstnessIterator &c);
private:
/**
- * Constructor used internally
- * in this class. The arguments
- * match exactly the values of
- * the respective member
- * variables.
+ * Constructor used internally in this class. The arguments match
+ * exactly the values of the respective member variables.
*/
Iterator (BlockVector &parent,
const size_type global_index,
Iterator &operator = (const Iterator &c);
/**
- * Dereferencing operator. If the
- * template argument
- * <tt>constness</tt> is
- * <tt>true</tt>, then no writing to
- * the result is possible, making
+ * Dereferencing operator. If the template argument <tt>constness</tt>
+ * is <tt>true</tt>, then no writing to the result is possible, making
* this a const_iterator.
*/
dereference_type operator * () const;
/**
- * Random access operator,
- * grant access to arbitrary
- * elements relative to the one
- * presently pointed to.
+ * Random access operator, grant access to arbitrary elements relative
+ * to the one presently pointed to.
*/
dereference_type operator [] (const difference_type d) const;
/**
- * Prefix increment operator. This
- * operator advances the iterator to
- * the next element and returns a
- * reference to <tt>*this</tt>.
+ * Prefix increment operator. This operator advances the iterator to the
+ * next element and returns a reference to <tt>*this</tt>.
*/
Iterator &operator ++ ();
/**
- * Postfix increment
- * operator. This operator
- * advances the iterator to
- * the next element and
- * returns a copy of the old
- * value of this iterator.
+ * Postfix increment operator. This operator advances the iterator to
+ * the next element and returns a copy of the old value of this
+ * iterator.
*/
Iterator operator ++ (int);
/**
- * Prefix decrement operator. This
- * operator retracts the iterator to
- * the previous element and returns a
- * reference to <tt>*this</tt>.
+ * Prefix decrement operator. This operator retracts the iterator to the
+ * previous element and returns a reference to <tt>*this</tt>.
*/
Iterator &operator -- ();
/**
- * Postfix decrement
- * operator. This operator
- * retracts the iterator to
- * the previous element and
- * returns a copy of the old
- * value of this iterator.
+ * Postfix decrement operator. This operator retracts the iterator to
+ * the previous element and returns a copy of the old value of this
+ * iterator.
*/
Iterator operator -- (int);
/**
- * Compare for equality of
- * iterators. This operator
- * checks whether the vectors
- * pointed to are the same,
- * and if not it throws an
- * exception.
+ * Compare for equality of iterators. This operator checks whether the
+ * vectors pointed to are the same, and if not it throws an exception.
*/
bool operator == (const Iterator &i) const;
/**
- * Same, but compare with an
- * iterator of different
- * constness.
+ * Same, but compare with an iterator of different constness.
*/
bool operator == (const InverseConstnessIterator &i) const;
/**
- * Compare for inequality of
- * iterators. This operator
- * checks whether the vectors
- * pointed to are the same,
- * and if not it throws an
- * exception.
+ * Compare for inequality of iterators. This operator checks whether the
+ * vectors pointed to are the same, and if not it throws an exception.
*/
bool operator != (const Iterator &i) const;
/**
- * Same, but compare with an
- * iterator of different
- * constness.
+ * Same, but compare with an iterator of different constness.
*/
bool operator != (const InverseConstnessIterator &i) const;
/**
- * Check whether this
- * iterators points to an
- * element previous to the
- * one pointed to by the
- * given argument. This
- * operator checks whether
- * the vectors pointed to are
- * the same, and if not it
- * throws an exception.
+ * Check whether this iterators points to an element previous to the one
+ * pointed to by the given argument. This operator checks whether the
+ * vectors pointed to are the same, and if not it throws an exception.
*/
bool operator < (const Iterator &i) const;
/**
- * Same, but compare with an
- * iterator of different
- * constness.
+ * Same, but compare with an iterator of different constness.
*/
bool operator < (const InverseConstnessIterator &i) const;
/**
- * Comparison operator alike
- * to the one above.
+ * Comparison operator alike to the one above.
*/
bool operator <= (const Iterator &i) const;
/**
- * Same, but compare with an
- * iterator of different
- * constness.
+ * Same, but compare with an iterator of different constness.
*/
bool operator <= (const InverseConstnessIterator &i) const;
/**
- * Comparison operator alike
- * to the one above.
+ * Comparison operator alike to the one above.
*/
bool operator > (const Iterator &i) const;
/**
- * Same, but compare with an
- * iterator of different
- * constness.
+ * Same, but compare with an iterator of different constness.
*/
bool operator > (const InverseConstnessIterator &i) const;
/**
- * Comparison operator alike
- * to the one above.
+ * Comparison operator alike to the one above.
*/
bool operator >= (const Iterator &i) const;
/**
- * Same, but compare with an
- * iterator of different
- * constness.
+ * Same, but compare with an iterator of different constness.
*/
bool operator >= (const InverseConstnessIterator &i) const;
/**
- * Return the distance between
- * the two iterators, in
- * elements.
+ * Return the distance between the two iterators, in elements.
*/
difference_type operator - (const Iterator &i) const;
/**
- * Same, but for iterators of
- * opposite constness.
+ * Same, but for iterators of opposite constness.
*/
difference_type operator - (const InverseConstnessIterator &i) const;
/**
- * Return an iterator which is
- * the given number of elements
- * in front of the present one.
+ * Return an iterator which is the given number of elements in front of
+ * the present one.
*/
Iterator operator + (const difference_type &d) const;
/**
- * Return an iterator which is
- * the given number of elements
- * behind the present one.
+ * Return an iterator which is the given number of elements behind the
+ * present one.
*/
Iterator operator - (const difference_type &d) const;
/**
- * Move the iterator <tt>d</tt>
- * elements forward at once,
- * and return the result.
+ * Move the iterator <tt>d</tt> elements forward at once, and return the
+ * result.
*/
Iterator &operator += (const difference_type &d);
/**
- * Move the iterator <tt>d</tt>
- * elements backward at once,
- * and return the result.
+ * Move the iterator <tt>d</tt> elements backward at once, and return
+ * the result.
*/
Iterator &operator -= (const difference_type &d);
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception.
//@}
private:
/**
- * Pointer to the block
- * vector object to which
- * this iterator
- * points. Depending on the
- * value of the <tt>constness</tt>
- * template argument of this
- * class, this is a <tt>const</tt>
- * or non-<tt>const</tt> pointer.
+ * Pointer to the block vector object to which this iterator points.
+ * Depending on the value of the <tt>constness</tt> template argument of
+ * this class, this is a <tt>const</tt> or non-<tt>const</tt> pointer.
*/
BlockVector *parent;
/**
- * Global index of the
- * element to which we
- * presently point.
+ * Global index of the element to which we presently point.
*/
size_type global_index;
/**
- * Current block and index
- * within this block of the
- * element presently pointed
- * to.
+ * Current block and index within this block of the element presently
+ * pointed to.
*/
unsigned int current_block;
size_type index_within_block;
/**
- * Indices of the global
- * element address at which
- * we have to move on to
- * another block when moving
- * forward and
- * backward. These indices
- * are kept as a cache since
- * this is much more
- * efficient than always
- * asking the parent object.
+ * Indices of the global element address at which we have to move on to
+ * another block when moving forward and backward. These indices are
+ * kept as a cache since this is much more efficient than always asking
+ * the parent object.
*/
size_type next_break_forward;
size_type next_break_backward;
/**
- * Mark all other instances of
- * this template as friends. In
- * fact, we only need the
- * inverse constness iterator
- * as friend, but this is
- * something that ISO C++ does
- * not allow to specify.
+ * Mark all other instances of this template as friends. In fact, we
+ * only need the inverse constness iterator as friend, but this is
+ * something that ISO C++ does not allow to specify.
*/
template <typename N, bool C>
friend class Iterator;
/**
- * A vector composed of several blocks each representing a vector of
- * its own.
+ * A vector composed of several blocks each representing a vector of its own.
*
* The BlockVector is a collection of Vectors (e.g. of either deal.II Vector
* objects or PETScWrappers::Vector object). Each of the vectors inside can
* have a different size.
*
* The functionality of BlockVector includes everything a Vector can do, plus
- * the access to a single Vector inside the BlockVector by
- * <tt>block(i)</tt>. It also has a complete random access iterator, just as
- * the other Vector classes or the standard C++ library template
- * <tt>std::vector</tt>. Therefore, all algorithms working on iterators also
- * work with objects of this class.
+ * the access to a single Vector inside the BlockVector by <tt>block(i)</tt>.
+ * It also has a complete random access iterator, just as the other Vector
+ * classes or the standard C++ library template <tt>std::vector</tt>.
+ * Therefore, all algorithms working on iterators also work with objects of
+ * this class.
*
* While this base class implements most of the functionality by dispatching
* calls to its member functions to the respective functions on each of the
*
* <h3>Accessing individual blocks, and resizing vectors</h3>
*
- * Apart from using this object as a whole, you can use each block
- * separately as a vector, using the block() function. There
- * is a single caveat: if you have changed the size of one or several
- * blocks, you must call the function collect_sizes() of the block
- * vector to update its internal structures.
+ * Apart from using this object as a whole, you can use each block separately
+ * as a vector, using the block() function. There is a single caveat: if you
+ * have changed the size of one or several blocks, you must call the function
+ * collect_sizes() of the block vector to update its internal structures.
*
- * @attention Warning: If you change the sizes of single blocks
- * without calling collect_sizes(), results may be unpredictable. The
- * debug version does not check consistency here for performance
- * reasons!
+ * @attention Warning: If you change the sizes of single blocks without
+ * calling collect_sizes(), results may be unpredictable. The debug version
+ * does not check consistency here for performance reasons!
*
* @see @ref GlossBlockLA "Block (linear algebra)"
* @author Wolfgang Bangerth, Guido Kanschat, 1999, 2000, 2001, 2002, 2004
{
public:
/**
- * Typedef the type of the underlying
- * vector.
+ * Typedef the type of the underlying vector.
*/
typedef VectorType BlockType;
typedef types::global_dof_index size_type;
/**
- * Declare a type that has holds
- * real-valued numbers with the
- * same precision as the template
- * argument to this class. If the
- * template argument of this
- * class is a real data type,
- * then real_type equals the
- * template argument. If the
- * template argument is a
- * std::complex type then
- * real_type equals the type
- * underlying the complex
- * numbers.
+ * Declare a type that has holds real-valued numbers with the same precision
+ * as the template argument to this class. If the template argument of this
+ * class is a real data type, then real_type equals the template argument.
+ * If the template argument is a std::complex type then real_type equals the
+ * type underlying the complex numbers.
*
- * This typedef is used to
- * represent the return type of
- * norms.
+ * This typedef is used to represent the return type of norms.
*/
typedef typename BlockType::real_type real_type;
/**
- * A variable that indicates whether this vector
- * supports distributed data storage. If true, then
- * this vector also needs an appropriate compress()
- * function that allows communicating recent set or
- * add operations to individual elements to be communicated
- * to other processors.
+ * A variable that indicates whether this vector supports distributed data
+ * storage. If true, then this vector also needs an appropriate compress()
+ * function that allows communicating recent set or add operations to
+ * individual elements to be communicated to other processors.
*
- * For the current class, the variable equals the
- * value declared for the type of the individual blocks.
+ * For the current class, the variable equals the value declared for the
+ * type of the individual blocks.
*/
static const bool supports_distributed_data = BlockType::supports_distributed_data;
BlockVectorBase ();
/**
- * Update internal structures
- * after resizing
- * vectors. Whenever you reinited
- * a block of a block vector, the
- * internal data structures are
- * corrupted. Therefore, you
- * should call this function
- * after al blocks got their new
+ * Update internal structures after resizing vectors. Whenever you reinited
+ * a block of a block vector, the internal data structures are corrupted.
+ * Therefore, you should call this function after al blocks got their new
* size.
*/
void collect_sizes ();
/**
- * Call the compress() function on all
- * the subblocks of the matrix.
- *
- * This functionality only needs to be
- * called if using MPI based vectors and
- * exists in other objects for
- * compatibility.
- *
- * See @ref GlossCompress "Compressing
- * distributed objects" for more
- * information.
+ * Call the compress() function on all the subblocks of the matrix.
+ *
+ * This functionality only needs to be called if using MPI based vectors and
+ * exists in other objects for compatibility.
+ *
+ * See @ref GlossCompress "Compressing distributed objects" for more
+ * information.
*/
void compress (::dealii::VectorOperation::values operation);
block (const unsigned int i) const;
/**
- * Return a reference on the
- * object that describes the
- * mapping between block and
- * global indices. The use of
- * this function is highly
- * deprecated and it should
- * vanish in one of the next
- * versions
+ * Return a reference on the object that describes the mapping between block
+ * and global indices. The use of this function is highly deprecated and it
+ * should vanish in one of the next versions
*/
const BlockIndices &
get_block_indices () const;
unsigned int n_blocks () const;
/**
- * Return dimension of the vector. This
- * is the sum of the dimensions of all
+ * Return dimension of the vector. This is the sum of the dimensions of all
* components.
*/
std::size_t size () const;
/**
- * Return an index set that describes which elements of this vector
- * are owned by the current processor. Note that this index set does
- * not include elements this vector may store locally as ghost
- * elements but that are in fact owned by another processor.
- * As a consequence, the index sets returned on different
- * processors if this is a distributed vector will form disjoint
- * sets that add up to the complete index set.
- * Obviously, if a vector is created on only one processor, then
- * the result would satisfy
+ * Return an index set that describes which elements of this vector are
+ * owned by the current processor. Note that this index set does not include
+ * elements this vector may store locally as ghost elements but that are in
+ * fact owned by another processor. As a consequence, the index sets
+ * returned on different processors if this is a distributed vector will
+ * form disjoint sets that add up to the complete index set. Obviously, if a
+ * vector is created on only one processor, then the result would satisfy
* @code
* vec.locally_owned_elements() == complete_index_set (vec.size())
* @endcode
*
- * For block vectors, this function returns the union of the
- * locally owned elements of the individual blocks, shifted by
- * their respective index offsets.
+ * For block vectors, this function returns the union of the locally owned
+ * elements of the individual blocks, shifted by their respective index
+ * offsets.
*/
IndexSet locally_owned_elements () const;
/**
- * Return an iterator pointing to
- * the first element.
+ * Return an iterator pointing to the first element.
*/
iterator begin ();
/**
- * Return an iterator pointing to
- * the first element of a
- * constant block vector.
+ * Return an iterator pointing to the first element of a constant block
+ * vector.
*/
const_iterator begin () const;
/**
- * Return an iterator pointing to
- * the element past the end.
+ * Return an iterator pointing to the element past the end.
*/
iterator end ();
/**
- * Return an iterator pointing to
- * the element past the end of a
- * constant block vector.
+ * Return an iterator pointing to the element past the end of a constant
+ * block vector.
*/
const_iterator end () const;
value_type operator() (const size_type i) const;
/**
- * Access components, returns U(i)
- * as a writeable reference.
+ * Access components, returns U(i) as a writeable reference.
*/
reference operator() (const size_type i);
value_type operator[] (const size_type i) const;
/**
- * Access components, returns U(i)
- * as a writeable reference.
+ * Access components, returns U(i) as a writeable reference.
*
* Exactly the same as operator().
*/
reference operator[] (const size_type i);
/**
- * A collective get operation: instead
- * of getting individual elements of a
- * vector, this function allows to get
- * a whole set of elements at once. The
- * indices of the elements to be read
- * are stated in the first argument,
- * the corresponding values are returned in the
- * second.
+ * A collective get operation: instead of getting individual elements of a
+ * vector, this function allows to get a whole set of elements at once. The
+ * indices of the elements to be read are stated in the first argument, the
+ * corresponding values are returned in the second.
*/
template <typename OtherNumber>
void extract_subvector_to (const std::vector<size_type> &indices,
std::vector<OtherNumber> &values) const;
/**
- * Just as the above, but with pointers.
- * Useful in minimizing copying of data around.
+ * Just as the above, but with pointers. Useful in minimizing copying of
+ * data around.
*/
template <typename ForwardIterator, typename OutputIterator>
void extract_subvector_to (ForwardIterator indices_begin,
OutputIterator values_begin) const;
/**
- * Copy operator: fill all components of
- * the vector with the given scalar
+ * Copy operator: fill all components of the vector with the given scalar
* value.
*/
BlockVectorBase &operator = (const value_type s);
/**
- * Copy operator for arguments of the
- * same type.
+ * Copy operator for arguments of the same type.
*/
BlockVectorBase &
operator= (const BlockVectorBase &V);
/**
- * Copy operator for template arguments
- * of different types.
+ * Copy operator for template arguments of different types.
*/
template <class VectorType2>
BlockVectorBase &
operator= (const BlockVectorBase<VectorType2> &V);
/**
- * Copy operator from non-block
- * vectors to block vectors.
+ * Copy operator from non-block vectors to block vectors.
*/
BlockVectorBase &
operator = (const VectorType &v);
/**
- * Check for equality of two block vector
- * types. This operation is only allowed
- * if the two vectors already have the
- * same block structure.
+ * Check for equality of two block vector types. This operation is only
+ * allowed if the two vectors already have the same block structure.
*/
template <class VectorType2>
bool
real_type norm_sqr () const;
/**
- * Return the mean value of the elements
- * of this vector.
+ * Return the mean value of the elements of this vector.
*/
value_type mean_value () const;
/**
- * Return the $l_1$-norm of the vector,
- * i.e. the sum of the absolute values.
+ * Return the $l_1$-norm of the vector, i.e. the sum of the absolute values.
*/
real_type l1_norm () const;
/**
- * Return the $l_2$-norm of the vector,
- * i.e. the square root of the sum of
+ * Return the $l_2$-norm of the vector, i.e. the square root of the sum of
* the squares of the elements.
*/
real_type l2_norm () const;
/**
- * Return the maximum absolute value of
- * the elements of this vector, which is
- * the $l_\infty$-norm of a vector.
+ * Return the maximum absolute value of the elements of this vector, which
+ * is the $l_\infty$-norm of a vector.
*/
real_type linfty_norm () const;
/**
- * Performs a combined operation of a vector addition and a subsequent
- * inner product, returning the value of the inner product. In other words,
- * the result of this function is the same as if the user called
+ * Performs a combined operation of a vector addition and a subsequent inner
+ * product, returning the value of the inner product. In other words, the
+ * result of this function is the same as if the user called
* @code
* this->add(a, V);
* return_value = *this * W;
*
* The reason this function exists is that this operation involves less
* memory transfer than calling the two functions separately on deal.II's
- * vector classes (Vector<Number> and parallel::distributed::Vector<double>).
- * This method only needs to load three vectors, @p this, @p V, @p W,
- * whereas calling separate methods means to load the calling vector @p this
- * twice. Since most vector operations are memory transfer limited, this
- * reduces the time by 25\% (or 50\% if @p W equals @p this).
+ * vector classes (Vector<Number> and
+ * parallel::distributed::Vector<double>). This method only needs to load
+ * three vectors, @p this, @p V, @p W, whereas calling separate methods
+ * means to load the calling vector @p this twice. Since most vector
+ * operations are memory transfer limited, this reduces the time by 25\% (or
+ * 50\% if @p W equals @p this).
*/
value_type add_and_dot (const value_type a,
const BlockVectorBase &V,
const BlockVectorBase &W);
/**
- * Returns true if the given global index is
- * in the local range of this processor.
- * Asks the corresponding block.
+ * Returns true if the given global index is in the local range of this
+ * processor. Asks the corresponding block.
*/
bool in_local_range (const size_type global_index) const;
/**
- * Return whether the vector contains only
- * elements with value zero. This function
- * is mainly for internal consistency
- * check and should seldom be used when
- * not in debug mode since it uses quite
- * some time.
+ * Return whether the vector contains only elements with value zero. This
+ * function is mainly for internal consistency check and should seldom be
+ * used when not in debug mode since it uses quite some time.
*/
bool all_zero () const;
/**
- * Return @p true if the vector has no
- * negative entries, i.e. all entries are
- * zero or positive. This function is
- * used, for example, to check whether
- * refinement indicators are really all
- * positive (or zero).
+ * Return @p true if the vector has no negative entries, i.e. all entries
+ * are zero or positive. This function is used, for example, to check
+ * whether refinement indicators are really all positive (or zero).
*/
bool is_non_negative () const;
/**
- * Addition operator. Fast equivalent to
- * <tt>U.add(1, V)</tt>.
+ * Addition operator. Fast equivalent to <tt>U.add(1, V)</tt>.
*/
BlockVectorBase &
operator += (const BlockVectorBase &V);
/**
- * Subtraction operator. Fast equivalent
- * to <tt>U.add(-1, V)</tt>.
+ * Subtraction operator. Fast equivalent to <tt>U.add(-1, V)</tt>.
*/
BlockVectorBase &
operator -= (const BlockVectorBase &V);
/**
- * A collective add operation:
- * This funnction adds a whole
- * set of values stored in @p
- * values to the vector
- * components specified by @p
- * indices.
+ * A collective add operation: This funnction adds a whole set of values
+ * stored in @p values to the vector components specified by @p indices.
*/
template <typename Number>
void add (const std::vector<size_type> &indices,
const std::vector<Number> &values);
/**
- * This is a second collective
- * add operation. As a
- * difference, this function
- * takes a deal.II vector of
- * values.
+ * This is a second collective add operation. As a difference, this function
+ * takes a deal.II vector of values.
*/
template <typename Number>
void add (const std::vector<size_type> &indices,
const Vector<Number> &values);
/**
- * Take an address where
- * <tt>n_elements</tt> are stored
- * contiguously and add them into
- * the vector. Handles all cases
- * which are not covered by the
- * other two <tt>add()</tt>
- * functions above.
+ * Take an address where <tt>n_elements</tt> are stored contiguously and add
+ * them into the vector. Handles all cases which are not covered by the
+ * other two <tt>add()</tt> functions above.
*/
template <typename Number>
void add (const size_type n_elements,
const Number *values);
/**
- * $U(0-DIM)+=s$. Addition of <tt>s</tt>
- * to all components. Note that
- * <tt>s</tt> is a scalar and not a
- * vector.
+ * $U(0-DIM)+=s$. Addition of <tt>s</tt> to all components. Note that
+ * <tt>s</tt> is a scalar and not a vector.
*/
void add (const value_type s);
/**
- * U+=V.
- * Simple vector addition, equal to the
- * <tt>operator +=</tt>.
+ * U+=V. Simple vector addition, equal to the <tt>operator +=</tt>.
*/
void add (const BlockVectorBase &V);
/**
- * U+=a*V.
- * Simple addition of a scaled vector.
+ * U+=a*V. Simple addition of a scaled vector.
*/
void add (const value_type a, const BlockVectorBase &V);
/**
- * U+=a*V+b*W.
- * Multiple addition of scaled vectors.
+ * U+=a*V+b*W. Multiple addition of scaled vectors.
*/
void add (const value_type a, const BlockVectorBase &V,
const value_type b, const BlockVectorBase &W);
/**
- * U=s*U+V.
- * Scaling and simple vector addition.
+ * U=s*U+V. Scaling and simple vector addition.
*/
void sadd (const value_type s, const BlockVectorBase &V);
/**
- * U=s*U+a*V.
- * Scaling and simple addition.
+ * U=s*U+a*V. Scaling and simple addition.
*/
void sadd (const value_type s, const value_type a, const BlockVectorBase &V);
/**
- * U=s*U+a*V+b*W.
- * Scaling and multiple addition.
+ * U=s*U+a*V+b*W. Scaling and multiple addition.
*/
void sadd (const value_type s, const value_type a,
const BlockVectorBase &V,
const value_type b, const BlockVectorBase &W);
/**
- * U=s*U+a*V+b*W+c*X.
- * Scaling and multiple addition.
+ * U=s*U+a*V+b*W+c*X. Scaling and multiple addition.
*/
void sadd (const value_type s, const value_type a,
const BlockVectorBase &V,
const value_type c, const BlockVectorBase &X);
/**
- * Scale each element of the
- * vector by a constant
- * value.
+ * Scale each element of the vector by a constant value.
*/
BlockVectorBase &operator *= (const value_type factor);
/**
- * Scale each element of the
- * vector by the inverse of the
- * given value.
+ * Scale each element of the vector by the inverse of the given value.
*/
BlockVectorBase &operator /= (const value_type factor);
/**
- * Multiply each element of this
- * vector by the corresponding
- * element of <tt>v</tt>.
+ * Multiply each element of this vector by the corresponding element of
+ * <tt>v</tt>.
*/
template <class BlockVector2>
void scale (const BlockVector2 &v);
/**
- * U=a*V. Assignment.
+ * U=a*V. Assignment.
*/
template <class BlockVector2>
void equ (const value_type a, const BlockVector2 &V);
/**
- * U=a*V+b*W.
- * Replacing by sum.
+ * U=a*V+b*W. Replacing by sum.
*/
void equ (const value_type a, const BlockVectorBase &V,
const value_type b, const BlockVectorBase &W);
/**
- * This function does nothing but is
- * there for compatibility with the
- * @p PETScWrappers::Vector class.
+ * This function does nothing but is there for compatibility with the @p
+ * PETScWrappers::Vector class.
*
- * For the PETSc vector wrapper class,
- * this function updates the ghost
- * values of the PETSc vector. This
- * is necessary after any modification
+ * For the PETSc vector wrapper class, this function updates the ghost
+ * values of the PETSc vector. This is necessary after any modification
* before reading ghost values.
*
- * However, for the implementation of
- * this class, it is immaterial and thus
+ * However, for the implementation of this class, it is immaterial and thus
* an empty function.
*/
void update_ghost_values () const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
std::vector<VectorType> components;
/**
- * Object managing the
- * transformation between global
- * indices and indices within the
- * different blocks.
+ * Object managing the transformation between global indices and indices
+ * within the different blocks.
*/
BlockIndices block_indices;
/**
- * Make the iterator class a
- * friend.
+ * Make the iterator class a friend.
*/
template <typename N, bool C>
friend class dealii::internal::BlockVectorIterators::Iterator;
MatrixType;
/**
- * A typedef for the type you get when you dereference an iterator
- * of the current kind.
+ * A typedef for the type you get when you dereference an iterator of the
+ * current kind.
*/
typedef
const Accessor<number,Constness> &value_type;
bool operator > (const Iterator &) const;
/**
- * Return the distance between the current iterator and the argument.
- * The distance is given by how many times one has to apply operator++
- * to the current iterator to get the argument (for a positive return
- * value), or operator-- (for a negative return value).
+ * Return the distance between the current iterator and the argument. The
+ * distance is given by how many times one has to apply operator++ to the
+ * current iterator to get the argument (for a positive return value), or
+ * operator-- (for a negative return value).
*/
int operator - (const Iterator &p) const;
/**
- * Sparse matrix. This class implements the function to store values
- * in the locations of a sparse matrix denoted by a
- * SparsityPattern. The separation of sparsity pattern and values is
- * done since one can store data elements of different type in these
- * locations without the SparsityPattern having to know this, and more
- * importantly one can associate more than one matrix with the same
- * sparsity pattern.
+ * Sparse matrix. This class implements the function to store values in the
+ * locations of a sparse matrix denoted by a SparsityPattern. The separation
+ * of sparsity pattern and values is done since one can store data elements of
+ * different type in these locations without the SparsityPattern having to
+ * know this, and more importantly one can associate more than one matrix with
+ * the same sparsity pattern.
*
* The use of this class is demonstrated in step-51.
*
typedef types::global_dof_index size_type;
/**
- * Type of matrix entries. In analogy to
- * the STL container classes.
+ * Type of matrix entries. In analogy to the STL container classes.
*/
typedef number value_type;
/**
* Declare a type that has holds real-valued numbers with the same precision
* as the template argument to this class. If the template argument of this
- * class is a real data type, then real_type equals the template
- * argument. If the template argument is a std::complex type then real_type
- * equals the type underlying the complex numbers.
+ * class is a real data type, then real_type equals the template argument.
+ * If the template argument is a std::complex type then real_type equals the
+ * type underlying the complex numbers.
*
* This typedef is used to represent the return type of norms.
*/
/**
* Return the value of the entry (<i>i,j</i>). This may be an expensive
- * operation and you should always take care where to call this function.
- * In order to avoid abuse, this function throws an exception if the
- * required element does not exist in the matrix.
+ * operation and you should always take care where to call this function. In
+ * order to avoid abuse, this function throws an exception if the required
+ * element does not exist in the matrix.
*
* In case you want a function that returns zero instead (for entries that
* are not in the sparsity pattern of the matrix), use the el() function.
void block_write (std::ostream &out) const;
/**
- * Read data that has previously been written by block_write() from a
- * file. This is done using the inverse operations to the above function, so
- * it is reasonably fast because the bitstream is not interpreted except for
- * a few numbers up front.
+ * Read data that has previously been written by block_write() from a file.
+ * This is done using the inverse operations to the above function, so it is
+ * reasonably fast because the bitstream is not interpreted except for a few
+ * numbers up front.
*
* The object is resized on this operation, and all previous contents are
* lost. Note, however, that no checks are performed whether new data and
*/
void block_read (std::istream &in);
//@}
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
template <typename somenumber> friend class ChunkSparseMatrix;
/**
- * Also give access to internal details to the iterator/accessor
- * classes.
+ * Also give access to internal details to the iterator/accessor classes.
*/
template <typename,bool> friend class ChunkSparseMatrixIterators::Iterator;
template <typename,bool> friend class ChunkSparseMatrixIterators::Accessor;
typedef types::global_dof_index size_type;
/**
- * Add the result of multiplying a chunk
- * of size chunk_size times chunk_size by
- * a source vector fragment of size
- * chunk_size to the destination vector
- * fragment.
+ * Add the result of multiplying a chunk of size chunk_size times
+ * chunk_size by a source vector fragment of size chunk_size to the
+ * destination vector fragment.
*/
template <typename MatrixIterator,
typename SrcIterator,
class Iterator;
/**
- * Accessor class for iterators into sparsity patterns. This class is
- * also the base class for both const and non-const accessor classes
- * into sparse matrices.
+ * Accessor class for iterators into sparsity patterns. This class is also
+ * the base class for both const and non-const accessor classes into sparse
+ * matrices.
*
- * Note that this class only allows read access to elements, providing
- * their row and column number. It does not allow modifying the
- * sparsity pattern itself.
+ * Note that this class only allows read access to elements, providing their
+ * row and column number. It does not allow modifying the sparsity pattern
+ * itself.
*
* @author Martin Kronbichler
* @date 2013
* entries are valid. However, before compression, the sparsity pattern
* allocated some memory to be used while still adding new nonzero
* entries; if you create iterators in this phase of the sparsity
- * pattern's lifetime, you will iterate over elements that are not
- * valid. If this is so, then this function will return false.
+ * pattern's lifetime, you will iterate over elements that are not valid.
+ * If this is so, then this function will return false.
*/
bool is_valid_entry () const;
/**
- * Structure representing the sparsity pattern of a sparse matrix.
- * This class is an example of the "static" type of @ref Sparsity.
- * It uses the compressed row storage (CSR) format to store data.
+ * Structure representing the sparsity pattern of a sparse matrix. This class
+ * is an example of the "static" type of @ref Sparsity. It uses the compressed
+ * row storage (CSR) format to store data.
*
* The use of this class is demonstrated in step-51.
*
/**
* Initialize a rectangular matrix.
*
- * @arg m number of rows
- * @arg n number of columns
- * @arg max_per_row maximum number of nonzero entries per row
+ * @arg m number of rows @arg n number of columns @arg max_per_row maximum
+ * number of nonzero entries per row
*/
ChunkSparsityPattern (const size_type m,
const size_type n,
const size_type chunk_size);
/**
- * @deprecated This constructor is deprecated. Use the version
- * without the last argument
+ * @deprecated This constructor is deprecated. Use the version without the
+ * last argument
*/
ChunkSparsityPattern (const size_type m,
const size_type n,
/**
* Initialize a rectangular matrix.
*
- * @arg m number of rows
- * @arg n number of columns
- * @arg row_lengths possible number of nonzero entries for each row. This
- * vector must have one entry for each row.
+ * @arg m number of rows @arg n number of columns @arg row_lengths possible
+ * number of nonzero entries for each row. This vector must have one entry
+ * for each row.
*/
ChunkSparsityPattern (const size_type m,
const size_type n,
const size_type chunk_size);
/**
- * @deprecated This constructor is deprecated. Use the version
- * without the last argument
+ * @deprecated This constructor is deprecated. Use the version without the
+ * last argument
*/
ChunkSparsityPattern (const size_type m,
const size_type n,
/**
* Initialize a quadratic matrix.
*
- * @arg m number of rows and columns
- * @arg row_lengths possible number of nonzero entries for each row. This
- * vector must have one entry for each row.
+ * @arg m number of rows and columns @arg row_lengths possible number of
+ * nonzero entries for each row. This vector must have one entry for each
+ * row.
*/
ChunkSparsityPattern (const size_type m,
const std::vector<size_type> &row_lengths,
const size_type chunk_size);
/**
- * @deprecated This constructor is deprecated. Use the version
- * without the last argument
+ * @deprecated This constructor is deprecated. Use the version without the
+ * last argument
*/
ChunkSparsityPattern (const size_type m,
const std::vector<size_type> &row_lengths,
const size_type chunk_size);
/**
- * @deprecated This function is deprecated. Use the function
- * without the last argument
+ * @deprecated This function is deprecated. Use the function without the
+ * last argument
*/
void reinit (const size_type m,
const size_type n,
* allocated if the new size extends the old one. This is done to save time
* and to avoid fragmentation of the heap.
*
- * If the number of rows equals
- * the number of columns then
- * diagonal elements are stored
- * first in each row to allow
- * optimized access in relaxation
+ * If the number of rows equals the number of columns then diagonal elements
+ * are stored first in each row to allow optimized access in relaxation
* methods of SparseMatrix.
*/
void reinit (const size_type m,
const size_type chunk_size);
/**
- * @deprecated This function is deprecated. Use the function
- * without the last argument
+ * @deprecated This function is deprecated. Use the function without the
+ * last argument
*/
void reinit (const size_type m,
const size_type n,
const size_type chunk_size);
/**
- * @deprecated This function is deprecated. Use the function
- * without the last argument
+ * @deprecated This function is deprecated. Use the function without the
+ * last argument
*/
void reinit (const size_type m,
const size_type n,
const size_type chunk_size);
/**
- * @deprecated This function is deprecated. Use the function
- * without the last argument
+ * @deprecated This function is deprecated. Use the function without the
+ * last argument
*/
template <typename ForwardIterator>
void copy_from (const size_type n_rows,
/**
* Copy data from an object of type CompressedSparsityPattern,
- * CompressedSetSparsityPattern or CompressedSimpleSparsityPattern.
- * Previous content of this object is lost, and the sparsity pattern is in
- * compressed mode afterwards.
+ * CompressedSetSparsityPattern or CompressedSimpleSparsityPattern. Previous
+ * content of this object is lost, and the sparsity pattern is in compressed
+ * mode afterwards.
*/
template <typename SparsityType>
void copy_from (const SparsityType &csp,
const size_type chunk_size);
/**
- * @deprecated This function is deprecated. Use the function
- * without the last argument
+ * @deprecated This function is deprecated. Use the function without the
+ * last argument
*/
template <typename SparsityType>
void copy_from (const SparsityType &csp,
const size_type chunk_size);
/**
- * @deprecated This function is deprecated. Use the function
- * without the last argument
+ * @deprecated This function is deprecated. Use the function without the
+ * last argument
*/
template <typename number>
void copy_from (const FullMatrix<number> &matrix,
* Determine whether the matrix uses the special convention for quadratic
* matrices that the diagonal entries are stored first in each row.
*
- * @deprecated The function always returns true if the matrix is
- * square and false if it is not.
+ * @deprecated The function always returns true if the matrix is square and
+ * false if it is not.
*/
bool optimize_diagonal () const DEAL_II_DEPRECATED;
* explicitly, or if the sparsity pattern contains elements that have been
* added through other means (implicitly) while building it. For the current
* class, the result is true if and only if it is square because it then
- * unconditionally stores the diagonal entries whether they have been added explicitly or not.
+ * unconditionally stores the diagonal entries whether they have been added
+ * explicitly or not.
*
* This function mainly serves the purpose of describing the current class
* in cases where several kinds of sparsity patterns can be passed as
void block_write (std::ostream &out) const;
/**
- * Read data that has previously been written by block_write() from a
- * file. This is done using the inverse operations to the above function, so
- * it is reasonably fast because the bitstream is not interpreted except for
- * a few numbers up front.
+ * Read data that has previously been written by block_write() from a file.
+ * This is done using the inverse operations to the above function, so it is
+ * reasonably fast because the bitstream is not interpreted except for a few
+ * numbers up front.
*
* The object is resized on this operation, and all previous contents are
* lost.
*/
std::size_t memory_consumption () const;
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
*/
/**
- * This class acts as an intermediate form of the
- * SparsityPattern class. From the interface it mostly
- * represents a SparsityPattern object that is kept compressed
- * at all times. However, since the final sparsity pattern is not
- * known while constructing it, keeping the pattern compressed at all
- * times can only be achieved at the expense of either increased
- * memory or run time consumption upon use. The main purpose of this
- * class is to avoid some memory bottlenecks, so we chose to implement
- * it memory conservative, but the chosen data format is too unsuited
- * to be used for actual matrices. It is therefore necessary to first
- * copy the data of this object over to an object of type
- * SparsityPattern before using it in actual matrices.
+ * This class acts as an intermediate form of the SparsityPattern class. From
+ * the interface it mostly represents a SparsityPattern object that is kept
+ * compressed at all times. However, since the final sparsity pattern is not
+ * known while constructing it, keeping the pattern compressed at all times
+ * can only be achieved at the expense of either increased memory or run time
+ * consumption upon use. The main purpose of this class is to avoid some
+ * memory bottlenecks, so we chose to implement it memory conservative, but
+ * the chosen data format is too unsuited to be used for actual matrices. It
+ * is therefore necessary to first copy the data of this object over to an
+ * object of type SparsityPattern before using it in actual matrices.
*
* Another viewpoint is that this class does not need up front allocation of a
* certain amount of memory, but grows as necessary. An extensive description
* of sparsity patterns can be found in the documentation of the @ref Sparsity
* module.
*
- * This class is an example of the "dynamic" type of @ref Sparsity. It
- * is discussed in the step-27 and @ref step_22
- * "step-22" tutorial programs.
+ * This class is an example of the "dynamic" type of @ref Sparsity. It is
+ * discussed in the step-27 and @ref step_22 "step-22" tutorial programs.
*
* <h3>Interface</h3>
*
* Since this class is intended as an intermediate replacement of the
- * SparsityPattern class, it has mostly the same interface, with
- * small changes where necessary. In particular, the add()
- * function, and the functions inquiring properties of the sparsity
- * pattern are the same.
+ * SparsityPattern class, it has mostly the same interface, with small changes
+ * where necessary. In particular, the add() function, and the functions
+ * inquiring properties of the sparsity pattern are the same.
*
*
* <h3>Usage</h3>
* sp.copy_from (compressed_pattern);
* @endcode
*
- * See also step-11 and step-18 for usage
- * patterns of the related CompressedSparsityPattern class, and
- * step-27 of the current class.
+ * See also step-11 and step-18 for usage patterns of the related
+ * CompressedSparsityPattern class, and step-27 of the current class.
*
* <h3>Notes</h3>
*
- * There are several, exchangeable variations of this class, see @ref Sparsity,
- * section '"Dynamic" or "compressed" sparsity patterns' for more information.
+ * There are several, exchangeable variations of this class, see @ref
+ * Sparsity, section '"Dynamic" or "compressed" sparsity patterns' for more
+ * information.
*
- * This class is a variation of the CompressedSparsityPattern class.
- * Instead of using sorted vectors together with a caching algorithm
- * for storing the column indices of nonzero entries, the std::set
- * container is used. This solution might not be the fastest in all
- * situations, but seems to work much better than the
- * CompressedSparsityPattern in the context of hp-adaptivity (see for
- * example step-27), or generally when there are many
- * nonzero entries in each row of a matrix (see @ref step_22
- * "step-22"). On the other hand, a benchmark where nonzero entries
- * were randomly inserted into the sparsity pattern revealed that this
- * class is slower by a factor 4-6 in this situation. Hence, currently
- * the suggestion is to carefully analyze which of the
- * CompressedSparsityPattern classes works best in a certain
- * setting. An algorithm which performs equally well in all situations
- * still has to be found.
+ * This class is a variation of the CompressedSparsityPattern class. Instead
+ * of using sorted vectors together with a caching algorithm for storing the
+ * column indices of nonzero entries, the std::set container is used. This
+ * solution might not be the fastest in all situations, but seems to work much
+ * better than the CompressedSparsityPattern in the context of hp-adaptivity
+ * (see for example step-27), or generally when there are many nonzero entries
+ * in each row of a matrix (see @ref step_22 "step-22"). On the other hand, a
+ * benchmark where nonzero entries were randomly inserted into the sparsity
+ * pattern revealed that this class is slower by a factor 4-6 in this
+ * situation. Hence, currently the suggestion is to carefully analyze which of
+ * the CompressedSparsityPattern classes works best in a certain setting. An
+ * algorithm which performs equally well in all situations still has to be
+ * found.
*
*
* @author Oliver Kayser-Herold, 2007
typedef types::global_dof_index size_type;
/**
- * An iterator that can be used to
- * iterate over the elements of a single
- * row. The result of dereferencing such
- * an iterator is a column index.
+ * An iterator that can be used to iterate over the elements of a single
+ * row. The result of dereferencing such an iterator is a column index.
*/
typedef std::set<size_type>::const_iterator row_iterator;
/**
- * Initialize the matrix empty,
- * that is with no memory
- * allocated. This is useful if
- * you want such objects as
- * member variables in other
- * classes. You can make the
- * structure usable by calling
- * the reinit() function.
+ * Initialize the matrix empty, that is with no memory allocated. This is
+ * useful if you want such objects as member variables in other classes. You
+ * can make the structure usable by calling the reinit() function.
*/
CompressedSetSparsityPattern ();
/**
- * Copy constructor. This constructor is
- * only allowed to be called if the
- * matrix structure to be copied is
- * empty. This is so in order to prevent
- * involuntary copies of objects for
- * temporaries, which can use large
- * amounts of computing time. However,
- * copy constructors are needed if yo
- * want to use the STL data types on
- * classes like this, e.g. to write such
- * statements like <tt>v.push_back
- * (CompressedSetSparsityPattern());</tt>,
- * with @p v a vector of @p
- * CompressedSetSparsityPattern objects.
+ * Copy constructor. This constructor is only allowed to be called if the
+ * matrix structure to be copied is empty. This is so in order to prevent
+ * involuntary copies of objects for temporaries, which can use large
+ * amounts of computing time. However, copy constructors are needed if yo
+ * want to use the STL data types on classes like this, e.g. to write such
+ * statements like <tt>v.push_back (CompressedSetSparsityPattern());</tt>,
+ * with @p v a vector of @p CompressedSetSparsityPattern objects.
*/
CompressedSetSparsityPattern (const CompressedSetSparsityPattern &);
/**
- * Initialize a rectangular
- * matrix with @p m rows and
- * @p n columns.
+ * Initialize a rectangular matrix with @p m rows and @p n columns.
*/
CompressedSetSparsityPattern (const size_type m,
const size_type n);
/**
- * Initialize a square matrix of
- * dimension @p n.
+ * Initialize a square matrix of dimension @p n.
*/
CompressedSetSparsityPattern (const size_type n);
/**
- * Copy operator. For this the
- * same holds as for the copy
- * constructor: it is declared,
- * defined and fine to be called,
- * but the latter only for empty
+ * Copy operator. For this the same holds as for the copy constructor: it is
+ * declared, defined and fine to be called, but the latter only for empty
* objects.
*/
CompressedSetSparsityPattern &operator = (const CompressedSetSparsityPattern &);
/**
- * Reallocate memory and set up
- * data structures for a new
- * matrix with @p m rows and
- * @p n columns, with at most
- * max_entries_per_row() nonzero
- * entries per row.
+ * Reallocate memory and set up data structures for a new matrix with @p m
+ * rows and @p n columns, with at most max_entries_per_row() nonzero entries
+ * per row.
*/
void reinit (const size_type m,
const size_type n);
/**
- * Since this object is kept
- * compressed at all times anway,
- * this function does nothing,
- * but is declared to make the
- * interface of this class as
- * much alike as that of the
- * SparsityPattern class.
+ * Since this object is kept compressed at all times anway, this function
+ * does nothing, but is declared to make the interface of this class as much
+ * alike as that of the SparsityPattern class.
*/
void compress ();
/**
- * Return whether the object is
- * empty. It is empty if no
- * memory is allocated, which is
- * the same as that both
- * dimensions are zero.
+ * Return whether the object is empty. It is empty if no memory is
+ * allocated, which is the same as that both dimensions are zero.
*/
bool empty () const;
/**
- * Return the maximum number of
- * entries per row. Note that
- * this number may change as
- * entries are added.
+ * Return the maximum number of entries per row. Note that this number may
+ * change as entries are added.
*/
size_type max_entries_per_row () const;
/**
- * Add a nonzero entry to the
- * matrix. If the entry already
- * exists, nothing bad happens.
+ * Add a nonzero entry to the matrix. If the entry already exists, nothing
+ * bad happens.
*/
void add (const size_type i,
const size_type j);
/**
- * Add several nonzero entries to the
- * specified row of the matrix. If the
- * entries already exist, nothing bad
- * happens.
+ * Add several nonzero entries to the specified row of the matrix. If the
+ * entries already exist, nothing bad happens.
*/
template <typename ForwardIterator>
void add_entries (const size_type row,
const bool indices_are_sorted = false);
/**
- * Check if a value at a certain
- * position may be non-zero.
+ * Check if a value at a certain position may be non-zero.
*/
bool exists (const size_type i,
const size_type j) const;
/**
- * Make the sparsity pattern
- * symmetric by adding the
- * sparsity pattern of the
+ * Make the sparsity pattern symmetric by adding the sparsity pattern of the
* transpose object.
*
- * This function throws an
- * exception if the sparsity
- * pattern does not represent a
- * square matrix.
+ * This function throws an exception if the sparsity pattern does not
+ * represent a square matrix.
*/
void symmetrize ();
/**
- * Print the sparsity of the
- * matrix. The output consists of
- * one line per row of the format
- * <tt>[i,j1,j2,j3,...]</tt>. <i>i</i>
- * is the row number and
- * <i>jn</i> are the allocated
- * columns in this row.
+ * Print the sparsity of the matrix. The output consists of one line per row
+ * of the format <tt>[i,j1,j2,j3,...]</tt>. <i>i</i> is the row number and
+ * <i>jn</i> are the allocated columns in this row.
*/
void print (std::ostream &out) const;
/**
- * Print the sparsity of the matrix in a
- * format that @p gnuplot understands and
- * which can be used to plot the sparsity
- * pattern in a graphical way. The format
- * consists of pairs <tt>i j</tt> of
- * nonzero elements, each representing
- * one entry of this matrix, one per line
- * of the output file. Indices are
- * counted from zero on, as usual. Since
- * sparsity patterns are printed in the
- * same way as matrices are displayed, we
- * print the negative of the column
- * index, which means that the
- * <tt>(0,0)</tt> element is in the top
- * left rather than in the bottom left
- * corner.
+ * Print the sparsity of the matrix in a format that @p gnuplot understands
+ * and which can be used to plot the sparsity pattern in a graphical way.
+ * The format consists of pairs <tt>i j</tt> of nonzero elements, each
+ * representing one entry of this matrix, one per line of the output file.
+ * Indices are counted from zero on, as usual. Since sparsity patterns are
+ * printed in the same way as matrices are displayed, we print the negative
+ * of the column index, which means that the <tt>(0,0)</tt> element is in
+ * the top left rather than in the bottom left corner.
*
- * Print the sparsity pattern in
- * gnuplot by setting the data style
- * to dots or points and use the
- * @p plot command.
+ * Print the sparsity pattern in gnuplot by setting the data style to dots
+ * or points and use the @p plot command.
*/
void print_gnuplot (std::ostream &out) const;
/**
- * Return number of rows of this
- * matrix, which equals the dimension
- * of the image space.
+ * Return number of rows of this matrix, which equals the dimension of the
+ * image space.
*/
size_type n_rows () const;
/**
- * Return number of columns of this
- * matrix, which equals the dimension
- * of the range space.
+ * Return number of columns of this matrix, which equals the dimension of
+ * the range space.
*/
size_type n_cols () const;
size_type row_length (const size_type row) const;
/**
- * Return an iterator that can loop over
- * all entries in the given
- * row. Dereferencing the iterator yields
- * a column index.
+ * Return an iterator that can loop over all entries in the given row.
+ * Dereferencing the iterator yields a column index.
*/
row_iterator row_begin (const size_type row) const;
/**
- * Compute the bandwidth of the matrix
- * represented by this structure. The
- * bandwidth is the maximum of
- * $|i-j|$ for which the index pair
- * $(i,j)$ represents a nonzero entry
- * of the matrix.
+ * Compute the bandwidth of the matrix represented by this structure. The
+ * bandwidth is the maximum of $|i-j|$ for which the index pair $(i,j)$
+ * represents a nonzero entry of the matrix.
*/
size_type bandwidth () const;
/**
- * Return the number of nonzero elements
- * allocated through this sparsity
+ * Return the number of nonzero elements allocated through this sparsity
* pattern.
*/
size_type n_nonzero_elements () const;
/**
- * Return whether this object stores only
- * those entries that have been added
- * explicitly, or if the sparsity pattern
- * contains elements that have been added
- * through other means (implicitly) while
- * building it. For the current class,
- * the result is always true.
+ * Return whether this object stores only those entries that have been added
+ * explicitly, or if the sparsity pattern contains elements that have been
+ * added through other means (implicitly) while building it. For the current
+ * class, the result is always true.
*
- * This function mainly serves the
- * purpose of describing the current
- * class in cases where several kinds of
- * sparsity patterns can be passed as
+ * This function mainly serves the purpose of describing the current class
+ * in cases where several kinds of sparsity patterns can be passed as
* template arguments.
*/
static
private:
/**
- * Number of rows that this sparsity
- * structure shall represent.
+ * Number of rows that this sparsity structure shall represent.
*/
size_type rows;
/**
- * Number of columns that this sparsity
- * structure shall represent.
+ * Number of columns that this sparsity structure shall represent.
*/
size_type cols;
/**
- * For each row of the matrix, store the
- * allocated non-zero entries as a
- * std::set of column indices. For a
- * discussion of storage schemes see the
+ * For each row of the matrix, store the allocated non-zero entries as a
+ * std::set of column indices. For a discussion of storage schemes see the
* CompressedSparsityPattern::Line class.
*/
struct Line
Line ();
/**
- * Add the given column number to
- * this line.
+ * Add the given column number to this line.
*/
void add (const size_type col_num);
/**
- * Add the columns specified by the
- * iterator range to this line.
+ * Add the columns specified by the iterator range to this line.
*/
template <typename ForwardIterator>
void add_entries (ForwardIterator begin,
/**
- * Actual data: store for each
- * row the set of nonzero
- * entries.
+ * Actual data: store for each row the set of nonzero entries.
*/
std::vector<Line> lines;
};
/**
- * This class acts as an intermediate form of the
- * SparsityPattern class. From the interface it mostly
- * represents a SparsityPattern object that is kept compressed
- * at all times. However, since the final sparsity pattern is not
- * known while constructing it, keeping the pattern compressed at all
- * times can only be achieved at the expense of either increased
- * memory or run time consumption upon use. The main purpose of this
- * class is to avoid some memory bottlenecks, so we chose to implement
- * it memory conservative. The chosen data format is too unsuited
- * to be used for actual matrices, though. It is therefore necessary to first
- * copy the data of this object over to an object of type
- * SparsityPattern before using it in actual matrices.
+ * This class acts as an intermediate form of the SparsityPattern class. From
+ * the interface it mostly represents a SparsityPattern object that is kept
+ * compressed at all times. However, since the final sparsity pattern is not
+ * known while constructing it, keeping the pattern compressed at all times
+ * can only be achieved at the expense of either increased memory or run time
+ * consumption upon use. The main purpose of this class is to avoid some
+ * memory bottlenecks, so we chose to implement it memory conservative. The
+ * chosen data format is too unsuited to be used for actual matrices, though.
+ * It is therefore necessary to first copy the data of this object over to an
+ * object of type SparsityPattern before using it in actual matrices.
*
* Another viewpoint is that this class does not need up front allocation of a
* certain amount of memory, but grows as necessary. An extensive description
* <h3>Interface</h3>
*
* Since this class is intended as an intermediate replacement of the
- * SparsityPattern class, it has mostly the same interface, with
- * small changes where necessary. In particular, the add()
- * function, and the functions inquiring properties of the sparsity
- * pattern are the same.
+ * SparsityPattern class, it has mostly the same interface, with small changes
+ * where necessary. In particular, the add() function, and the functions
+ * inquiring properties of the sparsity pattern are the same.
*
*
* <h3>Usage</h3>
*
* <h3>Notes</h3>
*
- * There are several, exchangeable variations of this class, see @ref Sparsity,
- * section '"Dynamic" or "compressed" sparsity patterns' for more information.
+ * There are several, exchangeable variations of this class, see @ref
+ * Sparsity, section '"Dynamic" or "compressed" sparsity patterns' for more
+ * information.
*
* @author Timo Heister, 2008
*/
/**
* Print the sparsity of the matrix in a format that @p gnuplot understands
- * and which can be used to plot the sparsity pattern in a graphical
- * way. The format consists of pairs <tt>i j</tt> of nonzero elements, each
- * representing one entry of this matrix, one per line of the output
- * file. Indices are counted from zero on, as usual. Since sparsity patterns
- * are printed in the same way as matrices are displayed, we print the
- * negative of the column index, which means that the <tt>(0,0)</tt> element
- * is in the top left rather than in the bottom left corner.
+ * and which can be used to plot the sparsity pattern in a graphical way.
+ * The format consists of pairs <tt>i j</tt> of nonzero elements, each
+ * representing one entry of this matrix, one per line of the output file.
+ * Indices are counted from zero on, as usual. Since sparsity patterns are
+ * printed in the same way as matrices are displayed, we print the negative
+ * of the column index, which means that the <tt>(0,0)</tt> element is in
+ * the top left rather than in the bottom left corner.
*
* Print the sparsity pattern in gnuplot by setting the data style to dots
* or points and use the @p plot command.
const size_type index) const;
/**
- * Return an iterator that can loop over all entries in the given
- * row. Dereferencing the iterator yields a column index.
+ * Return an iterator that can loop over all entries in the given row.
+ * Dereferencing the iterator yields a column index.
*/
row_iterator row_begin (const size_type row) const;
/**
- * This class acts as an intermediate form of the
- * SparsityPattern class. From the interface it mostly
- * represents a SparsityPattern object that is kept compressed
- * at all times. However, since the final sparsity pattern is not
- * known while constructing it, keeping the pattern compressed at all
- * times can only be achieved at the expense of either increased
- * memory or run time consumption upon use. The main purpose of this
- * class is to avoid some memory bottlenecks, so we chose to implement
- * it memory conservative, but the chosen data format is too unsuited
- * to be used for actual matrices. It is therefore necessary to first
- * copy the data of this object over to an object of type
- * SparsityPattern before using it in actual matrices.
+ * This class acts as an intermediate form of the SparsityPattern class. From
+ * the interface it mostly represents a SparsityPattern object that is kept
+ * compressed at all times. However, since the final sparsity pattern is not
+ * known while constructing it, keeping the pattern compressed at all times
+ * can only be achieved at the expense of either increased memory or run time
+ * consumption upon use. The main purpose of this class is to avoid some
+ * memory bottlenecks, so we chose to implement it memory conservative, but
+ * the chosen data format is too unsuited to be used for actual matrices. It
+ * is therefore necessary to first copy the data of this object over to an
+ * object of type SparsityPattern before using it in actual matrices.
*
* Another viewpoint is that this class does not need up front allocation of a
* certain amount of memory, but grows as necessary. An extensive description
* <h3>Interface</h3>
*
* Since this class is intended as an intermediate replacement of the
- * SparsityPattern class, it has mostly the same interface, with
- * small changes where necessary. In particular, the add()
- * function, and the functions inquiring properties of the sparsity
- * pattern are the same.
+ * SparsityPattern class, it has mostly the same interface, with small changes
+ * where necessary. In particular, the add() function, and the functions
+ * inquiring properties of the sparsity pattern are the same.
*
*
* <h3>Usage</h3>
* sp.copy_from (compressed_pattern);
* @endcode
*
- * See also step-11 and step-18 for usage
- * patterns.
+ * See also step-11 and step-18 for usage patterns.
*
* <h3>Notes</h3>
*
- * There are several, exchangeable variations of this class, see @ref Sparsity,
- * section '"Dynamic" or "compressed" sparsity patterns' for more information.
+ * There are several, exchangeable variations of this class, see @ref
+ * Sparsity, section '"Dynamic" or "compressed" sparsity patterns' for more
+ * information.
*
* @author Wolfgang Bangerth, 2001
*/
typedef types::global_dof_index size_type;
/**
- * An iterator that can be used to
- * iterate over the elements of a single
- * row. The result of dereferencing such
- * an iterator is a column index.
+ * An iterator that can be used to iterate over the elements of a single
+ * row. The result of dereferencing such an iterator is a column index.
*/
typedef std::vector<size_type>::const_iterator row_iterator;
/**
- * Initialize the matrix empty,
- * that is with no memory
- * allocated. This is useful if
- * you want such objects as
- * member variables in other
- * classes. You can make the
- * structure usable by calling
- * the reinit() function.
+ * Initialize the matrix empty, that is with no memory allocated. This is
+ * useful if you want such objects as member variables in other classes. You
+ * can make the structure usable by calling the reinit() function.
*/
CompressedSparsityPattern ();
/**
- * Copy constructor. This constructor is
- * only allowed to be called if the
- * matrix structure to be copied is
- * empty. This is so in order to prevent
- * involuntary copies of objects for
- * temporaries, which can use large
- * amounts of computing time. However,
- * copy constructors are needed if yo
- * want to use the STL data types on
- * classes like this, e.g. to write such
- * statements like <tt>v.push_back
- * (CompressedSparsityPattern());</tt>,
- * with @p v a vector of @p
- * CompressedSparsityPattern objects.
+ * Copy constructor. This constructor is only allowed to be called if the
+ * matrix structure to be copied is empty. This is so in order to prevent
+ * involuntary copies of objects for temporaries, which can use large
+ * amounts of computing time. However, copy constructors are needed if yo
+ * want to use the STL data types on classes like this, e.g. to write such
+ * statements like <tt>v.push_back (CompressedSparsityPattern());</tt>, with
+ * @p v a vector of @p CompressedSparsityPattern objects.
*/
CompressedSparsityPattern (const CompressedSparsityPattern &);
/**
- * Initialize a rectangular
- * matrix with @p m rows and
- * @p n columns.
+ * Initialize a rectangular matrix with @p m rows and @p n columns.
*/
CompressedSparsityPattern (const size_type m,
const size_type n);
/**
- * Initialize a square matrix of
- * dimension @p n.
+ * Initialize a square matrix of dimension @p n.
*/
CompressedSparsityPattern (const size_type n);
/**
- * Copy operator. For this the
- * same holds as for the copy
- * constructor: it is declared,
- * defined and fine to be called,
- * but the latter only for empty
+ * Copy operator. For this the same holds as for the copy constructor: it is
+ * declared, defined and fine to be called, but the latter only for empty
* objects.
*/
CompressedSparsityPattern &operator = (const CompressedSparsityPattern &);
/**
- * Reallocate memory and set up
- * data structures for a new
- * matrix with @p m rows and
- * @p n columns, with at most
- * max_entries_per_row() nonzero
- * entries per row.
+ * Reallocate memory and set up data structures for a new matrix with @p m
+ * rows and @p n columns, with at most max_entries_per_row() nonzero entries
+ * per row.
*/
void reinit (const size_type m,
const size_type n);
/**
- * Since this object is kept
- * compressed at all times anway,
- * this function does nothing,
- * but is declared to make the
- * interface of this class as
- * much alike as that of the
- * SparsityPattern class.
+ * Since this object is kept compressed at all times anway, this function
+ * does nothing, but is declared to make the interface of this class as much
+ * alike as that of the SparsityPattern class.
*/
void compress ();
/**
- * Return whether the object is
- * empty. It is empty if no
- * memory is allocated, which is
- * the same as that both
- * dimensions are zero.
+ * Return whether the object is empty. It is empty if no memory is
+ * allocated, which is the same as that both dimensions are zero.
*/
bool empty () const;
/**
- * Return the maximum number of
- * entries per row. Note that
- * this number may change as
- * entries are added.
+ * Return the maximum number of entries per row. Note that this number may
+ * change as entries are added.
*/
size_type max_entries_per_row () const;
/**
- * Add a nonzero entry to the
- * matrix. If the entry already
- * exists, nothing bad happens.
+ * Add a nonzero entry to the matrix. If the entry already exists, nothing
+ * bad happens.
*/
void add (const size_type i,
const size_type j);
/**
- * Add several nonzero entries to the
- * specified row of the matrix. If the
- * entries already exist, nothing bad
- * happens.
+ * Add several nonzero entries to the specified row of the matrix. If the
+ * entries already exist, nothing bad happens.
*/
template <typename ForwardIterator>
void add_entries (const size_type row,
const bool indices_are_unique_and_sorted = false);
/**
- * Check if a value at a certain
- * position may be non-zero.
+ * Check if a value at a certain position may be non-zero.
*/
bool exists (const size_type i,
const size_type j) const;
/**
- * Make the sparsity pattern
- * symmetric by adding the
- * sparsity pattern of the
+ * Make the sparsity pattern symmetric by adding the sparsity pattern of the
* transpose object.
*
- * This function throws an
- * exception if the sparsity
- * pattern does not represent a
- * square matrix.
+ * This function throws an exception if the sparsity pattern does not
+ * represent a square matrix.
*/
void symmetrize ();
/**
- * Print the sparsity of the
- * matrix. The output consists of
- * one line per row of the format
- * <tt>[i,j1,j2,j3,...]</tt>. <i>i</i>
- * is the row number and
- * <i>jn</i> are the allocated
- * columns in this row.
+ * Print the sparsity of the matrix. The output consists of one line per row
+ * of the format <tt>[i,j1,j2,j3,...]</tt>. <i>i</i> is the row number and
+ * <i>jn</i> are the allocated columns in this row.
*/
void print (std::ostream &out) const;
/**
- * Print the sparsity of the matrix in a
- * format that @p gnuplot understands and
- * which can be used to plot the sparsity
- * pattern in a graphical way. The format
- * consists of pairs <tt>i j</tt> of
- * nonzero elements, each representing
- * one entry of this matrix, one per line
- * of the output file. Indices are
- * counted from zero on, as usual. Since
- * sparsity patterns are printed in the
- * same way as matrices are displayed, we
- * print the negative of the column
- * index, which means that the
- * <tt>(0,0)</tt> element is in the top
- * left rather than in the bottom left
- * corner.
+ * Print the sparsity of the matrix in a format that @p gnuplot understands
+ * and which can be used to plot the sparsity pattern in a graphical way.
+ * The format consists of pairs <tt>i j</tt> of nonzero elements, each
+ * representing one entry of this matrix, one per line of the output file.
+ * Indices are counted from zero on, as usual. Since sparsity patterns are
+ * printed in the same way as matrices are displayed, we print the negative
+ * of the column index, which means that the <tt>(0,0)</tt> element is in
+ * the top left rather than in the bottom left corner.
*
- * Print the sparsity pattern in
- * gnuplot by setting the data style
- * to dots or points and use the
- * @p plot command.
+ * Print the sparsity pattern in gnuplot by setting the data style to dots
+ * or points and use the @p plot command.
*/
void print_gnuplot (std::ostream &out) const;
/**
- * Return number of rows of this
- * matrix, which equals the dimension
- * of the image space.
+ * Return number of rows of this matrix, which equals the dimension of the
+ * image space.
*/
size_type n_rows () const;
/**
- * Return number of columns of this
- * matrix, which equals the dimension
- * of the range space.
+ * Return number of columns of this matrix, which equals the dimension of
+ * the range space.
*/
size_type n_cols () const;
size_type row_length (const size_type row) const;
/**
- * Access to column number field.
- * Return the column number of
- * the @p indexth entry in @p row.
+ * Access to column number field. Return the column number of the @p indexth
+ * entry in @p row.
*/
size_type column_number (const size_type row,
const size_type index) const;
/**
- * Return an iterator that can loop over
- * all entries in the given
- * row. Dereferencing the iterator yields
- * a column index.
+ * Return an iterator that can loop over all entries in the given row.
+ * Dereferencing the iterator yields a column index.
*/
row_iterator row_begin (const size_type row) const;
row_iterator row_end (const size_type row) const;
/**
- * Compute the bandwidth of the matrix
- * represented by this structure. The
- * bandwidth is the maximum of
- * $|i-j|$ for which the index pair
- * $(i,j)$ represents a nonzero entry
- * of the matrix.
+ * Compute the bandwidth of the matrix represented by this structure. The
+ * bandwidth is the maximum of $|i-j|$ for which the index pair $(i,j)$
+ * represents a nonzero entry of the matrix.
*/
size_type bandwidth () const;
/**
- * Return the number of nonzero elements
- * allocated through this sparsity
+ * Return the number of nonzero elements allocated through this sparsity
* pattern.
*/
size_type n_nonzero_elements () const;
/**
- * Return whether this object stores only
- * those entries that have been added
- * explicitly, or if the sparsity pattern
- * contains elements that have been added
- * through other means (implicitly) while
- * building it. For the current class,
- * the result is always true.
+ * Return whether this object stores only those entries that have been added
+ * explicitly, or if the sparsity pattern contains elements that have been
+ * added through other means (implicitly) while building it. For the current
+ * class, the result is always true.
*
- * This function mainly serves the
- * purpose of describing the current
- * class in cases where several kinds of
- * sparsity patterns can be passed as
+ * This function mainly serves the purpose of describing the current class
+ * in cases where several kinds of sparsity patterns can be passed as
* template arguments.
*/
static
private:
/**
- * Number of rows that this sparsity
- * structure shall represent.
+ * Number of rows that this sparsity structure shall represent.
*/
size_type rows;
/**
- * Number of columns that this sparsity
- * structure shall represent.
+ * Number of columns that this sparsity structure shall represent.
*/
size_type cols;
/**
- * Store some data for each row
- * describing which entries of this row
- * are nonzero. Data is organized as
- * follows: if an entry is added to a
- * row, it is first added to the #cache
- * variable, irrespective of whether an
- * entry with same column number has
- * already been added. Only if the cache
- * is full do we flush it by removing
- * duplicates, removing entries that are
- * already stored in the @p entries
- * array, sorting everything, and merging
- * the two arrays.
+ * Store some data for each row describing which entries of this row are
+ * nonzero. Data is organized as follows: if an entry is added to a row, it
+ * is first added to the #cache variable, irrespective of whether an entry
+ * with same column number has already been added. Only if the cache is full
+ * do we flush it by removing duplicates, removing entries that are already
+ * stored in the @p entries array, sorting everything, and merging the two
+ * arrays.
*
- * The reasoning behind this scheme is
- * that memory allocation is expensive,
- * and we only want to do it when really
- * necessary. Previously (in deal.II
- * versions up to 5.0), we used to store
- * the column indices inside a std::set,
- * but this would allocate 20 bytes each
- * time we added an entry. (A std::set
- * based class has later been revived in
- * form of the
- * CompressedSetSparsityPattern class, as
- * this turned out to be more efficient
- * for hp finite element programs such as
- * step-27). Using the
- * present scheme, we only need to
- * allocate memory once for every 8 added
- * entries, and we waste a lot less
- * memory by not using a balanced tree
- * for storing column indices.
+ * The reasoning behind this scheme is that memory allocation is expensive,
+ * and we only want to do it when really necessary. Previously (in deal.II
+ * versions up to 5.0), we used to store the column indices inside a
+ * std::set, but this would allocate 20 bytes each time we added an entry.
+ * (A std::set based class has later been revived in form of the
+ * CompressedSetSparsityPattern class, as this turned out to be more
+ * efficient for hp finite element programs such as step-27). Using the
+ * present scheme, we only need to allocate memory once for every 8 added
+ * entries, and we waste a lot less memory by not using a balanced tree for
+ * storing column indices.
*
- * Since some functions that are @p const
- * need to access the data of this
- * object, but need to flush caches
- * before, the flush_cache() function is
- * marked const, and the data members are
- * marked @p mutable.
+ * Since some functions that are @p const need to access the data of this
+ * object, but need to flush caches before, the flush_cache() function is
+ * marked const, and the data members are marked @p mutable.
*
- * A small testseries about the size of
- * the cache showed that the run time of
- * a small program just testing the
- * compressed sparsity pattern element
- * insertion routine ran for 3.6 seconds
- * with a cache size of 8, and 4.2
- * seconds with a cache size of 16. We
- * deem even smaller cache sizes
- * undesirable, since they lead to more
- * memory allocations, while larger cache
- * sizes lead to waste of memory. The
- * original version of this class, with
- * one std::set per row took 8.2 seconds
- * on the same program.
+ * A small testseries about the size of the cache showed that the run time
+ * of a small program just testing the compressed sparsity pattern element
+ * insertion routine ran for 3.6 seconds with a cache size of 8, and 4.2
+ * seconds with a cache size of 16. We deem even smaller cache sizes
+ * undesirable, since they lead to more memory allocations, while larger
+ * cache sizes lead to waste of memory. The original version of this class,
+ * with one std::set per row took 8.2 seconds on the same program.
*/
struct Line
{
public:
/**
- * Storage for the column indices of
- * this row, unless they are still in
- * the cache. This array is always
- * kept sorted.
+ * Storage for the column indices of this row, unless they are still in
+ * the cache. This array is always kept sorted.
*/
mutable std::vector<size_type> entries;
/**
- * Cache of entries that have not yet
- * been written to #entries;
+ * Cache of entries that have not yet been written to #entries;
*/
mutable size_type cache[cache_size];
Line ();
/**
- * Add the given column number to
- * this line.
+ * Add the given column number to this line.
*/
void add (const size_type col_num);
/**
- * Add the columns specified by the
- * iterator range to this line.
+ * Add the columns specified by the iterator range to this line.
*/
template <typename ForwardIterator>
void add_entries (ForwardIterator begin,
const bool indices_are_sorted);
/**
- * Flush the cache my merging it with
- * the #entries array.
+ * Flush the cache my merging it with the #entries array.
*/
void flush_cache () const;
};
/**
- * Actual data: store for each
- * row the set of nonzero
- * entries.
+ * Actual data: store for each row the set of nonzero entries.
*/
std::vector<Line> lines;
};
* constraints is extensively described in the @ref constraints module. The
* class is meant to deal with a limited number of constraints relative to the
* total number of degrees of freedom, for example a few per cent up to maybe
- * 30 per cent; and with a linear combination of <i>M</i> other degrees of freedom
- * where <i>M</i> is also relatively small (no larger than at most around the
- * average number of entries per row of a linear system). It is <em>not</em>
- * meant to describe full rank linear systems.
+ * 30 per cent; and with a linear combination of <i>M</i> other degrees of
+ * freedom where <i>M</i> is also relatively small (no larger than at most
+ * around the average number of entries per row of a linear system). It is
+ * <em>not</em> meant to describe full rank linear systems.
*
* The algorithms used in the implementation of this class are described in
* some detail in the @ref hp_paper "hp paper". There is also a significant
- * amount of documentation on how to use this class in the
- * @ref constraints module.
+ * amount of documentation on how to use this class in the @ref constraints
+ * module.
*
*
* <h3>Description of constraints</h3>
*
* Each "line" in objects of this class corresponds to one constrained degree
- * of freedom, with the number of the line being <i>i</i>, entered by
- * using add_line() or add_lines(). The entries in
- * this line are pairs of the form
+ * of freedom, with the number of the line being <i>i</i>, entered by using
+ * add_line() or add_lines(). The entries in this line are pairs of the form
* (<i>j</i>,<i>a<sub>ij</sub></i>), which are added by add_entry() or
- * add_entries(). The organization is essentially a
- * SparsityPattern, but with only a few lines containing nonzero
- * elements, and therefore no data wasted on the others. For each
- * line, which has been added by the mechanism above, an elimination
- * of the constrained degree of freedom of the form
+ * add_entries(). The organization is essentially a SparsityPattern, but with
+ * only a few lines containing nonzero elements, and therefore no data wasted
+ * on the others. For each line, which has been added by the mechanism above,
+ * an elimination of the constrained degree of freedom of the form
* @f[
* x_i = \sum_j a_{ij} x_j + b_i
* @f]
* is performed, where <i>b<sub>i</sub></i> is optional and set by
- * set_inhomogeneity(). Thus, if a constraint is formulated for
- * instance as a zero mean value of several degrees of freedom, one of
- * the degrees has to be chosen to be eliminated.
+ * set_inhomogeneity(). Thus, if a constraint is formulated for instance as a
+ * zero mean value of several degrees of freedom, one of the degrees has to be
+ * chosen to be eliminated.
*
- * Note that the constraints are linear
- * in the <i>x<sub>i</sub></i>, and that there might be a constant (non-homogeneous) term in
- * the constraint. This is exactly the form we need for hanging node
- * constraints, where we need to constrain one degree of freedom in terms of
- * others. There are other conditions of this form possible, for example for
- * implementing mean value conditions as is done in the step-11
- * tutorial program. The name of the class stems from the fact that these
- * constraints can be represented in matrix form as <b>X</b> <i>x</i> = <i>b</i>, and this object
- * then describes the matrix <b>X</b> (and the vector <i>b</i>;
- * originally, the ConstraintMatrix class was only meant to handle homogenous
- * constraints where <i>b</i>=0, thus the name). The most frequent way to
- * create/fill objects of this type is using the
- * DoFTools::make_hanging_node_constraints() function. The use of these
- * objects is first explained in step-6.
+ * Note that the constraints are linear in the <i>x<sub>i</sub></i>, and that
+ * there might be a constant (non-homogeneous) term in the constraint. This is
+ * exactly the form we need for hanging node constraints, where we need to
+ * constrain one degree of freedom in terms of others. There are other
+ * conditions of this form possible, for example for implementing mean value
+ * conditions as is done in the step-11 tutorial program. The name of the
+ * class stems from the fact that these constraints can be represented in
+ * matrix form as <b>X</b> <i>x</i> = <i>b</i>, and this object then describes
+ * the matrix <b>X</b> (and the vector <i>b</i>; originally, the
+ * ConstraintMatrix class was only meant to handle homogenous constraints
+ * where <i>b</i>=0, thus the name). The most frequent way to create/fill
+ * objects of this type is using the DoFTools::make_hanging_node_constraints()
+ * function. The use of these objects is first explained in step-6.
*
* Objects of the present type are organized in lines (rows), but only those
* lines are stored where constraints are present. New constraints are added
* been added, you need to call close(), which compresses the storage format
* and sorts the entries.
*
- * @note Many of the algorithms this class implements are discussed in
- * the @ref hp_paper . The algorithms are also related to those shown
- * in <i>M. S. Shephard: Linear multipoint constraints applied via
- * transformation as part of a direct stiffness assembly process. Int. J.
- * Numer. Meth. Engrg., vol. 20 (1984), pp. 2107-2112.</i>, with the
- * difference that the algorithms shown there completely eliminated
- * constrained degrees of freedom, whereas we usually keep them as part
- * of the linear system.
+ * @note Many of the algorithms this class implements are discussed in the
+ * @ref hp_paper . The algorithms are also related to those shown in <i>M. S.
+ * Shephard: Linear multipoint constraints applied via transformation as part
+ * of a direct stiffness assembly process. Int. J. Numer. Meth. Engrg., vol.
+ * 20 (1984), pp. 2107-2112.</i>, with the difference that the algorithms
+ * shown there completely eliminated constrained degrees of freedom, whereas
+ * we usually keep them as part of the linear system.
*
* @ingroup dofs
* @ingroup constraints
/**
* Constructor. The supplied IndexSet defines which indices might be
* constrained inside this ConstraintMatrix. In a calculation with a
- * parallel::distributed::DoFHandler one should use
- * locally_relevant_dofs. The IndexSet allows the ConstraintMatrix to save
- * memory. Otherwise internal data structures for all possible indices will
- * be created.
+ * parallel::distributed::DoFHandler one should use locally_relevant_dofs.
+ * The IndexSet allows the ConstraintMatrix to save memory. Otherwise
+ * internal data structures for all possible indices will be created.
*/
ConstraintMatrix (const IndexSet &local_constraints = IndexSet());
ConstraintMatrix (const ConstraintMatrix &constraint_matrix);
/**
- * clear() the ConstraintMatrix object and supply an IndexSet with lines that
- * may be constrained. This function is only relevant in the distributed
- * case to supply a different IndexSet. Otherwise this routine is equivalent
- * to calling clear(). See the constructor for details.
+ * clear() the ConstraintMatrix object and supply an IndexSet with lines
+ * that may be constrained. This function is only relevant in the
+ * distributed case to supply a different IndexSet. Otherwise this routine
+ * is equivalent to calling clear(). See the constructor for details.
*/
void reinit (const IndexSet &local_constraints = IndexSet());
* This function essentially exists to allow adding several constraints of
* the form <i>x<sub>i</sub></i>=0 all at once, where the set of indices
* <i>i</i> for which these constraints should be added are given by the
- * argument of this function. On the other hand, just as if the
- * single-argument add_line() function were called repeatedly, the
- * constraints can later be modified to include linear dependencies using
- * the add_entry() function as well as inhomogeneities using
- * set_inhomogeneity().
+ * argument of this function. On the other hand, just as if the single-
+ * argument add_line() function were called repeatedly, the constraints can
+ * later be modified to include linear dependencies using the add_entry()
+ * function as well as inhomogeneities using set_inhomogeneity().
*/
void add_lines (const std::vector<bool> &lines);
* This function essentially exists to allow adding several constraints of
* the form <i>x<sub>i</sub></i>=0 all at once, where the set of indices
* <i>i</i> for which these constraints should be added are given by the
- * argument of this function. On the other hand, just as if the
- * single-argument add_line() function were called repeatedly, the
- * constraints can later be modified to include linear dependencies using
- * the add_entry() function as well as inhomogeneities using
- * set_inhomogeneity().
+ * argument of this function. On the other hand, just as if the single-
+ * argument add_line() function were called repeatedly, the constraints can
+ * later be modified to include linear dependencies using the add_entry()
+ * function as well as inhomogeneities using set_inhomogeneity().
*/
void add_lines (const std::set<size_type> &lines);
* This function essentially exists to allow adding several constraints of
* the form <i>x<sub>i</sub></i>=0 all at once, where the set of indices
* <i>i</i> for which these constraints should be added are given by the
- * argument of this function. On the other hand, just as if the
- * single-argument add_line() function were called repeatedly, the
- * constraints can later be modified to include linear dependencies using
- * the add_entry() function as well as inhomogeneities using
- * set_inhomogeneity().
+ * argument of this function. On the other hand, just as if the single-
+ * argument add_line() function were called repeatedly, the constraints can
+ * later be modified to include linear dependencies using the add_entry()
+ * function as well as inhomogeneities using set_inhomogeneity().
*/
void add_lines (const IndexSet &lines);
/**
* Add an entry to a given line. The list of lines is searched from the back
* to the front, so clever programming would add a new line (which is pushed
- * to the back) and immediately afterwards fill the entries of that
- * line. This way, no expensive searching is needed.
+ * to the back) and immediately afterwards fill the entries of that line.
+ * This way, no expensive searching is needed.
*
* If an entry with the same indices as the one this function call denotes
* already exists, then this function simply returns provided that the value
/**
* Set an imhomogeneity to the constraint line <i>i</i>, according to the
* discussion in the general class description.
- *
+ *
* @note the line needs to be added with one of the add_line() calls first.
*/
void set_inhomogeneity (const size_type line,
* Merge the constraints represented by the object given as argument into
* the constraints represented by this object. Both objects may or may not
* be closed (by having their function close() called before). If this
- * object was closed before, then it will be closed afterwards as
- * well. Note, however, that if the other argument is closed, then merging
- * may be significantly faster.
+ * object was closed before, then it will be closed afterwards as well.
+ * Note, however, that if the other argument is closed, then merging may be
+ * significantly faster.
*
* Using the default value of the second arguments, the constraints in each
* of the two objects (the old one represented by this object and the
* argument) may not refer to the same degree of freedom, i.e. a degree of
* freedom that is constrained in one object may not be constrained in the
- * second. If this is nevertheless the case, an exception is
- * thrown. However, this behavior can be changed by providing a different
- * value for the second argument.
+ * second. If this is nevertheless the case, an exception is thrown.
+ * However, this behavior can be changed by providing a different value for
+ * the second argument.
*/
void merge (const ConstraintMatrix &other_constraints,
const MergeConflictBehavior merge_conflict_behavior = no_conflicts_allowed);
const size_type index2) const;
/**
- * Return the maximum number of other dofs that one dof is constrained
- * to. For example, in 2d a hanging node is constrained only to its two
+ * Return the maximum number of other dofs that one dof is constrained to.
+ * For example, in 2d a hanging node is constrained only to its two
* neighbors, so the returned value would be 2. However, for higher order
* elements and/or higher dimensions, or other types of constraints, this
* number is no more obvious.
size_type max_constraint_indirections () const;
/**
- * Returns <tt>true</tt> in case the dof is constrained and there is a
- * non-trivial inhomogeneous valeus set to the dof.
+ * Returns <tt>true</tt> in case the dof is constrained and there is a non-
+ * trivial inhomogeneous valeus set to the dof.
*/
bool is_inhomogeneously_constrained (const size_type index) const;
*
* The constraint matrix object must be closed to call this function.
*
- * @deprecated The functions converting an uncondensed matrix into
- * its condensed form are deprecated. Use the functions doing the
- * in-place condensation leaving the size of the linear system unchanged.
+ * @deprecated The functions converting an uncondensed matrix into its
+ * condensed form are deprecated. Use the functions doing the in-place
+ * condensation leaving the size of the linear system unchanged.
*/
template<typename number>
void condense (const SparseMatrix<number> &uncondensed,
* Vector<float>, Vector<double>, BlockVector<tt><...></tt>, a PETSc or
* Trilinos vector wrapper class, or any other type having the same
* interface. Note that this function does not take any inhomogeneity into
- * account and throws an exception in case there are any
- * inhomogeneities. Use the function using both a matrix and vector for that
- * case.
+ * account and throws an exception in case there are any inhomogeneities.
+ * Use the function using both a matrix and vector for that case.
*
* @note This function does not work for MPI vectors. Use condense() with
* two vector arguments instead.
*
* The constraint matrix object must be closed to call this function.
*
- * @deprecated The functions converting an uncondensed matrix into
- * its condensed form are deprecated. Use the functions doing the
- * in-place condensation leaving the size of the linear system unchanged.
+ * @deprecated The functions converting an uncondensed matrix into its
+ * condensed form are deprecated. Use the functions doing the in-place
+ * condensation leaving the size of the linear system unchanged.
*/
template<typename number, class VectorType>
void condense (const SparseMatrix<number> &uncondensed_matrix,
*
* @note This function in itself is thread-safe, i.e., it works properly
* also when several threads call it simultaneously. However, the function
- * call is only thread-safe if the underlying global vector allows
- * for simultaneous access and the access is not to rows with the same
- * global index at the same time. This needs to be made sure from the
- * caller's site. There is no locking mechanism inside this method to
- * prevent data races.
+ * call is only thread-safe if the underlying global vector allows for
+ * simultaneous access and the access is not to rows with the same global
+ * index at the same time. This needs to be made sure from the caller's
+ * site. There is no locking mechanism inside this method to prevent data
+ * races.
*/
template <class InVector, class OutVector>
void
*
* @note This function in itself is thread-safe, i.e., it works properly
* also when several threads call it simultaneously. However, the function
- * call is only thread-safe if the underlying global vector allows
- * for simultaneous access and the access is not to rows with the same
- * global index at the same time. This needs to be made sure from the
- * caller's site. There is no locking mechanism inside this method to
- * prevent data races.
+ * call is only thread-safe if the underlying global vector allows for
+ * simultaneous access and the access is not to rows with the same global
+ * index at the same time. This needs to be made sure from the caller's
+ * site. There is no locking mechanism inside this method to prevent data
+ * races.
*/
template <typename VectorType>
void
*
* @note This function in itself is thread-safe, i.e., it works properly
* also when several threads call it simultaneously. However, the function
- * call is only thread-safe if the underlying global vector allows
- * for simultaneous access and the access is not to rows with the same
- * global index at the same time. This needs to be made sure from the
- * caller's site. There is no locking mechanism inside this method to
- * prevent data races.
+ * call is only thread-safe if the underlying global vector allows for
+ * simultaneous access and the access is not to rows with the same global
+ * index at the same time. This needs to be made sure from the caller's
+ * site. There is no locking mechanism inside this method to prevent data
+ * races.
*/
template <typename ForwardIteratorVec, typename ForwardIteratorInd,
class VectorType>
* corresponding to constrained nodes. Thus, if a degree of freedom in @p
* local_dof_indices is constrained, we distribute the corresponding entries
* in the matrix, but also add the absolute value of the diagonal entry of
- * the local matrix to the corresponding entry in the global
- * matrix. Assuming the discretized operator is positive definite,
- * this guarantees that the diagonal entry is always
- * non-zero, positive, and of the same order of magnitude as the other
- * entries of the matrix. On the other hand, when solving a source
- * problem $Au=f$ the exact value of the diagonal element is not
- * important, since the value of
- * the respective degree of freedom will be overwritten by the distribute()
- * call later on anyway.
- *
- * @note The procedure described above adds an unforeseeable number
- * of artificial eigenvalues to the spectrum of the
- * matrix. Therefore, it is recommended to use the equivalent
- * function with two local index vectors in such a case.
- *
- * By using this function to distribute local contributions to the
- * global object, one saves the call to the condense function after the
- * vectors and matrices are fully assembled.
+ * the local matrix to the corresponding entry in the global matrix.
+ * Assuming the discretized operator is positive definite, this guarantees
+ * that the diagonal entry is always non-zero, positive, and of the same
+ * order of magnitude as the other entries of the matrix. On the other hand,
+ * when solving a source problem $Au=f$ the exact value of the diagonal
+ * element is not important, since the value of the respective degree of
+ * freedom will be overwritten by the distribute() call later on anyway.
+ *
+ * @note The procedure described above adds an unforeseeable number of
+ * artificial eigenvalues to the spectrum of the matrix. Therefore, it is
+ * recommended to use the equivalent function with two local index vectors
+ * in such a case.
+ *
+ * By using this function to distribute local contributions to the global
+ * object, one saves the call to the condense function after the vectors and
+ * matrices are fully assembled.
*
* @note This function in itself is thread-safe, i.e., it works properly
* also when several threads call it simultaneously. However, the function
- * call is only thread-safe if the underlying global matrix allows
- * for simultaneous access and the access is not to rows with the same
- * global index at the same time. This needs to be made sure from the
- * caller's site. There is no locking mechanism inside this method to
- * prevent data races.
+ * call is only thread-safe if the underlying global matrix allows for
+ * simultaneous access and the access is not to rows with the same global
+ * index at the same time. This needs to be made sure from the caller's
+ * site. There is no locking mechanism inside this method to prevent data
+ * races.
*/
template <typename MatrixType>
void
/**
* Does almost the same as the function above but can treat general
- * rectangular matrices. The main difference to achieve this is
- * that the diagonal entries in constrained rows are left untouched
- * instead of being filled with arbitrary values.
+ * rectangular matrices. The main difference to achieve this is that the
+ * diagonal entries in constrained rows are left untouched instead of being
+ * filled with arbitrary values.
*
- * Since the diagonal entries corresponding to eliminated degrees of
- * freedom are not set, the result may have a zero eigenvalue, if
- * applied to a square matrix. This has to be considered when
- * solving the resulting problems. For solving a source problem
- * $Au=f$, it is possible to set the diagonal entry after building
- * the matrix by a piece of code of the form
+ * Since the diagonal entries corresponding to eliminated degrees of freedom
+ * are not set, the result may have a zero eigenvalue, if applied to a
+ * square matrix. This has to be considered when solving the resulting
+ * problems. For solving a source problem $Au=f$, it is possible to set the
+ * diagonal entry after building the matrix by a piece of code of the form
*
* @code
* for (unsigned int i=0;i<matrix.m();++i)
* matrix.diag_element(i) = 1.;
* @endcode
*
- * The value of one which is used here is arbitrary, but in the
- * context of Krylov space methods uncritical, since it corresponds
- * to an invariant subspace. If the other matrix entries are smaller
- * or larger by a factor close to machine accuracy, it may be
- * advisable to adjust it.
+ * The value of one which is used here is arbitrary, but in the context of
+ * Krylov space methods uncritical, since it corresponds to an invariant
+ * subspace. If the other matrix entries are smaller or larger by a factor
+ * close to machine accuracy, it may be advisable to adjust it.
*
- * For solving eigenvalue problems, this will only add one spurious
- * zero eigenvalue (with a multiplicity that is possibly greater
- * than one). Taking this into account, nothing else has to be changed.
+ * For solving eigenvalue problems, this will only add one spurious zero
+ * eigenvalue (with a multiplicity that is possibly greater than one).
+ * Taking this into account, nothing else has to be changed.
*/
template <typename MatrixType>
void
/**
* This function simultaneously writes elements into matrix and vector,
- * according to the constraints specified by the calling
- * ConstraintMatrix. This function can correctly handle inhomogeneous
- * constraints as well. For the parameter use_inhomogeneities_for_rhs see
- * the documentation in @ref constraints module.
+ * according to the constraints specified by the calling ConstraintMatrix.
+ * This function can correctly handle inhomogeneous constraints as well. For
+ * the parameter use_inhomogeneities_for_rhs see the documentation in @ref
+ * constraints module.
*
* @note This function in itself is thread-safe, i.e., it works properly
* also when several threads call it simultaneously. However, the function
* that.
*
* Because the function only allocates entries in a sparsity pattern, all it
- * needs to know are the degrees of freedom that couple to each
- * other. Unlike the previous function, no actual values are written, so the
- * second input argument is not necessary here.
+ * needs to know are the degrees of freedom that couple to each other.
+ * Unlike the previous function, no actual values are written, so the second
+ * input argument is not necessary here.
*
* The third argument to this function, keep_constrained_entries determines
* whether the function shall allocate entries in the sparsity pattern at
*/
/**
- * Re-distribute the elements of the vector @p condensed to @p
- * uncondensed. It is the user's responsibility to guarantee that all
- * entries of @p uncondensed be zero!
+ * Re-distribute the elements of the vector @p condensed to @p uncondensed.
+ * It is the user's responsibility to guarantee that all entries of @p
+ * uncondensed be zero!
*
* This function undoes the action of @p condense somehow, but it should be
* noted that it is not the inverse of @p condense.
* To make things worse, traversing the list of existing constraints
* requires reads from many different places in memory. Thus, in large 3d
* applications, the add_line() function showed up very prominently in the
- * overall compute time, mainly because it generated a lot of cache
- * misses. This should also be fixed by using the O(1) algorithm to access
- * the fields of this array.
+ * overall compute time, mainly because it generated a lot of cache misses.
+ * This should also be fixed by using the O(1) algorithm to access the
+ * fields of this array.
*
* The field is useful in a number of other contexts as well, e.g. when one
* needs random access to the constraints as in all the functions that apply
* Since each thread gets its private version of scratch data out of the
* ThreadLocalStorage, no conflicting access can occur. For this to be
* valid, we need to make sure that no call within
- * distribute_local_to_global is made that by itself can spawn
- * tasks. Otherwise, we might end up in a situation where several threads
- * fight for the data.
+ * distribute_local_to_global is made that by itself can spawn tasks.
+ * Otherwise, we might end up in a situation where several threads fight for
+ * the data.
*
* Access to the scratch data is only through the accessor class which
* handles the access as well as marking the data as used.
/**
* Power method (von Mises) for eigenvalue computations.
*
- * This method determines the largest eigenvalue of a matrix by
- * applying increasing powers of this matrix to a vector. If there is
- * an eigenvalue $l$ with dominant absolute value, the iteration vectors
- * will become aligned to its eigenspace and $Ax = lx$.
+ * This method determines the largest eigenvalue of a matrix by applying
+ * increasing powers of this matrix to a vector. If there is an eigenvalue $l$
+ * with dominant absolute value, the iteration vectors will become aligned to
+ * its eigenspace and $Ax = lx$.
*
- * A shift parameter allows to shift the spectrum, so it is possible
- * to compute the smallest eigenvalue, too.
+ * A shift parameter allows to shift the spectrum, so it is possible to
+ * compute the smallest eigenvalue, too.
*
* Convergence of this method is known to be slow.
*
typedef types::global_dof_index size_type;
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
{
/**
- * Shift parameter. This
- * parameter allows to shift
- * the spectrum to compute a
- * different eigenvalue.
+ * Shift parameter. This parameter allows to shift the spectrum to compute
+ * a different eigenvalue.
*/
double shift;
/**
virtual ~EigenPower ();
/**
- * Power method. @p x is the
- * (not necessarily normalized,
- * but nonzero) start vector for
- * the power method. After the
- * iteration, @p value is the
- * approximated eigenvalue and
- * @p x is the corresponding
- * eigenvector, normalized with
- * respect to the l2-norm.
+ * Power method. @p x is the (not necessarily normalized, but nonzero) start
+ * vector for the power method. After the iteration, @p value is the
+ * approximated eigenvalue and @p x is the corresponding eigenvector,
+ * normalized with respect to the l2-norm.
*/
template <class MATRIX>
void
/**
* Inverse iteration (Wieland) for eigenvalue computations.
*
- * This class implements an adaptive version of the inverse iteration by Wieland.
+ * This class implements an adaptive version of the inverse iteration by
+ * Wieland.
*
- * There are two choices for the stopping criterion: by default, the
- * norm of the residual $A x - l x$ is computed. Since this might not
- * converge to zero for non-symmetric matrices with non-trivial Jordan
- * blocks, it can be replaced by checking the difference of successive
- * eigenvalues. Use AdditionalData::use_residual for switching
- * this option.
+ * There are two choices for the stopping criterion: by default, the norm of
+ * the residual $A x - l x$ is computed. Since this might not converge to zero
+ * for non-symmetric matrices with non-trivial Jordan blocks, it can be
+ * replaced by checking the difference of successive eigenvalues. Use
+ * AdditionalData::use_residual for switching this option.
*
- * Usually, the initial guess entering this method is updated after
- * each step, replacing it with the new approximation of the
- * eigenvalue. Using a parameter AdditionalData::relaxation
- * between 0 and 1, this update can be damped. With relaxation
- * parameter 0, no update is performed. This damping allows for slower
- * adaption of the shift value to make sure that the method converges
- * to the eigenvalue closest to the initial guess. This can be aided
- * by the parameter AdditionalData::start_adaption, which
- * indicates the first iteration step in which the shift value should
- * be adapted.
+ * Usually, the initial guess entering this method is updated after each step,
+ * replacing it with the new approximation of the eigenvalue. Using a
+ * parameter AdditionalData::relaxation between 0 and 1, this update can be
+ * damped. With relaxation parameter 0, no update is performed. This damping
+ * allows for slower adaption of the shift value to make sure that the method
+ * converges to the eigenvalue closest to the initial guess. This can be aided
+ * by the parameter AdditionalData::start_adaption, which indicates the first
+ * iteration step in which the shift value should be adapted.
*
* @author Guido Kanschat, 2000, 2003
*/
typedef types::global_dof_index size_type;
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
{
double relaxation;
/**
- * Start step of adaptive
- * shift parameter.
+ * Start step of adaptive shift parameter.
*/
unsigned int start_adaption;
/**
virtual ~EigenInverse ();
/**
- * Inverse method. @p value is
- * the start guess for the
- * eigenvalue and @p x is the
- * (not necessarily normalized,
- * but nonzero) start vector for
- * the power method. After the
- * iteration, @p value is the
- * approximated eigenvalue and
- * @p x is the corresponding
- * eigenvector, normalized with
+ * Inverse method. @p value is the start guess for the eigenvalue and @p x
+ * is the (not necessarily normalized, but nonzero) start vector for the
+ * power method. After the iteration, @p value is the approximated
+ * eigenvalue and @p x is the corresponding eigenvector, normalized with
* respect to the l2-norm.
*/
template <class MATRIX>
//@{
/**
- * This function only works for
- * quadratic matrices.
+ * This function only works for quadratic matrices.
*/
DeclException0 (ExcNotQuadratic);
/**
- * The operation cannot be finished
- * since the matrix is singular.
+ * The operation cannot be finished since the matrix is singular.
*/
DeclException0 (ExcSingular);
/**
- * Block indices of two block
- * objects are different.
+ * Block indices of two block objects are different.
*/
DeclException0 (ExcDifferentBlockIndices);
/**
- * An error of a PETSc function was
- * encountered. Check the PETSc
+ * An error of a PETSc function was encountered. Check the PETSc
* documentation for details.
*/
DeclException1 (ExcPETScError,
<< " occurred while calling a PETSc function");
/**
- * An error of a Trilinos function was
- * encountered. Check the Trilinos
+ * An error of a Trilinos function was encountered. Check the Trilinos
* documentation for details.
*/
DeclException1 (ExcTrilinosError,
/**
* This class is a wrapper for linear systems of equations with simple
- * equality constraints fixing individual degrees of freedom to a
- * certain value such as when using Dirichlet boundary
- * values.
+ * equality constraints fixing individual degrees of freedom to a certain
+ * value such as when using Dirichlet boundary values.
*
* In order to accomplish this, the vmult(), Tvmult(), vmult_add() and
- * Tvmult_add functions modify the same function of the original
- * matrix such as if all constrained entries of the source vector were
- * zero. Additionally, all constrained entries of the destination
- * vector are set to zero.
+ * Tvmult_add functions modify the same function of the original matrix such
+ * as if all constrained entries of the source vector were zero. Additionally,
+ * all constrained entries of the destination vector are set to zero.
*
* <h3>Usage</h3>
*
- * Usage is simple: create an object of this type, point it to a
- * matrix that shall be used for $A$ above (either through the
- * constructor, the copy constructor, or the
- * set_referenced_matrix() function), specify the list of boundary
- * values or other constraints (through the add_constraints()
- * function), and then for each required solution modify the right
- * hand side vector (through apply_constraints()) and use this
- * object as matrix object in a linear solver. As linear solvers
- * should only use vmult() and residual() functions of a
- * matrix class, this class should be as good a matrix as any other
- * for that purpose.
+ * Usage is simple: create an object of this type, point it to a matrix that
+ * shall be used for $A$ above (either through the constructor, the copy
+ * constructor, or the set_referenced_matrix() function), specify the list of
+ * boundary values or other constraints (through the add_constraints()
+ * function), and then for each required solution modify the right hand side
+ * vector (through apply_constraints()) and use this object as matrix object
+ * in a linear solver. As linear solvers should only use vmult() and
+ * residual() functions of a matrix class, this class should be as good a
+ * matrix as any other for that purpose.
*
- * Furthermore, also the precondition_Jacobi() function is
- * provided (since the computation of diagonal elements of the
- * filtered matrix $A_X$ is simple), so you can use this as a
- * preconditioner. Some other functions useful for matrices are also
- * available.
+ * Furthermore, also the precondition_Jacobi() function is provided (since the
+ * computation of diagonal elements of the filtered matrix $A_X$ is simple),
+ * so you can use this as a preconditioner. Some other functions useful for
+ * matrices are also available.
*
* A typical code snippet showing the above steps is as follows:
* @code
*
* <h3>Connection to other classes</h3>
*
- * The function MatrixTools::apply_boundary_values() does exactly
- * the same that this class does, except for the fact that that
- * function actually modifies the matrix. Consequently, it is only
- * possible to solve with a matrix to which
- * MatrixTools::apply_boundary_values() was applied for one right
- * hand side and one set of boundary values since the modification of
+ * The function MatrixTools::apply_boundary_values() does exactly the same
+ * that this class does, except for the fact that that function actually
+ * modifies the matrix. Consequently, it is only possible to solve with a
+ * matrix to which MatrixTools::apply_boundary_values() was applied for one
+ * right hand side and one set of boundary values since the modification of
* the right hand side depends on the original matrix.
*
- * While this is a feasible method in cases where only
- * one solution of the linear system is required, for example in
- * solving linear stationary systems, one would often like to have the
- * ability to solve multiple times with the same matrix in nonlinear
- * problems (where one often does not want to update the Hessian
- * between Newton steps, despite having different right hand sides in
- * subsequent steps) or time dependent problems, without having to
- * re-assemble the matrix or copy it to temporary matrices with which
- * one then can work. For these cases, this class is meant.
+ * While this is a feasible method in cases where only one solution of the
+ * linear system is required, for example in solving linear stationary
+ * systems, one would often like to have the ability to solve multiple times
+ * with the same matrix in nonlinear problems (where one often does not want
+ * to update the Hessian between Newton steps, despite having different right
+ * hand sides in subsequent steps) or time dependent problems, without having
+ * to re-assemble the matrix or copy it to temporary matrices with which one
+ * then can work. For these cases, this class is meant.
*
*
- * <h3>Some background</h3>
- * Mathematically speaking, it is used to represent a system
- * of linear equations $Ax=b$ with the constraint that $B_D x = g_D$,
- * where $B_D$ is a rectangular matrix with exactly one $1$ in each
- * row, and these $1$s in those columns representing constrained
- * degrees of freedom (e.g. for Dirichlet boundary nodes, thus the
- * index $D$) and zeroes for all other diagonal entries, and $g_D$
- * having the requested nodal values for these constrained
- * nodes. Thus, the underdetermined equation $B_D x = g_D$ fixes only
- * the constrained nodes and does not impose any condition on the
- * others. We note that $B_D B_D^T = 1_D$, where $1_D$ is the identity
- * matrix with dimension as large as the number of constrained degrees
- * of freedom. Likewise, $B_D^T B_D$ is the diagonal matrix with
- * diagonal entries $0$ or $1$ that, when applied to a vector, leaves
- * all constrained nodes untouched and deletes all unconstrained ones.
+ * <h3>Some background</h3> Mathematically speaking, it is used to represent a
+ * system of linear equations $Ax=b$ with the constraint that $B_D x = g_D$,
+ * where $B_D$ is a rectangular matrix with exactly one $1$ in each row, and
+ * these $1$s in those columns representing constrained degrees of freedom
+ * (e.g. for Dirichlet boundary nodes, thus the index $D$) and zeroes for all
+ * other diagonal entries, and $g_D$ having the requested nodal values for
+ * these constrained nodes. Thus, the underdetermined equation $B_D x = g_D$
+ * fixes only the constrained nodes and does not impose any condition on the
+ * others. We note that $B_D B_D^T = 1_D$, where $1_D$ is the identity matrix
+ * with dimension as large as the number of constrained degrees of freedom.
+ * Likewise, $B_D^T B_D$ is the diagonal matrix with diagonal entries $0$ or
+ * $1$ that, when applied to a vector, leaves all constrained nodes untouched
+ * and deletes all unconstrained ones.
*
- * For solving such a system of equations, we first write down the
- * Lagrangian $L=1/2 x^T A x - x^T b + l^T B_D x$, where $l$
- * is a Lagrange multiplier for the constraints. The stationarity
- * condition then reads
+ * For solving such a system of equations, we first write down the Lagrangian
+ * $L=1/2 x^T A x - x^T b + l^T B_D x$, where $l$ is a Lagrange multiplier for
+ * the constraints. The stationarity condition then reads
* @code
* [ A B_D^T ] [x] = [b ]
* [ B_D 0 ] [l] = [g_D]
* @endcode
*
- * The first equation then reads $B_D^T l = b-Ax$. On the other hand,
- * if we left-multiply the first equation by $B_D^T B_D$, we obtain
- * $B_D^T B_D A x + B_D^T l = B_D^T B_D b$ after equating $B_D B_D^T$
- * to the identity matrix. Inserting the previous equality, this
- * yields $(A - B_D^T B_D A) x = (1 - B_D^T B_D)b$. Since
- * $x=(1 - B_D^T B_D) x + B_D^T B_D x = (1 - B_D^T B_D) x + B_D^T g_D$,
- * we can restate the linear system:
- * $A_D x = (1 - B_D^T B_D)b - (1 - B_D^T B_D) A B^T g_D$, where
- * $A_D = (1 - B_D^T B_D) A (1 - B_D^T B_D)$ is the matrix where all
- * rows and columns corresponding to constrained nodes have been deleted.
+ * The first equation then reads $B_D^T l = b-Ax$. On the other hand, if we
+ * left-multiply the first equation by $B_D^T B_D$, we obtain $B_D^T B_D A x +
+ * B_D^T l = B_D^T B_D b$ after equating $B_D B_D^T$ to the identity matrix.
+ * Inserting the previous equality, this yields $(A - B_D^T B_D A) x = (1 -
+ * B_D^T B_D)b$. Since $x=(1 - B_D^T B_D) x + B_D^T B_D x = (1 - B_D^T B_D) x
+ * + B_D^T g_D$, we can restate the linear system: $A_D x = (1 - B_D^T B_D)b -
+ * (1 - B_D^T B_D) A B^T g_D$, where $A_D = (1 - B_D^T B_D) A (1 - B_D^T B_D)$
+ * is the matrix where all rows and columns corresponding to constrained nodes
+ * have been deleted.
*
- * The last system of equation only defines the value of the
- * unconstrained nodes, while the constrained ones are determined by
- * the equation $B_D x = g_D$. We can combine these two linear systems
- * by using the zeroed out rows of $A_D$: if we set the diagonal to
- * $1$ and the corresponding zeroed out element of the right hand side
- * to that of $g_D$, then this fixes the constrained elements as
- * well. We can write this as follows:
- * $A_X x = (1 - B_D^T B_D)b - (1 - B_D^T B_D) A B^T g_D + B_D^T g_D$,
- * where $A_X = A_D + B_D^T B_D$. Note that the two parts of the
- * latter matrix operate on disjoint subspaces (the first on the
- * unconstrained nodes, the latter on the constrained ones).
+ * The last system of equation only defines the value of the unconstrained
+ * nodes, while the constrained ones are determined by the equation $B_D x =
+ * g_D$. We can combine these two linear systems by using the zeroed out rows
+ * of $A_D$: if we set the diagonal to $1$ and the corresponding zeroed out
+ * element of the right hand side to that of $g_D$, then this fixes the
+ * constrained elements as well. We can write this as follows: $A_X x = (1 -
+ * B_D^T B_D)b - (1 - B_D^T B_D) A B^T g_D + B_D^T g_D$, where $A_X = A_D +
+ * B_D^T B_D$. Note that the two parts of the latter matrix operate on
+ * disjoint subspaces (the first on the unconstrained nodes, the latter on the
+ * constrained ones).
*
* In iterative solvers, it is not actually necessary to compute $A_X$
- * explicitly, since only matrix-vector operations need to be
- * performed. This can be done in a three-step procedure that first
- * clears all elements in the incoming vector that belong to
- * constrained nodes, then performs the product with the matrix $A$,
- * then clears again. This class is a wrapper to this procedure, it
- * takes a pointer to a matrix with which to perform matrix-vector
- * products, and does the cleaning of constrained elements itself.
- * This class therefore implements an overloaded @p vmult function
- * that does the matrix-vector product, as well as @p Tvmult for
- * transpose matrix-vector multiplication and @p residual for
- * residual computation, and can thus be used as a matrix replacement
- * in linear solvers.
+ * explicitly, since only matrix-vector operations need to be performed. This
+ * can be done in a three-step procedure that first clears all elements in the
+ * incoming vector that belong to constrained nodes, then performs the product
+ * with the matrix $A$, then clears again. This class is a wrapper to this
+ * procedure, it takes a pointer to a matrix with which to perform matrix-
+ * vector products, and does the cleaning of constrained elements itself. This
+ * class therefore implements an overloaded @p vmult function that does the
+ * matrix-vector product, as well as @p Tvmult for transpose matrix-vector
+ * multiplication and @p residual for residual computation, and can thus be
+ * used as a matrix replacement in linear solvers.
*
- * It also has the ability to generate the modification of the right
- * hand side, through the apply_constraints() function.
+ * It also has the ability to generate the modification of the right hand
+ * side, through the apply_constraints() function.
*
*
*
* <h3>Template arguments</h3>
*
- * This class takes as template arguments a matrix and a vector
- * class. The former must provide @p vmult, @p vmult_add, @p Tvmult, and
- * @p residual member function that operate on the vector type (the
- * second template argument). The latter template parameter must
- * provide access to indivual elements through <tt>operator()</tt>,
- * assignment through <tt>operator=</tt>.
+ * This class takes as template arguments a matrix and a vector class. The
+ * former must provide @p vmult, @p vmult_add, @p Tvmult, and @p residual
+ * member function that operate on the vector type (the second template
+ * argument). The latter template parameter must provide access to indivual
+ * elements through <tt>operator()</tt>, assignment through
+ * <tt>operator=</tt>.
*
*
* <h3>Thread-safety</h3>
class Accessor
{
/**
- * Constructor. Since we use
- * accessors only for read
- * access, a const matrix
- * pointer is sufficient.
+ * Constructor. Since we use accessors only for read access, a const
+ * matrix pointer is sufficient.
*/
Accessor (const FilteredMatrix<VECTOR> *matrix,
const size_type index);
public:
/**
- * Row number of the element
- * represented by this
- * object.
+ * Row number of the element represented by this object.
*/
size_type row() const;
/**
- * Column number of the
- * element represented by
- * this object.
+ * Column number of the element represented by this object.
*/
size_type column() const;
/**
- * Value of the right hand
- * side for this row.
+ * Value of the right hand side for this row.
*/
double value() const;
const Accessor *operator-> () const;
/**
- * Comparison. True, if
- * both iterators point to
- * the same matrix
- * position.
+ * Comparison. True, if both iterators point to the same matrix position.
*/
bool operator == (const const_iterator &) const;
/**
bool operator != (const const_iterator &) const;
/**
- * Comparison operator. Result is
- * true if either the first row
- * number is smaller or if the row
- * numbers are equal and the first
- * index is smaller.
+ * Comparison operator. Result is true if either the first row number is
+ * smaller or if the row numbers are equal and the first index is smaller.
*/
bool operator < (const const_iterator &) const;
/**
- * Comparison operator. Compares just
- * the other way around than the
+ * Comparison operator. Compares just the other way around than the
* operator above.
*/
bool operator > (const const_iterator &) const;
private:
/**
- * Store an object of the
- * accessor class.
+ * Store an object of the accessor class.
*/
Accessor accessor;
};
/**
- * Typedef defining a type that
- * represents a pair of degree of
- * freedom index and the value it
- * shall have.
+ * Typedef defining a type that represents a pair of degree of freedom index
+ * and the value it shall have.
*/
typedef std::pair<size_type, double> IndexValuePair;
*/
//@{
/**
- * Default constructor. You will
- * have to set the matrix to be
- * used later using
- * initialize().
+ * Default constructor. You will have to set the matrix to be used later
+ * using initialize().
*/
FilteredMatrix ();
/**
- * Copy constructor. Use the
- * matrix and the constraints set
- * in the given object for the
- * present one as well.
+ * Copy constructor. Use the matrix and the constraints set in the given
+ * object for the present one as well.
*/
FilteredMatrix (const FilteredMatrix &fm);
/**
- * Constructor. Use the given
- * matrix for future operations.
+ * Constructor. Use the given matrix for future operations.
*
* @arg @p m: The matrix being used in multiplications.
*
- * @arg @p
- * expect_constrained_source: See
- * documentation of
+ * @arg @p expect_constrained_source: See documentation of
* #expect_constrained_source.
*/
template <class MATRIX>
bool expect_constrained_source = false);
/**
- * Copy operator. Take over
- * matrix and constraints from
- * the other object.
+ * Copy operator. Take over matrix and constraints from the other object.
*/
FilteredMatrix &operator = (const FilteredMatrix &fm);
/**
- * Set the matrix to be used
- * further on. You will probably
- * also want to call the
- * clear_constraints()
- * function if constraits were
- * previously added.
+ * Set the matrix to be used further on. You will probably also want to call
+ * the clear_constraints() function if constraits were previously added.
*
* @arg @p m: The matrix being used in multiplications.
*
- * @arg @p
- * expect_constrained_source: See
- * documentation of
+ * @arg @p expect_constrained_source: See documentation of
* #expect_constrained_source.
*/
template <class MATRIX>
bool expect_constrained_source = false);
/**
- * Delete all constraints and the
- * matrix pointer.
+ * Delete all constraints and the matrix pointer.
*/
void clear ();
//@}
*/
//@{
/**
- * Add the constraint that the
- * value with index <tt>i</tt>
- * should have the value
- * <tt>v</tt>.
+ * Add the constraint that the value with index <tt>i</tt> should have the
+ * value <tt>v</tt>.
*/
void add_constraint (const size_type i, const double v);
/**
- * Add a list of constraints to
- * the ones already managed by
- * this object. The actual data
- * type of this list must be so
- * that dereferenced iterators
- * are pairs of indices and the
- * corresponding values to be
- * enforced on the respective
- * solution vector's entry. Thus,
- * the data type might be, for
- * example, a @p std::list or
- * @p std::vector of
- * IndexValuePair objects,
- * but also a
- * <tt>std::map<unsigned, double></tt>.
+ * Add a list of constraints to the ones already managed by this object. The
+ * actual data type of this list must be so that dereferenced iterators are
+ * pairs of indices and the corresponding values to be enforced on the
+ * respective solution vector's entry. Thus, the data type might be, for
+ * example, a @p std::list or @p std::vector of IndexValuePair objects, but
+ * also a <tt>std::map<unsigned, double></tt>.
*
- * The second component of these
- * pairs will only be used in
- * apply_constraints(). The first
- * is used to set values to zero
- * in matrix vector
- * multiplications.
+ * The second component of these pairs will only be used in
+ * apply_constraints(). The first is used to set values to zero in matrix
+ * vector multiplications.
*
- * It is an error if the argument
- * contains an entry for a degree
- * of freedom that has already
- * been constrained
- * previously.
+ * It is an error if the argument contains an entry for a degree of freedom
+ * that has already been constrained previously.
*/
template <class ConstraintList>
void add_constraints (const ConstraintList &new_constraints);
/**
- * Delete the list of constraints
- * presently in use.
+ * Delete the list of constraints presently in use.
*/
void clear_constraints ();
//@}
*/
//@{
/**
- * Apply the constraints to a
- * right hand side vector. This
- * needs to be done before
- * starting to solve with the
- * filtered matrix. If the matrix
- * is symmetric (i.e. the matrix
- * itself, not only its sparsity
- * pattern), set the second
- * parameter to @p true to use a
- * faster algorithm.
+ * Apply the constraints to a right hand side vector. This needs to be done
+ * before starting to solve with the filtered matrix. If the matrix is
+ * symmetric (i.e. the matrix itself, not only its sparsity pattern), set
+ * the second parameter to @p true to use a faster algorithm.
*/
void apply_constraints (VECTOR &v,
const bool matrix_is_symmetric) const;
/**
- * Matrix-vector multiplication:
- * this operation performs
- * pre_filter(), multiplication
- * with the stored matrix and
- * post_filter() in that order.
+ * Matrix-vector multiplication: this operation performs pre_filter(),
+ * multiplication with the stored matrix and post_filter() in that order.
*/
void vmult (VECTOR &dst,
const VECTOR &src) const;
/**
- * Matrix-vector multiplication:
- * this operation performs
- * pre_filter(), transposed
- * multiplication with the stored
- * matrix and post_filter() in
+ * Matrix-vector multiplication: this operation performs pre_filter(),
+ * transposed multiplication with the stored matrix and post_filter() in
* that order.
*/
void Tvmult (VECTOR &dst,
/**
* Adding matrix-vector multiplication.
*
- * @note The result vector of
- * this multiplication will have
- * the constraint entries set to
- * zero, independent of the
- * previous value of
- * <tt>dst</tt>. We excpect that
- * in most cases this is the
- * required behavior.
+ * @note The result vector of this multiplication will have the constraint
+ * entries set to zero, independent of the previous value of <tt>dst</tt>.
+ * We excpect that in most cases this is the required behavior.
*/
void vmult_add (VECTOR &dst,
const VECTOR &src) const;
/**
* Adding transpose matrix-vector multiplication:
*
- * @note The result vector of
- * this multiplication will have
- * the constraint entries set to
- * zero, independent of the
- * previous value of
- * <tt>dst</tt>. We excpect that
- * in most cases this is the
- * required behavior.
+ * @note The result vector of this multiplication will have the constraint
+ * entries set to zero, independent of the previous value of <tt>dst</tt>.
+ * We excpect that in most cases this is the required behavior.
*/
void Tvmult_add (VECTOR &dst,
const VECTOR &src) const;
*/
//@{
/**
- * Iterator to the first
- * constraint.
+ * Iterator to the first constraint.
*/
const_iterator begin () const;
/**
//@}
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object. Since we are
- * not the owner of the matrix
- * referenced, its memory
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object. Since we are not the owner of the matrix referenced, its memory
* consumption is not included.
*/
std::size_t memory_consumption () const;
private:
/**
- * Determine, whether
- * multiplications can expect
- * that the source vector has all
- * constrained entries set to
- * zero.
+ * Determine, whether multiplications can expect that the source vector has
+ * all constrained entries set to zero.
*
- * If so, the auxiliary vector
- * can be avoided and memory as
- * well as time can be saved.
+ * If so, the auxiliary vector can be avoided and memory as well as time can
+ * be saved.
*
- * We expect this for instance in
- * Newton's method, where the
- * residual already should be
- * zero on constrained
- * nodes. This is, because there
- * is no testfunction in these
- * nodes.
+ * We expect this for instance in Newton's method, where the residual
+ * already should be zero on constrained nodes. This is, because there is no
+ * testfunction in these nodes.
*/
bool expect_constrained_source;
/**
- * Declare an abbreviation for an
- * iterator into the array
- * constraint pairs, since that
- * data type is so often used and
- * is rather awkward to write out
+ * Declare an abbreviation for an iterator into the array constraint pairs,
+ * since that data type is so often used and is rather awkward to write out
* each time.
*/
typedef typename std::vector<IndexValuePair>::const_iterator const_index_value_iterator;
/**
- * Helper class used to sort
- * pairs of indices and
- * values. Only the index is
+ * Helper class used to sort pairs of indices and values. Only the index is
* considered as sort key.
*/
struct PairComparison
{
/**
- * Function comparing the
- * pairs @p i1 and @p i2
- * for their keys.
+ * Function comparing the pairs @p i1 and @p i2 for their keys.
*/
bool operator () (const IndexValuePair &i1,
const IndexValuePair &i2) const;
};
/**
- * Pointer to the sparsity
- * pattern used for this
- * matrix.
+ * Pointer to the sparsity pattern used for this matrix.
*/
std_cxx11::shared_ptr<PointerMatrixBase<VECTOR> > matrix;
/**
- * Sorted list of pairs denoting
- * the index of the variable and
- * the value to which it shall be
- * fixed.
+ * Sorted list of pairs denoting the index of the variable and the value to
+ * which it shall be fixed.
*/
std::vector<IndexValuePair> constraints;
/**
- * Do the pre-filtering step,
- * i.e. zero out those components
- * that belong to constrained
- * degrees of freedom.
+ * Do the pre-filtering step, i.e. zero out those components that belong to
+ * constrained degrees of freedom.
*/
void pre_filter (VECTOR &v) const;
/**
- * Do the postfiltering step,
- * i.e. set constrained degrees
- * of freedom to the value of the
- * input vector, as the matrix
- * contains only ones on the
- * diagonal for these degrees of
- * freedom.
+ * Do the postfiltering step, i.e. set constrained degrees of freedom to the
+ * value of the input vector, as the matrix contains only ones on the
+ * diagonal for these degrees of freedom.
*/
void post_filter (const VECTOR &in,
VECTOR &out) const;
friend class Accessor;
/**
- * FilteredMatrixBlock accesses
- * pre_filter() and post_filter().
+ * FilteredMatrixBlock accesses pre_filter() and post_filter().
*/
friend class FilteredMatrixBlock<VECTOR>;
};
/**
- * Implementation of a classical rectangular scheme of numbers. The
- * data type of the entries is provided in the template argument
- * <tt>number</tt>. The interface is quite fat and in fact has grown every
- * time a new feature was needed. So, a lot of functions are provided.
+ * Implementation of a classical rectangular scheme of numbers. The data type
+ * of the entries is provided in the template argument <tt>number</tt>. The
+ * interface is quite fat and in fact has grown every time a new feature was
+ * needed. So, a lot of functions are provided.
*
- * Internal calculations are usually done with the accuracy of the
- * vector argument to functions. If there is no argument with a number
- * type, the matrix number type is used.
+ * Internal calculations are usually done with the accuracy of the vector
+ * argument to functions. If there is no argument with a number type, the
+ * matrix number type is used.
*
- * @note Instantiations for this template are provided for
- * <tt>@<float@>, @<double@>, @<long double@>,
- * @<std::complex@<float@>@>, @<std::complex@<double@>@>,
- * @<std::complex@<long double@>@></tt>; others can be generated in
- * application programs (see the section on @ref Instantiations in the
- * manual).
+ * @note Instantiations for this template are provided for <tt>@<float@>,
+ * @<double@>, @<long double@>, @<std::complex@<float@>@>,
+ * @<std::complex@<double@>@>, @<std::complex@<long double@>@></tt>; others
+ * can be generated in application programs (see the section on @ref
+ * Instantiations in the manual).
*
* @author Guido Kanschat, Franz-Theo Suttmeier, Wolfgang Bangerth, 1993-2004
*/
{
public:
/**
- * A type of used to index into this container. Because we can not
- * expect to store matrices bigger than what can be indexed by a regular
- * unsigned integer, <code>unsigned int</code> is completely sufficient
- * as an index type.
+ * A type of used to index into this container. Because we can not expect to
+ * store matrices bigger than what can be indexed by a regular unsigned
+ * integer, <code>unsigned int</code> is completely sufficient as an index
+ * type.
*/
typedef unsigned int size_type;
/**
* Declare a type that has holds real-valued numbers with the same precision
* as the template argument to this class. If the template argument of this
- * class is a real data type, then real_type equals the template
- * argument. If the template argument is a std::complex type then real_type
- * equals the type underlying the complex numbers.
+ * class is a real data type, then real_type equals the template argument.
+ * If the template argument is a std::complex type then real_type equals the
+ * type underlying the complex numbers.
*
* This typedef is used to represent the return type of norms.
*/
const size_type cols);
/**
- * Copy constructor. This constructor does a deep copy of the
- * matrix. Therefore, it poses a possible efficiency problem, if for
- * example, function arguments are passed by value rather than by
- * reference. Unfortunately, we can't mark this copy constructor
- * <tt>explicit</tt>, since that prevents the use of this class in
- * containers, such as <tt>std::vector</tt>. The responsibility to check
- * performance of programs must therefore remain with the user of this
- * class.
+ * Copy constructor. This constructor does a deep copy of the matrix.
+ * Therefore, it poses a possible efficiency problem, if for example,
+ * function arguments are passed by value rather than by reference.
+ * Unfortunately, we can't mark this copy constructor <tt>explicit</tt>,
+ * since that prevents the use of this class in containers, such as
+ * <tt>std::vector</tt>. The responsibility to check performance of programs
+ * must therefore remain with the user of this class.
*/
FullMatrix (const FullMatrix &);
const size_type dst_c=0) const;
/**
- * Copy a subset of the rows and columns of another matrix into the
- * current object.
+ * Copy a subset of the rows and columns of another matrix into the current
+ * object.
*
* @param matrix The matrix from which a subset is to be taken from.
* @param row_index_set The set of rows of @p matrix from which to extract.
- * @param column_index_set The set of columns of @p matrix from which to extract.
- * @pre The number of elements in @p row_index_set and
- * @p column_index_set shall be equal to the number of
- * rows and columns in the current object. In other words,
- * the current object is not resized for this operation.
+ * @param column_index_set The set of columns of @p matrix from which to
+ * extract. @pre The number of elements in @p row_index_set and @p
+ * column_index_set shall be equal to the number of rows and columns in the
+ * current object. In other words, the current object is not resized for
+ * this operation.
*/
template <typename MatrixType, typename index_type>
void extract_submatrix_from (const MatrixType &matrix,
const std::vector<index_type> &column_index_set);
/**
- * Copy the elements of the current matrix object into a specified
- * set of rows and columns of another matrix. Thus, this is a scatter operation.
+ * Copy the elements of the current matrix object into a specified set of
+ * rows and columns of another matrix. Thus, this is a scatter operation.
*
* @param row_index_set The rows of @p matrix into which to write.
* @param column_index_set The columns of @p matrix into which to write.
- * @param matrix The matrix within which certain elements are to be replaced.
- * @pre The number of elements in @p row_index_set and
- * @p column_index_set shall be equal to the number of
- * rows and columns in the current object. In other words,
- * the current object is not resized for this operation.
+ * @param matrix The matrix within which certain elements are to be
+ * replaced. @pre The number of elements in @p row_index_set and @p
+ * column_index_set shall be equal to the number of rows and columns in the
+ * current object. In other words, the current object is not resized for
+ * this operation.
*/
template <typename MatrixType, typename index_type>
void
/**
* Set a particular entry of the matrix to a value. Thus, calling
* <code>A.set(1,2,3.141);</code> is entirely equivalent to the operation
- * <code>A(1,2) = 3.141;</code>. This function exists for compatibility
- * with the various sparse matrix objects.
+ * <code>A(1,2) = 3.141;</code>. This function exists for compatibility with
+ * the various sparse matrix objects.
*
* @param i The row index of the element to be set.
* @param j The columns index of the element to be set.
*
* @arg <tt>threshold</tt>: all entries with absolute value smaller than
* this are considered zero.
- */
+ */
void print_formatted (std::ostream &out,
const unsigned int precision=3,
const bool scientific = true,
/**
* Add rectangular block.
*
- * A rectangular block of the matrix <tt>src</tt> is added to
- * <tt>this</tt>. The upper left corner of the block being copied is
+ * A rectangular block of the matrix <tt>src</tt> is added to <tt>this</tt>.
+ * The upper left corner of the block being copied is
* <tt>(src_offset_i,src_offset_j)</tt>. The upper left corner of the
* copied block is <tt>(dst_offset_i,dst_offset_j)</tt>. The size of the
* rectangular block being copied is the maximum size possible, determined
const size_type j);
/**
- * Swap <i>A(1...n,i) <-> A(1...n,j)</i>. Swap columns i and j of this
+ * Swap <i>A(1...n,i) <-> A(1...n,j)</i>. Swap columns i and j of this
*/
void swap_col (const size_type i,
const size_type j);
/**
* A=Inverse(A). A must be a square matrix. Inversion of this matrix by
- * Gauss-Jordan algorithm with partial pivoting. This process is
- * well-behaved for positive definite matrices, but be aware of round-off
- * errors in the indefinite case.
+ * Gauss-Jordan algorithm with partial pivoting. This process is well-
+ * behaved for positive definite matrices, but be aware of round-off errors
+ * in the indefinite case.
*
* In case deal.II was configured with LAPACK, the functions Xgetrf and
* Xgetri build an LU factorization and invert the matrix upon that
* The optional parameter <tt>adding</tt> determines, whether the result is
* stored in <tt>C</tt> or added to <tt>C</tt>.
*
- * if (adding)
- * <i>C += A*B</i>
+ * if (adding) <i>C += A*B</i>
*
- * if (!adding)
- * <i>C = A*B</i>
+ * if (!adding) <i>C = A*B</i>
*
* Assumes that <tt>A</tt> and <tt>B</tt> have compatible sizes and that
* <tt>C</tt> already has the right size.
* The optional parameter <tt>adding</tt> determines, whether the result is
* stored in <tt>C</tt> or added to <tt>C</tt>.
*
- * if (adding)
- * <i>C += A<sup>T</sup>*B</i>
+ * if (adding) <i>C += A<sup>T</sup>*B</i>
*
- * if (!adding)
- * <i>C = A<sup>T</sup>*B</i>
+ * if (!adding) <i>C = A<sup>T</sup>*B</i>
*
* Assumes that <tt>A</tt> and <tt>B</tt> have compatible sizes and that
* <tt>C</tt> already has the right size.
* The optional parameter <tt>adding</tt> determines, whether the result is
* stored in <tt>C</tt> or added to <tt>C</tt>.
*
- * if (adding)
- * <i>C += A*B<sup>T</sup></i>
+ * if (adding) <i>C += A*B<sup>T</sup></i>
*
- * if (!adding)
- * <i>C = A*B<sup>T</sup></i>
+ * if (!adding) <i>C = A*B<sup>T</sup></i>
*
* Assumes that <tt>A</tt> and <tt>B</tt> have compatible sizes and that
* <tt>C</tt> already has the right size.
* The optional parameter <tt>adding</tt> determines, whether the result is
* stored in <tt>C</tt> or added to <tt>C</tt>.
*
- * if (adding)
- * <i>C += A<sup>T</sup>*B<sup>T</sup></i>
+ * if (adding) <i>C += A<sup>T</sup>*B<sup>T</sup></i>
*
- * if (!adding)
- * <i>C = A<sup>T</sup>*B<sup>T</sup></i>
+ * if (!adding) <i>C = A<sup>T</sup>*B<sup>T</sup></i>
*
* Assumes that <tt>A</tt> and <tt>B</tt> have compatible sizes and that
* <tt>C</tt> already has the right size.
* The optional parameter <tt>adding</tt> determines, whether the result is
* stored in <tt>w</tt> or added to <tt>w</tt>.
*
- * if (adding)
- * <i>w += A*v</i>
+ * if (adding) <i>w += A*v</i>
*
- * if (!adding)
- * <i>w = A*v</i>
+ * if (!adding) <i>w = A*v</i>
*
* Source and destination must not be the same vector.
*/
* The optional parameter <tt>adding</tt> determines, whether the result is
* stored in <tt>w</tt> or added to <tt>w</tt>.
*
- * if (adding)
- * <i>w += A<sup>T</sup>*v</i>
+ * if (adding) <i>w += A<sup>T</sup>*v</i>
*
- * if (!adding)
- * <i>w = A<sup>T</sup>*v</i>
+ * if (!adding) <i>w = A<sup>T</sup>*v</i>
*
*
* Source and destination must not be the same vector.
//@}
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
typedef PETScWrappers::MPI::Vector Vector;
/**
- * Typedef for the type used to describe vectors that
- * consist of multiple blocks.
+ * Typedef for the type used to describe vectors that consist of multiple
+ * blocks.
*/
typedef PETScWrappers::MPI::BlockVector BlockVector;
typedef PETScWrappers::MPI::SparseMatrix SparseMatrix;
/**
- * Typedef for the type used to describe sparse matrices that
- * consist of multiple blocks.
+ * Typedef for the type used to describe sparse matrices that consist of
+ * multiple blocks.
*/
typedef PETScWrappers::MPI::BlockSparseMatrix BlockSparseMatrix;
typedef TrilinosWrappers::MPI::Vector Vector;
/**
- * Typedef for the type used to describe vectors that
- * consist of multiple blocks.
+ * Typedef for the type used to describe vectors that consist of multiple
+ * blocks.
*/
typedef TrilinosWrappers::MPI::BlockVector BlockVector;
typedef TrilinosWrappers::SparseMatrix SparseMatrix;
/**
- * Typedef for the type used to describe sparse matrices that
- * consist of multiple blocks.
+ * Typedef for the type used to describe sparse matrices that consist of
+ * multiple blocks.
*/
typedef TrilinosWrappers::BlockSparseMatrix BlockSparseMatrix;
/**
* QR-decomposition of a full matrix.
*
- * Whenever an object of this class is created, it copies the matrix
- * given and computes its QR-decomposition by Householder
- * algorithm. Then, the function least_squares() can be used to
- * compute the vector <i>x</i> minimizing <i>||Ax-b||</i> for a given
- * vector <i>b</i>.
+ * Whenever an object of this class is created, it copies the matrix given and
+ * computes its QR-decomposition by Householder algorithm. Then, the function
+ * least_squares() can be used to compute the vector <i>x</i> minimizing
+ * <i>||Ax-b||</i> for a given vector <i>b</i>.
*
* @note Instantiations for this template are provided for <tt>@<float@> and
* @<double@></tt>; others can be generated in application programs (see the
Householder ();
/**
- * Create an object holding the
- * QR-decomposition of a matrix.
+ * Create an object holding the QR-decomposition of a matrix.
*/
template<typename number2>
Householder (const FullMatrix<number2> &);
/**
- * Compute the QR-decomposition
- * of another matrix.
+ * Compute the QR-decomposition of another matrix.
*/
template<typename number2>
void
initialize (const FullMatrix<number2> &);
/**
- * Solve the least-squares
- * problem for the right hand
- * side <tt>src</tt>. The return
- * value is the Euclidean norm of
- * the approximation error.
+ * Solve the least-squares problem for the right hand side <tt>src</tt>. The
+ * return value is the Euclidean norm of the approximation error.
*
- * @arg @c dst contains the
- * solution of the least squares
- * problem on return.
+ * @arg @c dst contains the solution of the least squares problem on return.
*
- * @arg @c src contains the right
- * hand side <i>b</i> of the
- * least squares problem. It will
- * be changed during the algorithm
- * and is unusable on return.
+ * @arg @c src contains the right hand side <i>b</i> of the least squares
+ * problem. It will be changed during the algorithm and is unusable on
+ * return.
*/
template<typename number2>
double least_squares (Vector<number2> &dst,
const Vector<number2> &src) const;
/**
- * This function does the same as
- * the one for BlockVectors.
+ * This function does the same as the one for BlockVectors.
*/
template<typename number2>
double least_squares (BlockVector<number2> &dst,
const BlockVector<number2> &src) const;
/**
- * A wrapper to least_squares(),
- * implementing the standard
- * MATRIX interface.
+ * A wrapper to least_squares(), implementing the standard MATRIX interface.
*/
template<class VECTOR>
void vmult (VECTOR &dst, const VECTOR &src) const;
private:
/**
- * Storage for the diagonal
- * elements of the orthogonal
- * transformation.
+ * Storage for the diagonal elements of the orthogonal transformation.
*/
std::vector<number> diagonal;
};
/**
- * Implementation of a simple class representing the identity matrix
- * of a given size, i.e. a matrix with entries
- * $A_{ij}=\delta_{ij}$. While it has the most important ingredients
- * of a matrix, in particular that one can ask for its size and
- * perform matrix-vector products with it, a matrix of this type is
- * really only useful in two contexts: preconditioning and
+ * Implementation of a simple class representing the identity matrix of a
+ * given size, i.e. a matrix with entries $A_{ij}=\delta_{ij}$. While it has
+ * the most important ingredients of a matrix, in particular that one can ask
+ * for its size and perform matrix-vector products with it, a matrix of this
+ * type is really only useful in two contexts: preconditioning and
* initializing other matrices.
*
-
- * <h4>Initialization</h4>
+ * <h4>Initialization</h4>
*
- * The main usefulness of this class lies in its ability to initialize
- * other matrix, like this:
- @code
- FullMatrix<double> identity (IdentityMatrix(10));
- @endcode
+ * The main usefulness of this class lies in its ability to initialize other
+ * matrix, like this:
+ * @code
+ * FullMatrix<double> identity (IdentityMatrix(10));
+ * @endcode
*
- * This creates a $10\times 10$ matrix with ones on the diagonal and
- * zeros everywhere else. Most matrix types, in particular FullMatrix
- * and SparseMatrix, have conversion constructors and assignment
- * operators for IdentityMatrix, and can therefore be filled rather
- * easily with identity matrices.
+ * This creates a $10\times 10$ matrix with ones on the diagonal and zeros
+ * everywhere else. Most matrix types, in particular FullMatrix and
+ * SparseMatrix, have conversion constructors and assignment operators for
+ * IdentityMatrix, and can therefore be filled rather easily with identity
+ * matrices.
*
*
* <h4>Preconditioning</h4>
*
* No preconditioning at all is equivalent to preconditioning with
- * preconditioning with the identity matrix. deal.II has a specialized
- * class for this purpose, PreconditionIdentity, than can be used in a
- * context as shown in the documentation of that class. The present
- * class can be used in much the same way, although without any
- * additional benefit:
- @code
- SolverControl solver_control (1000, 1e-12);
- SolverCG<> cg (solver_control);
- cg.solve (system_matrix, solution, system_rhs,
- IdentityMatrix(solution.size()));
- @endcode
+ * preconditioning with the identity matrix. deal.II has a specialized class
+ * for this purpose, PreconditionIdentity, than can be used in a context as
+ * shown in the documentation of that class. The present class can be used in
+ * much the same way, although without any additional benefit:
+ * @code
+ * SolverControl solver_control (1000, 1e-12);
+ * SolverCG<> cg (solver_control);
+ * cg.solve (system_matrix, solution, system_rhs,
+ * IdentityMatrix(solution.size()));
+ * @endcode
*
*
* @author Wolfgang Bangerth, 2006
typedef types::global_dof_index size_type;
/**
- * Default constructor. Creates a
- * zero-sized matrix that should
- * be resized later on using the
- * reinit() function.
+ * Default constructor. Creates a zero-sized matrix that should be resized
+ * later on using the reinit() function.
*/
IdentityMatrix ();
/**
- * Constructor. Creates a
- * identity matrix of size #n.
+ * Constructor. Creates a identity matrix of size #n.
*/
IdentityMatrix (const size_type n);
/**
- * Resize the matrix to be of
- * size #n by #n.
+ * Resize the matrix to be of size #n by #n.
*/
void reinit (const size_type n);
/**
- * Number of rows of this
- * matrix. For the present
- * matrix, the number of rows and
- * columns are equal, of course.
+ * Number of rows of this matrix. For the present matrix, the number of rows
+ * and columns are equal, of course.
*/
size_type m () const;
/**
- * Number of columns of this
- * matrix. For the present
- * matrix, the number of rows and
- * columns are equal, of course.
+ * Number of columns of this matrix. For the present matrix, the number of
+ * rows and columns are equal, of course.
*/
size_type n () const;
/**
- * Matrix-vector
- * multiplication. For the
- * present case, this of course
- * amounts to simply copying the
- * input vector to the output
- * vector.
+ * Matrix-vector multiplication. For the present case, this of course
+ * amounts to simply copying the input vector to the output vector.
*/
template <class VECTOR1, class VECTOR2>
void vmult (VECTOR1 &out,
const VECTOR2 &in) const;
/**
- * Matrix-vector multiplication
- * with addition to the output
- * vector. For the present case,
- * this of course amounts to
- * simply adding the input
- * vector to the output vector.
+ * Matrix-vector multiplication with addition to the output vector. For the
+ * present case, this of course amounts to simply adding the input vector to
+ * the output vector.
*/
template <class VECTOR1, class VECTOR2>
void vmult_add (VECTOR1 &out,
const VECTOR2 &in) const;
/**
- * Matrix-vector multiplication
- * with the transpose matrix. For
- * the present case, this of
- * course amounts to simply
- * copying the input vector to
- * the output vector.
+ * Matrix-vector multiplication with the transpose matrix. For the present
+ * case, this of course amounts to simply copying the input vector to the
+ * output vector.
*/
template <class VECTOR1, class VECTOR2>
void Tvmult (VECTOR1 &out,
/**
- * Matrix-vector multiplication
- * with the transpose matrix,
- * with addition to the output
- * vector. For the present case,
- * this of course amounts to
- * simply adding the input vector
- * to the output vector.
+ * Matrix-vector multiplication with the transpose matrix, with addition to
+ * the output vector. For the present case, this of course amounts to simply
+ * adding the input vector to the output vector.
*/
template <class VECTOR1, class VECTOR2>
void Tvmult_add (VECTOR1 &out,
private:
/**
- * Number of rows and columns of
- * this matrix.
+ * Number of rows and columns of this matrix.
*/
size_type size;
};
/**
- * Implementation of the inverse of a matrix, using an iterative
- * method.
+ * Implementation of the inverse of a matrix, using an iterative method.
*
- * The function vmult() of this class starts an iterative solver in
- * order to approximate the action of the inverse matrix.
+ * The function vmult() of this class starts an iterative solver in order to
+ * approximate the action of the inverse matrix.
*
- * Krylov space methods like SolverCG or SolverBicgstab
- * become inefficient if solution down to machine accuracy is
- * needed. This is due to the fact, that round-off errors spoil the
- * orthogonality of the vector sequences. Therefore, a nested
- * iteration of two methods is proposed: The outer method is
- * SolverRichardson, since it is robust with respect to round-of
- * errors. The inner loop is an appropriate Krylov space method, since
- * it is fast.
+ * Krylov space methods like SolverCG or SolverBicgstab become inefficient if
+ * solution down to machine accuracy is needed. This is due to the fact, that
+ * round-off errors spoil the orthogonality of the vector sequences.
+ * Therefore, a nested iteration of two methods is proposed: The outer method
+ * is SolverRichardson, since it is robust with respect to round-of errors.
+ * The inner loop is an appropriate Krylov space method, since it is fast.
*
* @code
* // Declare related objects
* outer_iteration.solve (A, x, b, precondition);
* @endcode
*
- * Each time we call the inner loop, reduction of the residual by a
- * factor <tt>1.e-2</tt> is attempted. Since the right hand side vector of
- * the inner iteration is the residual of the outer loop, the relative
- * errors are far from machine accuracy, even if the errors of the
- * outer loop are in the range of machine accuracy.
+ * Each time we call the inner loop, reduction of the residual by a factor
+ * <tt>1.e-2</tt> is attempted. Since the right hand side vector of the inner
+ * iteration is the residual of the outer loop, the relative errors are far
+ * from machine accuracy, even if the errors of the outer loop are in the
+ * range of machine accuracy.
*
* @ingroup Matrix2
* @author Guido Kanschat
{
public:
/**
- * Initialization
- * function. Provide a matrix and
- * preconditioner for the solve in
- * vmult().
+ * Initialization function. Provide a matrix and preconditioner for the
+ * solve in vmult().
*/
template <class MATRIX, class PRECONDITION>
void initialize (const MATRIX &, const PRECONDITION &);
/**
- * Delete the pointers to matrix
- * and preconditioner.
+ * Delete the pointers to matrix and preconditioner.
*/
void clear();
void vmult (VECTOR &dst, const VECTOR &src) const;
/**
- * Solve for right hand side <tt>src</tt>, but allow for the fact
- * that the vectors given to this function have different type from
- * the vectors used by the inner solver.
+ * Solve for right hand side <tt>src</tt>, but allow for the fact that the
+ * vectors given to this function have different type from the vectors used
+ * by the inner solver.
*/
template <class VECTOR2>
void vmult (VECTOR2 &dst, const VECTOR2 &src) const;
/**
- * The solver, which allows
- * selection of the actual solver
- * as well as adjuxtment of
- * parameters.
+ * The solver, which allows selection of the actual solver as well as
+ * adjuxtment of parameters.
*/
SolverSelector<VECTOR> solver;
/**
- * A variant of FullMatrix using LAPACK functions wherever
- * possible. In order to do this, the matrix is stored in transposed
- * order. The element access functions hide this fact by reverting the
- * transposition.
+ * A variant of FullMatrix using LAPACK functions wherever possible. In order
+ * to do this, the matrix is stored in transposed order. The element access
+ * functions hide this fact by reverting the transposition.
*
* @note In order to perform LAPACK functions, the class contains a lot of
- * auxiliary data in the private section. The names of these data
- * vectors are usually the names chosen for the arguments in the
- * LAPACK documentation.
+ * auxiliary data in the private section. The names of these data vectors are
+ * usually the names chosen for the arguments in the LAPACK documentation.
*
* @ingroup Matrix1
* @author Guido Kanschat, 2005
/**
- * Copy constructor. This constructor does a deep copy of the
- * matrix. Therefore, it poses a possible efficiency problem, if for
- * example, function arguments are passed by value rather than by
- * reference. Unfortunately, we can't mark this copy constructor
- * <tt>explicit</tt>, since that prevents the use of this class in
- * containers, such as <tt>std::vector</tt>. The responsibility to check
- * performance of programs must therefore remain with the user of this
- * class.
+ * Copy constructor. This constructor does a deep copy of the matrix.
+ * Therefore, it poses a possible efficiency problem, if for example,
+ * function arguments are passed by value rather than by reference.
+ * Unfortunately, we can't mark this copy constructor <tt>explicit</tt>,
+ * since that prevents the use of this class in containers, such as
+ * <tt>std::vector</tt>. The responsibility to check performance of programs
+ * must therefore remain with the user of this class.
*/
LAPACKFullMatrix (const LAPACKFullMatrix &);
operator = (const LAPACKFullMatrix<number> &);
/**
- * Assignment operator from a regular FullMatrix. @note Since LAPACK
- * expects matrices in transposed order, this transposition is
- * included here.
+ * Assignment operator from a regular FullMatrix. @note Since LAPACK expects
+ * matrices in transposed order, this transposition is included here.
*/
template <typename number2>
LAPACKFullMatrix<number> &
operator = (const FullMatrix<number2> &);
/**
- * Assignment operator from a regular SparseMatrix. @note Since
- * LAPACK expects matrices in transposed order, this transposition
- * is included here.
+ * Assignment operator from a regular SparseMatrix. @note Since LAPACK
+ * expects matrices in transposed order, this transposition is included
+ * here.
*/
template <typename number2>
LAPACKFullMatrix<number> &
void copy_from (const MATRIX &);
/**
- * Regenerate the current matrix by one that has the same properties
- * as if it were created by the constructor of this class with the
- * same argument list as this present function.
+ * Regenerate the current matrix by one that has the same properties as if
+ * it were created by the constructor of this class with the same argument
+ * list as this present function.
*/
void reinit (const size_type size);
/**
- * Regenerate the current matrix by one that has the same properties
- * as if it were created by the constructor of this class with the
- * same argument list as this present function.
+ * Regenerate the current matrix by one that has the same properties as if
+ * it were created by the constructor of this class with the same argument
+ * list as this present function.
*/
void reinit (const size_type rows,
const size_type cols);
/**
- * Return the dimension of the range space. @note The matrix is of
- * dimension $m \times n$.
+ * Return the dimension of the range space. @note The matrix is of dimension
+ * $m \times n$.
*/
unsigned int m () const;
/**
- * Return the number of the range space. @note The matrix is of
- * dimension $m \times n$.
+ * Return the number of the range space. @note The matrix is of dimension $m
+ * \times n$.
*/
unsigned int n () const;
* The optional parameter <tt>adding</tt> determines, whether the result is
* stored in <tt>w</tt> or added to <tt>w</tt>.
*
- * if (adding)
- * <i>w += A*v</i>
+ * if (adding) <i>w += A*v</i>
*
- * if (!adding)
- * <i>w = A*v</i>
+ * if (!adding) <i>w = A*v</i>
*
* @note Source and destination must not be the same vector.
*
* The optional parameter <tt>adding</tt> determines, whether the result is
* stored in <tt>w</tt> or added to <tt>w</tt>.
*
- * if (adding)
- * <i>w += A<sup>T</sup>*v</i>
+ * if (adding) <i>w += A<sup>T</sup>*v</i>
*
- * if (!adding)
- * <i>w = A<sup>T</sup>*v</i>
+ * if (!adding) <i>w = A<sup>T</sup>*v</i>
*
- * See the documentation of vmult() for details on the implementation.
+ * See the documentation of vmult() for details on the implementation.
*/
template <class VECTOR>
void Tvmult (VECTOR &w, const VECTOR &v,
* The optional parameter <tt>adding</tt> determines, whether the result is
* stored in <tt>C</tt> or added to <tt>C</tt>.
*
- * if (adding)
- * <i>C += A*B</i>
+ * if (adding) <i>C += A*B</i>
*
- * if (!adding)
- * <i>C = A*B</i>
+ * if (!adding) <i>C = A*B</i>
*
* Assumes that <tt>A</tt> and <tt>B</tt> have compatible sizes and that
* <tt>C</tt> already has the right size.
* The optional parameter <tt>adding</tt> determines, whether the result is
* stored in <tt>C</tt> or added to <tt>C</tt>.
*
- * if (adding)
- * <i>C += A<sup>T</sup>*B</i>
+ * if (adding) <i>C += A<sup>T</sup>*B</i>
*
- * if (!adding)
- * <i>C = A<sup>T</sup>*B</i>
+ * if (!adding) <i>C = A<sup>T</sup>*B</i>
*
* Assumes that <tt>A</tt> and <tt>B</tt> have compatible sizes and that
* <tt>C</tt> already has the right size.
* The optional parameter <tt>adding</tt> determines, whether the result is
* stored in <tt>C</tt> or added to <tt>C</tt>.
*
- * if (adding)
- * <i>C += A*B<sup>T</sup></i>
+ * if (adding) <i>C += A*B<sup>T</sup></i>
*
- * if (!adding)
- * <i>C = A*B<sup>T</sup></i>
+ * if (!adding) <i>C = A*B<sup>T</sup></i>
*
* Assumes that <tt>A</tt> and <tt>B</tt> have compatible sizes and that
* <tt>C</tt> already has the right size.
* The optional parameter <tt>adding</tt> determines, whether the result is
* stored in <tt>C</tt> or added to <tt>C</tt>.
*
- * if (adding)
- * <i>C += A<sup>T</sup>*B<sup>T</sup></i>
+ * if (adding) <i>C += A<sup>T</sup>*B<sup>T</sup></i>
*
- * if (!adding)
- * <i>C = A<sup>T</sup>*B<sup>T</sup></i>
+ * if (!adding) <i>C = A<sup>T</sup>*B<sup>T</sup></i>
*
* Assumes that <tt>A</tt> and <tt>B</tt> have compatible sizes and that
* <tt>C</tt> already has the right size.
* Compute the inverse of the matrix by singular value decomposition.
*
* Requires that #state is either LAPACKSupport::matrix or
- * LAPACKSupport::svd. In the first case, this function calls
- * compute_svd(). After this function, the object will have the #state
+ * LAPACKSupport::svd. In the first case, this function calls compute_svd().
+ * After this function, the object will have the #state
* LAPACKSupport::inverse_svd.
*
* For a singular value decomposition, the inverse is simply computed by
*
* @arg <tt>threshold</tt>: all entries with absolute value smaller than
* this are considered zero.
- */
+ */
void print_formatted (std::ostream &out,
const unsigned int presicion=3,
const bool scientific = true,
private:
/**
- * Since LAPACK operations notoriously change the meaning of the
- * matrix entries, we record the current state after the last
- * operation here.
+ * Since LAPACK operations notoriously change the meaning of the matrix
+ * entries, we record the current state after the last operation here.
*/
LAPACKSupport::State state;
mutable std::vector<number> work;
/**
- * The vector storing the permutations applied for pivoting in the
- * LU-factorization.
+ * The vector storing the permutations applied for pivoting in the LU-
+ * factorization.
*
* Also used as the scratch array IWORK for LAPACK functions needing it.
*/
namespace LAPACKSupport
{
/**
- * Most LAPACK functions change the contents of the matrix applied to
- * to something which is not a matrix anymore. Therefore, LAPACK
- * matrix classes in <tt>deal.II</tt> have a state flag indicating
- * what happened to them.
+ * Most LAPACK functions change the contents of the matrix applied to to
+ * something which is not a matrix anymore. Therefore, LAPACK matrix classes
+ * in <tt>deal.II</tt> have a state flag indicating what happened to them.
*
* @author Guido Kanschat, 2005
*/
}
/**
- * A matrix can have certain features allowing for optimization, but
- * hard to test. These are listed here.
+ * A matrix can have certain features allowing for optimization, but hard to
+ * test. These are listed here.
*/
enum Properties
{
static const int one = 1;
/**
- * A LAPACK function returned an
- * error code.
+ * A LAPACK function returned an error code.
*/
DeclException2(ExcErrorCode, char *, int,
<< "The function " << arg1 << " returned with an error code " << arg2);
/**
- * Exception thrown when a matrix
- * is not in a suitable state for
- * an operation. For instance, a
- * LAPACK routine may have left the
- * matrix in an unusable state,
- * then vmult does not make sense
- * anymore.
+ * Exception thrown when a matrix is not in a suitable state for an
+ * operation. For instance, a LAPACK routine may have left the matrix in an
+ * unusable state, then vmult does not make sense anymore.
*/
DeclException1(ExcState, State,
<< "The function cannot be called while the matrix is in state "
<< state_name(arg1));
/**
- * This exception is thrown if a
- * certain function is not
- * implemented in your LAPACK
- * version.
+ * This exception is thrown if a certain function is not implemented in your
+ * LAPACK version.
*/
DeclException1(ExcMissing, char *,
<< "The function "
}
/**
- * A wrapper around a matrix object, storing the coordinates in a
- * block matrix as well.
+ * A wrapper around a matrix object, storing the coordinates in a block matrix
+ * as well.
*
- * This class is an alternative to BlockMatrixBase, if you only want
- * to generate a single block of the system, not the whole
- * system. Using the add() functions of this class, it is possible to
- * use the standard assembling functions used for block matrices, but
- * only enter in one of the blocks and still avoiding the index
- * computations involved.
-
- * The reason for this class is, that we may need a different number
- * of matrices for different blocks in a block system. For example, a
- * preconditioner for the Oseen system can be built as a block system,
- * where the pressure block is of the form
- * <b>M</b><sup>-1</sup><b>FA</b><sup>-1</sup> with <b>M</b> the
- * pressure mass matrix, <b>A</b> the pressure Laplacian and <b>F</b>
- * the advection diffusion operator applied to the pressure
- * space. Since only a single matrix is needed for the other blocks,
- * using BlockSparseMatrix or similar would be a waste of memory.
+ * This class is an alternative to BlockMatrixBase, if you only want to
+ * generate a single block of the system, not the whole system. Using the
+ * add() functions of this class, it is possible to use the standard
+ * assembling functions used for block matrices, but only enter in one of the
+ * blocks and still avoiding the index computations involved. The reason for
+ * this class is, that we may need a different number of matrices for
+ * different blocks in a block system. For example, a preconditioner for the
+ * Oseen system can be built as a block system, where the pressure block is of
+ * the form <b>M</b><sup>-1</sup><b>FA</b><sup>-1</sup> with <b>M</b> the
+ * pressure mass matrix, <b>A</b> the pressure Laplacian and <b>F</b> the
+ * advection diffusion operator applied to the pressure space. Since only a
+ * single matrix is needed for the other blocks, using BlockSparseMatrix or
+ * similar would be a waste of memory.
*
- * While the add() functions make a MatrixBlock appear like a block
- * matrix for assembling, the functions vmult(), Tvmult(),
- * vmult_add(), and Tvmult_add() make it behave like a MATRIX, when it
- * comes to applying it to a vector. This behavior allows us to store
- * MatrixBlock objects in vectors, for instance in MGLevelObject
- * without extracting the #matrix first.
+ * While the add() functions make a MatrixBlock appear like a block matrix for
+ * assembling, the functions vmult(), Tvmult(), vmult_add(), and Tvmult_add()
+ * make it behave like a MATRIX, when it comes to applying it to a vector.
+ * This behavior allows us to store MatrixBlock objects in vectors, for
+ * instance in MGLevelObject without extracting the #matrix first.
*
- * MatrixBlock comes handy when using BlockMatrixArray. Once the
- * MatrixBlock has been properly initalized and filled, it can be used
- * in the simplest case as:
+ * MatrixBlock comes handy when using BlockMatrixArray. Once the MatrixBlock
+ * has been properly initalized and filled, it can be used in the simplest
+ * case as:
* @code
* MatrixBlockVector<SparseMatrix<double> > > blocks;
*
* matrix.enter(blocks.block(i).row, blocks.block(i).column, blocks.matrix(i));
* @endcode
*
- * Here, we have not gained very much, except that we do not need to
- * set up empty blocks in the block system.
+ * Here, we have not gained very much, except that we do not need to set up
+ * empty blocks in the block system.
*
- * @note This class expects, that the row and column BlockIndices
- * objects for the system are equal. If they are not, some functions
- * will throw ExcNotImplemented.
+ * @note This class expects, that the row and column BlockIndices objects for
+ * the system are equal. If they are not, some functions will throw
+ * ExcNotImplemented.
*
* @todo Example for the product preconditioner of the pressure Schur
* complement.
*
* @ingroup Matrix2
- * @ingroup vector_valued
- * @see @ref GlossBlockLA "Block (linear algebra)"
+ * @ingroup vector_valued @see @ref GlossBlockLA "Block (linear algebra)"
* @author Guido Kanschat, 2006
*/
template <class MATRIX>
typedef types::global_dof_index size_type;
/**
- * Constructor rendering an
- * uninitialized object.
+ * Constructor rendering an uninitialized object.
*/
MatrixBlock();
MatrixBlock(const MatrixBlock<MATRIX> &M);
/**
- * Constructor setting block
- * coordinates, but not
- * initializing the matrix.
+ * Constructor setting block coordinates, but not initializing the matrix.
*/
MatrixBlock(size_type i, size_type j);
/**
- * Reinitialize the matrix for a
- * new BlockSparsityPattern. This
- * adjusts the #matrix as well
- * as the #row_indices and
- * #column_indices.
+ * Reinitialize the matrix for a new BlockSparsityPattern. This adjusts the
+ * #matrix as well as the #row_indices and #column_indices.
*
- * @note The row and column block
- * structure of the sparsity
- * pattern must be equal.
+ * @note The row and column block structure of the sparsity pattern must be
+ * equal.
*/
void reinit(const BlockSparsityPattern &sparsity);
operator const MATRIX &() const;
/**
- * Add <tt>value</tt> to the
- * element (<i>i,j</i>). Throws
- * an error if the entry does not
- * exist or if it is in a
- * different block.
+ * Add <tt>value</tt> to the element (<i>i,j</i>). Throws an error if the
+ * entry does not exist or if it is in a different block.
*/
void add (const size_type i,
const size_type j,
const typename MATRIX::value_type value);
/**
- * Add all elements in a
- * FullMatrix into sparse
- * matrix locations given by
- * <tt>indices</tt>. This function
- * assumes a quadratic sparse
- * matrix and a quadratic
- * full_matrix. The global
- * locations are translated
- * into locations in this block
- * and ExcBlockIndexMismatch is
- * thrown, if the global index
- * does not point into the
- * block referred to by #row and
+ * Add all elements in a FullMatrix into sparse matrix locations given by
+ * <tt>indices</tt>. This function assumes a quadratic sparse matrix and a
+ * quadratic full_matrix. The global locations are translated into
+ * locations in this block and ExcBlockIndexMismatch is thrown, if the
+ * global index does not point into the block referred to by #row and
* #column.
*
- * @todo
- * <tt>elide_zero_values</tt> is
- * currently ignored.
+ * @todo <tt>elide_zero_values</tt> is currently ignored.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> can be
- * used to specify whether zero
- * values should be added anyway or
- * these should be filtered away and
- * only non-zero data is added. The
- * default value is <tt>true</tt>,
- * i.e., zero values won't be added
- * into the matrix.
+ * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+ * whether zero values should be added anyway or these should be filtered
+ * away and only non-zero data is added. The default value is <tt>true</tt>,
+ * i.e., zero values won't be added into the matrix.
*/
template <typename number>
void add (const std::vector<size_type> &indices,
const bool elide_zero_values = true);
/**
- * Add all elements in a
- * FullMatrix into global
- * locations given by
- * <tt>row_indices</tt> and
- * <tt>col_indices</tt>,
- * respectively. The global
- * locations are translated
- * into locations in this block
- * and ExcBlockIndexMismatch is
- * thrown, if the global index
- * does not point into the
- * block referred to by #row and
- * #column.
+ * Add all elements in a FullMatrix into global locations given by
+ * <tt>row_indices</tt> and <tt>col_indices</tt>, respectively. The global
+ * locations are translated into locations in this block and
+ * ExcBlockIndexMismatch is thrown, if the global index does not point into
+ * the block referred to by #row and #column.
*
- * @todo
- * <tt>elide_zero_values</tt> is
- * currently ignored.
+ * @todo <tt>elide_zero_values</tt> is currently ignored.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> can be
- * used to specify whether zero
- * values should be added anyway or
- * these should be filtered away and
- * only non-zero data is added. The
- * default value is <tt>true</tt>,
- * i.e., zero values won't be added
- * into the matrix.
+ * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+ * whether zero values should be added anyway or these should be filtered
+ * away and only non-zero data is added. The default value is <tt>true</tt>,
+ * i.e., zero values won't be added into the matrix.
*/
template <typename number>
void add (const std::vector<size_type> &row_indices,
const bool elide_zero_values = true);
/**
- * Set several elements in the
- * specified row of the matrix
- * with column indices as given
- * by <tt>col_indices</tt> to
- * the respective value. This
- * is the function doing thye
- * actual work for the ones
- * adding full matrices. The
- * global locations
- * <tt>row_index</tt> and
- * <tt>col_indices</tt> are
- * translated into locations in
- * this block and
- * ExcBlockIndexMismatch is
- * thrown, if the global index
- * does not point into the
- * block referred to by #row and
- * #column.
+ * Set several elements in the specified row of the matrix with column
+ * indices as given by <tt>col_indices</tt> to the respective value. This is
+ * the function doing thye actual work for the ones adding full matrices.
+ * The global locations <tt>row_index</tt> and <tt>col_indices</tt> are
+ * translated into locations in this block and ExcBlockIndexMismatch is
+ * thrown, if the global index does not point into the block referred to by
+ * #row and #column.
*
- * @todo
- * <tt>elide_zero_values</tt> is
- * currently ignored.
+ * @todo <tt>elide_zero_values</tt> is currently ignored.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> can be
- * used to specify whether zero
- * values should be added anyway or
- * these should be filtered away and
- * only non-zero data is added. The
- * default value is <tt>true</tt>,
- * i.e., zero values won't be added
- * into the matrix.
+ * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+ * whether zero values should be added anyway or these should be filtered
+ * away and only non-zero data is added. The default value is <tt>true</tt>,
+ * i.e., zero values won't be added into the matrix.
*/
template <typename number>
void add (const size_type row_index,
const bool elide_zero_values = true);
/**
- * Add an array of values given by
- * <tt>values</tt> in the given
- * global matrix row at columns
- * specified by col_indices in the
- * sparse matrix.
+ * Add an array of values given by <tt>values</tt> in the given global
+ * matrix row at columns specified by col_indices in the sparse matrix.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> can be
- * used to specify whether zero
- * values should be added anyway or
- * these should be filtered away and
- * only non-zero data is added. The
- * default value is <tt>true</tt>,
- * i.e., zero values won't be added
- * into the matrix.
+ * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+ * whether zero values should be added anyway or these should be filtered
+ * away and only non-zero data is added. The default value is <tt>true</tt>,
+ * i.e., zero values won't be added into the matrix.
*/
template <typename number>
void add (const size_type row,
const bool col_indices_are_sorted = false);
/**
- * Matrix-vector-multiplication,
- * forwarding to the same
- * function in MATRIX. No index
- * computations are done, thus,
- * the vectors need to have sizes
+ * Matrix-vector-multiplication, forwarding to the same function in MATRIX.
+ * No index computations are done, thus, the vectors need to have sizes
* matching #matrix.
*/
template<class VECTOR>
void vmult (VECTOR &w, const VECTOR &v) const;
/**
- * Matrix-vector-multiplication,
- * forwarding to the same
- * function in MATRIX. No index
- * computations are done, thus,
- * the vectors need to have sizes
+ * Matrix-vector-multiplication, forwarding to the same function in MATRIX.
+ * No index computations are done, thus, the vectors need to have sizes
* matching #matrix.
*/
template<class VECTOR>
void vmult_add (VECTOR &w, const VECTOR &v) const;
/**
- * Matrix-vector-multiplication,
- * forwarding to the same
- * function in MATRIX. No index
- * computations are done, thus,
- * the vectors need to have sizes
+ * Matrix-vector-multiplication, forwarding to the same function in MATRIX.
+ * No index computations are done, thus, the vectors need to have sizes
* matching #matrix.
*/
template<class VECTOR>
void Tvmult (VECTOR &w, const VECTOR &v) const;
/**
- * Matrix-vector-multiplication,
- * forwarding to the same
- * function in MATRIX. No index
- * computations are done, thus,
- * the vectors need to have sizes
+ * Matrix-vector-multiplication, forwarding to the same function in MATRIX.
+ * No index computations are done, thus, the vectors need to have sizes
* matching #matrix.
*/
template<class VECTOR>
std::size_t memory_consumption () const;
/**
- * The block number computed from
- * an index by using
- * BlockIndices does not match
- * the block coordinates stored
- * in this object.
+ * The block number computed from an index by using BlockIndices does not
+ * match the block coordinates stored in this object.
*/
DeclException2(ExcBlockIndexMismatch, size_type, size_type,
<< "Block index " << arg1 << " does not match " << arg2);
/**
- * Row coordinate. This is the
- * position of the data member
- * matrix on the global matrix.
+ * Row coordinate. This is the position of the data member matrix on the
+ * global matrix.
*/
size_type row;
/**
- * Column coordinate. This is
- * the position of the data
- * member matrix on the global
- * matrix.
+ * Column coordinate. This is the position of the data member matrix on the
+ * global matrix.
*/
size_type column;
private:
/**
- * The rwo BlockIndices of the
- * whole system. Using row(),
- * this allows us to find the
- * index of the first row degree
- * of freedom for this block.
+ * The rwo BlockIndices of the whole system. Using row(), this allows us to
+ * find the index of the first row degree of freedom for this block.
*/
BlockIndices row_indices;
/**
- * The column BlockIndices of the
- * whole system. Using column(),
- * this allows us to find the
- * index of the first column
- * degree of freedom for this
+ * The column BlockIndices of the whole system. Using column(), this allows
+ * us to find the index of the first column degree of freedom for this
* block.
*/
BlockIndices column_indices;
/**
- * A vector of MatrixBlock, which is implemented using shared
- * pointers, in order to allow for copying and rearranging. Each
- * matrix block can be identified by name.
+ * A vector of MatrixBlock, which is implemented using shared pointers, in
+ * order to allow for copying and rearranging. Each matrix block can be
+ * identified by name.
*
* @relates MatrixBlock
* @ingroup vector_valued
typedef MatrixBlock<MATRIX> value_type;
/**
- * Add a new matrix block at the
- * position <tt>(row,column)</tt>
- * in the block system.
+ * Add a new matrix block at the position <tt>(row,column)</tt> in the block
+ * system.
*/
void add(size_type row, size_type column, const std::string &name);
/**
- * For matrices using a
- * SparsityPattern, this function
- * reinitializes each matrix in
- * the vector with the correct
- * pattern from the block system.
+ * For matrices using a SparsityPattern, this function reinitializes each
+ * matrix in the vector with the correct pattern from the block system.
*/
void reinit(const BlockSparsityPattern &sparsity);
/**
* Clears the object.
*
- * Since often only clearing of
- * the individual matrices is
- * desired, but not removing the
- * blocks themselves, there is an
- * optional argument. If the
- * argument is missing or @p
- * false, all matrices will be
- * mepty, but the size of this
- * object and the block positions
- * will not change. If @p
- * really_clean is @p true, then
- * the object will contain no
- * blocks at the end.
+ * Since often only clearing of the individual matrices is desired, but not
+ * removing the blocks themselves, there is an optional argument. If the
+ * argument is missing or @p false, all matrices will be mepty, but the size
+ * of this object and the block positions will not change. If @p
+ * really_clean is @p true, then the object will contain no blocks at the
+ * end.
*/
void clear (bool really_clean = false);
std::size_t memory_consumption () const;
/**
- * Access a constant reference to
- * the block at position <i>i</i>.
+ * Access a constant reference to the block at position <i>i</i>.
*/
const value_type &block(size_type i) const;
/**
- * Access a reference to
- * the block at position <i>i</i>.
+ * Access a reference to the block at position <i>i</i>.
*/
value_type &block(size_type i);
/**
- * Access the matrix at position
- * <i>i</i> for read and write
- * access.
+ * Access the matrix at position <i>i</i> for read and write access.
*/
MATRIX &matrix(size_type i);
/**
* A vector of MGLevelObject<MatrixBlock>, which is implemented using shared
- * pointers, in order to allow for copying and rearranging. Each
- * matrix block can be identified by name.
+ * pointers, in order to allow for copying and rearranging. Each matrix block
+ * can be identified by name.
*
* @relates MatrixBlock
* @ingroup vector_valued
*/
typedef MGLevelObject<MatrixBlock<MATRIX> > value_type;
/**
- * Constructor, determining which
- * matrices should be stored.
+ * Constructor, determining which matrices should be stored.
*
- * If <tt>edge_matrices</tt> is
- * true, then objects for edge
- * matrices for discretizations
- * with degrees of freedom on
- * faces are allocated.
+ * If <tt>edge_matrices</tt> is true, then objects for edge matrices for
+ * discretizations with degrees of freedom on faces are allocated.
*
- * If <tt>edge_flux_matrices</tt>
- * is true, then objects for DG
- * fluxes on the refinement edge
- * are allocated.
+ * If <tt>edge_flux_matrices</tt> is true, then objects for DG fluxes on the
+ * refinement edge are allocated.
*/
MGMatrixBlockVector(const bool edge_matrices = false,
const bool edge_flux_matrices = false);
unsigned int size () const;
/**
- * Add a new matrix block at the
- * position <tt>(row,column)</tt>
- * in the block system. The third
- * argument allows to give the
- * matrix a name for later
+ * Add a new matrix block at the position <tt>(row,column)</tt> in the block
+ * system. The third argument allows to give the matrix a name for later
* identification.
*/
void add(size_type row, size_type column, const std::string &name);
/**
- * For matrices using a
- * SparsityPattern, this function
- * reinitializes each matrix in
- * the vector with the correct
- * pattern from the block system.
+ * For matrices using a SparsityPattern, this function reinitializes each
+ * matrix in the vector with the correct pattern from the block system.
*
- * This function reinitializes
- * the level matrices.
+ * This function reinitializes the level matrices.
*/
void reinit_matrix(const MGLevelObject<BlockSparsityPattern> &sparsity);
/**
- * For matrices using a
- * SparsityPattern, this function
- * reinitializes each matrix in
- * the vector with the correct
- * pattern from the block system.
+ * For matrices using a SparsityPattern, this function reinitializes each
+ * matrix in the vector with the correct pattern from the block system.
*
- * This function reinitializes
- * the matrices for degrees of
- * freedom on the refinement edge.
+ * This function reinitializes the matrices for degrees of freedom on the
+ * refinement edge.
*/
void reinit_edge(const MGLevelObject<BlockSparsityPattern> &sparsity);
/**
- * For matrices using a
- * SparsityPattern, this function
- * reinitializes each matrix in
- * the vector with the correct
- * pattern from the block system.
+ * For matrices using a SparsityPattern, this function reinitializes each
+ * matrix in the vector with the correct pattern from the block system.
*
- * This function reinitializes
- * the flux matrices over the
- * refinement edge.
+ * This function reinitializes the flux matrices over the refinement edge.
*/
void reinit_edge_flux(const MGLevelObject<BlockSparsityPattern> &sparsity);
/**
* Clears the object.
*
- * Since often only clearing of
- * the individual matrices is
- * desired, but not removing the
- * blocks themselves, there is an
- * optional argument. If the
- * argument is missing or @p
- * false, all matrices will be
- * mepty, but the size of this
- * object and the block positions
- * will not change. If @p
- * really_clean is @p true, then
- * the object will contain no
- * blocks at the end.
+ * Since often only clearing of the individual matrices is desired, but not
+ * removing the blocks themselves, there is an optional argument. If the
+ * argument is missing or @p false, all matrices will be mepty, but the size
+ * of this object and the block positions will not change. If @p
+ * really_clean is @p true, then the object will contain no blocks at the
+ * end.
*/
void clear (bool really_clean = false);
/**
- * Access a constant reference to
- * the matrix block at position <i>i</i>.
+ * Access a constant reference to the matrix block at position <i>i</i>.
*/
const value_type &block(size_type i) const;
/**
- * Access a reference to
- * the matrix block at position <i>i</i>.
+ * Access a reference to the matrix block at position <i>i</i>.
*/
value_type &block(size_type i);
/**
- * Access a constant reference to
- * the edge matrix block at position <i>i</i>.
+ * Access a constant reference to the edge matrix block at position
+ * <i>i</i>.
*/
const value_type &block_in(size_type i) const;
/**
- * Access a reference to
- * the edge matrix block at position <i>i</i>.
+ * Access a reference to the edge matrix block at position <i>i</i>.
*/
value_type &block_in(size_type i);
/**
- * Access a constant reference to
- * the edge matrix block at position <i>i</i>.
+ * Access a constant reference to the edge matrix block at position
+ * <i>i</i>.
*/
const value_type &block_out(size_type i) const;
/**
- * Access a reference to
- * the edge matrix block at position <i>i</i>.
+ * Access a reference to the edge matrix block at position <i>i</i>.
*/
value_type &block_out(size_type i);
/**
- * Access a constant reference to
- * the edge flux matrix block at position <i>i</i>.
+ * Access a constant reference to the edge flux matrix block at position
+ * <i>i</i>.
*/
const value_type &block_up(size_type i) const;
/**
- * Access a reference to
- * the edge flux matrix block at position <i>i</i>.
+ * Access a reference to the edge flux matrix block at position <i>i</i>.
*/
value_type &block_up(size_type i);
/**
- * Access a constant reference to
- * the edge flux matrix block at position <i>i</i>.
+ * Access a constant reference to the edge flux matrix block at position
+ * <i>i</i>.
*/
const value_type &block_down(size_type i) const;
/**
- * Access a reference to
- * the edge flux matrix block at position <i>i</i>.
+ * Access a reference to the edge flux matrix block at position <i>i</i>.
*/
value_type &block_down(size_type i);
DEAL_II_NAMESPACE_OPEN
/**
- * STL conforming iterator for constant
- * and non-constant matrices.
+ * STL conforming iterator for constant and non-constant matrices.
*
- * This iterator is abstracted from
- * the actual matrix type and can be
- * used for any matrix having the
- * required ACCESSOR type.
+ * This iterator is abstracted from the actual matrix type and can be used for
+ * any matrix having the required ACCESSOR type.
*
* @author Guido Kanschat, 2006, based on previous a implementation
*/
typedef types::global_dof_index size_type;
/**
- * Typedef for the matrix type
- * (including constness) we are to
- * operate on.
+ * Typedef for the matrix type (including constness) we are to operate on.
*/
typedef typename ACCESSOR::MatrixType MatrixType;
/**
- * Constructor. Create an
- * iterator into the matrix
- * <tt>matrix</tt> for the given
- * <tt>row</tt> and the
- * <tt>index</tt> within it.
+ * Constructor. Create an iterator into the matrix <tt>matrix</tt> for the
+ * given <tt>row</tt> and the <tt>index</tt> within it.
*/
MatrixIterator (MatrixType *matrix,
const size_type row = 0,
const size_type index = 0);
/**
- * Copy from another matrix
- * iterator. Mostly implemented
- * to allow initialization of a
- * constant iterator from a non
- * constant, this function only
- * requires that a conversion
- * from the other iterator's
- * accessor to this accessor
- * object is possible.
+ * Copy from another matrix iterator. Mostly implemented to allow
+ * initialization of a constant iterator from a non constant, this function
+ * only requires that a conversion from the other iterator's accessor to
+ * this accessor object is possible.
*/
template <class OtherAccessor>
MatrixIterator(const MatrixIterator<OtherAccessor> &other);
const ACCESSOR *operator-> () const;
/**
- * Comparison. True, if
- * both accessors are equal.
+ * Comparison. True, if both accessors are equal.
*/
bool operator == (const MatrixIterator &) const;
bool operator != (const MatrixIterator &) const;
/**
- * Comparison operator. Result is
- * true if either the first row
- * number is smaller or if the row
- * numbers are equal and the first
- * index is smaller.
+ * Comparison operator. Result is true if either the first row number is
+ * smaller or if the row numbers are equal and the first index is smaller.
*
- * This function is only valid if
- * both iterators point into the same
- * matrix.
+ * This function is only valid if both iterators point into the same matrix.
*/
bool operator < (const MatrixIterator &) const;
/**
- * Comparison operator. Works in the
- * same way as above operator, just
- * the other way round.
+ * Comparison operator. Works in the same way as above operator, just the
+ * other way round.
*/
bool operator > (const MatrixIterator &) const;
private:
/**
- * Store an object of the
- * accessor class.
+ * Store an object of the accessor class.
*/
ACCESSOR accessor;
/**
- * Allow other iterators access
- * to private data.
+ * Allow other iterators access to private data.
*/
template <class OtherAccessor> friend class MatrixIterator;
};
/**
- * Poor man's matrix product of two quadratic matrices. Stores two
- * quadratic matrices #m1 and #m2 of arbitrary types and implements
- * matrix-vector multiplications for the product
- * <i>M<sub>1</sub>M<sub>2</sub></i> by performing multiplication with
- * both factors consecutively. Because the types of the matrices are
- * opaque (i.e., they can be arbitrary), you can stack products of three
- * or more matrices by making one of the two matrices an object of the
- * current type handles be a ProductMatrix itself.
+ * Poor man's matrix product of two quadratic matrices. Stores two quadratic
+ * matrices #m1 and #m2 of arbitrary types and implements matrix-vector
+ * multiplications for the product <i>M<sub>1</sub>M<sub>2</sub></i> by
+ * performing multiplication with both factors consecutively. Because the
+ * types of the matrices are opaque (i.e., they can be arbitrary), you can
+ * stack products of three or more matrices by making one of the two matrices
+ * an object of the current type handles be a ProductMatrix itself.
*
- * Here is an example multiplying two different FullMatrix objects:
- * @include product_matrix.cc
+ * Here is an example multiplying two different FullMatrix objects: @include
+ * product_matrix.cc
*
* @author Guido Kanschat, 2000, 2001, 2002, 2005
*/
{
public:
/**
- * Standard constructor. Matrices
- * and the memory pool must be
- * added later using
- * initialize().
+ * Standard constructor. Matrices and the memory pool must be added later
+ * using initialize().
*/
ProductMatrix();
/**
- * Constructor only assigning the
- * memory pool. Matrices must be
- * added by reinit() later.
+ * Constructor only assigning the memory pool. Matrices must be added by
+ * reinit() later.
*/
ProductMatrix(VectorMemory<VECTOR> &mem);
/**
- * Constructor. Additionally to
- * the two constituting matrices, a
- * memory pool for the auxiliary
- * vector must be provided.
+ * Constructor. Additionally to the two constituting matrices, a memory
+ * pool for the auxiliary vector must be provided.
*/
template <class MATRIX1, class MATRIX2>
ProductMatrix(const MATRIX1 &m1,
void clear();
/**
- * Matrix-vector product <i>w =
- * m1 * m2 * v</i>.
+ * Matrix-vector product <i>w = m1 * m2 * v</i>.
*/
virtual void vmult (VECTOR &w,
const VECTOR &v) const;
/**
- * Transposed matrix-vector
- * product <i>w = m2<sup>T</sup> *
- * m1<sup>T</sup> * v</i>.
+ * Transposed matrix-vector product <i>w = m2<sup>T</sup> * m1<sup>T</sup> *
+ * v</i>.
*/
virtual void Tvmult (VECTOR &w,
const VECTOR &v) const;
/**
- * Adding matrix-vector product
- * <i>w += m1 * m2 * v</i>
+ * Adding matrix-vector product <i>w += m1 * m2 * v</i>
*/
virtual void vmult_add (VECTOR &w,
const VECTOR &v) const;
/**
- * Adding, transposed
- * matrix-vector product <i>w +=
- * m2<sup>T</sup> *
+ * Adding, transposed matrix-vector product <i>w += m2<sup>T</sup> *
* m1<sup>T</sup> * v</i>.
*/
virtual void Tvmult_add (VECTOR &w,
/**
* A matrix that is the multiple of another matrix.
*
- * Matrix-vector products of this matrix are composed of those of the
- * original matrix with the vector and then scaling of the result by
- * a constant factor.
+ * Matrix-vector products of this matrix are composed of those of the original
+ * matrix with the vector and then scaling of the result by a constant factor.
*
* @author Guido Kanschat, 2007
*/
{
public:
/**
- * Constructor leaving an
- * uninitialized object.
+ * Constructor leaving an uninitialized object.
*/
ScaledMatrix ();
/**
*/
~ScaledMatrix ();
/**
- * Initialize for use with a new
- * matrix and factor.
+ * Initialize for use with a new matrix and factor.
*/
template <class MATRIX>
void initialize (const MATRIX &M, const double factor);
void vmult (VECTOR &w, const VECTOR &v) const;
/**
- * Tranposed matrix-vector
- * product.
+ * Tranposed matrix-vector product.
*/
void Tvmult (VECTOR &w, const VECTOR &v) const;
/**
- * Poor man's matrix product of two sparse matrices. Stores two
- * matrices #m1 and #m2 of arbitrary type SparseMatrix and implements
- * matrix-vector multiplications for the product
- * <i>M<sub>1</sub>M<sub>2</sub></i> by performing multiplication with
- * both factors consecutively.
+ * Poor man's matrix product of two sparse matrices. Stores two matrices #m1
+ * and #m2 of arbitrary type SparseMatrix and implements matrix-vector
+ * multiplications for the product <i>M<sub>1</sub>M<sub>2</sub></i> by
+ * performing multiplication with both factors consecutively.
*
- * The documentation of ProductMatrix applies with exception that
- * these matrices here may be rectangular.
+ * The documentation of ProductMatrix applies with exception that these
+ * matrices here may be rectangular.
*
* @author Guido Kanschat, 2000, 2001, 2002, 2005
*/
typedef SparseMatrix<number> MatrixType;
/**
- * Define the type of vectors we
- * plly this matrix to.
+ * Define the type of vectors we plly this matrix to.
*/
typedef Vector<vector_number> VectorType;
/**
- * Constructor. Additionally to
- * the two constituting matrices, a
- * memory pool for the auxiliary
- * vector must be provided.
+ * Constructor. Additionally to the two constituting matrices, a memory
+ * pool for the auxiliary vector must be provided.
*/
ProductSparseMatrix(const MatrixType &m1,
const MatrixType &m2,
VectorMemory<VectorType> &mem);
/**
- * Constructor leaving an
- * uninitialized
- * matrix. initialize() must be
- * called, before the matrix can
- * be used.
+ * Constructor leaving an uninitialized matrix. initialize() must be called,
+ * before the matrix can be used.
*/
ProductSparseMatrix();
void clear();
/**
- * Matrix-vector product <i>w =
- * m1 * m2 * v</i>.
+ * Matrix-vector product <i>w = m1 * m2 * v</i>.
*/
virtual void vmult (VectorType &w,
const VectorType &v) const;
/**
- * Transposed matrix-vector
- * product <i>w = m2<sup>T</sup> *
- * m1<sup>T</sup> * v</i>.
+ * Transposed matrix-vector product <i>w = m2<sup>T</sup> * m1<sup>T</sup> *
+ * v</i>.
*/
virtual void Tvmult (VectorType &w,
const VectorType &v) const;
/**
- * Adding matrix-vector product
- * <i>w += m1 * m2 * v</i>
+ * Adding matrix-vector product <i>w += m1 * m2 * v</i>
*/
virtual void vmult_add (VectorType &w,
const VectorType &v) const;
/**
- * Adding, transposed
- * matrix-vector product <i>w +=
- * m2<sup>T</sup> *
+ * Adding, transposed matrix-vector product <i>w += m2<sup>T</sup> *
* m1<sup>T</sup> * v</i>.
*/
virtual void Tvmult_add (VectorType &w,
/**
- * Mean value filter. The vmult() functions of this matrix filter
- * out mean values of the vector. If the vector is of type
- * BlockVector, then an additional parameter selects a single
- * component for this operation.
+ * Mean value filter. The vmult() functions of this matrix filter out mean
+ * values of the vector. If the vector is of type BlockVector, then an
+ * additional parameter selects a single component for this operation.
*
- * In mathematical terms, this class acts as if it was the matrix
- * $I-\frac 1n{\mathbf 1}_n{\mathbf 1}_n^T$ where ${\mathbf 1}_n$ is
- * a vector of size $n$ that has only ones as its entries. Thus,
- * taking the dot product between a vector $\mathbf v$ and
- * $\frac 1n {\mathbf 1}_n$ yields the <i>mean value</i> of the entries
- * of ${\mathbf v}$. Consequently,
- * $ \left[I-\frac 1n{\mathbf 1}_n{\mathbf 1}_n^T\right] \mathbf v
- * = \mathbf v - \left[\frac 1n \mathbf v} \cdot {\mathbf 1}_n\right]{\mathbf 1}_n$
- * subtracts from every vector element the mean value of all elements.
+ * In mathematical terms, this class acts as if it was the matrix $I-\frac
+ * 1n{\mathbf 1}_n{\mathbf 1}_n^T$ where ${\mathbf 1}_n$ is a vector of size
+ * $n$ that has only ones as its entries. Thus, taking the dot product between
+ * a vector $\mathbf v$ and $\frac 1n {\mathbf 1}_n$ yields the <i>mean
+ * value</i> of the entries of ${\mathbf v}$. Consequently, $ \left[I-\frac
+ * 1n{\mathbf 1}_n{\mathbf 1}_n^T\right] \mathbf v = \mathbf v - \left[\frac
+ * 1n \mathbf v} \cdot {\mathbf 1}_n\right]{\mathbf 1}_n$ subtracts from every
+ * vector element the mean value of all elements.
*
* @author Guido Kanschat, 2002, 2003
*/
typedef types::global_dof_index size_type;
/**
- * Constructor, optionally
- * selecting a component.
+ * Constructor, optionally selecting a component.
*/
MeanValueFilter(const size_type component = numbers::invalid_size_type);
void filter (BlockVector<number> &v) const;
/**
- * Return the source vector with
- * subtracted mean value.
+ * Return the source vector with subtracted mean value.
*/
template <typename number>
void vmult (Vector<number> &dst,
const Vector<number> &src) const;
/**
- * Add source vector with
- * subtracted mean value to dest.
+ * Add source vector with subtracted mean value to dest.
*/
template <typename number>
void vmult_add (Vector<number> &dst,
const Vector<number> &src) const;
/**
- * Return the source vector with
- * subtracted mean value in
- * selected component.
+ * Return the source vector with subtracted mean value in selected
+ * component.
*/
template <typename number>
void vmult (BlockVector<number> &dst,
const BlockVector<number> &src) const;
/**
- * Add a soruce to dest, where
- * the mean value in the selected
- * component is subtracted.
+ * Add a soruce to dest, where the mean value in the selected component is
+ * subtracted.
*/
template <typename number>
void vmult_add (BlockVector<number> &dst,
/**
- * Objects of this type represent the inverse of a matrix as
- * computed approximately by using the SolverRichardson
- * iterative solver. In other words, if you set up an object
- * of the current type for a matrix $A$, then calling the
- * vmult() function with arguments $v,w$ amounts to setting
- * $w=A^{-1}v$ by solving the linear system $Aw=v$ using the
- * Richardson solver with a preconditioner that can be chosen. Similarly,
- * this class allows to also multiple with the transpose of the
- * inverse (i.e., the inverse of the transpose) using the function
- * SolverRichardson::Tsolve().
+ * Objects of this type represent the inverse of a matrix as computed
+ * approximately by using the SolverRichardson iterative solver. In other
+ * words, if you set up an object of the current type for a matrix $A$, then
+ * calling the vmult() function with arguments $v,w$ amounts to setting
+ * $w=A^{-1}v$ by solving the linear system $Aw=v$ using the Richardson solver
+ * with a preconditioner that can be chosen. Similarly, this class allows to
+ * also multiple with the transpose of the inverse (i.e., the inverse of the
+ * transpose) using the function SolverRichardson::Tsolve().
*
- * The functions vmult() and Tvmult() approximate the inverse
- * iteratively starting with the vector <tt>dst</tt>. Functions
- * vmult_add() and Tvmult_add() start the iteration with a zero
- * vector. All of the matrix-vector multiplication functions
- * expect that the Richardson solver with the given preconditioner
- * actually converge. If the Richardson solver does not converge
- * within the specified number of iterations, the exception that will
- * result in the solver will simply be propagated to the caller of
- * the member function of the current class.
+ * The functions vmult() and Tvmult() approximate the inverse iteratively
+ * starting with the vector <tt>dst</tt>. Functions vmult_add() and
+ * Tvmult_add() start the iteration with a zero vector. All of the matrix-
+ * vector multiplication functions expect that the Richardson solver with the
+ * given preconditioner actually converge. If the Richardson solver does not
+ * converge within the specified number of iterations, the exception that will
+ * result in the solver will simply be propagated to the caller of the member
+ * function of the current class.
*
* @note A more powerful version of this class is provided by the
* IterativeInverse class.
{
public:
/**
- * Constructor, initializing the
- * solver with a control and
- * memory object. The inverted
- * matrix and the preconditioner
- * are added in initialize().
+ * Constructor, initializing the solver with a control and memory object.
+ * The inverted matrix and the preconditioner are added in initialize().
*/
InverseMatrixRichardson (SolverControl &control,
VectorMemory<VECTOR> &mem);
/**
- * Since we use two pointers, we
- * must implement a destructor.
+ * Since we use two pointers, we must implement a destructor.
*/
~InverseMatrixRichardson();
/**
- * Initialization
- * function. Provide a solver
- * object, a matrix, and another
+ * Initialization function. Provide a solver object, a matrix, and another
* preconditioner for this.
*/
template <class MATRIX, class PRECONDITION>
const PRECONDITION &);
/**
- * Access to the SolverControl
- * object used by the solver.
+ * Access to the SolverControl object used by the solver.
*/
SolverControl &control() const;
/**
private:
/**
- * A reference to the provided
- * VectorMemory object.
+ * A reference to the provided VectorMemory object.
*/
VectorMemory<VECTOR> &mem;
DEAL_II_NAMESPACE_OPEN
/**
- * Output a matrix in graphical form using the generic format
- * independent output routines of the base class. The matrix is
- * converted into a list of patches on a 2d domain where the height is
- * given by the elements of the matrix. The functions of the base
- * class can then write this "mountain representation" of the matrix
- * in a variety of graphical output formats. The coordinates of the
- * matrix output are that the columns run with increasing x-axis, as
- * usual, starting from zero, while the rows run into the negative
+ * Output a matrix in graphical form using the generic format independent
+ * output routines of the base class. The matrix is converted into a list of
+ * patches on a 2d domain where the height is given by the elements of the
+ * matrix. The functions of the base class can then write this "mountain
+ * representation" of the matrix in a variety of graphical output formats. The
+ * coordinates of the matrix output are that the columns run with increasing
+ * x-axis, as usual, starting from zero, while the rows run into the negative
* y-axis, also starting from zero. Note that due to some internal
- * restrictions, this class can only output one matrix at a time,
- * i.e. it can not take advantage of the multiple dataset capabilities
- * of the base class.
+ * restrictions, this class can only output one matrix at a time, i.e. it can
+ * not take advantage of the multiple dataset capabilities of the base class.
*
* A typical usage of this class would be as follows:
* @code
* matrix_out.build_patches (M, "M");
* matrix_out.write_gnuplot (out);
* @endcode
- * Of course, you can as well choose a different graphical output
- * format. Also, this class supports any matrix, not only of type
- * FullMatrix, as long as it satisfies a number of requirements,
- * stated with the member functions of this class.
+ * Of course, you can as well choose a different graphical output format.
+ * Also, this class supports any matrix, not only of type FullMatrix, as long
+ * as it satisfies a number of requirements, stated with the member functions
+ * of this class.
*
- * The generation of patches through the build_patches() function
- * can be modified by giving it an object holding certain flags. See
- * the documentation of the members of the Options class for a
- * description of these flags.
+ * The generation of patches through the build_patches() function can be
+ * modified by giving it an object holding certain flags. See the
+ * documentation of the members of the Options class for a description of
+ * these flags.
*
*
* <h3>Internals</h3>
*
- * To avoid a compiler error in Sun's Forte compiler, we derive
- * privately from DataOutBase. Since the base class
- * DataOutInterface does so as well, this does no harm, but
- * calms the compiler which is suspecting an access control conflict
- * otherwise. Testcase here:
+ * To avoid a compiler error in Sun's Forte compiler, we derive privately from
+ * DataOutBase. Since the base class DataOutInterface does so as well, this
+ * does no harm, but calms the compiler which is suspecting an access control
+ * conflict otherwise. Testcase here:
* @code
* template <typename T> class V {};
*
typedef types::global_dof_index size_type;
/**
- * Class holding various
- * variables which are used to
- * modify the output of the
- * MatrixOut class.
+ * Class holding various variables which are used to modify the output of
+ * the MatrixOut class.
*/
struct Options
{
/**
- * If @p true, only show the
- * absolute values of the
- * matrix entries, rather
- * than their true values
- * including the
- * sign. Default value is
- * @p false.
+ * If @p true, only show the absolute values of the matrix entries, rather
+ * than their true values including the sign. Default value is @p false.
*/
bool show_absolute_values;
/**
- * If larger than one, do not
- * show each element of the
- * matrix, but rather an
- * average over a number of
- * entries. The number of
- * output patches is
- * accordingly smaller. This
- * flag determines how large
- * each shown block shall be
- * (in rows/columns). For
- * example, if it is two,
- * then always four entries
- * are collated into one.
+ * If larger than one, do not show each element of the matrix, but rather
+ * an average over a number of entries. The number of output patches is
+ * accordingly smaller. This flag determines how large each shown block
+ * shall be (in rows/columns). For example, if it is two, then always four
+ * entries are collated into one.
*
* Default value is one.
*/
unsigned int block_size;
/**
- * If true, plot
- * discontinuous patches, one
- * for each entry.
+ * If true, plot discontinuous patches, one for each entry.
*/
bool discontinuous;
/**
- * Default constructor. Set
- * all elements of this
- * structure to their default
- * values.
+ * Default constructor. Set all elements of this structure to their
+ * default values.
*/
Options (const bool show_absolute_values = false,
const unsigned int block_size = 1,
};
/**
- * Destructor. Declared in order
- * to make it virtual.
+ * Destructor. Declared in order to make it virtual.
*/
virtual ~MatrixOut ();
/**
- * Generate a list of patches
- * from the given matrix and use
- * the given string as the name
- * of the data set upon writing
- * to a file. Once patches have
- * been built, you can use the
- * functions of the base class to
- * write the data into a files,
- * using one of the supported
- * output formats.
+ * Generate a list of patches from the given matrix and use the given string
+ * as the name of the data set upon writing to a file. Once patches have
+ * been built, you can use the functions of the base class to write the data
+ * into a files, using one of the supported output formats.
*
- * You may give a structure
- * holding various options. See
- * the description of the fields
- * of this structure for more
- * information.
+ * You may give a structure holding various options. See the description of
+ * the fields of this structure for more information.
*
- * Note that this function
- * requires that we can extract
- * elements of the matrix, which
- * is done using the
- * get_element() function
- * declared below. By adding
- * specializations, you can
- * extend this class to other
- * matrix classes which are not
- * presently
- * supported. Furthermore, we
- * need to be able to extract the
- * size of the matrix, for which
- * we assume that the matrix type
- * offers member functions
- * <tt>m()</tt> and <tt>n()</tt>, which
- * return the number of rows and
- * columns, respectively.
+ * Note that this function requires that we can extract elements of the
+ * matrix, which is done using the get_element() function declared below. By
+ * adding specializations, you can extend this class to other matrix classes
+ * which are not presently supported. Furthermore, we need to be able to
+ * extract the size of the matrix, for which we assume that the matrix type
+ * offers member functions <tt>m()</tt> and <tt>n()</tt>, which return the
+ * number of rows and columns, respectively.
*/
template <class Matrix>
void build_patches (const Matrix &matrix,
private:
/**
- * Abbreviate the somewhat
- * lengthy name for the dealii::DataOutBase::Patch
+ * Abbreviate the somewhat lengthy name for the dealii::DataOutBase::Patch
* class.
*
- * Note that we have to indicate the
- * global scope in front of DataOutBase,
- * since otherwise the C++ rules specify
- * that this here indicates the
- * DataOutBase base class of this
- * class. Since that is a private base
- * class, we cannot access its members,
- * and so access to the local Patch type
- * would be forbidden.
+ * Note that we have to indicate the global scope in front of DataOutBase,
+ * since otherwise the C++ rules specify that this here indicates the
+ * DataOutBase base class of this class. Since that is a private base class,
+ * we cannot access its members, and so access to the local Patch type would
+ * be forbidden.
*/
typedef dealii::DataOutBase::Patch<2,2> Patch;
/**
- * This is a list of patches that
- * is created each time
- * build_patches() is
- * called. These patches are used
- * in the output routines of the
- * base classes.
+ * This is a list of patches that is created each time build_patches() is
+ * called. These patches are used in the output routines of the base
+ * classes.
*/
std::vector<Patch> patches;
/**
- * Name of the matrix to be
- * written.
+ * Name of the matrix to be written.
*/
std::string name;
/**
- * Function by which the base
- * class's functions get to know
- * what patches they shall write
- * to a file.
+ * Function by which the base class's functions get to know what patches
+ * they shall write to a file.
*/
virtual const std::vector<Patch> &
get_patches () const;
/**
- * Virtual function through which
- * the names of data sets are
- * obtained by the output
- * functions of the base class.
+ * Virtual function through which the names of data sets are obtained by the
+ * output functions of the base class.
*/
virtual std::vector<std::string> get_dataset_names () const;
/**
- * Return the element with given
- * indices of a sparse matrix.
+ * Return the element with given indices of a sparse matrix.
*/
template <typename number>
static double get_element (const SparseMatrix<number> &matrix,
const size_type j);
/**
- * Return the element with given
- * indices of a block sparse
- * matrix.
+ * Return the element with given indices of a block sparse matrix.
*/
template <typename number>
static double get_element (const BlockSparseMatrix<number> &matrix,
const size_type j);
/**
- * Return the element with given
- * indices from any matrix type
- * for which no specialization of
- * this function was declared
- * above. This will call
+ * Return the element with given indices from any matrix type for which no
+ * specialization of this function was declared above. This will call
* <tt>operator()</tt> on the matrix.
*/
template <class Matrix>
const size_type j);
/**
- * Get the value of the matrix at
- * gridpoint <tt>(i,j)</tt>. Depending
- * on the given flags, this can
- * mean different things, for
- * example if only absolute
- * values shall be shown then the
- * absolute value of the matrix
- * entry is taken. If the block
- * size is larger than one, then
- * an average of several matrix
- * entries is taken.
+ * Get the value of the matrix at gridpoint <tt>(i,j)</tt>. Depending on the
+ * given flags, this can mean different things, for example if only absolute
+ * values shall be shown then the absolute value of the matrix entry is
+ * taken. If the block size is larger than one, then an average of several
+ * matrix entries is taken.
*/
template <class Matrix>
static double get_gridpoint_value (const Matrix &matrix,
/**
- * An implementation of block vectors based on distribued deal.II
- * vectors. While the base class provides for most of the interface, this
- * class handles the actual allocation of vectors and provides functions that
+ * An implementation of block vectors based on distribued deal.II vectors.
+ * While the base class provides for most of the interface, this class
+ * handles the actual allocation of vectors and provides functions that
* are specific to the underlying vector type.
*
- * @note Instantiations for this template are provided for <tt>@<float@> and
- * @<double@></tt>; others can be generated in application programs (see the
- * section on @ref Instantiations in the manual).
+ * @note Instantiations for this template are provided for <tt>@<float@>
+ * and @<double@></tt>; others can be generated in application programs
+ * (see the section on @ref Instantiations in the manual).
*
* @see @ref GlossBlockLA "Block (linear algebra)"
* @author Katharina Kormann, Martin Kronbichler, 2011
typedef typename BaseClass::const_iterator const_iterator;
/**
- * Constructor. There are three ways to use this constructor. First,
- * without any arguments, it generates an object with no blocks. Given
- * one argument, it initializes <tt>num_blocks</tt> blocks, but these
- * blocks have size zero. The third variant finally initializes all
- * blocks to the same size <tt>block_size</tt>.
+ * Constructor. There are three ways to use this constructor. First,
+ * without any arguments, it generates an object with no blocks. Given
+ * one argument, it initializes <tt>num_blocks</tt> blocks, but these
+ * blocks have size zero. The third variant finally initializes all
+ * blocks to the same size <tt>block_size</tt>.
*
- * Confer the other constructor further down if you intend to use
- * blocks of different sizes.
+ * Confer the other constructor further down if you intend to use blocks
+ * of different sizes.
*/
explicit BlockVector (const size_type num_blocks = 0,
const size_type block_size = 0);
BlockVector (const std::vector<size_type> &block_sizes);
/**
- * Construct a block vector with an IndexSet for the local range
- * and ghost entries for each block.
+ * Construct a block vector with an IndexSet for the local range and
+ * ghost entries for each block.
*/
BlockVector (const std::vector<IndexSet> &local_ranges,
const std::vector<IndexSet> &ghost_indices,
bool has_ghost_elements() const;
/**
- * Return whether the vector contains only elements with value
- * zero. This function is mainly for internal consistency checks and
- * should seldom be used when not in debug mode since it uses quite some
- * time.
+ * Return whether the vector contains only elements with value zero.
+ * This function is mainly for internal consistency checks and should
+ * seldom be used when not in debug mode since it uses quite some time.
*/
bool all_zero () const;
/**
* Scale each element of the vector by the given factor.
*
- * This function is deprecated and will be removed in a future
- * version. Use <tt>operator *=</tt> and <tt>operator /=</tt> instead.
+ * This function is deprecated and will be removed in a future version.
+ * Use <tt>operator *=</tt> and <tt>operator /=</tt> instead.
*
* @deprecated Use <tt>operator*=</tt> instead.
*/
*/
void swap (BlockVector<Number> &v);
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
} // end of namespace parallel
/**
- * Global function which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two vectors.
+ * Global function which overloads the default implementation of the C++
+ * standard library which uses a temporary object. The function simply
+ * exchanges the data of the two vectors.
*
* @relates BlockVector
* @author Katharina Kormann, Martin Kronbichler, 2011
* similar to the standard ::dealii::Vector class in deal.II, with the
* exception that storage is distributed with MPI.
*
- * The vector is designed for the following scheme of parallel partitioning:
- * - The indices held by individual processes (locally owned part) in the
- * MPI parallelization form a contiguous range
- * <code>[my_first_index,my_last_index)</code>.
- * - Ghost indices residing on arbitrary positions of other processors are
- * allowed. It is in general more efficient if ghost indices are
- * clustered, since they are stored as a set of intervals. The
- * communication pattern of the ghost indices is determined when calling
- * the function <code>reinit (locally_owned, ghost_indices,
- * communicator)</code>, and retained until the partitioning is changed
- * again. This allows for efficient parallel communication of indices. In
- * particular, it stores the communication pattern, rather than having
- * to compute it again for every communication. (For more information on
- * ghost vectors, see also the
- * @ref GlossGhostedVector "glossary entry on vectors with ghost elements".)
- * - Besides the usual global access operator () it is also possible to
- * access vector entries in the local index space with the function @p
- * local_element(). Locally owned indices are placed first, [0,
- * local_size()), and then all ghost indices follow after them
- * contiguously, [local_size(), local_size()+n_ghost_entries()).
+ * The vector is designed for the following scheme of parallel
+ * partitioning: - The indices held by individual processes (locally owned
+ * part) in the MPI parallelization form a contiguous range
+ * <code>[my_first_index,my_last_index)</code>. - Ghost indices residing
+ * on arbitrary positions of other processors are allowed. It is in
+ * general more efficient if ghost indices are clustered, since they are
+ * stored as a set of intervals. The communication pattern of the ghost
+ * indices is determined when calling the function <code>reinit
+ * (locally_owned, ghost_indices, communicator)</code>, and retained until
+ * the partitioning is changed again. This allows for efficient parallel
+ * communication of indices. In particular, it stores the communication
+ * pattern, rather than having to compute it again for every
+ * communication. (For more information on ghost vectors, see also the
+ * @ref GlossGhostedVector "glossary entry on vectors with ghost
+ * elements".) - Besides the usual global access operator () it is also
+ * possible to access vector entries in the local index space with the
+ * function @p local_element(). Locally owned indices are placed first,
+ * [0, local_size()), and then all ghost indices follow after them
+ * contiguously, [local_size(), local_size()+n_ghost_entries()).
*
- * Functions related to parallel functionality:
- * - The function <code>compress()</code> goes through the data associated
- * with ghost indices and communicates it to the owner process, which can
- * then add it to the correct position. This can be used e.g. after
- * having run an assembly routine involving ghosts that fill this vector.
- * Note that the @p insert mode of @p compress() does not set the
- * elements included in ghost entries but simply discards them, assuming
- * that the owning processor has set them to the desired value already.
- * (See also the @ref GlossCompress "glossary entry on compress".)
- * - The <code>update_ghost_values()</code> function imports the data from
- * the owning processor to the ghost indices in order to provide read
- * access to the data associated with ghosts.
- * - It is possible to split the above functions into two phases, where
- * the first initiates the communication and the second one finishes
- * it. These functions can be used to overlap communication with
- * computations in other parts of the code.
- * - Of course, reduction operations (like norms) make use of collective
- * all-to-all MPI communications.
+ * Functions related to parallel functionality: - The function
+ * <code>compress()</code> goes through the data associated with ghost
+ * indices and communicates it to the owner process, which can then add it
+ * to the correct position. This can be used e.g. after having run an
+ * assembly routine involving ghosts that fill this vector. Note that the
+ * @p insert mode of @p compress() does not set the elements included in
+ * ghost entries but simply discards them, assuming that the owning
+ * processor has set them to the desired value already. (See also the @ref
+ * GlossCompress "glossary entry on compress".) - The
+ * <code>update_ghost_values()</code> function imports the data from the
+ * owning processor to the ghost indices in order to provide read access
+ * to the data associated with ghosts. - It is possible to split the above
+ * functions into two phases, where the first initiates the communication
+ * and the second one finishes it. These functions can be used to overlap
+ * communication with computations in other parts of the code. - Of
+ * course, reduction operations (like norms) make use of collective all-
+ * to-all MPI communications.
*
* This vector can take two different states with respect to ghost
- * elements:
- * - After creation and whenever zero_out_ghosts() is called (or
- * <code>operator = (0.)</code>), the vector does only allow writing
- * into ghost elements but not reading from ghost elements.
- * - After a call to update_ghost_values(), the vector does not allow
- * writing into ghost elements but only reading from them. This is in
- * order to avoid undesired ghost data artifacts when calling compress()
- * after modifying some vector entries.
- * The current status of the ghost entries (read mode or write mode) can
- * be queried by the method has_ghost_elements(), which returns
- * <code>true</code> exactly when ghost elements have been updated and
- * <code>false</code> otherwise, irrespective of the actual number of
+ * elements: - After creation and whenever zero_out_ghosts() is called (or
+ * <code>operator = (0.)</code>), the vector does only allow writing into
+ * ghost elements but not reading from ghost elements. - After a call to
+ * update_ghost_values(), the vector does not allow writing into ghost
+ * elements but only reading from them. This is in order to avoid
+ * undesired ghost data artifacts when calling compress() after modifying
+ * some vector entries. The current status of the ghost entries (read mode
+ * or write mode) can be queried by the method has_ghost_elements(), which
+ * returns <code>true</code> exactly when ghost elements have been updated
+ * and <code>false</code> otherwise, irrespective of the actual number of
* ghost entries in the vector layout (for that information, use
* n_ghost_entries() instead).
*
typedef typename numbers::NumberTraits<Number>::real_type real_type;
/**
- * A variable that indicates whether this vector
- * supports distributed data storage. If true, then
- * this vector also needs an appropriate compress()
- * function that allows communicating recent set or
- * add operations to individual elements to be communicated
- * to other processors.
+ * A variable that indicates whether this vector supports distributed
+ * data storage. If true, then this vector also needs an appropriate
+ * compress() function that allows communicating recent set or add
+ * operations to individual elements to be communicated to other
+ * processors.
*
- * For the current class, the variable equals
- * true, since it does support parallel data storage.
+ * For the current class, the variable equals true, since it does
+ * support parallel data storage.
*/
static const bool supports_distributed_data = true;
* both the element on the ghost site as well as the owning site), this
* operation makes the assumption that all data is set correctly on the
* owning processor. Upon call of compress(VectorOperation::insert), all
- * ghost entries are thus simply zeroed out (using
- * zero_ghost_values()). In debug mode, a check is performed for whether
- * the data set is actually consistent between processors,
- * i.e., whenever a non-zero ghost element is found, it is compared to
- * the value on the owning processor and an exception is thrown if these
- * elements do not agree.
+ * ghost entries are thus simply zeroed out (using zero_ghost_values()).
+ * In debug mode, a check is performed for whether the data set is
+ * actually consistent between processors, i.e., whenever a non-zero
+ * ghost element is found, it is compared to the value on the owning
+ * processor and an exception is thrown if these elements do not agree.
*/
void compress (::dealii::VectorOperation::values operation);
void update_ghost_values () const;
/**
- * Initiates communication for the @p compress() function with
- * non-blocking communication. This function does not wait for the
- * transfer to finish, in order to allow for other computations during
- * the time it takes until all data arrives.
+ * Initiates communication for the @p compress() function with non-
+ * blocking communication. This function does not wait for the transfer
+ * to finish, in order to allow for other computations during the time
+ * it takes until all data arrives.
*
* Before the data is actually exchanged, the function must be followed
* by a call to @p compress_finish().
* For all requests that have been initiated in compress_start, wait for
* the communication to finish. Once it is finished, add or set the data
* (depending on the flag operation) to the respective positions in the
- * owning processor, and clear the contents in the ghost data
- * fields. The meaning of this argument is the same as in
- * compress().
+ * owning processor, and clear the contents in the ghost data fields.
+ * The meaning of this argument is the same as in compress().
*
* This function should be called exactly once per vector after calling
* compress_start, otherwise the result is undefined. In particular, it
bool has_ghost_elements() const;
/**
- * Return whether the vector contains only elements with value
- * zero. This is a collective operation. This function is expensive, because
+ * Return whether the vector contains only elements with value zero.
+ * This is a collective operation. This function is expensive, because
* potentially all elements have to be checked.
*/
bool all_zero () const;
bool in_local_range (const size_type global_index) const;
/**
- * Return an index set that describes which elements of this vector
- * are owned by the current processor. Note that this index set does
- * not include elements this vector may store locally as ghost
- * elements but that are in fact owned by another processor.
- * As a consequence, the index sets returned on different
- * processors if this is a distributed vector will form disjoint
- * sets that add up to the complete index set.
- * Obviously, if a vector is created on only one processor, then
- * the result would satisfy
+ * Return an index set that describes which elements of this vector are
+ * owned by the current processor. Note that this index set does not
+ * include elements this vector may store locally as ghost elements but
+ * that are in fact owned by another processor. As a consequence, the
+ * index sets returned on different processors if this is a distributed
+ * vector will form disjoint sets that add up to the complete index set.
+ * Obviously, if a vector is created on only one processor, then the
+ * result would satisfy
* @code
* vec.locally_owned_elements() == complete_index_set (vec.size())
* @endcode
Number &operator [] (const size_type global_index);
/**
- * A collective get operation: instead
- * of getting individual elements of a
- * vector, this function allows to get
- * a whole set of elements at once. The
- * indices of the elements to be read
- * are stated in the first argument,
- * the corresponding values are returned in the
- * second.
+ * A collective get operation: instead of getting individual elements of
+ * a vector, this function allows to get a whole set of elements at
+ * once. The indices of the elements to be read are stated in the first
+ * argument, the corresponding values are returned in the second.
*/
template <typename OtherNumber>
void extract_subvector_to (const std::vector<size_type> &indices,
std::vector<OtherNumber> &values) const;
/**
- * Just as the above, but with pointers.
- * Useful in minimizing copying of data around.
+ * Just as the above, but with pointers. Useful in minimizing copying of
+ * data around.
*/
template <typename ForwardIterator, typename OutputIterator>
void extract_subvector_to (ForwardIterator indices_begin,
Number local_element (const size_type local_index) const;
/**
- * Read and write access to the data field specified by @p
- * local_index. Locally owned indices can be accessed with indices
+ * Read and write access to the data field specified by @p local_index.
+ * Locally owned indices can be accessed with indices
* <code>[0,local_size)</code>, and ghost indices with indices
* <code>[local_size,local_size+n_ghosts]</code>.
*
#ifdef DEAL_II_WITH_MPI
/**
- * A vector that collects all requests from @p compress()
- * operations. This class uses persistent MPI communicators, i.e., the
- * communication channels are stored during successive calls to a given
- * function. This reduces the overhead involved with setting up the MPI
- * machinery, but it does not remove the need for a receive operation to
- * be posted before the data can actually be sent.
+ * A vector that collects all requests from @p compress() operations.
+ * This class uses persistent MPI communicators, i.e., the communication
+ * channels are stored during successive calls to a given function. This
+ * reduces the overhead involved with setting up the MPI machinery, but
+ * it does not remove the need for a receive operation to be posted
+ * before the data can actually be sent.
*/
std::vector<MPI_Request> compress_requests;
/**
- * Global function @p swap which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two vectors.
+ * Global function @p swap which overloads the default implementation of the
+ * C++ standard library which uses a temporary object. The function simply
+ * exchanges the data of the two vectors.
*
* @relates Vector
* @author Katharina Kormann, Martin Kronbichler, 2011
*/
/**
- * Blocked sparse matrix based on the PETScWrappers::SparseMatrix class. This
- * class implements the functions that are specific to the PETSc SparseMatrix
- * base objects for a blocked sparse matrix, and leaves the actual work
- * relaying most of the calls to the individual blocks to the functions
- * implemented in the base class. See there also for a description of when
- * this class is useful.
+ * Blocked sparse matrix based on the PETScWrappers::SparseMatrix class.
+ * This class implements the functions that are specific to the PETSc
+ * SparseMatrix base objects for a blocked sparse matrix, and leaves the
+ * actual work relaying most of the calls to the individual blocks to the
+ * functions implemented in the base class. See there also for a description
+ * of when this class is useful.
*
* In contrast to the deal.II-type SparseMatrix class, the PETSc matrices do
* not have external objects for the sparsity patterns. Thus, one does not
- * determine the size of the individual blocks of a block matrix of this type
- * by attaching a block sparsity pattern, but by calling reinit() to set the
- * number of blocks and then by setting the size of each block separately. In
- * order to fix the data structures of the block matrix, it is then necessary
- * to let it know that we have changed the sizes of the underlying
- * matrices. For this, one has to call the collect_sizes() function, for much
- * the same reason as is documented with the BlockSparsityPattern class.
+ * determine the size of the individual blocks of a block matrix of this
+ * type by attaching a block sparsity pattern, but by calling reinit() to
+ * set the number of blocks and then by setting the size of each block
+ * separately. In order to fix the data structures of the block matrix, it
+ * is then necessary to let it know that we have changed the sizes of the
+ * underlying matrices. For this, one has to call the collect_sizes()
+ * function, for much the same reason as is documented with the
+ * BlockSparsityPattern class.
*
- * @ingroup Matrix1
- * @see @ref GlossBlockLA "Block (linear algebra)"
+ * @ingroup Matrix1 @see @ref GlossBlockLA "Block (linear algebra)"
* @author Wolfgang Bangerth, 2004
*/
class BlockSparseMatrix : public BlockMatrixBase<PETScWrappers::SparseMatrix>
{
public:
/**
- * Typedef the base class for simpler
- * access to its own typedefs.
+ * Typedef the base class for simpler access to its own typedefs.
*/
typedef BlockMatrixBase<SparseMatrix> BaseClass;
/**
- * Typedef the type of the underlying
- * matrix.
+ * Typedef the type of the underlying matrix.
*/
typedef BaseClass::BlockType BlockType;
/**
- * Import the typedefs from the base
- * class.
+ * Import the typedefs from the base class.
*/
typedef BaseClass::value_type value_type;
typedef BaseClass::pointer pointer;
typedef BaseClass::const_iterator const_iterator;
/**
- * Constructor; initializes the
- * matrix to be empty, without
- * any structure, i.e. the
- * matrix is not usable at
- * all. This constructor is
- * therefore only useful for
- * matrices which are members of
- * a class. All other matrices
- * should be created at a point
- * in the data flow where all
- * necessary information is
- * available.
+ * Constructor; initializes the matrix to be empty, without any structure,
+ * i.e. the matrix is not usable at all. This constructor is therefore
+ * only useful for matrices which are members of a class. All other
+ * matrices should be created at a point in the data flow where all
+ * necessary information is available.
*
- * You have to initialize the
- * matrix before usage with
- * reinit(BlockSparsityPattern). The
- * number of blocks per row and
- * column are then determined by
- * that function.
+ * You have to initialize the matrix before usage with
+ * reinit(BlockSparsityPattern). The number of blocks per row and column
+ * are then determined by that function.
*/
BlockSparseMatrix ();
~BlockSparseMatrix ();
/**
- * Pseudo copy operator only copying
- * empty objects. The sizes of the block
+ * Pseudo copy operator only copying empty objects. The sizes of the block
* matrices need to be the same.
*/
BlockSparseMatrix &
operator = (const BlockSparseMatrix &);
/**
- * This operator assigns a scalar to a
- * matrix. Since this does usually not
- * make much sense (should we set all
- * matrix entries to this value? Only
- * the nonzero entries of the sparsity
- * pattern?), this operation is only
- * allowed if the actual value to be
- * assigned is zero. This operator only
- * exists to allow for the obvious
- * notation <tt>matrix=0</tt>, which
- * sets all elements of the matrix to
- * zero, but keep the sparsity pattern
+ * This operator assigns a scalar to a matrix. Since this does usually not
+ * make much sense (should we set all matrix entries to this value? Only
+ * the nonzero entries of the sparsity pattern?), this operation is only
+ * allowed if the actual value to be assigned is zero. This operator only
+ * exists to allow for the obvious notation <tt>matrix=0</tt>, which sets
+ * all elements of the matrix to zero, but keep the sparsity pattern
* previously used.
*/
BlockSparseMatrix &
operator = (const double d);
/**
- * Resize the matrix, by setting
- * the number of block rows and
- * columns. This deletes all
- * blocks and replaces them by
- * unitialized ones, i.e. ones
- * for which also the sizes are
- * not yet set. You have to do
- * that by calling the @p reinit
- * functions of the blocks
- * themselves. Do not forget to
- * call collect_sizes() after
- * that on this object.
+ * Resize the matrix, by setting the number of block rows and columns.
+ * This deletes all blocks and replaces them by unitialized ones, i.e.
+ * ones for which also the sizes are not yet set. You have to do that by
+ * calling the @p reinit functions of the blocks themselves. Do not forget
+ * to call collect_sizes() after that on this object.
*
- * The reason that you have to
- * set sizes of the blocks
- * yourself is that the sizes may
- * be varying, the maximum number
- * of elements per row may be
- * varying, etc. It is simpler
- * not to reproduce the interface
- * of the @p SparsityPattern
- * class here but rather let the
- * user call whatever function
- * she desires.
+ * The reason that you have to set sizes of the blocks yourself is that
+ * the sizes may be varying, the maximum number of elements per row may be
+ * varying, etc. It is simpler not to reproduce the interface of the @p
+ * SparsityPattern class here but rather let the user call whatever
+ * function she desires.
*/
void reinit (const size_type n_block_rows,
const size_type n_block_columns);
/**
- * This function collects the
- * sizes of the sub-objects and
- * stores them in internal
- * arrays, in order to be able to
- * relay global indices into the
- * matrix to indices into the
- * subobjects. You *must* call
- * this function each time after
- * you have changed the size of
- * the sub-objects.
+ * This function collects the sizes of the sub-objects and stores them in
+ * internal arrays, in order to be able to relay global indices into the
+ * matrix to indices into the subobjects. You *must* call this function
+ * each time after you have changed the size of the sub-objects.
*/
void collect_sizes ();
/**
- * Matrix-vector multiplication:
- * let $dst = M*src$ with $M$
- * being this matrix.
+ * Matrix-vector multiplication: let $dst = M*src$ with $M$ being this
+ * matrix.
*/
void vmult (BlockVector &dst,
const BlockVector &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block column.
+ * Matrix-vector multiplication. Just like the previous function, but only
+ * applicable if the matrix has only one block column.
*/
void vmult (BlockVector &dst,
const Vector &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block row.
+ * Matrix-vector multiplication. Just like the previous function, but only
+ * applicable if the matrix has only one block row.
*/
void vmult (Vector &dst,
const BlockVector &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block.
+ * Matrix-vector multiplication. Just like the previous function, but only
+ * applicable if the matrix has only one block.
*/
void vmult (Vector &dst,
const Vector &src) const;
/**
- * Matrix-vector multiplication:
- * let $dst = M^T*src$ with $M$
- * being this matrix. This
- * function does the same as
- * vmult() but takes the
- * transposed matrix.
+ * Matrix-vector multiplication: let $dst = M^T*src$ with $M$ being this
+ * matrix. This function does the same as vmult() but takes the transposed
+ * matrix.
*/
void Tvmult (BlockVector &dst,
const BlockVector &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block row.
+ * Matrix-vector multiplication. Just like the previous function, but only
+ * applicable if the matrix has only one block row.
*/
void Tvmult (BlockVector &dst,
const Vector &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block column.
+ * Matrix-vector multiplication. Just like the previous function, but only
+ * applicable if the matrix has only one block column.
*/
void Tvmult (Vector &dst,
const BlockVector &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block.
+ * Matrix-vector multiplication. Just like the previous function, but only
+ * applicable if the matrix has only one block.
*/
void Tvmult (Vector &dst,
const Vector &src) const;
/**
- * Make the clear() function in the
- * base class visible, though it is
+ * Make the clear() function in the base class visible, though it is
* protected.
*/
using BlockMatrixBase<SparseMatrix>::clear;
- /** @addtogroup Exceptions
+ /**
+ * @addtogroup Exceptions
* @{
*/
*/
/**
- * An implementation of block vectors based on the vector class implemented in
- * PETScWrappers. While the base class provides for most of the interface,
- * this class handles the actual allocation of vectors and provides functions
- * that are specific to the underlying vector type.
+ * An implementation of block vectors based on the vector class implemented
+ * in PETScWrappers. While the base class provides for most of the
+ * interface, this class handles the actual allocation of vectors and
+ * provides functions that are specific to the underlying vector type.
*
- * @ingroup Vectors
- * @see @ref GlossBlockLA "Block (linear algebra)"
+ * @ingroup Vectors @see @ref GlossBlockLA "Block (linear algebra)"
* @author Wolfgang Bangerth, 2004
*/
class BlockVector : public BlockVectorBase<Vector>
{
public:
/**
- * Typedef the base class for simpler
- * access to its own typedefs.
+ * Typedef the base class for simpler access to its own typedefs.
*/
typedef BlockVectorBase<Vector> BaseClass;
/**
- * Typedef the type of the underlying
- * vector.
+ * Typedef the type of the underlying vector.
*/
typedef BaseClass::BlockType BlockType;
/**
- * Import the typedefs from the base
- * class.
+ * Import the typedefs from the base class.
*/
typedef BaseClass::value_type value_type;
typedef BaseClass::pointer pointer;
typedef BaseClass::const_iterator const_iterator;
/**
- * Constructor. There are three
- * ways to use this
- * constructor. First, without
- * any arguments, it generates
- * an object with no
- * blocks. Given one argument,
- * it initializes <tt>num_blocks</tt>
- * blocks, but these blocks have
- * size zero. The third variant
- * finally initializes all
- * blocks to the same size
- * <tt>block_size</tt>.
+ * Constructor. There are three ways to use this constructor. First,
+ * without any arguments, it generates an object with no blocks. Given one
+ * argument, it initializes <tt>num_blocks</tt> blocks, but these blocks
+ * have size zero. The third variant finally initializes all blocks to the
+ * same size <tt>block_size</tt>.
*
- * Confer the other constructor
- * further down if you intend to
- * use blocks of different
- * sizes.
+ * Confer the other constructor further down if you intend to use blocks
+ * of different sizes.
*/
explicit BlockVector (const unsigned int num_blocks = 0,
const size_type block_size = 0);
/**
- * Copy-Constructor. Dimension set to
- * that of V, all components are copied
+ * Copy-Constructor. Dimension set to that of V, all components are copied
* from V
*/
BlockVector (const BlockVector &V);
/**
- * Copy-constructor: copy the values
- * from a PETSc wrapper parallel block
+ * Copy-constructor: copy the values from a PETSc wrapper parallel block
* vector class.
*
*
- * Note that due to the communication
- * model of MPI, @em all processes have
- * to actually perform this operation,
- * even if they do not use the
- * result. It is not sufficient if only
- * one processor tries to copy the
- * elements from the other processors
- * over to its own process space.
+ * Note that due to the communication model of MPI, @em all processes have
+ * to actually perform this operation, even if they do not use the result.
+ * It is not sufficient if only one processor tries to copy the elements
+ * from the other processors over to its own process space.
*/
explicit BlockVector (const MPI::BlockVector &v);
/**
- * Constructor. Set the number of
- * blocks to <tt>n.size()</tt> and
- * initialize each block with
- * <tt>n[i]</tt> zero elements.
+ * Constructor. Set the number of blocks to <tt>n.size()</tt> and
+ * initialize each block with <tt>n[i]</tt> zero elements.
*/
BlockVector (const std::vector<size_type> &n);
/**
- * Constructor. Set the number of
- * blocks to
- * <tt>n.size()</tt>. Initialize the
- * vector with the elements
- * pointed to by the range of
- * iterators given as second and
- * third argument. Apart from the
- * first argument, this
- * constructor is in complete
- * analogy to the respective
- * constructor of the
- * <tt>std::vector</tt> class, but the
- * first argument is needed in
- * order to know how to subdivide
- * the block vector into
- * different blocks.
+ * Constructor. Set the number of blocks to <tt>n.size()</tt>. Initialize
+ * the vector with the elements pointed to by the range of iterators given
+ * as second and third argument. Apart from the first argument, this
+ * constructor is in complete analogy to the respective constructor of the
+ * <tt>std::vector</tt> class, but the first argument is needed in order
+ * to know how to subdivide the block vector into different blocks.
*/
template <typename InputIterator>
BlockVector (const std::vector<size_type> &n,
~BlockVector ();
/**
- * Copy operator: fill all components of
- * the vector with the given scalar
+ * Copy operator: fill all components of the vector with the given scalar
* value.
*/
BlockVector &operator = (const value_type s);
/**
- * Copy operator for arguments of the
- * same type.
+ * Copy operator for arguments of the same type.
*/
BlockVector &
operator= (const BlockVector &V);
/**
- * Copy all the elements of the
- * parallel block vector @p v into this
- * local vector. Note that due to the
- * communication model of MPI, @em all
- * processes have to actually perform
- * this operation, even if they do not
- * use the result. It is not sufficient
- * if only one processor tries to copy
- * the elements from the other
- * processors over to its own process
+ * Copy all the elements of the parallel block vector @p v into this local
+ * vector. Note that due to the communication model of MPI, @em all
+ * processes have to actually perform this operation, even if they do not
+ * use the result. It is not sufficient if only one processor tries to
+ * copy the elements from the other processors over to its own process
* space.
*/
BlockVector &
operator = (const MPI::BlockVector &v);
/**
- * Reinitialize the BlockVector to
- * contain <tt>num_blocks</tt> blocks of
+ * Reinitialize the BlockVector to contain <tt>num_blocks</tt> blocks of
* size <tt>block_size</tt> each.
*
- * If <tt>fast==false</tt>, the vector
- * is filled with zeros.
+ * If <tt>fast==false</tt>, the vector is filled with zeros.
*/
void reinit (const unsigned int num_blocks,
const size_type block_size,
const bool fast = false);
/**
- * Reinitialize the BlockVector such
- * that it contains
- * <tt>block_sizes.size()</tt>
- * blocks. Each block is reinitialized
- * to dimension
- * <tt>block_sizes[i]</tt>.
+ * Reinitialize the BlockVector such that it contains
+ * <tt>block_sizes.size()</tt> blocks. Each block is reinitialized to
+ * dimension <tt>block_sizes[i]</tt>.
*
- * If the number of blocks is the
- * same as before this function
- * was called, all vectors remain
- * the same and reinit() is
- * called for each vector.
+ * If the number of blocks is the same as before this function was called,
+ * all vectors remain the same and reinit() is called for each vector.
*
- * If <tt>fast==false</tt>, the vector
- * is filled with zeros.
+ * If <tt>fast==false</tt>, the vector is filled with zeros.
*
- * Note that you must call this
- * (or the other reinit()
- * functions) function, rather
- * than calling the reinit()
- * functions of an individual
- * block, to allow the block
- * vector to update its caches of
- * vector sizes. If you call
- * reinit() on one of the
- * blocks, then subsequent
- * actions on this object may
- * yield unpredictable results
- * since they may be routed to
+ * Note that you must call this (or the other reinit() functions)
+ * function, rather than calling the reinit() functions of an individual
+ * block, to allow the block vector to update its caches of vector sizes.
+ * If you call reinit() on one of the blocks, then subsequent actions on
+ * this object may yield unpredictable results since they may be routed to
* the wrong block.
*/
void reinit (const std::vector<size_type> &N,
const bool fast=false);
/**
- * Change the dimension to that
- * of the vector <tt>V</tt>. The same
- * applies as for the other
- * reinit() function.
+ * Change the dimension to that of the vector <tt>V</tt>. The same applies
+ * as for the other reinit() function.
*
- * The elements of <tt>V</tt> are not
- * copied, i.e. this function is
- * the same as calling <tt>reinit
- * (V.size(), fast)</tt>.
+ * The elements of <tt>V</tt> are not copied, i.e. this function is the
+ * same as calling <tt>reinit (V.size(), fast)</tt>.
*
- * Note that you must call this
- * (or the other reinit()
- * functions) function, rather
- * than calling the reinit()
- * functions of an individual
- * block, to allow the block
- * vector to update its caches of
- * vector sizes. If you call
- * reinit() of one of the
- * blocks, then subsequent
- * actions of this object may
- * yield unpredictable results
- * since they may be routed to
+ * Note that you must call this (or the other reinit() functions)
+ * function, rather than calling the reinit() functions of an individual
+ * block, to allow the block vector to update its caches of vector sizes.
+ * If you call reinit() of one of the blocks, then subsequent actions of
+ * this object may yield unpredictable results since they may be routed to
* the wrong block.
*/
void reinit (const BlockVector &V,
const bool fast=false);
/**
- * Change the number of blocks to
- * <tt>num_blocks</tt>. The individual
- * blocks will get initialized with
- * zero size, so it is assumed that
- * the user resizes the
- * individual blocks by herself
- * in an appropriate way, and
- * calls <tt>collect_sizes</tt>
- * afterwards.
+ * Change the number of blocks to <tt>num_blocks</tt>. The individual
+ * blocks will get initialized with zero size, so it is assumed that the
+ * user resizes the individual blocks by herself in an appropriate way,
+ * and calls <tt>collect_sizes</tt> afterwards.
*/
void reinit (const unsigned int num_blocks);
/**
- * Swap the contents of this
- * vector and the other vector
- * <tt>v</tt>. One could do this
- * operation with a temporary
- * variable and copying over the
- * data elements, but this
- * function is significantly more
- * efficient since it only swaps
- * the pointers to the data of
- * the two vectors and therefore
- * does not need to allocate
- * temporary storage and move
- * data around.
+ * Swap the contents of this vector and the other vector <tt>v</tt>. One
+ * could do this operation with a temporary variable and copying over the
+ * data elements, but this function is significantly more efficient since
+ * it only swaps the pointers to the data of the two vectors and therefore
+ * does not need to allocate temporary storage and move data around.
*
- * Limitation: right now this
- * function only works if both
- * vectors have the same number
- * of blocks. If needed, the
- * numbers of blocks should be
+ * Limitation: right now this function only works if both vectors have the
+ * same number of blocks. If needed, the numbers of blocks should be
* exchanged, too.
*
- * This function is analog to the
- * the swap() function of all C++
- * standard containers. Also,
- * there is a global function
- * swap(u,v) that simply calls
- * <tt>u.swap(v)</tt>, again in analogy
- * to standard functions.
+ * This function is analog to the the swap() function of all C++ standard
+ * containers. Also, there is a global function swap(u,v) that simply
+ * calls <tt>u.swap(v)</tt>, again in analogy to standard functions.
*/
void swap (BlockVector &v);
const bool scientific = true,
const bool across = true) const;
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
/**
- * Global function which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two vectors.
+ * Global function which overloads the default implementation of the C++
+ * standard library which uses a temporary object. The function simply
+ * exchanges the data of the two vectors.
*
* @relates PETScWrappers::BlockVector
* @author Wolfgang Bangerth, 2000
/**
* Implementation of a sequential dense matrix class based on PETSC. All the
* functionality is actually in the base class, except for the calls to
- * generate a sequential dense matrix. This is possible since PETSc only works
- * on an abstract matrix type and internally distributes to functions that do
- * the actual work depending on the actual matrix type (much like using
- * virtual functions). Only the functions creating a matrix of specific type
- * differ, and are implemented in this particular class.
+ * generate a sequential dense matrix. This is possible since PETSc only
+ * works on an abstract matrix type and internally distributes to functions
+ * that do the actual work depending on the actual matrix type (much like
+ * using virtual functions). Only the functions creating a matrix of
+ * specific type differ, and are implemented in this particular class.
*
* @ingroup Matrix1
* @author Wolfgang Bangerth, 2004
/**
- * Throw away the present matrix and generate one that has the
- * same properties as if it were created by the constructor of
- * this class with the same argument list as the present function.
+ * Throw away the present matrix and generate one that has the same
+ * properties as if it were created by the constructor of this class with
+ * the same argument list as the present function.
*/
void reinit (const size_type m,
const size_type n);
/**
- * Return a reference to the MPI communicator object in use with
- * this matrix. Since this is a sequential matrix, it returns the
- * MPI_COMM_SELF communicator.
+ * Return a reference to the MPI communicator object in use with this
+ * matrix. Since this is a sequential matrix, it returns the MPI_COMM_SELF
+ * communicator.
*/
virtual const MPI_Comm &get_mpi_communicator () const;
/**
* Do the actual work for the respective reinit() function and the
- * matching constructor, i.e. create a matrix. Getting rid of the
- * previous matrix is left to the caller.
+ * matching constructor, i.e. create a matrix. Getting rid of the previous
+ * matrix is left to the caller.
*/
void do_reinit (const size_type m,
const size_type n);
namespace MatrixIterators
{
/**
- * STL conforming iterator. This class acts as an iterator walking over the
- * elements of PETSc matrices. Since PETSc offers a uniform interface for all
- * types of matrices, this iterator can be used to access both sparse and full
- * matrices.
+ * STL conforming iterator. This class acts as an iterator walking over
+ * the elements of PETSc matrices. Since PETSc offers a uniform interface
+ * for all types of matrices, this iterator can be used to access both
+ * sparse and full matrices.
*
- * Note that PETSc does not give any guarantees as to the order of elements
- * within each row. Note also that accessing the elements of a full matrix
- * surprisingly only shows the nonzero elements of the matrix, not all
- * elements.
+ * Note that PETSc does not give any guarantees as to the order of
+ * elements within each row. Note also that accessing the elements of a
+ * full matrix surprisingly only shows the nonzero elements of the matrix,
+ * not all elements.
*
* @ingroup PETScWrappers
* @author Guido Kanschat, Roy Stogner, Wolfgang Bangerth, 2004
typedef types::global_dof_index size_type;
/**
- * Constructor. Since we use
- * accessors only for read
- * access, a const matrix
- * pointer is sufficient.
+ * Constructor. Since we use accessors only for read access, a const
+ * matrix pointer is sufficient.
*/
Accessor (const MatrixBase *matrix,
const size_type row,
Accessor (const Accessor &a);
/**
- * Row number of the element
- * represented by this
- * object.
+ * Row number of the element represented by this object.
*/
size_type row() const;
/**
- * Index in row of the element
- * represented by this
- * object.
+ * Index in row of the element represented by this object.
*/
size_type index() const;
/**
- * Column number of the
- * element represented by
- * this object.
+ * Column number of the element represented by this object.
*/
size_type column() const;
size_type a_index;
/**
- * Cache where we store the
- * column indices of the present
- * row. This is necessary, since
- * PETSc makes access to the
- * elements of its matrices
- * rather hard, and it is much
- * more efficient to copy all
- * column entries of a row once
- * when we enter it than
- * repeatedly asking PETSc for
- * individual ones. This also
- * makes some sense since it is
- * likely that we will access
- * them sequentially anyway.
+ * Cache where we store the column indices of the present row. This is
+ * necessary, since PETSc makes access to the elements of its matrices
+ * rather hard, and it is much more efficient to copy all column
+ * entries of a row once when we enter it than repeatedly asking PETSc
+ * for individual ones. This also makes some sense since it is likely
+ * that we will access them sequentially anyway.
*
- * In order to make copying of
- * iterators/accessor of
- * acceptable performance, we
- * keep a shared pointer to these
- * entries so that more than one
- * accessor can access this data
- * if necessary.
+ * In order to make copying of iterators/accessor of acceptable
+ * performance, we keep a shared pointer to these entries so that more
+ * than one accessor can access this data if necessary.
*/
std_cxx11::shared_ptr<const std::vector<size_type> > colnum_cache;
/**
- * Similar cache for the values
- * of this row.
+ * Similar cache for the values of this row.
*/
std_cxx11::shared_ptr<const std::vector<PetscScalar> > value_cache;
/**
- * Discard the old row caches
- * (they may still be used by
- * other accessors) and generate
- * new ones for the row pointed
- * to presently by this accessor.
+ * Discard the old row caches (they may still be used by other
+ * accessors) and generate new ones for the row pointed to presently
+ * by this accessor.
*/
void visit_present_row ();
/**
- * Make enclosing class a
- * friend.
+ * Make enclosing class a friend.
*/
friend class const_iterator;
};
typedef types::global_dof_index size_type;
/**
- * Constructor. Create an iterator
- * into the matrix @p matrix for the
+ * Constructor. Create an iterator into the matrix @p matrix for the
* given row and the index within it.
*/
const_iterator (const MatrixBase *matrix,
const Accessor *operator-> () const;
/**
- * Comparison. True, if
- * both iterators point to
- * the same matrix
+ * Comparison. True, if both iterators point to the same matrix
* position.
*/
bool operator == (const const_iterator &) const;
bool operator != (const const_iterator &) const;
/**
- * Comparison
- * operator. Result is true
- * if either the first row
- * number is smaller or if
- * the row numbers are
- * equal and the first
- * index is smaller.
+ * Comparison operator. Result is true if either the first row number is
+ * smaller or if the row numbers are equal and the first index is
+ * smaller.
*/
bool operator < (const const_iterator &) const;
private:
/**
- * Store an object of the
- * accessor class.
+ * Store an object of the accessor class.
*/
Accessor accessor;
};
/**
- * Base class for all matrix classes that are implemented on top of the PETSc
- * matrix types. Since in PETSc all matrix types (i.e. sequential and
+ * Base class for all matrix classes that are implemented on top of the
+ * PETSc matrix types. Since in PETSc all matrix types (i.e. sequential and
* parallel, sparse, blocked, etc.) are built by filling the contents of an
- * abstract object that is only referenced through a pointer of a type that is
- * independent of the actual matrix type, we can implement almost all
- * functionality of matrices in this base class. Derived classes will then only
- * have to provide the functionality to create one or the other kind of
+ * abstract object that is only referenced through a pointer of a type that
+ * is independent of the actual matrix type, we can implement almost all
+ * functionality of matrices in this base class. Derived classes will then
+ * only have to provide the functionality to create one or the other kind of
* matrix.
*
- * The interface of this class is modeled after the existing
- * SparseMatrix class in deal.II. It has almost the same member
- * functions, and is often exchangable. However, since PETSc only supports a
- * single scalar type (either double, float, or a complex data type), it is
- * not templated, and only works with whatever your PETSc installation has
- * defined the data type PetscScalar to.
+ * The interface of this class is modeled after the existing SparseMatrix
+ * class in deal.II. It has almost the same member functions, and is often
+ * exchangable. However, since PETSc only supports a single scalar type
+ * (either double, float, or a complex data type), it is not templated, and
+ * only works with whatever your PETSc installation has defined the data
+ * type PetscScalar to.
*
* Note that PETSc only guarantees that operations do what you expect if the
* functions @p MatAssemblyBegin and @p MatAssemblyEnd have been called
{
public:
/**
- * Declare a typedef for the iterator
- * class.
+ * Declare a typedef for the iterator class.
*/
typedef MatrixIterators::const_iterator const_iterator;
typedef types::global_dof_index size_type;
/**
- * Declare a typedef in analogy to all
- * the other container classes.
+ * Declare a typedef in analogy to all the other container classes.
*/
typedef PetscScalar value_type;
MatrixBase ();
/**
- * Destructor. Made virtual so that one
- * can use pointers to this class.
+ * Destructor. Made virtual so that one can use pointers to this class.
*/
virtual ~MatrixBase ();
/**
- * This operator assigns a scalar to a
- * matrix. Since this does usually not
- * make much sense (should we set all
- * matrix entries to this value? Only
- * the nonzero entries of the sparsity
- * pattern?), this operation is only
- * allowed if the actual value to be
- * assigned is zero. This operator only
- * exists to allow for the obvious
- * notation <tt>matrix=0</tt>, which
- * sets all elements of the matrix to
- * zero, but keeps the sparsity pattern
+ * This operator assigns a scalar to a matrix. Since this does usually not
+ * make much sense (should we set all matrix entries to this value? Only
+ * the nonzero entries of the sparsity pattern?), this operation is only
+ * allowed if the actual value to be assigned is zero. This operator only
+ * exists to allow for the obvious notation <tt>matrix=0</tt>, which sets
+ * all elements of the matrix to zero, but keeps the sparsity pattern
* previously used.
*/
MatrixBase &
operator = (const value_type d);
/**
- * Release all memory and return
- * to a state just like after
- * having called the default
- * constructor.
+ * Release all memory and return to a state just like after having called
+ * the default constructor.
*/
void clear ();
/**
- * Set the element (<i>i,j</i>) to @p
- * value.
+ * Set the element (<i>i,j</i>) to @p value.
*
- * If the present object (from a
- * derived class of this one) happens
- * to be a sparse matrix, then this
- * function adds a new entry to the
- * matrix if it didn't exist before,
- * very much in contrast to the
- * SparseMatrix class which throws an
- * error if the entry does not exist.
- * If <tt>value</tt> is not a finite
- * number an exception is thrown.
+ * If the present object (from a derived class of this one) happens to be
+ * a sparse matrix, then this function adds a new entry to the matrix if
+ * it didn't exist before, very much in contrast to the SparseMatrix class
+ * which throws an error if the entry does not exist. If <tt>value</tt> is
+ * not a finite number an exception is thrown.
*/
void set (const size_type i,
const size_type j,
const PetscScalar value);
/**
- * Set all elements given in a
- * FullMatrix<double> into the sparse
- * matrix locations given by
- * <tt>indices</tt>. In other words,
- * this function writes the elements
- * in <tt>full_matrix</tt> into the
- * calling matrix, using the
- * local-to-global indexing specified
- * by <tt>indices</tt> for both the
- * rows and the columns of the
- * matrix. This function assumes a
- * quadratic sparse matrix and a
- * quadratic full_matrix, the usual
+ * Set all elements given in a FullMatrix<double> into the sparse matrix
+ * locations given by <tt>indices</tt>. In other words, this function
+ * writes the elements in <tt>full_matrix</tt> into the calling matrix,
+ * using the local-to-global indexing specified by <tt>indices</tt> for
+ * both the rows and the columns of the matrix. This function assumes a
+ * quadratic sparse matrix and a quadratic full_matrix, the usual
* situation in FE calculations.
*
- * If the present object (from a
- * derived class of this one) happens
- * to be a sparse matrix, then this
- * function adds some new entries to
- * the matrix if they didn't exist
- * before, very much in contrast to
- * the SparseMatrix class which
- * throws an error if the entry does
- * not exist.
+ * If the present object (from a derived class of this one) happens to be
+ * a sparse matrix, then this function adds some new entries to the matrix
+ * if they didn't exist before, very much in contrast to the SparseMatrix
+ * class which throws an error if the entry does not exist.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> can be
- * used to specify whether zero
- * values should be inserted anyway
- * or they should be filtered
- * away. The default value is
- * <tt>false</tt>, i.e., even zero
+ * The optional parameter <tt>elide_zero_values</tt> can be used to
+ * specify whether zero values should be inserted anyway or they should be
+ * filtered away. The default value is <tt>false</tt>, i.e., even zero
* values are inserted/replaced.
*/
void set (const std::vector<size_type> &indices,
const bool elide_zero_values = false);
/**
- * Same function as before, but now
- * including the possibility to use
- * rectangular full_matrices and
- * different local-to-global indexing
- * on rows and columns, respectively.
+ * Same function as before, but now including the possibility to use
+ * rectangular full_matrices and different local-to-global indexing on
+ * rows and columns, respectively.
*/
void set (const std::vector<size_type> &row_indices,
const std::vector<size_type> &col_indices,
const bool elide_zero_values = false);
/**
- * Set several elements in the
- * specified row of the matrix with
- * column indices as given by
- * <tt>col_indices</tt> to the
- * respective value.
+ * Set several elements in the specified row of the matrix with column
+ * indices as given by <tt>col_indices</tt> to the respective value.
*
- * If the present object (from a
- * derived class of this one) happens
- * to be a sparse matrix, then this
- * function adds some new entries to
- * the matrix if they didn't exist
- * before, very much in contrast to
- * the SparseMatrix class which
- * throws an error if the entry does
- * not exist.
+ * If the present object (from a derived class of this one) happens to be
+ * a sparse matrix, then this function adds some new entries to the matrix
+ * if they didn't exist before, very much in contrast to the SparseMatrix
+ * class which throws an error if the entry does not exist.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> can be
- * used to specify whether zero
- * values should be inserted anyway
- * or they should be filtered
- * away. The default value is
- * <tt>false</tt>, i.e., even zero
+ * The optional parameter <tt>elide_zero_values</tt> can be used to
+ * specify whether zero values should be inserted anyway or they should be
+ * filtered away. The default value is <tt>false</tt>, i.e., even zero
* values are inserted/replaced.
*/
void set (const size_type row,
const bool elide_zero_values = false);
/**
- * Set several elements to values
- * given by <tt>values</tt> in a
- * given row in columns given by
- * col_indices into the sparse
- * matrix.
+ * Set several elements to values given by <tt>values</tt> in a given row
+ * in columns given by col_indices into the sparse matrix.
*
- * If the present object (from a
- * derived class of this one) happens
- * to be a sparse matrix, then this
- * function adds some new entries to
- * the matrix if they didn't exist
- * before, very much in contrast to
- * the SparseMatrix class which
- * throws an error if the entry does
- * not exist.
+ * If the present object (from a derived class of this one) happens to be
+ * a sparse matrix, then this function adds some new entries to the matrix
+ * if they didn't exist before, very much in contrast to the SparseMatrix
+ * class which throws an error if the entry does not exist.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> can be
- * used to specify whether zero
- * values should be inserted anyway
- * or they should be filtered
- * away. The default value is
- * <tt>false</tt>, i.e., even zero
+ * The optional parameter <tt>elide_zero_values</tt> can be used to
+ * specify whether zero values should be inserted anyway or they should be
+ * filtered away. The default value is <tt>false</tt>, i.e., even zero
* values are inserted/replaced.
*/
void set (const size_type row,
const bool elide_zero_values = false);
/**
- * Add @p value to the element
- * (<i>i,j</i>).
+ * Add @p value to the element (<i>i,j</i>).
*
- * If the present object (from a
- * derived class of this one) happens
- * to be a sparse matrix, then this
- * function adds a new entry to the
- * matrix if it didn't exist before,
- * very much in contrast to the
- * SparseMatrix class which throws an
- * error if the entry does not exist.
- * If <tt>value</tt> is not a finite
- * number an exception is thrown.
+ * If the present object (from a derived class of this one) happens to be
+ * a sparse matrix, then this function adds a new entry to the matrix if
+ * it didn't exist before, very much in contrast to the SparseMatrix class
+ * which throws an error if the entry does not exist. If <tt>value</tt> is
+ * not a finite number an exception is thrown.
*/
void add (const size_type i,
const size_type j,
const PetscScalar value);
/**
- * Add all elements given in a
- * FullMatrix<double> into sparse
- * matrix locations given by
- * <tt>indices</tt>. In other words,
- * this function adds the elements in
- * <tt>full_matrix</tt> to the
- * respective entries in calling
- * matrix, using the local-to-global
- * indexing specified by
- * <tt>indices</tt> for both the rows
- * and the columns of the
- * matrix. This function assumes a
- * quadratic sparse matrix and a
- * quadratic full_matrix, the usual
- * situation in FE calculations.
+ * Add all elements given in a FullMatrix<double> into sparse matrix
+ * locations given by <tt>indices</tt>. In other words, this function adds
+ * the elements in <tt>full_matrix</tt> to the respective entries in
+ * calling matrix, using the local-to-global indexing specified by
+ * <tt>indices</tt> for both the rows and the columns of the matrix. This
+ * function assumes a quadratic sparse matrix and a quadratic full_matrix,
+ * the usual situation in FE calculations.
*
- * If the present object (from a
- * derived class of this one) happens
- * to be a sparse matrix, then this
- * function adds some new entries to
- * the matrix if they didn't exist
- * before, very much in contrast to
- * the SparseMatrix class which
- * throws an error if the entry does
- * not exist.
+ * If the present object (from a derived class of this one) happens to be
+ * a sparse matrix, then this function adds some new entries to the matrix
+ * if they didn't exist before, very much in contrast to the SparseMatrix
+ * class which throws an error if the entry does not exist.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> can be
- * used to specify whether zero
- * values should be added anyway or
- * these should be filtered away and
- * only non-zero data is added. The
- * default value is <tt>true</tt>,
- * i.e., zero values won't be added
- * into the matrix.
+ * The optional parameter <tt>elide_zero_values</tt> can be used to
+ * specify whether zero values should be added anyway or these should be
+ * filtered away and only non-zero data is added. The default value is
+ * <tt>true</tt>, i.e., zero values won't be added into the matrix.
*/
void add (const std::vector<size_type> &indices,
const FullMatrix<PetscScalar> &full_matrix,
const bool elide_zero_values = true);
/**
- * Same function as before, but now
- * including the possibility to use
- * rectangular full_matrices and
- * different local-to-global indexing
- * on rows and columns, respectively.
+ * Same function as before, but now including the possibility to use
+ * rectangular full_matrices and different local-to-global indexing on
+ * rows and columns, respectively.
*/
void add (const std::vector<size_type> &row_indices,
const std::vector<size_type> &col_indices,
const bool elide_zero_values = true);
/**
- * Set several elements in the
- * specified row of the matrix with
- * column indices as given by
- * <tt>col_indices</tt> to the
- * respective value.
+ * Set several elements in the specified row of the matrix with column
+ * indices as given by <tt>col_indices</tt> to the respective value.
*
- * If the present object (from a
- * derived class of this one) happens
- * to be a sparse matrix, then this
- * function adds some new entries to
- * the matrix if they didn't exist
- * before, very much in contrast to
- * the SparseMatrix class which
- * throws an error if the entry does
- * not exist.
+ * If the present object (from a derived class of this one) happens to be
+ * a sparse matrix, then this function adds some new entries to the matrix
+ * if they didn't exist before, very much in contrast to the SparseMatrix
+ * class which throws an error if the entry does not exist.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> can be
- * used to specify whether zero
- * values should be added anyway or
- * these should be filtered away and
- * only non-zero data is added. The
- * default value is <tt>true</tt>,
- * i.e., zero values won't be added
- * into the matrix.
+ * The optional parameter <tt>elide_zero_values</tt> can be used to
+ * specify whether zero values should be added anyway or these should be
+ * filtered away and only non-zero data is added. The default value is
+ * <tt>true</tt>, i.e., zero values won't be added into the matrix.
*/
void add (const size_type row,
const std::vector<size_type> &col_indices,
const bool elide_zero_values = true);
/**
- * Add an array of values given by
- * <tt>values</tt> in the given
- * global matrix row at columns
- * specified by col_indices in the
- * sparse matrix.
+ * Add an array of values given by <tt>values</tt> in the given global
+ * matrix row at columns specified by col_indices in the sparse matrix.
*
- * If the present object (from a
- * derived class of this one) happens
- * to be a sparse matrix, then this
- * function adds some new entries to
- * the matrix if they didn't exist
- * before, very much in contrast to
- * the SparseMatrix class which
- * throws an error if the entry does
- * not exist.
+ * If the present object (from a derived class of this one) happens to be
+ * a sparse matrix, then this function adds some new entries to the matrix
+ * if they didn't exist before, very much in contrast to the SparseMatrix
+ * class which throws an error if the entry does not exist.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> can be
- * used to specify whether zero
- * values should be added anyway or
- * these should be filtered away and
- * only non-zero data is added. The
- * default value is <tt>true</tt>,
- * i.e., zero values won't be added
- * into the matrix.
+ * The optional parameter <tt>elide_zero_values</tt> can be used to
+ * specify whether zero values should be added anyway or these should be
+ * filtered away and only non-zero data is added. The default value is
+ * <tt>true</tt>, i.e., zero values won't be added into the matrix.
*/
void add (const size_type row,
const size_type n_cols,
const bool col_indices_are_sorted = false);
/**
- * Remove all elements from
- * this <tt>row</tt> by setting
- * them to zero. The function
- * does not modify the number
- * of allocated nonzero
- * entries, it only sets some
- * entries to zero. It may drop
- * them from the sparsity
- * pattern, though (but retains
- * the allocated memory in case
- * new entries are again added
- * later).
+ * Remove all elements from this <tt>row</tt> by setting them to zero. The
+ * function does not modify the number of allocated nonzero entries, it
+ * only sets some entries to zero. It may drop them from the sparsity
+ * pattern, though (but retains the allocated memory in case new entries
+ * are again added later).
*
- * This operation is used in
- * eliminating constraints (e.g. due to
- * hanging nodes) and makes sure that
- * we can write this modification to
- * the matrix without having to read
- * entries (such as the locations of
- * non-zero elements) from it --
- * without this operation, removing
- * constraints on parallel matrices is
- * a rather complicated procedure.
+ * This operation is used in eliminating constraints (e.g. due to hanging
+ * nodes) and makes sure that we can write this modification to the matrix
+ * without having to read entries (such as the locations of non-zero
+ * elements) from it -- without this operation, removing constraints on
+ * parallel matrices is a rather complicated procedure.
*
- * The second parameter can be used to
- * set the diagonal entry of this row
- * to a value different from zero. The
- * default is to set it to zero.
+ * The second parameter can be used to set the diagonal entry of this row
+ * to a value different from zero. The default is to set it to zero.
*/
void clear_row (const size_type row,
const PetscScalar new_diag_value = 0);
/**
- * Same as clear_row(), except that it
- * works on a number of rows at once.
+ * Same as clear_row(), except that it works on a number of rows at once.
*
- * The second parameter can be used to
- * set the diagonal entries of all
- * cleared rows to something different
- * from zero. Note that all of these
- * diagonal entries get the same value
- * -- if you want different values for
- * the diagonal entries, you have to
- * set them by hand.
+ * The second parameter can be used to set the diagonal entries of all
+ * cleared rows to something different from zero. Note that all of these
+ * diagonal entries get the same value -- if you want different values for
+ * the diagonal entries, you have to set them by hand.
*/
void clear_rows (const std::vector<size_type> &rows,
const PetscScalar new_diag_value = 0);
/**
- * PETSc matrices store their own
- * sparsity patterns. So, in analogy to
- * our own SparsityPattern class,
- * this function compresses the
- * sparsity pattern and allows the
- * resulting matrix to be used in all
- * other operations where before only
- * assembly functions were
- * allowed. This function must
- * therefore be called once you have
- * assembled the matrix.
+ * PETSc matrices store their own sparsity patterns. So, in analogy to our
+ * own SparsityPattern class, this function compresses the sparsity
+ * pattern and allows the resulting matrix to be used in all other
+ * operations where before only assembly functions were allowed. This
+ * function must therefore be called once you have assembled the matrix.
*
- * See @ref GlossCompress "Compressing distributed objects"
- * for more information.
- * more information.
+ * See @ref GlossCompress "Compressing distributed objects" for more
+ * information. more information.
*/
void compress (::dealii::VectorOperation::values operation);
void compress () DEAL_II_DEPRECATED;
/**
- * Return the value of the entry
- * (<i>i,j</i>). This may be an
- * expensive operation and you should
- * always take care where to call this
- * function. In contrast to the
- * respective function in the
- * @p MatrixBase class, we don't
- * throw an exception if the respective
- * entry doesn't exist in the sparsity
- * pattern of this class, since PETSc
- * does not transmit this information.
+ * Return the value of the entry (<i>i,j</i>). This may be an expensive
+ * operation and you should always take care where to call this function.
+ * In contrast to the respective function in the @p MatrixBase class, we
+ * don't throw an exception if the respective entry doesn't exist in the
+ * sparsity pattern of this class, since PETSc does not transmit this
+ * information.
*
- * This function is therefore exactly
- * equivalent to the <tt>el()</tt> function.
+ * This function is therefore exactly equivalent to the <tt>el()</tt>
+ * function.
*/
PetscScalar operator () (const size_type i,
const size_type j) const;
/**
- * Return the value of the matrix entry
- * (<i>i,j</i>). If this entry does not
- * exist in the sparsity pattern, then
- * zero is returned. While this may be
- * convenient in some cases, note that
- * it is simple to write algorithms
- * that are slow compared to an optimal
- * solution, since the sparsity of the
- * matrix is not used.
+ * Return the value of the matrix entry (<i>i,j</i>). If this entry does
+ * not exist in the sparsity pattern, then zero is returned. While this
+ * may be convenient in some cases, note that it is simple to write
+ * algorithms that are slow compared to an optimal solution, since the
+ * sparsity of the matrix is not used.
*/
PetscScalar el (const size_type i,
const size_type j) const;
/**
- * Return the main diagonal
- * element in the <i>i</i>th
- * row. This function throws an
- * error if the matrix is not
- * quadratic.
+ * Return the main diagonal element in the <i>i</i>th row. This function
+ * throws an error if the matrix is not quadratic.
*
- * Since we do not have direct access
- * to the underlying data structure,
- * this function is no faster than the
- * elementwise access using the el()
- * function. However, we provide this
- * function for compatibility with the
+ * Since we do not have direct access to the underlying data structure,
+ * this function is no faster than the elementwise access using the el()
+ * function. However, we provide this function for compatibility with the
* SparseMatrix class.
*/
PetscScalar diag_element (const size_type i) const;
/**
- * Return the number of rows in this
- * matrix.
+ * Return the number of rows in this matrix.
*/
size_type m () const;
/**
- * Return the number of columns in this
- * matrix.
+ * Return the number of columns in this matrix.
*/
size_type n () const;
/**
- * Return the local dimension of the
- * matrix, i.e. the number of rows
- * stored on the present MPI
- * process. For sequential matrices,
- * this number is the same as m(),
- * but for parallel matrices it may be
- * smaller.
+ * Return the local dimension of the matrix, i.e. the number of rows
+ * stored on the present MPI process. For sequential matrices, this number
+ * is the same as m(), but for parallel matrices it may be smaller.
*
- * To figure out which elements
- * exactly are stored locally,
- * use local_range().
+ * To figure out which elements exactly are stored locally, use
+ * local_range().
*/
size_type local_size () const;
/**
- * Return a pair of indices
- * indicating which rows of
- * this matrix are stored
- * locally. The first number is
- * the index of the first
- * row stored, the second
- * the index of the one past
- * the last one that is stored
- * locally. If this is a
- * sequential matrix, then the
- * result will be the pair
- * (0,m()), otherwise it will be
- * a pair (i,i+n), where
+ * Return a pair of indices indicating which rows of this matrix are
+ * stored locally. The first number is the index of the first row stored,
+ * the second the index of the one past the last one that is stored
+ * locally. If this is a sequential matrix, then the result will be the
+ * pair (0,m()), otherwise it will be a pair (i,i+n), where
* <tt>n=local_size()</tt>.
*/
std::pair<size_type, size_type>
local_range () const;
/**
- * Return whether @p index is
- * in the local range or not,
- * see also local_range().
+ * Return whether @p index is in the local range or not, see also
+ * local_range().
*/
bool in_local_range (const size_type index) const;
/**
- * Return a reference to the MPI
- * communicator object in use with this
- * matrix. This function has to be
- * implemented in derived classes.
+ * Return a reference to the MPI communicator object in use with this
+ * matrix. This function has to be implemented in derived classes.
*/
virtual const MPI_Comm &get_mpi_communicator () const = 0;
/**
- * Return the number of nonzero
- * elements of this
- * matrix. Actually, it returns
- * the number of entries in the
- * sparsity pattern; if any of
- * the entries should happen to
- * be zero, it is counted anyway.
+ * Return the number of nonzero elements of this matrix. Actually, it
+ * returns the number of entries in the sparsity pattern; if any of the
+ * entries should happen to be zero, it is counted anyway.
*/
size_type n_nonzero_elements () const;
size_type row_length (const size_type row) const;
/**
- * Return the l1-norm of the matrix, that is
- * $|M|_1=max_{all columns j}\sum_{all
- * rows i} |M_ij|$,
- * (max. sum of columns).
- * This is the
- * natural matrix norm that is compatible
- * to the l1-norm for vectors, i.e.
- * $|Mv|_1\leq |M|_1 |v|_1$.
- * (cf. Haemmerlin-Hoffmann:
- * Numerische Mathematik)
+ * Return the l1-norm of the matrix, that is $|M|_1=max_{all columns
+ * j}\sum_{all rows i} |M_ij|$, (max. sum of columns). This is the natural
+ * matrix norm that is compatible to the l1-norm for vectors, i.e.
+ * $|Mv|_1\leq |M|_1 |v|_1$. (cf. Haemmerlin-Hoffmann: Numerische
+ * Mathematik)
*/
PetscReal l1_norm () const;
/**
- * Return the linfty-norm of the
- * matrix, that is
- * $|M|_infty=max_{all rows i}\sum_{all
- * columns j} |M_ij|$,
- * (max. sum of rows).
- * This is the
- * natural matrix norm that is compatible
- * to the linfty-norm of vectors, i.e.
- * $|Mv|_infty \leq |M|_infty |v|_infty$.
- * (cf. Haemmerlin-Hoffmann:
+ * Return the linfty-norm of the matrix, that is $|M|_infty=max_{all rows
+ * i}\sum_{all columns j} |M_ij|$, (max. sum of rows). This is the natural
+ * matrix norm that is compatible to the linfty-norm of vectors, i.e.
+ * $|Mv|_infty \leq |M|_infty |v|_infty$. (cf. Haemmerlin-Hoffmann:
* Numerische Mathematik)
*/
PetscReal linfty_norm () const;
/**
- * Return the frobenius norm of the
- * matrix, i.e. the square root of the
- * sum of squares of all entries in the
- * matrix.
+ * Return the frobenius norm of the matrix, i.e. the square root of the
+ * sum of squares of all entries in the matrix.
*/
PetscReal frobenius_norm () const;
/**
- * Return the square of the norm
- * of the vector $v$ with respect
- * to the norm induced by this
- * matrix,
- * i.e. $\left(v,Mv\right)$. This
- * is useful, e.g. in the finite
- * element context, where the
- * $L_2$ norm of a function
- * equals the matrix norm with
- * respect to the mass matrix of
- * the vector representing the
- * nodal values of the finite
- * element function.
+ * Return the square of the norm of the vector $v$ with respect to the
+ * norm induced by this matrix, i.e. $\left(v,Mv\right)$. This is useful,
+ * e.g. in the finite element context, where the $L_2$ norm of a function
+ * equals the matrix norm with respect to the mass matrix of the vector
+ * representing the nodal values of the finite element function.
*
- * Obviously, the matrix needs to
- * be quadratic for this operation.
+ * Obviously, the matrix needs to be quadratic for this operation.
*
- * The implementation of this function
- * is not as efficient as the one in
- * the @p MatrixBase class used in
- * deal.II (i.e. the original one, not
- * the PETSc wrapper class) since PETSc
- * doesn't support this operation and
+ * The implementation of this function is not as efficient as the one in
+ * the @p MatrixBase class used in deal.II (i.e. the original one, not the
+ * PETSc wrapper class) since PETSc doesn't support this operation and
* needs a temporary vector.
*
- * Note that if the current object
- * represents a parallel distributed
- * matrix (of type
- * PETScWrappers::MPI::SparseMatrix),
- * then the given vector has to be
- * a distributed vector as
- * well. Conversely, if the matrix is
- * not distributed, then neither
- * may the vector be.
+ * Note that if the current object represents a parallel distributed
+ * matrix (of type PETScWrappers::MPI::SparseMatrix), then the given
+ * vector has to be a distributed vector as well. Conversely, if the
+ * matrix is not distributed, then neither may the vector be.
*/
PetscScalar matrix_norm_square (const VectorBase &v) const;
/**
- * Compute the matrix scalar
- * product $\left(u,Mv\right)$.
+ * Compute the matrix scalar product $\left(u,Mv\right)$.
*
- * The implementation of this function
- * is not as efficient as the one in
- * the @p MatrixBase class used in
- * deal.II (i.e. the original one, not
- * the PETSc wrapper class) since PETSc
- * doesn't support this operation and
+ * The implementation of this function is not as efficient as the one in
+ * the @p MatrixBase class used in deal.II (i.e. the original one, not the
+ * PETSc wrapper class) since PETSc doesn't support this operation and
* needs a temporary vector.
*
- * Note that if the current object
- * represents a parallel distributed
- * matrix (of type
- * PETScWrappers::MPI::SparseMatrix),
- * then both vectors have to be
- * distributed vectors as
- * well. Conversely, if the matrix is
- * not distributed, then neither of the
- * vectors may be.
+ * Note that if the current object represents a parallel distributed
+ * matrix (of type PETScWrappers::MPI::SparseMatrix), then both vectors
+ * have to be distributed vectors as well. Conversely, if the matrix is
+ * not distributed, then neither of the vectors may be.
*/
PetscScalar matrix_scalar_product (const VectorBase &u,
const VectorBase &v) const;
#if DEAL_II_PETSC_VERSION_GTE(3,1,0)
/**
- * Return the trace of the
- * matrix, i.e. the sum of all
- * diagonal entries in the
- * matrix.
+ * Return the trace of the matrix, i.e. the sum of all diagonal entries in
+ * the matrix.
*/
PetscScalar trace () const;
#endif
/**
- * Multiply the entire matrix by a
- * fixed factor.
+ * Multiply the entire matrix by a fixed factor.
*/
MatrixBase &operator *= (const PetscScalar factor);
/**
- * Divide the entire matrix by a
- * fixed factor.
+ * Divide the entire matrix by a fixed factor.
*/
MatrixBase &operator /= (const PetscScalar factor);
const PetscScalar factor);
/**
- * Matrix-vector multiplication:
- * let <i>dst = M*src</i> with
- * <i>M</i> being this matrix.
+ * Matrix-vector multiplication: let <i>dst = M*src</i> with <i>M</i>
+ * being this matrix.
*
- * Source and destination must
- * not be the same vector.
+ * Source and destination must not be the same vector.
*
- * Note that if the current object
- * represents a parallel distributed
- * matrix (of type
- * PETScWrappers::MPI::SparseMatrix),
- * then both vectors have to be
- * distributed vectors as
- * well. Conversely, if the matrix is
- * not distributed, then neither of the
- * vectors may be.
+ * Note that if the current object represents a parallel distributed
+ * matrix (of type PETScWrappers::MPI::SparseMatrix), then both vectors
+ * have to be distributed vectors as well. Conversely, if the matrix is
+ * not distributed, then neither of the vectors may be.
*/
void vmult (VectorBase &dst,
const VectorBase &src) const;
/**
- * Matrix-vector multiplication: let
- * <i>dst = M<sup>T</sup>*src</i> with
- * <i>M</i> being this matrix. This
- * function does the same as vmult()
- * but takes the transposed matrix.
+ * Matrix-vector multiplication: let <i>dst = M<sup>T</sup>*src</i> with
+ * <i>M</i> being this matrix. This function does the same as vmult() but
+ * takes the transposed matrix.
*
- * Source and destination must
- * not be the same vector.
+ * Source and destination must not be the same vector.
*
- * Note that if the current object
- * represents a parallel distributed
- * matrix (of type
- * PETScWrappers::MPI::SparseMatrix),
- * then both vectors have to be
- * distributed vectors as
- * well. Conversely, if the matrix is
- * not distributed, then neither of the
- * vectors may be.
+ * Note that if the current object represents a parallel distributed
+ * matrix (of type PETScWrappers::MPI::SparseMatrix), then both vectors
+ * have to be distributed vectors as well. Conversely, if the matrix is
+ * not distributed, then neither of the vectors may be.
*/
void Tvmult (VectorBase &dst,
const VectorBase &src) const;
/**
- * Adding Matrix-vector
- * multiplication. Add
- * <i>M*src</i> on <i>dst</i>
- * with <i>M</i> being this
- * matrix.
+ * Adding Matrix-vector multiplication. Add <i>M*src</i> on <i>dst</i>
+ * with <i>M</i> being this matrix.
*
- * Source and destination must
- * not be the same vector.
+ * Source and destination must not be the same vector.
*
- * Note that if the current object
- * represents a parallel distributed
- * matrix (of type
- * PETScWrappers::MPI::SparseMatrix),
- * then both vectors have to be
- * distributed vectors as
- * well. Conversely, if the matrix is
- * not distributed, then neither of the
- * vectors may be.
+ * Note that if the current object represents a parallel distributed
+ * matrix (of type PETScWrappers::MPI::SparseMatrix), then both vectors
+ * have to be distributed vectors as well. Conversely, if the matrix is
+ * not distributed, then neither of the vectors may be.
*/
void vmult_add (VectorBase &dst,
const VectorBase &src) const;
/**
- * Adding Matrix-vector
- * multiplication. Add
- * <i>M<sup>T</sup>*src</i> to
- * <i>dst</i> with <i>M</i> being
- * this matrix. This function
- * does the same as vmult_add()
- * but takes the transposed
- * matrix.
+ * Adding Matrix-vector multiplication. Add <i>M<sup>T</sup>*src</i> to
+ * <i>dst</i> with <i>M</i> being this matrix. This function does the same
+ * as vmult_add() but takes the transposed matrix.
*
- * Source and destination must
- * not be the same vector.
+ * Source and destination must not be the same vector.
*
- * Note that if the current object
- * represents a parallel distributed
- * matrix (of type
- * PETScWrappers::MPI::SparseMatrix),
- * then both vectors have to be
- * distributed vectors as
- * well. Conversely, if the matrix is
- * not distributed, then neither of the
- * vectors may be.
+ * Note that if the current object represents a parallel distributed
+ * matrix (of type PETScWrappers::MPI::SparseMatrix), then both vectors
+ * have to be distributed vectors as well. Conversely, if the matrix is
+ * not distributed, then neither of the vectors may be.
*/
void Tvmult_add (VectorBase &dst,
const VectorBase &src) const;
/**
- * Compute the residual of an
- * equation <i>Mx=b</i>, where
- * the residual is defined to be
- * <i>r=b-Mx</i>. Write the
- * residual into
- * @p dst. The
- * <i>l<sub>2</sub></i> norm of
- * the residual vector is
- * returned.
+ * Compute the residual of an equation <i>Mx=b</i>, where the residual is
+ * defined to be <i>r=b-Mx</i>. Write the residual into @p dst. The
+ * <i>l<sub>2</sub></i> norm of the residual vector is returned.
*
- * Source <i>x</i> and destination
- * <i>dst</i> must not be the same
- * vector.
+ * Source <i>x</i> and destination <i>dst</i> must not be the same vector.
*
- * Note that if the current object
- * represents a parallel distributed
- * matrix (of type
- * PETScWrappers::MPI::SparseMatrix),
- * then all vectors have to be
- * distributed vectors as
- * well. Conversely, if the matrix is
- * not distributed, then neither of the
- * vectors may be.
+ * Note that if the current object represents a parallel distributed
+ * matrix (of type PETScWrappers::MPI::SparseMatrix), then all vectors
+ * have to be distributed vectors as well. Conversely, if the matrix is
+ * not distributed, then neither of the vectors may be.
*/
PetscScalar residual (VectorBase &dst,
const VectorBase &x,
const VectorBase &b) const;
/**
- * STL-like iterator with the
- * first entry.
+ * STL-like iterator with the first entry.
*/
const_iterator begin () const;
const_iterator end () const;
/**
- * STL-like iterator with the
- * first entry of row @p r.
+ * STL-like iterator with the first entry of row @p r.
*
- * Note that if the given row is empty,
- * i.e. does not contain any nonzero
- * entries, then the iterator returned by
- * this function equals
- * <tt>end(r)</tt>. Note also that the
- * iterator may not be dereferencable in
- * that case.
+ * Note that if the given row is empty, i.e. does not contain any nonzero
+ * entries, then the iterator returned by this function equals
+ * <tt>end(r)</tt>. Note also that the iterator may not be dereferencable
+ * in that case.
*/
const_iterator begin (const size_type r) const;
/**
- * Final iterator of row <tt>r</tt>. It
- * points to the first element past the
- * end of line @p r, or past the end of
- * the entire sparsity pattern.
+ * Final iterator of row <tt>r</tt>. It points to the first element past
+ * the end of line @p r, or past the end of the entire sparsity pattern.
*
- * Note that the end iterator is not
- * necessarily dereferencable. This is in
- * particular the case if it is the end
- * iterator for the last row of a matrix.
+ * Note that the end iterator is not necessarily dereferencable. This is
+ * in particular the case if it is the end iterator for the last row of a
+ * matrix.
*/
const_iterator end (const size_type r) const;
/**
- * Conversion operator to gain access
- * to the underlying PETSc type. If you
- * do this, you cut this class off some
- * information it may need, so this
- * conversion operator should only be
- * used if you know what you do. In
- * particular, it should only be used
- * for read-only operations into the
+ * Conversion operator to gain access to the underlying PETSc type. If you
+ * do this, you cut this class off some information it may need, so this
+ * conversion operator should only be used if you know what you do. In
+ * particular, it should only be used for read-only operations into the
* matrix.
*/
operator Mat () const;
/**
- * Make an in-place transpose of a
- * matrix.
+ * Make an in-place transpose of a matrix.
*/
void transpose ();
/**
- * Test whether a matrix is
- * symmetric. Default
- * tolerance is
- * $1000\times32$-bit machine
- * precision.
+ * Test whether a matrix is symmetric. Default tolerance is
+ * $1000\times32$-bit machine precision.
*/
#if DEAL_II_PETSC_VERSION_LT(3,2,0)
PetscTruth
is_symmetric (const double tolerance = 1.e-12);
/**
- * Test whether a matrix is
- * Hermitian, i.e. it is the
- * complex conjugate of its
- * transpose. Default
- * tolerance is
- * $1000\times32$-bit machine
+ * Test whether a matrix is Hermitian, i.e. it is the complex conjugate of
+ * its transpose. Default tolerance is $1000\times32$-bit machine
* precision.
*/
#if DEAL_II_PETSC_VERSION_LT(3,2,0)
is_hermitian (const double tolerance = 1.e-12);
/**
- * Prints the PETSc matrix object values
- * using PETSc internal matrix viewer function
- * <tt>MatView</tt>. The default format prints
- * the non-zero matrix elements. For other valid
- * view formats, consult
- * http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatView.html
+ * Prints the PETSc matrix object values using PETSc internal matrix
+ * viewer function <tt>MatView</tt>. The default format prints the non-
+ * zero matrix elements. For other valid view formats, consult
+ * http://www.mcs.anl.gov/petsc/petsc-
+ * current/docs/manualpages/Mat/MatView.html
*/
void write_ascii (const PetscViewerFormat format = PETSC_VIEWER_DEFAULT);
/**
- * print command, similar to write_ascii, but the same format as
- * produced by Trilinos
+ * print command, similar to write_ascii, but the same format as produced
+ * by Trilinos
*/
void print (std::ostream &out,
const bool alternative_output = false) const;
/**
- * Returns the number bytes consumed
- * by this matrix on this CPU.
+ * Returns the number bytes consumed by this matrix on this CPU.
*/
std::size_t memory_consumption() const;
DeclException0 (ExcSourceEqualsDestination);
/**
- * Exception.
- */
+ * Exception.
+ */
DeclException2 (ExcWrongMode,
int, int,
<< "You tried to do a "
protected:
/**
- * A generic matrix object in
- * PETSc. The actual type, a sparse
- * matrix, is set in the constructor.
+ * A generic matrix object in PETSc. The actual type, a sparse matrix, is
+ * set in the constructor.
*/
Mat matrix;
/**
- * PETSc doesn't allow to mix additions
- * to matrix entries and overwriting
- * them (to make synchronisation of
- * parallel computations
- * simpler). Since the interface of the
- * existing classes don't support the
- * notion of not interleaving things,
- * we have to emulate this
- * ourselves. The way we do it is to,
- * for each access operation, store
- * whether it is an insertion or an
- * addition. If the previous one was of
- * different type, then we first have
- * to flush the PETSc buffers;
- * otherwise, we can simply go on.
+ * PETSc doesn't allow to mix additions to matrix entries and overwriting
+ * them (to make synchronisation of parallel computations simpler). Since
+ * the interface of the existing classes don't support the notion of not
+ * interleaving things, we have to emulate this ourselves. The way we do
+ * it is to, for each access operation, store whether it is an insertion
+ * or an addition. If the previous one was of different type, then we
+ * first have to flush the PETSc buffers; otherwise, we can simply go on.
*
- * The following structure and variable
- * declare and store the previous
+ * The following structure and variable declare and store the previous
* state.
*/
struct LastAction
};
/**
- * Store whether the last action was a
- * write or add operation.
+ * Store whether the last action was a write or add operation.
*/
LastAction::Values last_action;
/**
- * Ensure that the add/set mode that
- * is required for actions following
- * this call is compatible with the
- * current mode.
- * Should be called from all internal
- * functions accessing matrix elements.
+ * Ensure that the add/set mode that is required for actions following
+ * this call is compatible with the current mode. Should be called from
+ * all internal functions accessing matrix elements.
*/
void prepare_action(const LastAction::Values new_action);
/**
- * For some matrix storage
- * formats, in particular for the
- * PETSc distributed blockmatrices,
- * set and add operations on
- * individual elements can not be
- * freely mixed. Rather, one has
- * to synchronize operations when
- * one wants to switch from
- * setting elements to adding to
- * elements.
- * BlockMatrixBase automatically
- * synchronizes the access by
- * calling this helper function
- * for each block.
- * This function ensures that the
- * matrix is in a state that
- * allows adding elements; if it
- * previously already was in this
- * state, the function does
- * nothing.
+ * For some matrix storage formats, in particular for the PETSc
+ * distributed blockmatrices, set and add operations on individual
+ * elements can not be freely mixed. Rather, one has to synchronize
+ * operations when one wants to switch from setting elements to adding to
+ * elements. BlockMatrixBase automatically synchronizes the access by
+ * calling this helper function for each block. This function ensures that
+ * the matrix is in a state that allows adding elements; if it previously
+ * already was in this state, the function does nothing.
*/
void prepare_add();
/**
- * Same as prepare_add() but
- * prepare the matrix for setting
- * elements if the representation
- * of elements in this class
- * requires such an operation.
+ * Same as prepare_add() but prepare the matrix for setting elements if
+ * the representation of elements in this class requires such an
+ * operation.
*/
void prepare_set();
MatrixBase &operator=(const MatrixBase &);
/**
- * An internal array of integer
- * values that is used to store the
- * column indices when
- * adding/inserting local data into
- * the (large) sparse matrix.
+ * An internal array of integer values that is used to store the column
+ * indices when adding/inserting local data into the (large) sparse
+ * matrix.
*/
std::vector<PetscInt> column_indices;
/**
- * An internal array of double values
- * that is used to store the column
- * indices when adding/inserting
- * local data into the (large) sparse
+ * An internal array of double values that is used to store the column
+ * indices when adding/inserting local data into the (large) sparse
* matrix.
*/
std::vector<PetscScalar> column_values;
/**
- * To allow calling protected
- * prepare_add() and
- * prepare_set().
+ * To allow calling protected prepare_add() and prepare_set().
*/
template <class> friend class dealii::BlockMatrixBase;
};
namespace PETScWrappers
{
/**
- * Implementation of a parallel matrix class based on PETSc <tt>MatShell</tt> matrix-type.
- * This base class implements only the interface to the PETSc matrix object,
- * while all the functionality is contained in the matrix-vector
- * multiplication which must be reimplemented in derived classes.
+ * Implementation of a parallel matrix class based on PETSc
+ * <tt>MatShell</tt> matrix-type. This base class implements only the
+ * interface to the PETSc matrix object, while all the functionality is
+ * contained in the matrix-vector multiplication which must be reimplemented
+ * in derived classes.
*
* This interface is an addition to the dealii::MatrixFree class to realize
- * user-defined matrix-classes together with PETSc solvers and functionalities.
- * See also the documentation of dealii::MatrixFree class and step-37 and step-48.
+ * user-defined matrix-classes together with PETSc solvers and
+ * functionalities. See also the documentation of dealii::MatrixFree class
+ * and step-37 and step-48.
*
- * Similar to other matrix classes in namespaces PETScWrappers and PETScWrappers::MPI,
- * the MatrixFree class provides the usual matrix-vector multiplication
- * <tt>vmult(VectorBase &dst, const VectorBase &src)</tt>
+ * Similar to other matrix classes in namespaces PETScWrappers and
+ * PETScWrappers::MPI, the MatrixFree class provides the usual matrix-vector
+ * multiplication <tt>vmult(VectorBase &dst, const VectorBase &src)</tt>
* which is pure virtual and must be reimplemented in derived classes.
- * Besides the usual interface, this class has a matrix-vector multiplication
- * <tt>vmult(Vec &dst, const Vec &src)</tt>
- * taking PETSc Vec objects, which will be called by
- * <tt>matrix_free_mult(Mat A, Vec src, Vec dst)</tt>
- * registered as matrix-vector multiplication of this PETSc matrix object.
- * The default implementation of the vmult function in the base class translates
- * the given PETSc <tt>Vec*</tt> vectors into a deal.II vector, calls
- * the usual vmult function with the usual interface and converts
- * the result back to PETSc <tt>Vec*</tt>. This could be made much more efficient
- * in derived classes without allocating new memory.
+ * Besides the usual interface, this class has a matrix-vector
+ * multiplication <tt>vmult(Vec &dst, const Vec &src)</tt> taking PETSc
+ * Vec objects, which will be called by <tt>matrix_free_mult(Mat A, Vec src,
+ * Vec dst)</tt> registered as matrix-vector multiplication of this PETSc
+ * matrix object. The default implementation of the vmult function in the
+ * base class translates the given PETSc <tt>Vec*</tt> vectors into a
+ * deal.II vector, calls the usual vmult function with the usual interface
+ * and converts the result back to PETSc <tt>Vec*</tt>. This could be made
+ * much more efficient in derived classes without allocating new memory.
*
* @ingroup PETScWrappers
* @ingroup Matrix1
public:
/**
- * Default constructor. Create an
- * empty matrix object.
+ * Default constructor. Create an empty matrix object.
*/
MatrixFree ();
/**
- * Create a matrix object of
- * dimensions @p m times @p n
- * with communication happening
- * over the provided @p communicator.
+ * Create a matrix object of dimensions @p m times @p n with communication
+ * happening over the provided @p communicator.
*
- * For the meaning of the @p local_rows
- * and @p local_columns parameters,
- * see the PETScWrappers::MPI::SparseMatrix
- * class documentation.
+ * For the meaning of the @p local_rows and @p local_columns parameters,
+ * see the PETScWrappers::MPI::SparseMatrix class documentation.
*
- * As other PETSc matrices, also the
- * the matrix-free object needs to
- * have a size and to perform matrix
- * vector multiplications efficiently
- * in parallel also @p local_rows
- * and @p local_columns. But in contrast
- * to PETSc::SparseMatrix classes a
- * PETSc matrix-free object does not need
- * any estimation of non_zero entries
- * and has no option <tt>is_symmetric</tt>.
+ * As other PETSc matrices, also the the matrix-free object needs to have
+ * a size and to perform matrix vector multiplications efficiently in
+ * parallel also @p local_rows and @p local_columns. But in contrast to
+ * PETSc::SparseMatrix classes a PETSc matrix-free object does not need
+ * any estimation of non_zero entries and has no option
+ * <tt>is_symmetric</tt>.
*/
MatrixFree (const MPI_Comm &communicator,
const unsigned int m,
const unsigned int local_columns);
/**
- * Create a matrix object of
- * dimensions @p m times @p n
- * with communication happening
- * over the provided @p communicator.
+ * Create a matrix object of dimensions @p m times @p n with communication
+ * happening over the provided @p communicator.
*
- * As other PETSc matrices, also the
- * the matrix-free object needs to
- * have a size and to perform matrix
- * vector multiplications efficiently
- * in parallel also @p local_rows
- * and @p local_columns. But in contrast
- * to PETSc::SparseMatrix classes a
- * PETSc matrix-free object does not need
- * any estimation of non_zero entries
- * and has no option <tt>is_symmetric</tt>.
+ * As other PETSc matrices, also the the matrix-free object needs to have
+ * a size and to perform matrix vector multiplications efficiently in
+ * parallel also @p local_rows and @p local_columns. But in contrast to
+ * PETSc::SparseMatrix classes a PETSc matrix-free object does not need
+ * any estimation of non_zero entries and has no option
+ * <tt>is_symmetric</tt>.
*/
MatrixFree (const MPI_Comm &communicator,
const unsigned int m,
const unsigned int this_process);
/**
- * Constructor for the serial case:
- * Same function as
- * <tt>MatrixFree()</tt>, see above,
- * with <tt>communicator = MPI_COMM_WORLD</tt>.
+ * Constructor for the serial case: Same function as
+ * <tt>MatrixFree()</tt>, see above, with <tt>communicator =
+ * MPI_COMM_WORLD</tt>.
*/
MatrixFree (const unsigned int m,
const unsigned int n,
const unsigned int local_columns);
/**
- * Constructor for the serial case:
- * Same function as
- * <tt>MatrixFree()</tt>, see above,
- * with <tt>communicator = MPI_COMM_WORLD</tt>.
+ * Constructor for the serial case: Same function as
+ * <tt>MatrixFree()</tt>, see above, with <tt>communicator =
+ * MPI_COMM_WORLD</tt>.
*/
MatrixFree (const unsigned int m,
const unsigned int n,
const unsigned int this_process);
/**
- * Throw away the present matrix and
- * generate one that has the same
- * properties as if it were created by
- * the constructor of this class with
- * the same argument list as the
- * present function.
+ * Throw away the present matrix and generate one that has the same
+ * properties as if it were created by the constructor of this class with
+ * the same argument list as the present function.
*/
void reinit (const MPI_Comm &communicator,
const unsigned int m,
const unsigned int local_columns);
/**
- * Throw away the present matrix and
- * generate one that has the same
- * properties as if it were created by
- * the constructor of this class with
- * the same argument list as the
- * present function.
+ * Throw away the present matrix and generate one that has the same
+ * properties as if it were created by the constructor of this class with
+ * the same argument list as the present function.
*/
void reinit (const MPI_Comm &communicator,
const unsigned int m,
const unsigned int this_process);
/**
- * Calls the @p reinit() function
- * above with <tt>communicator = MPI_COMM_WORLD</tt>.
+ * Calls the @p reinit() function above with <tt>communicator =
+ * MPI_COMM_WORLD</tt>.
*/
void reinit (const unsigned int m,
const unsigned int n,
const unsigned int local_columns);
/**
- * Calls the @p reinit() function
- * above with <tt>communicator = MPI_COMM_WORLD</tt>.
+ * Calls the @p reinit() function above with <tt>communicator =
+ * MPI_COMM_WORLD</tt>.
*/
void reinit (const unsigned int m,
const unsigned int n,
const unsigned int this_process);
/**
- * Release all memory and return
- * to a state just like after
- * having called the default
- * constructor.
+ * Release all memory and return to a state just like after having called
+ * the default constructor.
*/
void clear ();
/**
- * Return a reference to the MPI
- * communicator object in use with
- * this matrix.
+ * Return a reference to the MPI communicator object in use with this
+ * matrix.
*/
const MPI_Comm &get_mpi_communicator () const;
/**
- * Matrix-vector multiplication:
- * let <i>dst = M*src</i> with
- * <i>M</i> being this matrix.
+ * Matrix-vector multiplication: let <i>dst = M*src</i> with <i>M</i>
+ * being this matrix.
*
- * Source and destination must
- * not be the same vector.
+ * Source and destination must not be the same vector.
*
- * Note that if the current object
- * represents a parallel distributed
- * matrix (of type
- * PETScWrappers::MPI::SparseMatrix),
- * then both vectors have to be
- * distributed vectors as
- * well. Conversely, if the matrix is
- * not distributed, then neither of the
- * vectors may be.
+ * Note that if the current object represents a parallel distributed
+ * matrix (of type PETScWrappers::MPI::SparseMatrix), then both vectors
+ * have to be distributed vectors as well. Conversely, if the matrix is
+ * not distributed, then neither of the vectors may be.
*/
virtual
void vmult (VectorBase &dst,
const VectorBase &src) const = 0;
/**
- * Matrix-vector multiplication: let
- * <i>dst = M<sup>T</sup>*src</i> with
- * <i>M</i> being this matrix. This
- * function does the same as @p vmult()
+ * Matrix-vector multiplication: let <i>dst = M<sup>T</sup>*src</i> with
+ * <i>M</i> being this matrix. This function does the same as @p vmult()
* but takes the transposed matrix.
*
- * Source and destination must
- * not be the same vector.
+ * Source and destination must not be the same vector.
*
- * Note that if the current object
- * represents a parallel distributed
- * matrix then both vectors have to be
- * distributed vectors as
- * well. Conversely, if the matrix is
- * not distributed, then neither of the
+ * Note that if the current object represents a parallel distributed
+ * matrix then both vectors have to be distributed vectors as well.
+ * Conversely, if the matrix is not distributed, then neither of the
* vectors may be.
*/
virtual
const VectorBase &src) const = 0;
/**
- * Adding Matrix-vector
- * multiplication. Add
- * <i>M*src</i> on <i>dst</i>
- * with <i>M</i> being this
- * matrix.
+ * Adding Matrix-vector multiplication. Add <i>M*src</i> on <i>dst</i>
+ * with <i>M</i> being this matrix.
*
- * Source and destination must
- * not be the same vector.
+ * Source and destination must not be the same vector.
*
- * Note that if the current object
- * represents a parallel distributed
- * matrix then both vectors have to be
- * distributed vectors as
- * well. Conversely, if the matrix is
- * not distributed, then neither of the
+ * Note that if the current object represents a parallel distributed
+ * matrix then both vectors have to be distributed vectors as well.
+ * Conversely, if the matrix is not distributed, then neither of the
* vectors may be.
*/
virtual
const VectorBase &src) const = 0;
/**
- * Adding Matrix-vector
- * multiplication. Add
- * <i>M<sup>T</sup>*src</i> to
- * <i>dst</i> with <i>M</i> being
- * this matrix. This function
- * does the same as @p vmult_add()
- * but takes the transposed
- * matrix.
+ * Adding Matrix-vector multiplication. Add <i>M<sup>T</sup>*src</i> to
+ * <i>dst</i> with <i>M</i> being this matrix. This function does the same
+ * as @p vmult_add() but takes the transposed matrix.
*
- * Source and destination must
- * not be the same vector.
+ * Source and destination must not be the same vector.
*
- * Note that if the current object
- * represents a parallel distributed
- * matrix then both vectors have to be
- * distributed vectors as
- * well. Conversely, if the matrix is
- * not distributed, then neither of the
+ * Note that if the current object represents a parallel distributed
+ * matrix then both vectors have to be distributed vectors as well.
+ * Conversely, if the matrix is not distributed, then neither of the
* vectors may be.
*/
virtual
const VectorBase &src) const = 0;
/**
- * The matrix-vector multiplication
- * called by @p matrix_free_mult().
- * This function can be reimplemented
- * in derived classes for efficiency. The default
- * implementation copies the given vectors
- * into PETScWrappers::*::Vector
- * and calls <tt>vmult(VectorBase &dst, const VectorBase &src)</tt>
- * which is purely virtual and must be reimplemented
+ * The matrix-vector multiplication called by @p matrix_free_mult(). This
+ * function can be reimplemented in derived classes for efficiency. The
+ * default implementation copies the given vectors into
+ * PETScWrappers::*::Vector and calls <tt>vmult(VectorBase &dst, const
+ * VectorBase &src)</tt> which is purely virtual and must be reimplemented
* in derived classes.
*/
virtual
private:
/**
- * Copy of the communicator object to
- * be used for this parallel matrix-free object.
+ * Copy of the communicator object to be used for this parallel matrix-
+ * free object.
*/
MPI_Comm communicator;
/**
- * Callback-function registered
- * as the matrix-vector multiplication
- * of this matrix-free object
- * called by PETSc routines.
- * This function must be static and
- * takes a PETSc matrix @p A,
- * and vectors @p src and @p dst,
+ * Callback-function registered as the matrix-vector multiplication of
+ * this matrix-free object called by PETSc routines. This function must be
+ * static and takes a PETSc matrix @p A, and vectors @p src and @p dst,
* where <i>dst = A*src</i>
*
- * Source and destination must
- * not be the same vector.
+ * Source and destination must not be the same vector.
*
- * This function calls
- * <tt>vmult(Vec &dst, const Vec &src)</tt>
- * which should be reimplemented in
- * derived classes.
+ * This function calls <tt>vmult(Vec &dst, const Vec &src)</tt> which
+ * should be reimplemented in derived classes.
*/
static int matrix_free_mult (Mat A, Vec src, Vec dst);
/**
- * Do the actual work for the
- * respective @p reinit() function and
- * the matching constructor,
- * i.e. create a matrix object. Getting rid
- * of the previous matrix is left to
- * the caller.
+ * Do the actual work for the respective @p reinit() function and the
+ * matching constructor, i.e. create a matrix object. Getting rid of the
+ * previous matrix is left to the caller.
*/
void do_reinit (const unsigned int m,
const unsigned int n,
*/
/**
- * Blocked sparse matrix based on the PETScWrappers::SparseMatrix class. This
- * class implements the functions that are specific to the PETSc SparseMatrix
- * base objects for a blocked sparse matrix, and leaves the actual work
- * relaying most of the calls to the individual blocks to the functions
- * implemented in the base class. See there also for a description of when
- * this class is useful.
+ * Blocked sparse matrix based on the PETScWrappers::SparseMatrix class.
+ * This class implements the functions that are specific to the PETSc
+ * SparseMatrix base objects for a blocked sparse matrix, and leaves the
+ * actual work relaying most of the calls to the individual blocks to the
+ * functions implemented in the base class. See there also for a
+ * description of when this class is useful.
*
- * In contrast to the deal.II-type SparseMatrix class, the PETSc matrices do
- * not have external objects for the sparsity patterns. Thus, one does not
- * determine the size of the individual blocks of a block matrix of this type
- * by attaching a block sparsity pattern, but by calling reinit() to set the
- * number of blocks and then by setting the size of each block separately. In
- * order to fix the data structures of the block matrix, it is then necessary
- * to let it know that we have changed the sizes of the underlying
- * matrices. For this, one has to call the collect_sizes() function, for much
- * the same reason as is documented with the BlockSparsityPattern class.
+ * In contrast to the deal.II-type SparseMatrix class, the PETSc matrices
+ * do not have external objects for the sparsity patterns. Thus, one does
+ * not determine the size of the individual blocks of a block matrix of
+ * this type by attaching a block sparsity pattern, but by calling
+ * reinit() to set the number of blocks and then by setting the size of
+ * each block separately. In order to fix the data structures of the block
+ * matrix, it is then necessary to let it know that we have changed the
+ * sizes of the underlying matrices. For this, one has to call the
+ * collect_sizes() function, for much the same reason as is documented
+ * with the BlockSparsityPattern class.
*
- * @ingroup Matrix1
- * @see @ref GlossBlockLA "Block (linear algebra)"
+ * @ingroup Matrix1 @see @ref GlossBlockLA "Block (linear algebra)"
* @author Wolfgang Bangerth, 2004
*/
class BlockSparseMatrix : public BlockMatrixBase<SparseMatrix>
{
public:
/**
- * Typedef the base class for simpler
- * access to its own typedefs.
+ * Typedef the base class for simpler access to its own typedefs.
*/
typedef BlockMatrixBase<SparseMatrix> BaseClass;
/**
- * Typedef the type of the underlying
- * matrix.
+ * Typedef the type of the underlying matrix.
*/
typedef BaseClass::BlockType BlockType;
/**
- * Import the typedefs from the base
- * class.
+ * Import the typedefs from the base class.
*/
typedef BaseClass::value_type value_type;
typedef BaseClass::pointer pointer;
typedef BaseClass::const_iterator const_iterator;
/**
- * Constructor; initializes the
- * matrix to be empty, without
- * any structure, i.e. the
- * matrix is not usable at
- * all. This constructor is
- * therefore only useful for
- * matrices which are members of
- * a class. All other matrices
- * should be created at a point
- * in the data flow where all
- * necessary information is
- * available.
+ * Constructor; initializes the matrix to be empty, without any
+ * structure, i.e. the matrix is not usable at all. This constructor is
+ * therefore only useful for matrices which are members of a class. All
+ * other matrices should be created at a point in the data flow where
+ * all necessary information is available.
*
- * You have to initialize the
- * matrix before usage with
- * reinit(BlockSparsityPattern). The
- * number of blocks per row and
- * column are then determined by
- * that function.
+ * You have to initialize the matrix before usage with
+ * reinit(BlockSparsityPattern). The number of blocks per row and column
+ * are then determined by that function.
*/
BlockSparseMatrix ();
~BlockSparseMatrix ();
/**
- * Pseudo copy operator only copying
- * empty objects. The sizes of the
- * block matrices need to be the
- * same.
+ * Pseudo copy operator only copying empty objects. The sizes of the
+ * block matrices need to be the same.
*/
BlockSparseMatrix &
operator = (const BlockSparseMatrix &);
/**
- * This operator assigns a scalar to
- * a matrix. Since this does usually
- * not make much sense (should we set
- * all matrix entries to this value?
- * Only the nonzero entries of the
- * sparsity pattern?), this operation
- * is only allowed if the actual
- * value to be assigned is zero. This
- * operator only exists to allow for
- * the obvious notation
- * <tt>matrix=0</tt>, which sets all
- * elements of the matrix to zero,
- * but keep the sparsity pattern
- * previously used.
+ * This operator assigns a scalar to a matrix. Since this does usually
+ * not make much sense (should we set all matrix entries to this value?
+ * Only the nonzero entries of the sparsity pattern?), this operation is
+ * only allowed if the actual value to be assigned is zero. This
+ * operator only exists to allow for the obvious notation
+ * <tt>matrix=0</tt>, which sets all elements of the matrix to zero, but
+ * keep the sparsity pattern previously used.
*/
BlockSparseMatrix &
operator = (const double d);
/**
- * Resize the matrix, by setting
- * the number of block rows and
- * columns. This deletes all
- * blocks and replaces them by
- * unitialized ones, i.e. ones
- * for which also the sizes are
- * not yet set. You have to do
- * that by calling the @p reinit
- * functions of the blocks
- * themselves. Do not forget to
- * call collect_sizes() after
- * that on this object.
+ * Resize the matrix, by setting the number of block rows and columns.
+ * This deletes all blocks and replaces them by unitialized ones, i.e.
+ * ones for which also the sizes are not yet set. You have to do that by
+ * calling the @p reinit functions of the blocks themselves. Do not
+ * forget to call collect_sizes() after that on this object.
*
- * The reason that you have to
- * set sizes of the blocks
- * yourself is that the sizes may
- * be varying, the maximum number
- * of elements per row may be
- * varying, etc. It is simpler
- * not to reproduce the interface
- * of the SparsityPattern
- * class here but rather let the
- * user call whatever function
- * she desires.
+ * The reason that you have to set sizes of the blocks yourself is that
+ * the sizes may be varying, the maximum number of elements per row may
+ * be varying, etc. It is simpler not to reproduce the interface of the
+ * SparsityPattern class here but rather let the user call whatever
+ * function she desires.
*/
void reinit (const size_type n_block_rows,
const size_type n_block_columns);
/**
- * Efficiently reinit the block matrix for a parallel computation.
- * Only the BlockSparsityPattern of the Simple type can efficiently
- * store large sparsity patterns in parallel, so this is the only
- * supported argument.
- * The IndexSets describe the locally owned range of DoFs for each block.
- * Note that each IndexSet needs to be contiguous. For a symmetric structure
- * hand in the same vector for the first two arguments.
+ * Efficiently reinit the block matrix for a parallel computation. Only
+ * the BlockSparsityPattern of the Simple type can efficiently store
+ * large sparsity patterns in parallel, so this is the only supported
+ * argument. The IndexSets describe the locally owned range of DoFs for
+ * each block. Note that each IndexSet needs to be contiguous. For a
+ * symmetric structure hand in the same vector for the first two
+ * arguments.
*/
void reinit(const std::vector<IndexSet> &rows,
const std::vector<IndexSet> &cols,
/**
- * Matrix-vector multiplication:
- * let $dst = M*src$ with $M$
- * being this matrix.
+ * Matrix-vector multiplication: let $dst = M*src$ with $M$ being this
+ * matrix.
*/
void vmult (BlockVector &dst,
const BlockVector &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block column.
+ * Matrix-vector multiplication. Just like the previous function, but
+ * only applicable if the matrix has only one block column.
*/
void vmult (BlockVector &dst,
const Vector &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block row.
+ * Matrix-vector multiplication. Just like the previous function, but
+ * only applicable if the matrix has only one block row.
*/
void vmult (Vector &dst,
const BlockVector &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block.
+ * Matrix-vector multiplication. Just like the previous function, but
+ * only applicable if the matrix has only one block.
*/
void vmult (Vector &dst,
const Vector &src) const;
/**
- * Matrix-vector multiplication:
- * let $dst = M^T*src$ with $M$
- * being this matrix. This
- * function does the same as
- * vmult() but takes the
+ * Matrix-vector multiplication: let $dst = M^T*src$ with $M$ being this
+ * matrix. This function does the same as vmult() but takes the
* transposed matrix.
*/
void Tvmult (BlockVector &dst,
const BlockVector &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block row.
+ * Matrix-vector multiplication. Just like the previous function, but
+ * only applicable if the matrix has only one block row.
*/
void Tvmult (BlockVector &dst,
const Vector &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block column.
+ * Matrix-vector multiplication. Just like the previous function, but
+ * only applicable if the matrix has only one block column.
*/
void Tvmult (Vector &dst,
const BlockVector &src) const;
/**
- * Matrix-vector
- * multiplication. Just like the
- * previous function, but only
- * applicable if the matrix has
- * only one block.
+ * Matrix-vector multiplication. Just like the previous function, but
+ * only applicable if the matrix has only one block.
*/
void Tvmult (Vector &dst,
const Vector &src) const;
/**
- * This function collects the
- * sizes of the sub-objects and
- * stores them in internal
- * arrays, in order to be able to
- * relay global indices into the
- * matrix to indices into the
- * subobjects. You *must* call
- * this function each time after
- * you have changed the size of
- * the sub-objects.
+ * This function collects the sizes of the sub-objects and stores them
+ * in internal arrays, in order to be able to relay global indices into
+ * the matrix to indices into the subobjects. You *must* call this
+ * function each time after you have changed the size of the sub-
+ * objects.
*/
void collect_sizes ();
/**
- * Return a reference to the MPI
- * communicator object in use with
- * this matrix.
+ * Return a reference to the MPI communicator object in use with this
+ * matrix.
*/
const MPI_Comm &get_mpi_communicator () const;
/**
- * Make the clear() function in the
- * base class visible, though it is
+ * Make the clear() function in the base class visible, though it is
* protected.
*/
using BlockMatrixBase<SparseMatrix>::clear;
/**
* An implementation of block vectors based on the parallel vector class
- * implemented in PETScWrappers. While the base class provides for most of the
- * interface, this class handles the actual allocation of vectors and provides
- * functions that are specific to the underlying vector type.
+ * implemented in PETScWrappers. While the base class provides for most of
+ * the interface, this class handles the actual allocation of vectors and
+ * provides functions that are specific to the underlying vector type.
*
* The model of distribution of data is such that each of the blocks is
- * distributed across all MPI processes named in the MPI communicator. I.e. we
- * don't just distribute the whole vector, but each component. In the
- * constructors and reinit() functions, one therefore not only has to specify
- * the sizes of the individual blocks, but also the number of elements of each
- * of these blocks to be stored on the local process.
+ * distributed across all MPI processes named in the MPI communicator.
+ * I.e. we don't just distribute the whole vector, but each component. In
+ * the constructors and reinit() functions, one therefore not only has to
+ * specify the sizes of the individual blocks, but also the number of
+ * elements of each of these blocks to be stored on the local process.
*
- * @ingroup Vectors
- * @see @ref GlossBlockLA "Block (linear algebra)"
+ * @ingroup Vectors @see @ref GlossBlockLA "Block (linear algebra)"
* @author Wolfgang Bangerth, 2004
*/
class BlockVector : public BlockVectorBase<Vector>
{
public:
/**
- * Typedef the base class for simpler
- * access to its own typedefs.
+ * Typedef the base class for simpler access to its own typedefs.
*/
typedef BlockVectorBase<Vector> BaseClass;
/**
- * Typedef the type of the underlying
- * vector.
+ * Typedef the type of the underlying vector.
*/
typedef BaseClass::BlockType BlockType;
/**
- * Import the typedefs from the base
- * class.
+ * Import the typedefs from the base class.
*/
typedef BaseClass::value_type value_type;
typedef BaseClass::pointer pointer;
typedef BaseClass::const_iterator const_iterator;
/**
- * Default constructor. Generate an
- * empty vector without any blocks.
+ * Default constructor. Generate an empty vector without any blocks.
*/
BlockVector ();
/**
- * Constructor. Generate a block
- * vector with @p n_blocks blocks,
- * each of which is a parallel
- * vector across @p communicator
- * with @p block_size elements of
- * which @p local_size elements are
- * stored on the present process.
+ * Constructor. Generate a block vector with @p n_blocks blocks, each of
+ * which is a parallel vector across @p communicator with @p block_size
+ * elements of which @p local_size elements are stored on the present
+ * process.
*/
explicit BlockVector (const unsigned int n_blocks,
const MPI_Comm &communicator,
const size_type local_size);
/**
- * Copy-Constructor. Set all the
- * properties of the parallel vector
- * to those of the given argument and
- * copy the elements.
+ * Copy-Constructor. Set all the properties of the parallel vector to
+ * those of the given argument and copy the elements.
*/
BlockVector (const BlockVector &V);
/**
- * Constructor. Set the number of
- * blocks to
- * <tt>block_sizes.size()</tt> and
- * initialize each block with
- * <tt>block_sizes[i]</tt> zero
- * elements. The individual blocks
- * are distributed across the given
- * communicator, and each store
- * <tt>local_elements[i]</tt>
- * elements on the present process.
+ * Constructor. Set the number of blocks to <tt>block_sizes.size()</tt>
+ * and initialize each block with <tt>block_sizes[i]</tt> zero elements.
+ * The individual blocks are distributed across the given communicator,
+ * and each store <tt>local_elements[i]</tt> elements on the present
+ * process.
*/
BlockVector (const std::vector<size_type> &block_sizes,
const MPI_Comm &communicator,
const std::vector<size_type> &local_elements);
/**
- * Create a BlockVector with parallel_partitioning.size() blocks,
- * each initialized with the given IndexSet.
+ * Create a BlockVector with parallel_partitioning.size() blocks, each
+ * initialized with the given IndexSet.
*/
explicit BlockVector (const std::vector<IndexSet> ¶llel_partitioning,
const MPI_Comm &communicator = MPI_COMM_WORLD);
~BlockVector ();
/**
- * Copy operator: fill all components
- * of the vector that are locally
+ * Copy operator: fill all components of the vector that are locally
* stored with the given scalar value.
*/
BlockVector &operator = (const value_type s);
/**
- * Copy operator for arguments of the
- * same type.
+ * Copy operator for arguments of the same type.
*/
BlockVector &
operator= (const BlockVector &V);
/**
- * Copy the given sequential
- * (non-distributed) block vector
- * into the present parallel block
- * vector. It is assumed that they
- * have the same size, and this
- * operation does not change the
- * partitioning of the parallel
- * vectors by which its elements are
- * distributed across several MPI
- * processes. What this operation
- * therefore does is to copy that
- * chunk of the given vector @p v
- * that corresponds to elements of
- * the target vector that are stored
- * locally, and copies them, for each
- * of the individual blocks of this
- * object. Elements that are not
- * stored locally are not touched.
+ * Copy the given sequential (non-distributed) block vector into the
+ * present parallel block vector. It is assumed that they have the same
+ * size, and this operation does not change the partitioning of the
+ * parallel vectors by which its elements are distributed across several
+ * MPI processes. What this operation therefore does is to copy that
+ * chunk of the given vector @p v that corresponds to elements of the
+ * target vector that are stored locally, and copies them, for each of
+ * the individual blocks of this object. Elements that are not stored
+ * locally are not touched.
*
- * This being a parallel vector, you
- * must make sure that @em all
- * processes call this function at
- * the same time. It is not possible
- * to change the local part of a
- * parallel vector on only one
- * process, independent of what other
- * processes do, with this function.
+ * This being a parallel vector, you must make sure that @em all
+ * processes call this function at the same time. It is not possible to
+ * change the local part of a parallel vector on only one process,
+ * independent of what other processes do, with this function.
*/
BlockVector &
operator = (const PETScWrappers::BlockVector &v);
/**
- * Reinitialize the BlockVector to
- * contain @p n_blocks of size @p
- * block_size, each of which stores
- * @p local_size elements
- * locally. The @p communicator
- * argument denotes which MPI channel
- * each of these blocks shall
- * communicate.
+ * Reinitialize the BlockVector to contain @p n_blocks of size @p
+ * block_size, each of which stores @p local_size elements locally. The
+ * @p communicator argument denotes which MPI channel each of these
+ * blocks shall communicate.
*
- * If <tt>fast==false</tt>, the vector
- * is filled with zeros.
+ * If <tt>fast==false</tt>, the vector is filled with zeros.
*/
void reinit (const unsigned int n_blocks,
const MPI_Comm &communicator,
const bool fast = false);
/**
- * Reinitialize the BlockVector such
- * that it contains
- * <tt>block_sizes.size()</tt>
- * blocks. Each block is
- * reinitialized to dimension
- * <tt>block_sizes[i]</tt>. Each of
- * them stores
- * <tt>local_sizes[i]</tt> elements
- * on the present process.
+ * Reinitialize the BlockVector such that it contains
+ * <tt>block_sizes.size()</tt> blocks. Each block is reinitialized to
+ * dimension <tt>block_sizes[i]</tt>. Each of them stores
+ * <tt>local_sizes[i]</tt> elements on the present process.
*
- * If the number of blocks is the
- * same as before this function
- * was called, all vectors remain
- * the same and reinit() is
- * called for each vector.
+ * If the number of blocks is the same as before this function was
+ * called, all vectors remain the same and reinit() is called for each
+ * vector.
*
- * If <tt>fast==false</tt>, the vector
- * is filled with zeros.
+ * If <tt>fast==false</tt>, the vector is filled with zeros.
*
- * Note that you must call this
- * (or the other reinit()
- * functions) function, rather
- * than calling the reinit()
- * functions of an individual
- * block, to allow the block
- * vector to update its caches of
- * vector sizes. If you call
- * reinit() of one of the
- * blocks, then subsequent
- * actions on this object may
- * yield unpredictable results
- * since they may be routed to
- * the wrong block.
+ * Note that you must call this (or the other reinit() functions)
+ * function, rather than calling the reinit() functions of an individual
+ * block, to allow the block vector to update its caches of vector
+ * sizes. If you call reinit() of one of the blocks, then subsequent
+ * actions on this object may yield unpredictable results since they may
+ * be routed to the wrong block.
*/
void reinit (const std::vector<size_type> &block_sizes,
const MPI_Comm &communicator,
const bool fast=false);
/**
- * Change the dimension to that
- * of the vector <tt>V</tt>. The same
- * applies as for the other
- * reinit() function.
+ * Change the dimension to that of the vector <tt>V</tt>. The same
+ * applies as for the other reinit() function.
*
- * The elements of <tt>V</tt> are not
- * copied, i.e. this function is
- * the same as calling <tt>reinit
- * (V.size(), fast)</tt>.
+ * The elements of <tt>V</tt> are not copied, i.e. this function is the
+ * same as calling <tt>reinit (V.size(), fast)</tt>.
*
- * Note that you must call this
- * (or the other reinit()
- * functions) function, rather
- * than calling the reinit()
- * functions of an individual
- * block, to allow the block
- * vector to update its caches of
- * vector sizes. If you call
- * reinit() on one of the
- * blocks, then subsequent
- * actions on this object may
- * yield unpredictable results
- * since they may be routed to
- * the wrong block.
+ * Note that you must call this (or the other reinit() functions)
+ * function, rather than calling the reinit() functions of an individual
+ * block, to allow the block vector to update its caches of vector
+ * sizes. If you call reinit() on one of the blocks, then subsequent
+ * actions on this object may yield unpredictable results since they may
+ * be routed to the wrong block.
*/
void reinit (const BlockVector &V,
const bool fast=false);
const MPI_Comm &communicator);
/**
- * Change the number of blocks to
- * <tt>num_blocks</tt>. The individual
- * blocks will get initialized with
- * zero size, so it is assumed that
- * the user resizes the
- * individual blocks by herself
- * in an appropriate way, and
- * calls <tt>collect_sizes</tt>
- * afterwards.
+ * Change the number of blocks to <tt>num_blocks</tt>. The individual
+ * blocks will get initialized with zero size, so it is assumed that the
+ * user resizes the individual blocks by herself in an appropriate way,
+ * and calls <tt>collect_sizes</tt> afterwards.
*/
void reinit (const unsigned int num_blocks);
bool has_ghost_elements() const;
/**
- * Return a reference to the MPI
- * communicator object in use with
- * this vector.
+ * Return a reference to the MPI communicator object in use with this
+ * vector.
*/
const MPI_Comm &get_mpi_communicator () const;
/**
- * Swap the contents of this
- * vector and the other vector
- * <tt>v</tt>. One could do this
- * operation with a temporary
- * variable and copying over the
- * data elements, but this
- * function is significantly more
- * efficient since it only swaps
- * the pointers to the data of
- * the two vectors and therefore
- * does not need to allocate
- * temporary storage and move
- * data around.
+ * Swap the contents of this vector and the other vector <tt>v</tt>. One
+ * could do this operation with a temporary variable and copying over
+ * the data elements, but this function is significantly more efficient
+ * since it only swaps the pointers to the data of the two vectors and
+ * therefore does not need to allocate temporary storage and move data
+ * around.
*
- * Limitation: right now this
- * function only works if both
- * vectors have the same number
- * of blocks. If needed, the
- * numbers of blocks should be
+ * Limitation: right now this function only works if both vectors have
+ * the same number of blocks. If needed, the numbers of blocks should be
* exchanged, too.
*
- * This function is analog to the
- * the swap() function of all C++
- * standard containers. Also,
- * there is a global function
- * swap(u,v) that simply calls
- * <tt>u.swap(v)</tt>, again in analogy
- * to standard functions.
+ * This function is analog to the the swap() function of all C++
+ * standard containers. Also, there is a global function swap(u,v) that
+ * simply calls <tt>u.swap(v)</tt>, again in analogy to standard
+ * functions.
*/
void swap (BlockVector &v);
/**
- * Global function which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two vectors.
+ * Global function which overloads the default implementation of the C++
+ * standard library which uses a temporary object. The function simply
+ * exchanges the data of the two vectors.
*
* @relates PETScWrappers::MPI::BlockVector
* @author Wolfgang Bangerth, 2000
/**
- * Implementation of a parallel sparse matrix class based on PETSC, with rows
- * of the matrix distributed across an MPI network. All the functionality is
- * actually in the base class, except for the calls to generate a parallel
- * sparse matrix. This is possible since PETSc only works on an abstract
- * matrix type and internally distributes to functions that do the actual work
- * depending on the actual matrix type (much like using virtual
- * functions). Only the functions creating a matrix of specific type differ,
- * and are implemented in this particular class.
+ * Implementation of a parallel sparse matrix class based on PETSC, with
+ * rows of the matrix distributed across an MPI network. All the
+ * functionality is actually in the base class, except for the calls to
+ * generate a parallel sparse matrix. This is possible since PETSc only
+ * works on an abstract matrix type and internally distributes to
+ * functions that do the actual work depending on the actual matrix type
+ * (much like using virtual functions). Only the functions creating a
+ * matrix of specific type differ, and are implemented in this particular
+ * class.
*
- * There are a number of comments on the communication model as well as access
- * to individual elements in the documentation to the parallel vector
- * class. These comments apply here as well.
+ * There are a number of comments on the communication model as well as
+ * access to individual elements in the documentation to the parallel
+ * vector class. These comments apply here as well.
*
*
* <h3>Partitioning of matrices</h3>
* certain number of rows (i.e. only this process stores the respective
* entries in these rows). The number of rows each process owns has to be
* passed to the constructors and reinit() functions via the argument @p
- * local_rows. The individual values passed as @p local_rows on all the MPI
- * processes of course have to add up to the global number of rows of the
- * matrix.
+ * local_rows. The individual values passed as @p local_rows on all the
+ * MPI processes of course have to add up to the global number of rows of
+ * the matrix.
*
* In addition to this, PETSc also partitions the rectangular chunk of the
- * matrix it owns (i.e. the @p local_rows times n() elements in the matrix),
- * so that matrix vector multiplications can be performed efficiently. This
- * column-partitioning therefore has to match the partitioning of the vectors
- * with which the matrix is multiplied, just as the row-partitioning has to
- * match the partitioning of destination vectors. This partitioning is passed
- * to the constructors and reinit() functions through the @p local_columns
- * variable, which again has to add up to the global number of columns in the
- * matrix. The name @p local_columns may be named inappropriately since it
- * does not reflect that only these columns are stored locally, but it
- * reflects the fact that these are the columns for which the elements of
- * incoming vectors are stored locally.
+ * matrix it owns (i.e. the @p local_rows times n() elements in the
+ * matrix), so that matrix vector multiplications can be performed
+ * efficiently. This column-partitioning therefore has to match the
+ * partitioning of the vectors with which the matrix is multiplied, just
+ * as the row-partitioning has to match the partitioning of destination
+ * vectors. This partitioning is passed to the constructors and reinit()
+ * functions through the @p local_columns variable, which again has to add
+ * up to the global number of columns in the matrix. The name @p
+ * local_columns may be named inappropriately since it does not reflect
+ * that only these columns are stored locally, but it reflects the fact
+ * that these are the columns for which the elements of incoming vectors
+ * are stored locally.
*
- * To make things even more complicated, PETSc needs a very good estimate of
- * the number of elements to be stored in each row to be efficient. Otherwise
- * it spends most of the time with allocating small chunks of memory, a
- * process that can slow down programs to a crawl if it happens to often. As
- * if a good estimate of the number of entries per row isn't even, it even
- * needs to split this as follows: for each row it owns, it needs an estimate
- * for the number of elements in this row that fall into the columns that are
- * set apart for this process (see above), and the number of elements that are
- * in the rest of the columns.
+ * To make things even more complicated, PETSc needs a very good estimate
+ * of the number of elements to be stored in each row to be efficient.
+ * Otherwise it spends most of the time with allocating small chunks of
+ * memory, a process that can slow down programs to a crawl if it happens
+ * to often. As if a good estimate of the number of entries per row isn't
+ * even, it even needs to split this as follows: for each row it owns, it
+ * needs an estimate for the number of elements in this row that fall into
+ * the columns that are set apart for this process (see above), and the
+ * number of elements that are in the rest of the columns.
*
* Since in general this information is not readily available, most of the
* initializing functions of this class assume that all of the number of
* elements you give as an argument to @p n_nonzero_per_row or by @p
- * row_lengths fall into the columns "owned" by this process, and none into
- * the other ones. This is a fair guess for most of the rows, since in a good
- * domain partitioning, nodes only interact with nodes that are within the
- * same subdomain. It does not hold for nodes on the interfaces of subdomain,
- * however, and for the rows corresponding to these nodes, PETSc will have to
- * allocate additional memory, a costly process.
+ * row_lengths fall into the columns "owned" by this process, and none
+ * into the other ones. This is a fair guess for most of the rows, since
+ * in a good domain partitioning, nodes only interact with nodes that are
+ * within the same subdomain. It does not hold for nodes on the interfaces
+ * of subdomain, however, and for the rows corresponding to these nodes,
+ * PETSc will have to allocate additional memory, a costly process.
*
- * The only way to avoid this is to tell PETSc where the actual entries of the
- * matrix will be. For this, there are constructors and reinit() functions of
- * this class that take a CompressedSparsityPattern object containing all this
- * information. While in the general case it is sufficient if the constructors
- * and reinit() functions know the number of local rows and columns, the
- * functions getting a sparsity pattern also need to know the number of local
- * rows (@p local_rows_per_process) and columns (@p local_columns_per_process)
- * for all other processes, in order to compute which parts of the matrix are
- * which. Thus, it is not sufficient to just count the number of degrees of
- * freedom that belong to a particular process, but you have to have the
- * numbers for all processes available at all processes.
+ * The only way to avoid this is to tell PETSc where the actual entries of
+ * the matrix will be. For this, there are constructors and reinit()
+ * functions of this class that take a CompressedSparsityPattern object
+ * containing all this information. While in the general case it is
+ * sufficient if the constructors and reinit() functions know the number
+ * of local rows and columns, the functions getting a sparsity pattern
+ * also need to know the number of local rows (@p local_rows_per_process)
+ * and columns (@p local_columns_per_process) for all other processes, in
+ * order to compute which parts of the matrix are which. Thus, it is not
+ * sufficient to just count the number of degrees of freedom that belong
+ * to a particular process, but you have to have the numbers for all
+ * processes available at all processes.
*
* @ingroup PETScWrappers
* @ingroup Matrix1
typedef types::global_dof_index size_type;
/**
- * A structure that describes some of
- * the traits of this class in terms
- * of its run-time behavior. Some
- * other classes (such as the block
- * matrix classes) that take one or
- * other of the matrix classes as its
- * template parameters can tune their
- * behavior based on the variables in
+ * A structure that describes some of the traits of this class in terms
+ * of its run-time behavior. Some other classes (such as the block
+ * matrix classes) that take one or other of the matrix classes as its
+ * template parameters can tune their behavior based on the variables in
* this class.
*/
struct Traits
{
/**
- * It is not safe to elide
- * additions of zeros to
- * individual elements of this
- * matrix. The reason is that
- * additions to the matrix may
- * trigger collective operations
- * synchronising buffers on
- * multiple processes. If an
- * addition is elided on one
- * process, this may lead to
- * other processes hanging in an
- * infinite waiting loop.
+ * It is not safe to elide additions of zeros to individual elements
+ * of this matrix. The reason is that additions to the matrix may
+ * trigger collective operations synchronising buffers on multiple
+ * processes. If an addition is elided on one process, this may lead
+ * to other processes hanging in an infinite waiting loop.
*/
static const bool zero_addition_can_be_elided = false;
};
/**
- * Default constructor. Create an
- * empty matrix.
+ * Default constructor. Create an empty matrix.
*/
SparseMatrix ();
~SparseMatrix ();
/**
- * Create a sparse matrix of
- * dimensions @p m times @p n, with
- * an initial guess of @p
- * n_nonzero_per_row and @p
- * n_offdiag_nonzero_per_row nonzero
- * elements per row (see documentation
- * of the MatCreateAIJ PETSc function
- * for more information about these
- * parameters). PETSc is able to
- * cope with the situation that more
- * than this number of elements are
- * later allocated for a row, but this
- * involves copying data, and is thus
- * expensive.
+ * Create a sparse matrix of dimensions @p m times @p n, with an initial
+ * guess of @p n_nonzero_per_row and @p n_offdiag_nonzero_per_row
+ * nonzero elements per row (see documentation of the MatCreateAIJ PETSc
+ * function for more information about these parameters). PETSc is able
+ * to cope with the situation that more than this number of elements are
+ * later allocated for a row, but this involves copying data, and is
+ * thus expensive.
*
- * For the meaning of the @p
- * local_row and @p local_columns
- * parameters, see the class
- * documentation.
+ * For the meaning of the @p local_row and @p local_columns parameters,
+ * see the class documentation.
*
- * The @p is_symmetric flag determines
- * whether we should tell PETSc that
- * the matrix is going to be symmetric
- * (as indicated by the call
- * <tt>MatSetOption(mat,
- * MAT_SYMMETRIC)</tt>. Note that the
- * PETSc documentation states that one
- * cannot form an ILU decomposition of
- * a matrix for which this flag has
- * been set to @p true, only an
- * ICC. The default value of this flag
- * is @p false.
+ * The @p is_symmetric flag determines whether we should tell PETSc that
+ * the matrix is going to be symmetric (as indicated by the call
+ * <tt>MatSetOption(mat, MAT_SYMMETRIC)</tt>. Note that the PETSc
+ * documentation states that one cannot form an ILU decomposition of a
+ * matrix for which this flag has been set to @p true, only an ICC. The
+ * default value of this flag is @p false.
*/
SparseMatrix (const MPI_Comm &communicator,
const size_type m,
const size_type n_offdiag_nonzero_per_row = 0);
/**
- * Initialize a rectangular matrix
- * with @p m rows and @p n columns.
- * The maximal number of nonzero
- * entries for diagonal and off-
- * diagonal blocks of each row is
- * given by the @p row_lengths and
- * @p offdiag_row_lengths arrays.
+ * Initialize a rectangular matrix with @p m rows and @p n columns. The
+ * maximal number of nonzero entries for diagonal and off- diagonal
+ * blocks of each row is given by the @p row_lengths and @p
+ * offdiag_row_lengths arrays.
*
- * For the meaning of the @p
- * local_row and @p local_columns
- * parameters, see the class
- * documentation.
+ * For the meaning of the @p local_row and @p local_columns parameters,
+ * see the class documentation.
*
- * Just as for the other
- * constructors: PETSc is able to
- * cope with the situation that more
- * than this number of elements are
- * later allocated for a row, but
- * this involves copying data, and is
- * thus expensive.
+ * Just as for the other constructors: PETSc is able to cope with the
+ * situation that more than this number of elements are later allocated
+ * for a row, but this involves copying data, and is thus expensive.
*
- * The @p is_symmetric flag
- * determines whether we should tell
- * PETSc that the matrix is going to
- * be symmetric (as indicated by the
- * call <tt>MatSetOption(mat,
- * MAT_SYMMETRIC)</tt>. Note that the
- * PETSc documentation states that
- * one cannot form an ILU
- * decomposition of a matrix for
- * which this flag has been set to @p
- * true, only an ICC. The default
- * value of this flag is @p false.
+ * The @p is_symmetric flag determines whether we should tell PETSc that
+ * the matrix is going to be symmetric (as indicated by the call
+ * <tt>MatSetOption(mat, MAT_SYMMETRIC)</tt>. Note that the PETSc
+ * documentation states that one cannot form an ILU decomposition of a
+ * matrix for which this flag has been set to @p true, only an ICC. The
+ * default value of this flag is @p false.
*/
SparseMatrix (const MPI_Comm &communicator,
const size_type m,
const std::vector<size_type> &offdiag_row_lengths = std::vector<size_type>());
/**
- * Initialize using the given
- * sparsity pattern with
- * communication happening over the
- * provided @p communicator.
+ * Initialize using the given sparsity pattern with communication
+ * happening over the provided @p communicator.
*
- * For the meaning of the @p
- * local_rows_per_process and @p
- * local_columns_per_process
- * parameters, see the class
- * documentation.
+ * For the meaning of the @p local_rows_per_process and @p
+ * local_columns_per_process parameters, see the class documentation.
*
- * Note that PETSc can be very slow
- * if you do not provide it with a
- * good estimate of the lengths of
- * rows. Using the present function
- * is a very efficient way to do
- * this, as it uses the exact number
- * of nonzero entries for each row of
- * the matrix by using the given
- * sparsity pattern argument. If the
- * @p preset_nonzero_locations flag
- * is @p true, this function in
- * addition not only sets the correct
- * row sizes up front, but also
- * pre-allocated the correct nonzero
- * entries in the matrix.
+ * Note that PETSc can be very slow if you do not provide it with a good
+ * estimate of the lengths of rows. Using the present function is a very
+ * efficient way to do this, as it uses the exact number of nonzero
+ * entries for each row of the matrix by using the given sparsity
+ * pattern argument. If the @p preset_nonzero_locations flag is @p true,
+ * this function in addition not only sets the correct row sizes up
+ * front, but also pre-allocated the correct nonzero entries in the
+ * matrix.
*
- * PETsc allows to later add
- * additional nonzero entries to a
- * matrix, by simply writing to these
- * elements. However, this will then
- * lead to additional memory
- * allocations which are very
- * inefficient and will greatly slow
- * down your program. It is therefore
- * significantly more efficient to
- * get memory allocation right from
- * the start.
+ * PETsc allows to later add additional nonzero entries to a matrix, by
+ * simply writing to these elements. However, this will then lead to
+ * additional memory allocations which are very inefficient and will
+ * greatly slow down your program. It is therefore significantly more
+ * efficient to get memory allocation right from the start.
*/
template <typename SparsityType>
SparseMatrix (const MPI_Comm &communicator,
const bool preset_nonzero_locations = true);
/**
- * This operator assigns a scalar to
- * a matrix. Since this does usually
- * not make much sense (should we set
- * all matrix entries to this value?
- * Only the nonzero entries of the
- * sparsity pattern?), this operation
- * is only allowed if the actual
- * value to be assigned is zero. This
- * operator only exists to allow for
- * the obvious notation
- * <tt>matrix=0</tt>, which sets all
- * elements of the matrix to zero,
- * but keep the sparsity pattern
- * previously used.
+ * This operator assigns a scalar to a matrix. Since this does usually
+ * not make much sense (should we set all matrix entries to this value?
+ * Only the nonzero entries of the sparsity pattern?), this operation is
+ * only allowed if the actual value to be assigned is zero. This
+ * operator only exists to allow for the obvious notation
+ * <tt>matrix=0</tt>, which sets all elements of the matrix to zero, but
+ * keep the sparsity pattern previously used.
*/
SparseMatrix &operator = (const value_type d);
/**
- * Make a copy of the PETSc matrix @p other. It is assumed that both matrices have
- * the same SparsityPattern.
+ * Make a copy of the PETSc matrix @p other. It is assumed that both
+ * matrices have the same SparsityPattern.
*/
void copy_from(const SparseMatrix &other);
/**
- * Throw away the present matrix and
- * generate one that has the same
- * properties as if it were created by
- * the constructor of this class with
- * the same argument list as the
- * present function.
+ * Throw away the present matrix and generate one that has the same
+ * properties as if it were created by the constructor of this class
+ * with the same argument list as the present function.
*/
void reinit (const MPI_Comm &communicator,
const size_type m,
const size_type n_offdiag_nonzero_per_row = 0);
/**
- * Throw away the present matrix and
- * generate one that has the same
- * properties as if it were created by
- * the constructor of this class with
- * the same argument list as the
- * present function.
+ * Throw away the present matrix and generate one that has the same
+ * properties as if it were created by the constructor of this class
+ * with the same argument list as the present function.
*/
void reinit (const MPI_Comm &communicator,
const size_type m,
const std::vector<size_type> &offdiag_row_lengths = std::vector<size_type>());
/**
- * Initialize using the given
- * sparsity pattern with
- * communication happening over the
- * provided @p communicator.
+ * Initialize using the given sparsity pattern with communication
+ * happening over the provided @p communicator.
*
- * Note that PETSc can be very slow
- * if you do not provide it with a
- * good estimate of the lengths of
- * rows. Using the present function
- * is a very efficient way to do
- * this, as it uses the exact number
- * of nonzero entries for each row of
- * the matrix by using the given
- * sparsity pattern argument. If the
- * @p preset_nonzero_locations flag
- * is @p true, this function in
- * addition not only sets the correct
- * row sizes up front, but also
- * pre-allocated the correct nonzero
- * entries in the matrix.
+ * Note that PETSc can be very slow if you do not provide it with a good
+ * estimate of the lengths of rows. Using the present function is a very
+ * efficient way to do this, as it uses the exact number of nonzero
+ * entries for each row of the matrix by using the given sparsity
+ * pattern argument. If the @p preset_nonzero_locations flag is @p true,
+ * this function in addition not only sets the correct row sizes up
+ * front, but also pre-allocated the correct nonzero entries in the
+ * matrix.
*
- * PETsc allows to later add
- * additional nonzero entries to a
- * matrix, by simply writing to these
- * elements. However, this will then
- * lead to additional memory
- * allocations which are very
- * inefficient and will greatly slow
- * down your program. It is therefore
- * significantly more efficient to
- * get memory allocation right from
- * the start.
+ * PETsc allows to later add additional nonzero entries to a matrix, by
+ * simply writing to these elements. However, this will then lead to
+ * additional memory allocations which are very inefficient and will
+ * greatly slow down your program. It is therefore significantly more
+ * efficient to get memory allocation right from the start.
*/
template <typename SparsityType>
void reinit (const MPI_Comm &communicator,
const bool preset_nonzero_locations = true);
/**
- * Create a matrix where the size() of the IndexSets determine the global
- * number of rows and columns and the entries of the IndexSet give
- * the rows and columns for the calling processor.
- * Note that only contiguous IndexSets are supported.
+ * Create a matrix where the size() of the IndexSets determine the
+ * global number of rows and columns and the entries of the IndexSet
+ * give the rows and columns for the calling processor. Note that only
+ * contiguous IndexSets are supported.
*/
template <typename SparsityType>
void reinit (const IndexSet &local_rows,
const MPI_Comm &communicator);
/**
- * Return a reference to the MPI
- * communicator object in use with
- * this matrix.
+ * Return a reference to the MPI communicator object in use with this
+ * matrix.
*/
virtual const MPI_Comm &get_mpi_communicator () const;
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
*/
//@}
/**
- * Return the square of the norm
- * of the vector $v$ with respect
- * to the norm induced by this
- * matrix,
- * i.e. $\left(v,Mv\right)$. This
- * is useful, e.g. in the finite
- * element context, where the
- * $L_2$ norm of a function
- * equals the matrix norm with
- * respect to the mass matrix of
- * the vector representing the
- * nodal values of the finite
- * element function.
+ * Return the square of the norm of the vector $v$ with respect to the
+ * norm induced by this matrix, i.e. $\left(v,Mv\right)$. This is
+ * useful, e.g. in the finite element context, where the $L_2$ norm of a
+ * function equals the matrix norm with respect to the mass matrix of
+ * the vector representing the nodal values of the finite element
+ * function.
*
- * Obviously, the matrix needs to
- * be quadratic for this operation.
+ * Obviously, the matrix needs to be quadratic for this operation.
*
- * The implementation of this function
- * is not as efficient as the one in
- * the @p MatrixBase class used in
- * deal.II (i.e. the original one, not
- * the PETSc wrapper class) since PETSc
- * doesn't support this operation and
- * needs a temporary vector.
+ * The implementation of this function is not as efficient as the one in
+ * the @p MatrixBase class used in deal.II (i.e. the original one, not
+ * the PETSc wrapper class) since PETSc doesn't support this operation
+ * and needs a temporary vector.
*/
PetscScalar matrix_norm_square (const Vector &v) const;
/**
- * Compute the matrix scalar
- * product $\left(u,Mv\right)$.
+ * Compute the matrix scalar product $\left(u,Mv\right)$.
*
- * The implementation of this function
- * is not as efficient as the one in
- * the @p MatrixBase class used in
- * deal.II (i.e. the original one, not
- * the PETSc wrapper class) since PETSc
- * doesn't support this operation and
- * needs a temporary vector.
+ * The implementation of this function is not as efficient as the one in
+ * the @p MatrixBase class used in deal.II (i.e. the original one, not
+ * the PETSc wrapper class) since PETSc doesn't support this operation
+ * and needs a temporary vector.
*/
PetscScalar matrix_scalar_product (const Vector &u,
const Vector &v) const;
private:
/**
- * Copy of the communicator object to
- * be used for this parallel vector.
+ * Copy of the communicator object to be used for this parallel vector.
*/
MPI_Comm communicator;
/**
- * Do the actual work for the
- * respective reinit() function and
- * the matching constructor,
- * i.e. create a matrix. Getting rid
- * of the previous matrix is left to
- * the caller.
+ * Do the actual work for the respective reinit() function and the
+ * matching constructor, i.e. create a matrix. Getting rid of the
+ * previous matrix is left to the caller.
*/
void do_reinit (const size_type m,
const size_type n,
const SparsityType &sparsity_pattern);
/**
- * To allow calling protected
- * prepare_add() and
- * prepare_set().
+ * To allow calling protected prepare_add() and prepare_set().
*/
friend class BlockMatrixBase<SparseMatrix>;
};
/**
* Implementation of a parallel vector class based on PETSC and using MPI
- * communication to synchronise distributed operations. All the functionality
- * is actually in the base class, except for the calls to generate a
- * parallel vector. This is possible since PETSc only works on an abstract
- * vector type and internally distributes to functions that do the actual work
- * depending on the actual vector type (much like using virtual
- * functions). Only the functions creating a vector of specific type differ,
- * and are implemented in this particular class.
+ * communication to synchronise distributed operations. All the
+ * functionality is actually in the base class, except for the calls to
+ * generate a parallel vector. This is possible since PETSc only works on
+ * an abstract vector type and internally distributes to functions that do
+ * the actual work depending on the actual vector type (much like using
+ * virtual functions). Only the functions creating a vector of specific
+ * type differ, and are implemented in this particular class.
*
*
* <h3>Parallel communication model</h3>
*
- * The parallel functionality of PETSc is built on top of the Message Passing
- * Interface (MPI). MPI's communication model is built on collective
- * communications: if one process wants something from another, that other
- * process has to be willing to accept this communication. A process cannot
- * query data from another process by calling a remote function, without that
- * other process expecting such a transaction. The consequence is that most of
- * the operations in the base class of this class have to be called
- * collectively. For example, if you want to compute the l2 norm of a parallel
- * vector, @em all processes across which this vector is shared have to call
- * the @p l2_norm function. If you don't do this, but instead only call the @p
- * l2_norm function on one process, then the following happens: This one
- * process will call one of the collective MPI functions and wait for all the
- * other processes to join in on this. Since the other processes don't call
- * this function, you will either get a time-out on the first process, or,
- * worse, by the time the next a callto a PETSc function generates an MPI
- * message on the other processes, you will get a cryptic message that only a
- * subset of processes attempted a communication. These bugs can be very hard
- * to figure out, unless you are well-acquainted with the communication model
+ * The parallel functionality of PETSc is built on top of the Message
+ * Passing Interface (MPI). MPI's communication model is built on
+ * collective communications: if one process wants something from another,
+ * that other process has to be willing to accept this communication. A
+ * process cannot query data from another process by calling a remote
+ * function, without that other process expecting such a transaction. The
+ * consequence is that most of the operations in the base class of this
+ * class have to be called collectively. For example, if you want to
+ * compute the l2 norm of a parallel vector, @em all processes across
+ * which this vector is shared have to call the @p l2_norm function. If
+ * you don't do this, but instead only call the @p l2_norm function on one
+ * process, then the following happens: This one process will call one of
+ * the collective MPI functions and wait for all the other processes to
+ * join in on this. Since the other processes don't call this function,
+ * you will either get a time-out on the first process, or, worse, by the
+ * time the next a callto a PETSc function generates an MPI message on the
+ * other processes, you will get a cryptic message that only a subset of
+ * processes attempted a communication. These bugs can be very hard to
+ * figure out, unless you are well-acquainted with the communication model
* of MPI, and know which functions may generate MPI messages.
*
- * One particular case, where an MPI message may be generated unexpectedly is
- * discussed below.
+ * One particular case, where an MPI message may be generated unexpectedly
+ * is discussed below.
*
*
* <h3>Accessing individual elements of a vector</h3>
*
- * PETSc does allow read access to individual elements of a vector, but in the
- * distributed case only to elements that are stored locally. We implement
- * this through calls like <tt>d=vec(i)</tt>. However, if you access an
- * element outside the locally stored range, an exception is generated.
+ * PETSc does allow read access to individual elements of a vector, but in
+ * the distributed case only to elements that are stored locally. We
+ * implement this through calls like <tt>d=vec(i)</tt>. However, if you
+ * access an element outside the locally stored range, an exception is
+ * generated.
*
* In contrast to read access, PETSc (and the respective deal.II wrapper
- * classes) allow to write (or add) to individual elements of vectors, even if
- * they are stored on a different process. You can do this writing, for
- * example, <tt>vec(i)=d</tt> or <tt>vec(i)+=d</tt>, or similar
- * operations. There is one catch, however, that may lead to very confusing
- * error messages: PETSc requires application programs to call the compress()
- * function when they switch from adding, to elements to writing to
- * elements. The reasoning is that all processes might accumulate addition
- * operations to elements, even if multiple processes write to the same
- * elements. By the time we call compress() the next time, all these additions
- * are executed. However, if one process adds to an element, and another
- * overwrites to it, the order of execution would yield non-deterministic
- * behavior if we don't make sure that a synchronisation with compress()
- * happens in between.
+ * classes) allow to write (or add) to individual elements of vectors,
+ * even if they are stored on a different process. You can do this
+ * writing, for example, <tt>vec(i)=d</tt> or <tt>vec(i)+=d</tt>, or
+ * similar operations. There is one catch, however, that may lead to very
+ * confusing error messages: PETSc requires application programs to call
+ * the compress() function when they switch from adding, to elements to
+ * writing to elements. The reasoning is that all processes might
+ * accumulate addition operations to elements, even if multiple processes
+ * write to the same elements. By the time we call compress() the next
+ * time, all these additions are executed. However, if one process adds to
+ * an element, and another overwrites to it, the order of execution would
+ * yield non-deterministic behavior if we don't make sure that a
+ * synchronisation with compress() happens in between.
*
- * In order to make sure these calls to compress() happen at the appropriate
- * time, the deal.II wrappers keep a state variable that store which is the
- * presently allowed operation: additions or writes. If it encounters an
- * operation of the opposite kind, it calls compress() and flips the
- * state. This can sometimes lead to very confusing behavior, in code that may
- * for example look like this:
+ * In order to make sure these calls to compress() happen at the
+ * appropriate time, the deal.II wrappers keep a state variable that store
+ * which is the presently allowed operation: additions or writes. If it
+ * encounters an operation of the opposite kind, it calls compress() and
+ * flips the state. This can sometimes lead to very confusing behavior, in
+ * code that may for example look like this:
* @code
* PETScWrappers::MPI::Vector vector;
* ...
* @endcode
*
* This code can run into trouble: by the time we see the first addition
- * operation, we need to flush the overwrite buffers for the vector, and the
- * deal.II library will do so by calling compress(). However, it will only do
- * so for all processes that actually do an addition -- if the condition is
- * never true for one of the processes, then this one will not get to the
- * actual compress() call, whereas all the other ones do. This gets us into
- * trouble, since all the other processes hang in the call to flush the write
- * buffers, while the one other process advances to the call to compute the l2
- * norm. At this time, you will get an error that some operation was attempted
- * by only a subset of processes. This behavior may seem surprising, unless
- * you know that write/addition operations on single elements may trigger this
- * behavior.
+ * operation, we need to flush the overwrite buffers for the vector, and
+ * the deal.II library will do so by calling compress(). However, it will
+ * only do so for all processes that actually do an addition -- if the
+ * condition is never true for one of the processes, then this one will
+ * not get to the actual compress() call, whereas all the other ones do.
+ * This gets us into trouble, since all the other processes hang in the
+ * call to flush the write buffers, while the one other process advances
+ * to the call to compute the l2 norm. At this time, you will get an error
+ * that some operation was attempted by only a subset of processes. This
+ * behavior may seem surprising, unless you know that write/addition
+ * operations on single elements may trigger this behavior.
*
- * The problem described here may be avoided by placing additional calls to
- * compress(), or making sure that all processes do the same type of
+ * The problem described here may be avoided by placing additional calls
+ * to compress(), or making sure that all processes do the same type of
* operations at the same time, for example by placing zero additions if
* necessary.
*
typedef types::global_dof_index size_type;
/**
- * A variable that indicates whether this vector
- * supports distributed data storage. If true, then
- * this vector also needs an appropriate compress()
- * function that allows communicating recent set or
- * add operations to individual elements to be communicated
- * to other processors.
+ * A variable that indicates whether this vector supports distributed
+ * data storage. If true, then this vector also needs an appropriate
+ * compress() function that allows communicating recent set or add
+ * operations to individual elements to be communicated to other
+ * processors.
*
- * For the current class, the variable equals
- * true, since it does support parallel data storage.
+ * For the current class, the variable equals true, since it does
+ * support parallel data storage.
*/
static const bool supports_distributed_data = true;
/**
- * Default constructor. Initialize the
- * vector as empty.
- */
+ * Default constructor. Initialize the vector as empty.
+ */
Vector ();
/**
- * Constructor. Set dimension to
- * @p n and initialize all
- * elements with zero.
+ * Constructor. Set dimension to @p n and initialize all elements with
+ * zero.
*
- * @arg local_size denotes the size
- * of the chunk that shall be stored
- * on the present process.
+ * @arg local_size denotes the size of the chunk that shall be stored on
+ * the present process.
*
- * @arg communicator denotes the MPI
- * communicator over which the
- * different parts of the vector
- * shall communicate
+ * @arg communicator denotes the MPI communicator over which the
+ * different parts of the vector shall communicate
*
- * The constructor is made explicit
- * to avoid accidents like this:
- * <tt>v=0;</tt>. Presumably, the user
- * wants to set every element of the
- * vector to zero, but instead, what
- * happens is this call:
- * <tt>v=Vector@<number@>(0);</tt>, i.e. the
- * vector is replaced by one of
- * length zero.
+ * The constructor is made explicit to avoid accidents like this:
+ * <tt>v=0;</tt>. Presumably, the user wants to set every element of the
+ * vector to zero, but instead, what happens is this call:
+ * <tt>v=Vector@<number@>(0);</tt>, i.e. the vector is replaced by one
+ * of length zero.
*/
explicit Vector (const MPI_Comm &communicator,
const size_type n,
/**
- * Copy-constructor from deal.II
- * vectors. Sets the dimension to that
- * of the given vector, and copies all
- * elements.
+ * Copy-constructor from deal.II vectors. Sets the dimension to that of
+ * the given vector, and copies all elements.
*
- * @arg local_size denotes the size
- * of the chunk that shall be stored
- * on the present process.
+ * @arg local_size denotes the size of the chunk that shall be stored on
+ * the present process.
*
- * @arg communicator denotes the MPI
- * communicator over which the
- * different parts of the vector
- * shall communicate
+ * @arg communicator denotes the MPI communicator over which the
+ * different parts of the vector shall communicate
*/
template <typename Number>
explicit Vector (const MPI_Comm &communicator,
/**
- * Copy-constructor the
- * values from a PETSc wrapper vector
- * class.
+ * Copy-constructor the values from a PETSc wrapper vector class.
*
- * @arg local_size denotes the size
- * of the chunk that shall be stored
- * on the present process.
+ * @arg local_size denotes the size of the chunk that shall be stored on
+ * the present process.
*
- * @arg communicator denotes the MPI
- * communicator over which the
- * different parts of the vector
- * shall communicate
+ * @arg communicator denotes the MPI communicator over which the
+ * different parts of the vector shall communicate
*/
explicit Vector (const MPI_Comm &communicator,
const VectorBase &v,
/**
- * Constructs a new parallel ghosted PETSc
- * vector from an Indexset. Note that
- * @p local must be contiguous and
- * the global size of the vector is
- * determined by local.size(). The
- * global indices in @p ghost are
- * supplied as ghost indices that can
- * also be read locally.
+ * Constructs a new parallel ghosted PETSc vector from an Indexset. Note
+ * that @p local must be contiguous and the global size of the vector is
+ * determined by local.size(). The global indices in @p ghost are
+ * supplied as ghost indices that can also be read locally.
*
- * Note that the @p ghost IndexSet
- * may be empty and that any indices
- * already contained in @p local are
- * ignored during construction. That
- * way, the ghost parameter can equal
- * the set of locally relevant
+ * Note that the @p ghost IndexSet may be empty and that any indices
+ * already contained in @p local are ignored during construction. That
+ * way, the ghost parameter can equal the set of locally relevant
* degrees of freedom, see step-32.
*
- * @deprecated Use Vector::Vector(const IndexSet &,const IndexSet &,const MPI_Comm &) instead.
+ * @deprecated Use Vector::Vector(const IndexSet &,const IndexSet
+ * &,const MPI_Comm &) instead.
*
- * @note This operation always creates a ghosted
- * vector.
+ * @note This operation always creates a ghosted vector.
*
* @see @ref GlossGhostedVector "vectors with ghost elements"
*/
const IndexSet &ghost) DEAL_II_DEPRECATED;
/**
- * Constructs a new parallel ghosted PETSc
- * vector from an Indexset. Note that
- * @p local must be contiguous and
- * the global size of the vector is
- * determined by local.size(). The
- * global indices in @p ghost are
- * supplied as ghost indices that can
- * also be read locally.
+ * Constructs a new parallel ghosted PETSc vector from an Indexset. Note
+ * that @p local must be contiguous and the global size of the vector is
+ * determined by local.size(). The global indices in @p ghost are
+ * supplied as ghost indices that can also be read locally.
*
- * Note that the @p ghost IndexSet
- * may be empty and that any indices
- * already contained in @p local are
- * ignored during construction. That
- * way, the ghost parameter can equal
- * the set of locally relevant
+ * Note that the @p ghost IndexSet may be empty and that any indices
+ * already contained in @p local are ignored during construction. That
+ * way, the ghost parameter can equal the set of locally relevant
* degrees of freedom, see step-32.
*
- * @note This operation always creates a ghosted
- * vector.
+ * @note This operation always creates a ghosted vector.
*
* @see @ref GlossGhostedVector "vectors with ghost elements"
*/
const MPI_Comm &communicator);
/**
- * Constructs a new parallel PETSc
- * vector from an IndexSet. This creates a non
- * ghosted vector.
+ * Constructs a new parallel PETSc vector from an IndexSet. This creates
+ * a non ghosted vector.
*
- * @deprecated Use Vector::Vector(const IndexSet &,const MPI_Comm &) instead.
+ * @deprecated Use Vector::Vector(const IndexSet &,const MPI_Comm &)
+ * instead.
*/
explicit Vector (const MPI_Comm &communicator,
const IndexSet &local) DEAL_II_DEPRECATED;
/**
- * Constructs a new parallel PETSc
- * vector from an IndexSet. This creates a non
- * ghosted vector.
+ * Constructs a new parallel PETSc vector from an IndexSet. This creates
+ * a non ghosted vector.
*/
explicit Vector (const IndexSet &local,
const MPI_Comm &communicator);
/**
- * Copy the given vector. Resize the
- * present vector if necessary. Also
- * take over the MPI communicator of
- * @p v.
+ * Copy the given vector. Resize the present vector if necessary. Also
+ * take over the MPI communicator of @p v.
*/
Vector &operator = (const Vector &v);
/**
- * Copy the given sequential
- * (non-distributed) vector
- * into the present parallel
- * vector. It is assumed that
- * they have the same size,
- * and this operation does
- * not change the
- * partitioning of the
- * parallel vector by which
- * its elements are
- * distributed across several
- * MPI processes. What this
- * operation therefore does
- * is to copy that chunk of
- * the given vector @p v that
- * corresponds to elements of
- * the target vector that are
- * stored locally, and copies
- * them. Elements that are
- * not stored locally are not
- * touched.
+ * Copy the given sequential (non-distributed) vector into the present
+ * parallel vector. It is assumed that they have the same size, and this
+ * operation does not change the partitioning of the parallel vector by
+ * which its elements are distributed across several MPI processes. What
+ * this operation therefore does is to copy that chunk of the given
+ * vector @p v that corresponds to elements of the target vector that
+ * are stored locally, and copies them. Elements that are not stored
+ * locally are not touched.
*
- * This being a parallel
- * vector, you must make sure
- * that @em all processes
- * call this function at the
- * same time. It is not
- * possible to change the
- * local part of a parallel
- * vector on only one
- * process, independent of
- * what other processes do,
- * with this function.
+ * This being a parallel vector, you must make sure that @em all
+ * processes call this function at the same time. It is not possible to
+ * change the local part of a parallel vector on only one process,
+ * independent of what other processes do, with this function.
*/
Vector &operator = (const PETScWrappers::Vector &v);
/**
- * Set all components of the vector to
- * the given number @p s. Simply pass
- * this down to the base class, but we
- * still need to declare this function
- * to make the example given in the
- * discussion about making the
+ * Set all components of the vector to the given number @p s. Simply
+ * pass this down to the base class, but we still need to declare this
+ * function to make the example given in the discussion about making the
* constructor explicit work.
*/
Vector &operator = (const PetscScalar s);
/**
- * Copy the values of a deal.II vector
- * (as opposed to those of the PETSc
- * vector wrapper class) into this
- * object.
+ * Copy the values of a deal.II vector (as opposed to those of the PETSc
+ * vector wrapper class) into this object.
*
- * Contrary to the case of sequential
- * vectors, this operators requires
- * that the present vector already
- * has the correct size, since we
- * need to have a partition and a
- * communicator present which we
- * otherwise can't get from the
- * source vector.
+ * Contrary to the case of sequential vectors, this operators requires
+ * that the present vector already has the correct size, since we need
+ * to have a partition and a communicator present which we otherwise
+ * can't get from the source vector.
*/
template <typename number>
Vector &operator = (const dealii::Vector<number> &v);
/**
- * Change the dimension of the vector
- * to @p N. It is unspecified how
- * resizing the vector affects the
- * memory allocation of this object;
- * i.e., it is not guaranteed that
- * resizing it to a smaller size
- * actually also reduces memory
- * consumption, or if for efficiency
- * the same amount of memory is used
+ * Change the dimension of the vector to @p N. It is unspecified how
+ * resizing the vector affects the memory allocation of this object;
+ * i.e., it is not guaranteed that resizing it to a smaller size
+ * actually also reduces memory consumption, or if for efficiency the
+ * same amount of memory is used
*
- * @p local_size denotes how many
- * of the @p N values shall be
- * stored locally on the present
- * process.
- * for less data.
+ * @p local_size denotes how many of the @p N values shall be stored
+ * locally on the present process. for less data.
*
- * @p communicator denotes the MPI
- * communicator henceforth to be used
+ * @p communicator denotes the MPI communicator henceforth to be used
* for this vector.
*
- * If @p fast is false, the vector
- * is filled by zeros. Otherwise, the
- * elements are left an unspecified
- * state.
+ * If @p fast is false, the vector is filled by zeros. Otherwise, the
+ * elements are left an unspecified state.
*/
void reinit (const MPI_Comm &communicator,
const size_type N,
const bool fast = false);
/**
- * Change the dimension to that of
- * the vector @p v, and also take
- * over the partitioning into local
- * sizes as well as the MPI
- * communicator. The same applies as
- * for the other @p reinit function.
+ * Change the dimension to that of the vector @p v, and also take over
+ * the partitioning into local sizes as well as the MPI communicator.
+ * The same applies as for the other @p reinit function.
*
- * The elements of @p v are not
- * copied, i.e. this function is the
- * same as calling
- * <tt>reinit(v.size(),
- * v.local_size(), fast)</tt>.
+ * The elements of @p v are not copied, i.e. this function is the same
+ * as calling <tt>reinit(v.size(), v.local_size(), fast)</tt>.
*/
void reinit (const Vector &v,
const bool fast = false);
/**
- * Reinit as a ghosted vector. See
- * constructor with same signature
- * for more details.
+ * Reinit as a ghosted vector. See constructor with same signature for
+ * more details.
*
- * @deprecated Use Vector::reinit(const IndexSet &, const IndexSet &, const MPI_Comm &) instead.
+ * @deprecated Use Vector::reinit(const IndexSet &, const IndexSet &,
+ * const MPI_Comm &) instead.
*
* @see @ref GlossGhostedVector "vectors with ghost elements"
*/
const IndexSet &local,
const IndexSet &ghost) DEAL_II_DEPRECATED;
/**
- * Reinit as a vector without ghost elements. See
- * the constructor with same signature
- * for more details.
+ * Reinit as a vector without ghost elements. See the constructor with
+ * same signature for more details.
*
* @see @ref GlossGhostedVector "vectors with ghost elements"
*/
const MPI_Comm &communicator);
/**
- * Reinit as a vector without ghost elements. See
- * constructor with same signature
- * for more details.
+ * Reinit as a vector without ghost elements. See constructor with same
+ * signature for more details.
*
- * @deprecated Use Vector::reinit(const IndexSet &, const MPI_Comm &) instead.
+ * @deprecated Use Vector::reinit(const IndexSet &, const MPI_Comm &)
+ * instead.
*/
void reinit (const MPI_Comm &communicator,
const IndexSet &local) DEAL_II_DEPRECATED;
/**
- * Reinit as a vector without ghost elements. See
- * constructor with same signature
- * for more details.
+ * Reinit as a vector without ghost elements. See constructor with same
+ * signature for more details.
*
* @see @ref GlossGhostedVector "vectors with ghost elements"
*/
const MPI_Comm &communicator);
/**
- * Return a reference to the MPI
- * communicator object in use with
- * this vector.
+ * Return a reference to the MPI communicator object in use with this
+ * vector.
*/
const MPI_Comm &get_mpi_communicator () const;
/**
- * Print to a
- * stream. @p precision denotes
- * the desired precision with
- * which values shall be printed,
- * @p scientific whether
- * scientific notation shall be
- * used. If @p across is
- * @p true then the vector is
- * printed in a line, while if
- * @p false then the elements
- * are printed on a separate line
- * each.
+ * Print to a stream. @p precision denotes the desired precision with
+ * which values shall be printed, @p scientific whether scientific
+ * notation shall be used. If @p across is @p true then the vector is
+ * printed in a line, while if @p false then the elements are printed on
+ * a separate line each.
*
- * @note This function overloads the one in the
- * base class to ensure that the right thing happens
- * for parallel vectors that are distributed across
- * processors.
+ * @note This function overloads the one in the base class to ensure
+ * that the right thing happens for parallel vectors that are
+ * distributed across processors.
*/
void print (std::ostream &out,
const unsigned int precision = 3,
/**
* @copydoc PETScWrappers::VectorBase::all_zero()
*
- * @note This function overloads the one in the base class
- * to make this a collective operation.
+ * @note This function overloads the one in the base class to make this
+ * a collective operation.
*/
bool all_zero () const;
protected:
/**
- * Create a vector of length
- * @p n. For this class, we create a
- * parallel vector. @p n denotes
- * the total size of the vector to be
- * created. @p local_size denotes
- * how many of these elements shall
- * be stored locally.
+ * Create a vector of length @p n. For this class, we create a parallel
+ * vector. @p n denotes the total size of the vector to be created. @p
+ * local_size denotes how many of these elements shall be stored
+ * locally.
*/
virtual void create_vector (const size_type n,
const size_type local_size);
/**
- * Create a vector of global length
- * @p n, local size @p local_size and
- * with the specified ghost
- * indices. Note that you need to
- * call update_ghost_values() before
- * accessing those.
+ * Create a vector of global length @p n, local size @p local_size and
+ * with the specified ghost indices. Note that you need to call
+ * update_ghost_values() before accessing those.
*/
virtual void create_vector (const size_type n,
const size_type local_size,
private:
/**
- * Copy of the communicator object to
- * be used for this parallel vector.
+ * Copy of the communicator object to be used for this parallel vector.
*/
MPI_Comm communicator;
};
/**
- * Global function @p swap which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two vectors.
+ * Global function @p swap which overloads the default implementation of
+ * the C++ standard library which uses a temporary object. The function
+ * simply exchanges the data of the two vectors.
*
* @relates PETScWrappers::MPI::Vector
* @author Wolfgang Bangerth, 2004
*
* Note that derived classes only provide interfaces to the relevant
* functionality of PETSc. PETSc does not implement all preconditioners for
- * all matrix types. In particular, some preconditioners are not going to work
- * for parallel jobs, such as for example the ILU preconditioner.
+ * all matrix types. In particular, some preconditioners are not going to
+ * work for parallel jobs, such as for example the ILU preconditioner.
*
* @ingroup PETScWrappers
* @author Wolfgang Bangerth, Timo Heister, 2004, 2011
virtual ~PreconditionerBase ();
/**
- * Apply the preconditioner once to the
- * given src vector.
+ * Apply the preconditioner once to the given src vector.
*/
void vmult (VectorBase &dst,
const VectorBase &src) const;
/**
- * Gives access to the underlying PETSc
- * object.
+ * Gives access to the underlying PETSc object.
*/
const PC &get_pc () const;
PC pc;
/**
- * A pointer to the matrix that acts as
- * a preconditioner.
+ * A pointer to the matrix that acts as a preconditioner.
*/
Mat matrix;
/**
- * Internal function to create the
- * PETSc preconditioner object. Fails
- * if called twice.
+ * Internal function to create the PETSc preconditioner object. Fails if
+ * called twice.
*/
void create_pc ();
/**
- * Conversion operator to get a
- * representation of the matrix that
- * represents this preconditioner. We
- * use this inside the actual solver,
- * where we need to pass this matrix to
- * the PETSc solvers.
+ * Conversion operator to get a representation of the matrix that
+ * represents this preconditioner. We use this inside the actual solver,
+ * where we need to pass this matrix to the PETSc solvers.
*/
operator Mat () const;
/**
- * Make the solver class a friend,
- * since it needs to call the
- * conversion operator.
+ * Make the solver class a friend, since it needs to call the conversion
+ * operator.
*/
friend class SolverBase;
};
{
public:
/**
- * Standardized data struct to
- * pipe additional flags to the
+ * Standardized data struct to pipe additional flags to the
* preconditioner.
*/
struct AdditionalData
{};
/**
- * Empty Constructor. You need to call
- * initialize() before using this
+ * Empty Constructor. You need to call initialize() before using this
* object.
*/
PreconditionJacobi ();
/**
- * Constructor. Take the matrix which
- * is used to form the preconditioner,
- * and additional flags if there are
- * any.
+ * Constructor. Take the matrix which is used to form the preconditioner,
+ * and additional flags if there are any.
*/
PreconditionJacobi (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
/**
- * Initializes the preconditioner
- * object and calculate all data that
- * is necessary for applying it in a
- * solver. This function is
- * automatically called when calling
- * the constructor with the same
- * arguments and is only used if you
- * create the preconditioner without
- * arguments.
+ * Initializes the preconditioner object and calculate all data that is
+ * necessary for applying it in a solver. This function is automatically
+ * called when calling the constructor with the same arguments and is only
+ * used if you create the preconditioner without arguments.
*/
void initialize (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
protected:
/**
- * Store a copy of the flags for this
- * particular preconditioner.
+ * Store a copy of the flags for this particular preconditioner.
*/
AdditionalData additional_data;
};
/**
* A class that implements the interface to use the PETSc Block Jacobi
* preconditioner. The blocking structure of the matrix is determined by the
- * association of degrees of freedom to the individual processors in an
- * MPI-parallel job. If you use this preconditioner on a sequential job (or an
+ * association of degrees of freedom to the individual processors in an MPI-
+ * parallel job. If you use this preconditioner on a sequential job (or an
* MPI job with only one process) then the entire matrix is the only block.
*
* By default, PETSc uses an ILU(0) decomposition of each diagonal block of
- * the matrix for preconditioning. This can be changed, as is explained in the
- * relevant section of the PETSc manual, but is not implemented here.
+ * the matrix for preconditioning. This can be changed, as is explained in
+ * the relevant section of the PETSc manual, but is not implemented here.
*
* See the comment in the base class @ref PreconditionerBase for when this
* preconditioner may or may not work.
{
public:
/**
- * Standardized data struct to
- * pipe additional flags to the
+ * Standardized data struct to pipe additional flags to the
* preconditioner.
*/
struct AdditionalData
{};
/**
- * Empty Constructor. You need to call
- * initialize() before using this
+ * Empty Constructor. You need to call initialize() before using this
* object.
*/
PreconditionBlockJacobi ();
/**
- * Constructor. Take the matrix which
- * is used to form the preconditioner,
- * and additional flags if there are
- * any.
+ * Constructor. Take the matrix which is used to form the preconditioner,
+ * and additional flags if there are any.
*/
PreconditionBlockJacobi (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
/**
- * Initializes the preconditioner
- * object and calculate all data that
- * is necessary for applying it in a
- * solver. This function is
- * automatically called when calling
- * the constructor with the same
- * arguments and is only used if you
- * create the preconditioner without
- * arguments.
+ * Initializes the preconditioner object and calculate all data that is
+ * necessary for applying it in a solver. This function is automatically
+ * called when calling the constructor with the same arguments and is only
+ * used if you create the preconditioner without arguments.
*/
void initialize (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
protected:
/**
- * Store a copy of the flags for this
- * particular preconditioner.
+ * Store a copy of the flags for this particular preconditioner.
*/
AdditionalData additional_data;
};
{
public:
/**
- * Standardized data struct to
- * pipe additional flags to the
+ * Standardized data struct to pipe additional flags to the
* preconditioner.
*/
struct AdditionalData
{
/**
- * Constructor. By default,
- * set the damping parameter
- * to one.
+ * Constructor. By default, set the damping parameter to one.
*/
AdditionalData (const double omega = 1);
};
/**
- * Empty Constructor. You need to call
- * initialize() before using this
+ * Empty Constructor. You need to call initialize() before using this
* object.
*/
PreconditionSOR ();
/**
- * Constructor. Take the matrix which
- * is used to form the preconditioner,
- * and additional flags if there are
- * any.
+ * Constructor. Take the matrix which is used to form the preconditioner,
+ * and additional flags if there are any.
*/
PreconditionSOR (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
/**
- * Initializes the preconditioner
- * object and calculate all data that
- * is necessary for applying it in a
- * solver. This function is
- * automatically called when calling
- * the constructor with the same
- * arguments and is only used if you
- * create the preconditioner without
- * arguments.
+ * Initializes the preconditioner object and calculate all data that is
+ * necessary for applying it in a solver. This function is automatically
+ * called when calling the constructor with the same arguments and is only
+ * used if you create the preconditioner without arguments.
*/
void initialize (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
protected:
/**
- * Store a copy of the flags for this
- * particular preconditioner.
+ * Store a copy of the flags for this particular preconditioner.
*/
AdditionalData additional_data;
};
{
public:
/**
- * Standardized data struct to
- * pipe additional flags to the
+ * Standardized data struct to pipe additional flags to the
* preconditioner.
*/
struct AdditionalData
{
/**
- * Constructor. By default,
- * set the damping parameter
- * to one.
+ * Constructor. By default, set the damping parameter to one.
*/
AdditionalData (const double omega = 1);
};
/**
- * Empty Constructor. You need to call
- * initialize() before using this
+ * Empty Constructor. You need to call initialize() before using this
* object.
*/
PreconditionSSOR ();
/**
- * Constructor. Take the matrix which
- * is used to form the preconditioner,
- * and additional flags if there are
- * any.
+ * Constructor. Take the matrix which is used to form the preconditioner,
+ * and additional flags if there are any.
*/
PreconditionSSOR (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
/**
- * Initializes the preconditioner
- * object and calculate all data that
- * is necessary for applying it in a
- * solver. This function is
- * automatically called when calling
- * the constructor with the same
- * arguments and is only used if you
- * create the preconditioner without
- * arguments.
+ * Initializes the preconditioner object and calculate all data that is
+ * necessary for applying it in a solver. This function is automatically
+ * called when calling the constructor with the same arguments and is only
+ * used if you create the preconditioner without arguments.
*/
void initialize (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
protected:
/**
- * Store a copy of the flags for this
- * particular preconditioner.
+ * Store a copy of the flags for this particular preconditioner.
*/
AdditionalData additional_data;
};
{
public:
/**
- * Standardized data struct to
- * pipe additional flags to the
+ * Standardized data struct to pipe additional flags to the
* preconditioner.
*/
struct AdditionalData
{
/**
- * Constructor. By default,
- * set the damping parameter
- * to one.
+ * Constructor. By default, set the damping parameter to one.
*/
AdditionalData (const double omega = 1);
};
/**
- * Empty Constructor. You need to call
- * initialize() before using this
+ * Empty Constructor. You need to call initialize() before using this
* object.
*/
PreconditionEisenstat ();
/**
- * Constructor. Take the matrix which
- * is used to form the preconditioner,
- * and additional flags if there are
- * any.
+ * Constructor. Take the matrix which is used to form the preconditioner,
+ * and additional flags if there are any.
*/
PreconditionEisenstat (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
/**
- * Initializes the preconditioner
- * object and calculate all data that
- * is necessary for applying it in a
- * solver. This function is
- * automatically called when calling
- * the constructor with the same
- * arguments and is only used if you
- * create the preconditioner without
- * arguments.
+ * Initializes the preconditioner object and calculate all data that is
+ * necessary for applying it in a solver. This function is automatically
+ * called when calling the constructor with the same arguments and is only
+ * used if you create the preconditioner without arguments.
*/
void initialize (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
protected:
/**
- * Store a copy of the flags for this
- * particular preconditioner.
+ * Store a copy of the flags for this particular preconditioner.
*/
AdditionalData additional_data;
};
/**
- * A class that implements the interface to use the PETSc Incomplete Cholesky
- * preconditioner.
+ * A class that implements the interface to use the PETSc Incomplete
+ * Cholesky preconditioner.
*
* See the comment in the base class @ref PreconditionerBase for when this
* preconditioner may or may not work.
{
public:
/**
- * Standardized data struct to
- * pipe additional flags to the
+ * Standardized data struct to pipe additional flags to the
* preconditioner.
*/
struct AdditionalData
{
/**
- * Constructor. By default,
- * set the fill-in parameter
- * to zero.
+ * Constructor. By default, set the fill-in parameter to zero.
*/
AdditionalData (const unsigned int levels = 0);
};
/**
- * Empty Constructor. You need to call
- * initialize() before using this
+ * Empty Constructor. You need to call initialize() before using this
* object.
*/
PreconditionICC ();
/**
- * Constructor. Take the matrix which
- * is used to form the preconditioner,
- * and additional flags if there are
- * any.
+ * Constructor. Take the matrix which is used to form the preconditioner,
+ * and additional flags if there are any.
*/
PreconditionICC (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
/**
- * Initializes the preconditioner
- * object and calculate all data that
- * is necessary for applying it in a
- * solver. This function is
- * automatically called when calling
- * the constructor with the same
- * arguments and is only used if you
- * create the preconditioner without
- * arguments.
+ * Initializes the preconditioner object and calculate all data that is
+ * necessary for applying it in a solver. This function is automatically
+ * called when calling the constructor with the same arguments and is only
+ * used if you create the preconditioner without arguments.
*/
void initialize (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
protected:
/**
- * Store a copy of the flags for this
- * particular preconditioner.
+ * Store a copy of the flags for this particular preconditioner.
*/
AdditionalData additional_data;
};
{
public:
/**
- * Standardized data struct to
- * pipe additional flags to the
+ * Standardized data struct to pipe additional flags to the
* preconditioner.
*/
struct AdditionalData
{
/**
- * Constructor. By default,
- * set the fill-in parameter
- * to zero.
+ * Constructor. By default, set the fill-in parameter to zero.
*/
AdditionalData (const unsigned int levels = 0);
};
/**
- * Empty Constructor. You need to call
- * initialize() before using this
+ * Empty Constructor. You need to call initialize() before using this
* object.
*/
PreconditionILU ();
/**
- * Constructor. Take the matrix which
- * is used to form the preconditioner,
- * and additional flags if there are
- * any.
+ * Constructor. Take the matrix which is used to form the preconditioner,
+ * and additional flags if there are any.
*/
PreconditionILU (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
/**
- * Initializes the preconditioner
- * object and calculate all data that
- * is necessary for applying it in a
- * solver. This function is
- * automatically called when calling
- * the constructor with the same
- * arguments and is only used if you
- * create the preconditioner without
- * arguments.
+ * Initializes the preconditioner object and calculate all data that is
+ * necessary for applying it in a solver. This function is automatically
+ * called when calling the constructor with the same arguments and is only
+ * used if you create the preconditioner without arguments.
*/
void initialize (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
protected:
/**
- * Store a copy of the flags for this
- * particular preconditioner.
+ * Store a copy of the flags for this particular preconditioner.
*/
AdditionalData additional_data;
};
/**
- * A class that implements the interface to use the PETSc LU
- * preconditioner. The LU decomposition is only implemented for single
- * processor machines. It should provide a convenient interface to
- * another direct solver.
+ * A class that implements the interface to use the PETSc LU preconditioner.
+ * The LU decomposition is only implemented for single processor machines.
+ * It should provide a convenient interface to another direct solver.
*
* See the comment in the base class @ref PreconditionerBase for when this
* preconditioner may or may not work.
{
public:
/**
- * Standardized data struct to
- * pipe additional flags to the
+ * Standardized data struct to pipe additional flags to the
* preconditioner.
*/
struct AdditionalData
{
/**
- * Constructor. (Default values
- * taken from function PCCreate_LU
- * of the PetSC lib.)
+ * Constructor. (Default values taken from function PCCreate_LU of the
+ * PetSC lib.)
*/
AdditionalData (const double pivoting = 1.e-6,
const double zero_pivot = 1.e-12,
const double damping = 0.0);
/**
- * Determines, when Pivoting is
- * done during LU decomposition.
- * 0.0 indicates no pivoting,
- * and 1.0 complete pivoting.
- * Confer PetSC manual for more
- * details.
+ * Determines, when Pivoting is done during LU decomposition. 0.0
+ * indicates no pivoting, and 1.0 complete pivoting. Confer PetSC manual
+ * for more details.
*/
double pivoting;
/**
- * Size at which smaller pivots
- * are declared to be zero.
- * Confer PetSC manual for more
- * details.
+ * Size at which smaller pivots are declared to be zero. Confer PetSC
+ * manual for more details.
*/
double zero_pivot;
/**
- * This quantity is added to the
- * diagonal of the matrix during
+ * This quantity is added to the diagonal of the matrix during
* factorisation.
*/
double damping;
};
/**
- * Empty Constructor. You need to call
- * initialize() before using this
+ * Empty Constructor. You need to call initialize() before using this
* object.
*/
PreconditionLU ();
/**
- * Constructor. Take the matrix which
- * is used to form the preconditioner,
- * and additional flags if there are
- * any.
+ * Constructor. Take the matrix which is used to form the preconditioner,
+ * and additional flags if there are any.
*/
PreconditionLU (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
/**
- * Initializes the preconditioner
- * object and calculate all data that
- * is necessary for applying it in a
- * solver. This function is
- * automatically called when calling
- * the constructor with the same
- * arguments and is only used if you
- * create the preconditioner without
- * arguments.
+ * Initializes the preconditioner object and calculate all data that is
+ * necessary for applying it in a solver. This function is automatically
+ * called when calling the constructor with the same arguments and is only
+ * used if you create the preconditioner without arguments.
*/
void initialize (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
protected:
/**
- * Store a copy of the flags for this
- * particular preconditioner.
+ * Store a copy of the flags for this particular preconditioner.
*/
AdditionalData additional_data;
};
{
public:
/**
- * Standardized data struct to
- * pipe additional flags to the
+ * Standardized data struct to pipe additional flags to the
* preconditioner.
*/
struct AdditionalData
{
/**
- * Constructor. Note that BoomerAMG
- * offers a lot more options to set
+ * Constructor. Note that BoomerAMG offers a lot more options to set
* than what is exposed here.
*/
AdditionalData (
);
/**
- * Set this flag to true if you
- * have a symmetric system matrix
- * and you want to use a solver
- * which asumes a symmetric
- * preconditioner like CG. The
- * relaxation is done with
- * SSOR/Jacobi when set to true and
- * with SOR/Jacobi otherwise.
+ * Set this flag to true if you have a symmetric system matrix and you
+ * want to use a solver which asumes a symmetric preconditioner like CG.
+ * The relaxation is done with SSOR/Jacobi when set to true and with
+ * SOR/Jacobi otherwise.
*/
bool symmetric_operator;
/**
- * Threshold of when nodes are
- * considered strongly
- * connected. See
- * HYPRE_BoomerAMGSetStrongThreshold(). Recommended
- * values are 0.25 for 2d and 0.5
- * for 3d problems, but it is
- * problem dependent.
+ * Threshold of when nodes are considered strongly connected. See
+ * HYPRE_BoomerAMGSetStrongThreshold(). Recommended values are 0.25 for
+ * 2d and 0.5 for 3d problems, but it is problem dependent.
*/
double strong_threshold;
/**
- * If set to a value smaller than
- * 1.0 then diagonally dominant
- * parts of the matrix are treated
- * as having no strongly connected
- * nodes. If the row sum weighted
- * by the diagonal entry is bigger
- * than the given value, it is
- * considered diagonally
- * dominant. This feature is turned
- * of by setting the value to
- * 1.0. This is the default as some
- * matrices can result in having
- * only diagonally dominant entries
- * and thus no multigrid levels are
- * constructed. The default in
- * BoomerAMG for this is 0.9. When
- * you try this, check for a
- * reasonable number of levels
+ * If set to a value smaller than 1.0 then diagonally dominant parts of
+ * the matrix are treated as having no strongly connected nodes. If the
+ * row sum weighted by the diagonal entry is bigger than the given
+ * value, it is considered diagonally dominant. This feature is turned
+ * of by setting the value to 1.0. This is the default as some matrices
+ * can result in having only diagonally dominant entries and thus no
+ * multigrid levels are constructed. The default in BoomerAMG for this
+ * is 0.9. When you try this, check for a reasonable number of levels
* created.
*/
double max_row_sum;
/**
- * Number of levels of aggressive
- * coarsening. Increasing this
- * value reduces the construction
- * time and memory requirements but
- * may decrease effectiveness.*/
+ * Number of levels of aggressive coarsening. Increasing this value
+ * reduces the construction time and memory requirements but may
+ * decrease effectiveness.
+ */
unsigned int aggressive_coarsening_num_levels;
/**
- * Setting this flag to true
- * produces debug output from
- * HYPRE, when the preconditioner
- * is constructed.
+ * Setting this flag to true produces debug output from HYPRE, when the
+ * preconditioner is constructed.
*/
bool output_details;
};
/**
- * Empty Constructor. You need to call
- * initialize() before using this
+ * Empty Constructor. You need to call initialize() before using this
* object.
*/
PreconditionBoomerAMG ();
/**
- * Constructor. Take the matrix which
- * is used to form the preconditioner,
- * and additional flags if there are
- * any.
+ * Constructor. Take the matrix which is used to form the preconditioner,
+ * and additional flags if there are any.
*/
PreconditionBoomerAMG (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
/**
- * Initializes the preconditioner
- * object and calculate all data that
- * is necessary for applying it in a
- * solver. This function is
- * automatically called when calling
- * the constructor with the same
- * arguments and is only used if you
- * create the preconditioner without
- * arguments.
+ * Initializes the preconditioner object and calculate all data that is
+ * necessary for applying it in a solver. This function is automatically
+ * called when calling the constructor with the same arguments and is only
+ * used if you create the preconditioner without arguments.
*/
void initialize (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
protected:
/**
- * Store a copy of the flags for this
- * particular preconditioner.
+ * Store a copy of the flags for this particular preconditioner.
*/
AdditionalData additional_data;
};
/**
* A class that implements the interface to use the ParaSails sparse
- * approximate inverse preconditioner from the HYPRE suite. Note that
- * PETSc has to be configured with HYPRE (e.g. with --download-hypre=1).
+ * approximate inverse preconditioner from the HYPRE suite. Note that PETSc
+ * has to be configured with HYPRE (e.g. with --download-hypre=1).
*
- * ParaSails uses least-squares minimization to compute a sparse
- * approximate inverse. The sparsity pattern used is the pattern
- * of a power of a sparsified matrix. ParaSails also uses a post-filtering
- * technique to reduce the cost of applying the preconditioner.
+ * ParaSails uses least-squares minimization to compute a sparse approximate
+ * inverse. The sparsity pattern used is the pattern of a power of a
+ * sparsified matrix. ParaSails also uses a post-filtering technique to
+ * reduce the cost of applying the preconditioner.
*
- * ParaSails solves symmetric positive definite (SPD) problems
- * using a factorized SPD preconditioner and can also solve
- * general (nonsymmetric and/or indefinite) problems with a
- * nonfactorized preconditioner. The problem type has to be
- * set in @p AdditionalData.
+ * ParaSails solves symmetric positive definite (SPD) problems using a
+ * factorized SPD preconditioner and can also solve general (nonsymmetric
+ * and/or indefinite) problems with a nonfactorized preconditioner. The
+ * problem type has to be set in @p AdditionalData.
*
* The preconditioner does support parallel distributed computations.
*
{
public:
/**
- * Standardized data struct to
- * pipe additional flags to the
+ * Standardized data struct to pipe additional flags to the
* preconditioner.
*/
struct AdditionalData
);
/**
- * This parameter specifies the
- * type of problem to solve:
+ * This parameter specifies the type of problem to solve:
* <ul>
- * <li> @p 0: nonsymmetric and/or indefinite problem, and nonsymmetric preconditioner
+ * <li> @p 0: nonsymmetric and/or indefinite problem, and nonsymmetric
+ * preconditioner
* <li> @p 1: SPD problem, and SPD (factored) preconditioner
- * <li> @p 2: nonsymmetric, definite problem, and SPD (factored) preconditioner
+ * <li> @p 2: nonsymmetric, definite problem, and SPD (factored)
+ * preconditioner
* </ul>
* Default is <tt>symmetric = 1</tt>.
*/
unsigned int symmetric;
/**
- * The sparsity pattern used for the
- * approximate inverse is the pattern
- * of a power <tt>B^m</tt> where <tt>B</tt>
- * has been sparsified from the given
- * matrix <tt>A</tt>, <tt>n_level</tt>
- * is equal to <tt>m+1</tt>. Default
- * value is <tt>n_levels = 1</tt>.
+ * The sparsity pattern used for the approximate inverse is the pattern
+ * of a power <tt>B^m</tt> where <tt>B</tt> has been sparsified from the
+ * given matrix <tt>A</tt>, <tt>n_level</tt> is equal to <tt>m+1</tt>.
+ * Default value is <tt>n_levels = 1</tt>.
*/
unsigned int n_levels;
/**
- * Sparsification is performed by
- * dropping nonzeros which are smaller
- * than <tt>thresh</tt> in magnitude.
- * Lower values of <tt>thresh</tt>
- * lead to more accurate, but also more
- * expensive preconditioners. Default
- * value is <tt>thresh = 0.1</tt>. Setting
- * <tt>thresh < 0</tt> a threshold
- * is selected automatically, such that
- * <tt>-thresh</tt> represents the
- * fraction of nonzero elements that are
- * dropped. For example, if <tt>thresh = -0.9</tt>,
- * then <tt>B</tt> will contain about
- * ten percent of the nonzeros of the
- * given matrix <tt>A</tt>.
+ * Sparsification is performed by dropping nonzeros which are smaller
+ * than <tt>thresh</tt> in magnitude. Lower values of <tt>thresh</tt>
+ * lead to more accurate, but also more expensive preconditioners.
+ * Default value is <tt>thresh = 0.1</tt>. Setting <tt>thresh < 0</tt> a
+ * threshold is selected automatically, such that <tt>-thresh</tt>
+ * represents the fraction of nonzero elements that are dropped. For
+ * example, if <tt>thresh = -0.9</tt>, then <tt>B</tt> will contain
+ * about ten percent of the nonzeros of the given matrix <tt>A</tt>.
*/
double threshold;
/**
- * Filtering is a post-processing procedure,
- * <tt>filter</tt> represents a fraction
- * of nonzero elements that are dropped
- * after creating the approximate inverse
- * sparsity pattern. Default value is
- * <tt>filter = 0.05</tt>. Setting <tt>filter < 0</tt>
- * a value is selected automatically, such
- * that <tt>-filter</tt> represents the
- * fraction of nonzero elements that are
- * dropped. For example, if <tt>thresh = -0.9</tt>,
- * then about 90 percent of the entries
- * in the computed approximate inverse are
- * dropped.
+ * Filtering is a post-processing procedure, <tt>filter</tt> represents
+ * a fraction of nonzero elements that are dropped after creating the
+ * approximate inverse sparsity pattern. Default value is <tt>filter =
+ * 0.05</tt>. Setting <tt>filter < 0</tt> a value is selected
+ * automatically, such that <tt>-filter</tt> represents the fraction of
+ * nonzero elements that are dropped. For example, if <tt>thresh =
+ * -0.9</tt>, then about 90 percent of the entries in the computed
+ * approximate inverse are dropped.
*/
double filter;
/**
- * Setting this flag to true
- * produces output from HYPRE,
- * when the preconditioner
- * is constructed.
+ * Setting this flag to true produces output from HYPRE, when the
+ * preconditioner is constructed.
*/
bool output_details;
};
/**
- * Empty Constructor. You need to call
- * initialize() before using this
+ * Empty Constructor. You need to call initialize() before using this
* object.
*/
PreconditionParaSails ();
/**
- * Constructor. Take the matrix which
- * is used to form the preconditioner,
- * and additional flags if there are
- * any.
+ * Constructor. Take the matrix which is used to form the preconditioner,
+ * and additional flags if there are any.
*/
PreconditionParaSails (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
/**
- * Initializes the preconditioner
- * object and calculate all data that
- * is necessary for applying it in a
- * solver. This function is
- * automatically called when calling
- * the constructor with the same
- * arguments and is only used if you
- * create the preconditioner without
- * arguments.
+ * Initializes the preconditioner object and calculate all data that is
+ * necessary for applying it in a solver. This function is automatically
+ * called when calling the constructor with the same arguments and is only
+ * used if you create the preconditioner without arguments.
*/
void initialize (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
private:
/**
- * Store a copy of the flags for this
- * particular preconditioner.
+ * Store a copy of the flags for this particular preconditioner.
*/
AdditionalData additional_data;
};
{
public:
/**
- * Standardized data struct to
- * pipe additional flags to the
+ * Standardized data struct to pipe additional flags to the
* preconditioner.
*/
struct AdditionalData
{};
/**
- * Empty Constructor. You need to call
- * initialize() before using this
+ * Empty Constructor. You need to call initialize() before using this
* object.
*/
PreconditionNone ();
/**
- * Constructor. Take the matrix which
- * is used to form the preconditioner,
- * and additional flags if there are
- * any. The matrix is completely
- * ignored in computations.
+ * Constructor. Take the matrix which is used to form the preconditioner,
+ * and additional flags if there are any. The matrix is completely ignored
+ * in computations.
*/
PreconditionNone (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
/**
- * Initializes the preconditioner
- * object and calculate all data that
- * is necessary for applying it in a
- * solver. This function is
- * automatically called when calling
- * the constructor with the same
- * arguments and is only used if you
- * create the preconditioner without
- * arguments. The matrix is completely
- * ignored in computations.
+ * Initializes the preconditioner object and calculate all data that is
+ * necessary for applying it in a solver. This function is automatically
+ * called when calling the constructor with the same arguments and is only
+ * used if you create the preconditioner without arguments. The matrix is
+ * completely ignored in computations.
*/
void initialize (const MatrixBase &matrix,
const AdditionalData &additional_data = AdditionalData());
private:
/**
- * Store a copy of the flags for this
- * particular preconditioner.
+ * Store a copy of the flags for this particular preconditioner.
*/
AdditionalData additional_data;
};
* classes simply set the right flags to select one solver or another, or to
* set certain parameters for individual solvers.
*
- * Optionally, the user can create a solver derived from the
- * SolverBase class and can set the default arguments necessary to
- * solve the linear system of equations with SolverControl. These
- * default options can be overridden by specifying command line
- * arguments of the form @p -ksp_*. For example,
- * @p -ksp_monitor_true_residual prints out true residual norm
+ * Optionally, the user can create a solver derived from the SolverBase
+ * class and can set the default arguments necessary to solve the linear
+ * system of equations with SolverControl. These default options can be
+ * overridden by specifying command line arguments of the form @p -ksp_*.
+ * For example, @p -ksp_monitor_true_residual prints out true residual norm
* (unpreconditioned) at each iteration and @p -ksp_view provides
- * information about the linear solver and the preconditioner used in
- * the current context. The type of the solver can also be changed
- * during runtime by specifying @p -ksp_type {richardson, cg, gmres,
- * fgmres, ..} to dynamically test the optimal solver along with a
- * suitable preconditioner set using @p -pc_type {jacobi, bjacobi,
- * ilu, lu, ..}. There are several other command line options
- * available to modify the behavior of the PETSc linear solver and can
- * be obtained from the <a
- * href="http://www.mcs.anl.gov/petsc">documentation and manual
- * pages</a>.
+ * information about the linear solver and the preconditioner used in the
+ * current context. The type of the solver can also be changed during
+ * runtime by specifying @p -ksp_type {richardson, cg, gmres, fgmres, ..} to
+ * dynamically test the optimal solver along with a suitable preconditioner
+ * set using @p -pc_type {jacobi, bjacobi, ilu, lu, ..}. There are several
+ * other command line options available to modify the behavior of the PETSc
+ * linear solver and can be obtained from the <a
+ * href="http://www.mcs.anl.gov/petsc">documentation and manual pages</a>.
*
* @note Repeated calls to solve() on a solver object with a Preconditioner
- * must be used with care. The preconditioner is initialized in the first call
- * to solve() and subsequent calls reuse the solver and preconditioner
- * object. This is done for performance reasons. The solver and preconditioner
- * can be reset by calling reset().
+ * must be used with care. The preconditioner is initialized in the first
+ * call to solve() and subsequent calls reuse the solver and preconditioner
+ * object. This is done for performance reasons. The solver and
+ * preconditioner can be reset by calling reset().
*
* One of the gotchas of PETSc is that -- in particular in MPI mode -- it
* often does not produce very helpful error messages. In order to save
* other users some time in searching a hard to track down error, here is
- * one situation and the error message one gets there:
- * when you don't specify an MPI communicator to your solver's constructor. In
- * this case, you will get an error of the following form from each of your
- * parallel processes:
+ * one situation and the error message one gets there: when you don't
+ * specify an MPI communicator to your solver's constructor. In this case,
+ * you will get an error of the following form from each of your parallel
+ * processes:
* @verbatim
* [1]PETSC ERROR: PCSetVector() line 1173 in src/ksp/pc/interface/precon.c
* [1]PETSC ERROR: Arguments must have same communicators!
* [1]PETSC ERROR: KSPSetUp() line 195 in src/ksp/ksp/interface/itfunc.c
* @endverbatim
*
- * This error, on which one can spend a very long time figuring out
- * what exactly goes wrong, results from not specifying an MPI
- * communicator. Note that the communicator @em must match that of the
- * matrix and all vectors in the linear system which we want to
- * solve. Aggravating the situation is the fact that the default
- * argument to the solver classes, @p PETSC_COMM_SELF, is the
- * appropriate argument for the sequential case (which is why it is
- * the default argument), so this error only shows up in parallel
- * mode.
+ * This error, on which one can spend a very long time figuring out what
+ * exactly goes wrong, results from not specifying an MPI communicator. Note
+ * that the communicator @em must match that of the matrix and all vectors
+ * in the linear system which we want to solve. Aggravating the situation is
+ * the fact that the default argument to the solver classes, @p
+ * PETSC_COMM_SELF, is the appropriate argument for the sequential case
+ * (which is why it is the default argument), so this error only shows up in
+ * parallel mode.
*
* @ingroup PETScWrappers
* @author Wolfgang Bangerth, 2004
{
public:
/**
- * Constructor. Takes the solver
- * control object and the MPI
- * communicator over which parallel
- * computations are to happen.
+ * Constructor. Takes the solver control object and the MPI communicator
+ * over which parallel computations are to happen.
*
- * Note that the communicator used here
- * must match the communicator used in
- * the system matrix, solution, and
- * right hand side object of the solve
- * to be done with this
- * solver. Otherwise, PETSc will
- * generate hard to track down errors,
- * see the documentation of the
- * SolverBase class.
+ * Note that the communicator used here must match the communicator used
+ * in the system matrix, solution, and right hand side object of the solve
+ * to be done with this solver. Otherwise, PETSc will generate hard to
+ * track down errors, see the documentation of the SolverBase class.
*/
SolverBase (SolverControl &cn,
const MPI_Comm &mpi_communicator);
virtual ~SolverBase ();
/**
- * Solve the linear system
- * <tt>Ax=b</tt>. Depending on the
- * information provided by derived
- * classes and the object passed as a
- * preconditioner, one of the linear
- * solvers and preconditioners of PETSc
- * is chosen. Repeated calls to
- * solve() do not reconstruct the
- * preconditioner for performance
- * reasons. See class Documentation.
+ * Solve the linear system <tt>Ax=b</tt>. Depending on the information
+ * provided by derived classes and the object passed as a preconditioner,
+ * one of the linear solvers and preconditioners of PETSc is chosen.
+ * Repeated calls to solve() do not reconstruct the preconditioner for
+ * performance reasons. See class Documentation.
*/
void
solve (const MatrixBase &A,
/**
- * Resets the contained preconditioner
- * and solver object. See class
+ * Resets the contained preconditioner and solver object. See class
* description for more details.
*/
virtual void reset();
/**
- * Sets a prefix name for the solver
- * object. Useful when customizing the
- * PETSc KSP object with command-line
- * options.
- */
+ * Sets a prefix name for the solver object. Useful when customizing the
+ * PETSc KSP object with command-line options.
+ */
void set_prefix(const std::string &prefix);
/**
- * Access to object that controls
- * convergence.
+ * Access to object that controls convergence.
*/
SolverControl &control() const;
protected:
/**
- * Reference to the object that
- * controls convergence of the
- * iterative solver. In fact, for these
- * PETSc wrappers, PETSc does so
- * itself, but we copy the data from
- * this object before starting the
- * solution process, and copy the data
- * back into it afterwards.
+ * Reference to the object that controls convergence of the iterative
+ * solver. In fact, for these PETSc wrappers, PETSc does so itself, but we
+ * copy the data from this object before starting the solution process,
+ * and copy the data back into it afterwards.
*/
SolverControl &solver_control;
/**
- * Copy of the MPI communicator object
- * to be used for the solver.
+ * Copy of the MPI communicator object to be used for the solver.
*/
const MPI_Comm mpi_communicator;
/**
- * Function that takes a Krylov
- * Subspace Solver context object, and
- * sets the type of solver that is
- * requested by the derived class.
+ * Function that takes a Krylov Subspace Solver context object, and sets
+ * the type of solver that is requested by the derived class.
*/
virtual void set_solver_type (KSP &ksp) const = 0;
/**
- * Solver prefix name to qualify options
- * specific to the PETSc KSP object in the
- * current context.
- * Note: A hyphen (-) must NOT be given
- * at the beginning of the prefix name.
- * The first character of all runtime
+ * Solver prefix name to qualify options specific to the PETSc KSP object
+ * in the current context. Note: A hyphen (-) must NOT be given at the
+ * beginning of the prefix name. The first character of all runtime
* options is AUTOMATICALLY the hyphen.
*/
std::string prefix_name;
private:
/**
- * A function that is used in PETSc as
- * a callback to check on
- * convergence. It takes the
- * information provided from PETSc and
- * checks it against deal.II's own
- * SolverControl objects to see if
- * convergence has been reached.
+ * A function that is used in PETSc as a callback to check on convergence.
+ * It takes the information provided from PETSc and checks it against
+ * deal.II's own SolverControl objects to see if convergence has been
+ * reached.
*/
static
PetscErrorCode convergence_test (KSP ksp,
void *solver_control);
/**
- * A structure that contains the PETSc
- * solver and preconditioner
- * objects. This object is preserved
- * between subsequent calls to the
- * solver if the same preconditioner is
- * used as in the previous solver
- * step. This may save some computation
- * time, if setting up a preconditioner
- * is expensive, such as in the case of
- * an ILU for example.
+ * A structure that contains the PETSc solver and preconditioner objects.
+ * This object is preserved between subsequent calls to the solver if the
+ * same preconditioner is used as in the previous solver step. This may
+ * save some computation time, if setting up a preconditioner is
+ * expensive, such as in the case of an ILU for example.
*
- * The actual declaration of this class
- * is complicated by the fact that
- * PETSc changed its solver interface
- * completely and incompatibly between
+ * The actual declaration of this class is complicated by the fact that
+ * PETSc changed its solver interface completely and incompatibly between
* versions 2.1.6 and 2.2.0 :-(
*
- * Objects of this type are explicitly
- * created, but are destroyed when the
- * surrounding solver object goes out
- * of scope, or when we assign a new
- * value to the pointer to this
- * object. The respective *Destroy
- * functions are therefore written into
- * the destructor of this object, even
- * though the object does not have a
- * constructor.
+ * Objects of this type are explicitly created, but are destroyed when the
+ * surrounding solver object goes out of scope, or when we assign a new
+ * value to the pointer to this object. The respective *Destroy functions
+ * are therefore written into the destructor of this object, even though
+ * the object does not have a constructor.
*/
struct SolverData
{
~SolverData ();
/**
- * Objects for Krylov subspace
- * solvers and preconditioners.
+ * Objects for Krylov subspace solvers and preconditioners.
*/
KSP ksp;
PC pc;
};
/**
- * Pointer to an object that stores the
- * solver context. This is recreated in
- * the main solver routine if
- * necessary.
+ * Pointer to an object that stores the solver context. This is recreated
+ * in the main solver routine if necessary.
*/
std_cxx11::shared_ptr<SolverData> solver_data;
};
{
public:
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
{
/**
- * Constructor. By default,
- * set the damping parameter
- * to one.
+ * Constructor. By default, set the damping parameter to one.
*/
AdditionalData (const double omega = 1);
};
/**
- * Constructor. In contrast to
- * deal.II's own solvers, there is no
- * need to give a vector memory
- * object. However, PETSc solvers want
- * to have an MPI communicator context
- * over which computations are
- * parallelized. By default,
- * @p PETSC_COMM_SELF is used here,
- * but you can change this. Note that
- * for single processor (non-MPI)
- * versions, this parameter does not
+ * Constructor. In contrast to deal.II's own solvers, there is no need to
+ * give a vector memory object. However, PETSc solvers want to have an MPI
+ * communicator context over which computations are parallelized. By
+ * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+ * that for single processor (non-MPI) versions, this parameter does not
* have any effect.
*
- * The last argument takes a structure
- * with additional, solver dependent
+ * The last argument takes a structure with additional, solver dependent
* flags for tuning.
*
- * Note that the communicator used here
- * must match the communicator used in
- * the system matrix, solution, and
- * right hand side object of the solve
- * to be done with this
- * solver. Otherwise, PETSc will
- * generate hard to track down errors,
- * see the documentation of the
- * SolverBase class.
+ * Note that the communicator used here must match the communicator used
+ * in the system matrix, solution, and right hand side object of the solve
+ * to be done with this solver. Otherwise, PETSc will generate hard to
+ * track down errors, see the documentation of the SolverBase class.
*/
SolverRichardson (SolverControl &cn,
const MPI_Comm &mpi_communicator = PETSC_COMM_SELF,
protected:
/**
- * Store a copy of the flags for this
- * particular solver.
+ * Store a copy of the flags for this particular solver.
*/
const AdditionalData additional_data;
/**
- * Function that takes a Krylov
- * Subspace Solver context object, and
- * sets the type of solver that is
- *appropriate for this class.
+ * Function that takes a Krylov Subspace Solver context object, and sets
+ * the type of solver that is appropriate for this class.
*/
virtual void set_solver_type (KSP &ksp) const;
};
{
public:
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
{};
/**
- * Constructor. In contrast to
- * deal.II's own solvers, there is no
- * need to give a vector memory
- * object. However, PETSc solvers want
- * to have an MPI communicator context
- * over which computations are
- * parallelized. By default,
- * @p PETSC_COMM_SELF is used here,
- * but you can change this. Note that
- * for single processor (non-MPI)
- * versions, this parameter does not
+ * Constructor. In contrast to deal.II's own solvers, there is no need to
+ * give a vector memory object. However, PETSc solvers want to have an MPI
+ * communicator context over which computations are parallelized. By
+ * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+ * that for single processor (non-MPI) versions, this parameter does not
* have any effect.
*
- * The last argument takes a structure
- * with additional, solver dependent
+ * The last argument takes a structure with additional, solver dependent
* flags for tuning.
*
- * Note that the communicator used here
- * must match the communicator used in
- * the system matrix, solution, and
- * right hand side object of the solve
- * to be done with this
- * solver. Otherwise, PETSc will
- * generate hard to track down errors,
- * see the documentation of the
- * SolverBase class.
+ * Note that the communicator used here must match the communicator used
+ * in the system matrix, solution, and right hand side object of the solve
+ * to be done with this solver. Otherwise, PETSc will generate hard to
+ * track down errors, see the documentation of the SolverBase class.
*/
SolverChebychev (SolverControl &cn,
const MPI_Comm &mpi_communicator = PETSC_COMM_SELF,
protected:
/**
- * Store a copy of the flags for this
- * particular solver.
+ * Store a copy of the flags for this particular solver.
*/
const AdditionalData additional_data;
/**
- * Function that takes a Krylov
- * Subspace Solver context object, and
- * sets the type of solver that is
- *appropriate for this class.
+ * Function that takes a Krylov Subspace Solver context object, and sets
+ * the type of solver that is appropriate for this class.
*/
virtual void set_solver_type (KSP &ksp) const;
};
/**
- * An implementation of the solver interface using the PETSc CG
- * solver.
+ * An implementation of the solver interface using the PETSc CG solver.
*
* @ingroup PETScWrappers
* @author Wolfgang Bangerth, 2004
{
public:
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
{};
/**
- * Constructor. In contrast to
- * deal.II's own solvers, there is no
- * need to give a vector memory
- * object. However, PETSc solvers want
- * to have an MPI communicator context
- * over which computations are
- * parallelized. By default,
- * @p PETSC_COMM_SELF is used here,
- * but you can change this. Note that
- * for single processor (non-MPI)
- * versions, this parameter does not
+ * Constructor. In contrast to deal.II's own solvers, there is no need to
+ * give a vector memory object. However, PETSc solvers want to have an MPI
+ * communicator context over which computations are parallelized. By
+ * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+ * that for single processor (non-MPI) versions, this parameter does not
* have any effect.
*
- * The last argument takes a structure
- * with additional, solver dependent
+ * The last argument takes a structure with additional, solver dependent
* flags for tuning.
*
- * Note that the communicator used here
- * must match the communicator used in
- * the system matrix, solution, and
- * right hand side object of the solve
- * to be done with this
- * solver. Otherwise, PETSc will
- * generate hard to track down errors,
- * see the documentation of the
- * SolverBase class.
+ * Note that the communicator used here must match the communicator used
+ * in the system matrix, solution, and right hand side object of the solve
+ * to be done with this solver. Otherwise, PETSc will generate hard to
+ * track down errors, see the documentation of the SolverBase class.
*/
SolverCG (SolverControl &cn,
const MPI_Comm &mpi_communicator = PETSC_COMM_SELF,
protected:
/**
- * Store a copy of the flags for this
- * particular solver.
+ * Store a copy of the flags for this particular solver.
*/
const AdditionalData additional_data;
/**
- * Function that takes a Krylov
- * Subspace Solver context object, and
- * sets the type of solver that is
- *appropriate for this class.
+ * Function that takes a Krylov Subspace Solver context object, and sets
+ * the type of solver that is appropriate for this class.
*/
virtual void set_solver_type (KSP &ksp) const;
};
/**
- * An implementation of the solver interface using the PETSc BiCG
- * solver.
+ * An implementation of the solver interface using the PETSc BiCG solver.
*
* @ingroup PETScWrappers
* @author Wolfgang Bangerth, 2004
{
public:
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
{};
/**
- * Constructor. In contrast to
- * deal.II's own solvers, there is no
- * need to give a vector memory
- * object. However, PETSc solvers want
- * to have an MPI communicator context
- * over which computations are
- * parallelized. By default,
- * @p PETSC_COMM_SELF is used here,
- * but you can change this. Note that
- * for single processor (non-MPI)
- * versions, this parameter does not
+ * Constructor. In contrast to deal.II's own solvers, there is no need to
+ * give a vector memory object. However, PETSc solvers want to have an MPI
+ * communicator context over which computations are parallelized. By
+ * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+ * that for single processor (non-MPI) versions, this parameter does not
* have any effect.
*
- * The last argument takes a structure
- * with additional, solver dependent
+ * The last argument takes a structure with additional, solver dependent
* flags for tuning.
*
- * Note that the communicator used here
- * must match the communicator used in
- * the system matrix, solution, and
- * right hand side object of the solve
- * to be done with this
- * solver. Otherwise, PETSc will
- * generate hard to track down errors,
- * see the documentation of the
- * SolverBase class.
+ * Note that the communicator used here must match the communicator used
+ * in the system matrix, solution, and right hand side object of the solve
+ * to be done with this solver. Otherwise, PETSc will generate hard to
+ * track down errors, see the documentation of the SolverBase class.
*/
SolverBiCG (SolverControl &cn,
const MPI_Comm &mpi_communicator = PETSC_COMM_SELF,
protected:
/**
- * Store a copy of the flags for this
- * particular solver.
+ * Store a copy of the flags for this particular solver.
*/
const AdditionalData additional_data;
/**
- * Function that takes a Krylov
- * Subspace Solver context object, and
- * sets the type of solver that is
- *appropriate for this class.
+ * Function that takes a Krylov Subspace Solver context object, and sets
+ * the type of solver that is appropriate for this class.
*/
virtual void set_solver_type (KSP &ksp) const;
};
/**
- * An implementation of the solver interface using the PETSc GMRES
- * solver.
+ * An implementation of the solver interface using the PETSc GMRES solver.
*
* @author Wolfgang Bangerth, 2004
*/
{
public:
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
{
/**
- * Constructor. By default, set the
- * number of temporary vectors to
- * 30, i.e. do a restart every 30
- * iterations.
+ * Constructor. By default, set the number of temporary vectors to 30,
+ * i.e. do a restart every 30 iterations.
*/
AdditionalData (const unsigned int restart_parameter = 30,
const bool right_preconditioning = false);
/**
- * Maximum number of
- * tmp vectors.
+ * Maximum number of tmp vectors.
*/
unsigned int restart_parameter;
/**
- * Flag for right
- * preconditioning.
+ * Flag for right preconditioning.
*/
bool right_preconditioning;
};
/**
- * Constructor. In contrast to
- * deal.II's own solvers, there is no
- * need to give a vector memory
- * object. However, PETSc solvers want
- * to have an MPI communicator context
- * over which computations are
- * parallelized. By default,
- * @p PETSC_COMM_SELF is used here,
- * but you can change this. Note that
- * for single processor (non-MPI)
- * versions, this parameter does not
+ * Constructor. In contrast to deal.II's own solvers, there is no need to
+ * give a vector memory object. However, PETSc solvers want to have an MPI
+ * communicator context over which computations are parallelized. By
+ * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+ * that for single processor (non-MPI) versions, this parameter does not
* have any effect.
*
- * The last argument takes a structure
- * with additional, solver dependent
+ * The last argument takes a structure with additional, solver dependent
* flags for tuning.
*
- * Note that the communicator used here
- * must match the communicator used in
- * the system matrix, solution, and
- * right hand side object of the solve
- * to be done with this
- * solver. Otherwise, PETSc will
- * generate hard to track down errors,
- * see the documentation of the
- * SolverBase class.
+ * Note that the communicator used here must match the communicator used
+ * in the system matrix, solution, and right hand side object of the solve
+ * to be done with this solver. Otherwise, PETSc will generate hard to
+ * track down errors, see the documentation of the SolverBase class.
*/
SolverGMRES (SolverControl &cn,
const MPI_Comm &mpi_communicator = PETSC_COMM_SELF,
protected:
/**
- * Store a copy of the flags for this
- * particular solver.
+ * Store a copy of the flags for this particular solver.
*/
const AdditionalData additional_data;
/**
- * Function that takes a Krylov
- * Subspace Solver context object, and
- * sets the type of solver that is
- *appropriate for this class.
+ * Function that takes a Krylov Subspace Solver context object, and sets
+ * the type of solver that is appropriate for this class.
*/
virtual void set_solver_type (KSP &ksp) const;
};
{
public:
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
{};
/**
- * Constructor. In contrast to
- * deal.II's own solvers, there is no
- * need to give a vector memory
- * object. However, PETSc solvers want
- * to have an MPI communicator context
- * over which computations are
- * parallelized. By default,
- * @p PETSC_COMM_SELF is used here,
- * but you can change this. Note that
- * for single processor (non-MPI)
- * versions, this parameter does not
+ * Constructor. In contrast to deal.II's own solvers, there is no need to
+ * give a vector memory object. However, PETSc solvers want to have an MPI
+ * communicator context over which computations are parallelized. By
+ * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+ * that for single processor (non-MPI) versions, this parameter does not
* have any effect.
*
- * The last argument takes a structure
- * with additional, solver dependent
+ * The last argument takes a structure with additional, solver dependent
* flags for tuning.
*
- * Note that the communicator used here
- * must match the communicator used in
- * the system matrix, solution, and
- * right hand side object of the solve
- * to be done with this
- * solver. Otherwise, PETSc will
- * generate hard to track down errors,
- * see the documentation of the
- * SolverBase class.
+ * Note that the communicator used here must match the communicator used
+ * in the system matrix, solution, and right hand side object of the solve
+ * to be done with this solver. Otherwise, PETSc will generate hard to
+ * track down errors, see the documentation of the SolverBase class.
*/
SolverBicgstab (SolverControl &cn,
const MPI_Comm &mpi_communicator = PETSC_COMM_SELF,
protected:
/**
- * Store a copy of the flags for this
- * particular solver.
+ * Store a copy of the flags for this particular solver.
*/
const AdditionalData additional_data;
/**
- * Function that takes a Krylov
- * Subspace Solver context object, and
- * sets the type of solver that is
- *appropriate for this class.
+ * Function that takes a Krylov Subspace Solver context object, and sets
+ * the type of solver that is appropriate for this class.
*/
virtual void set_solver_type (KSP &ksp) const;
};
{
public:
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
{};
/**
- * Constructor. In contrast to
- * deal.II's own solvers, there is no
- * need to give a vector memory
- * object. However, PETSc solvers want
- * to have an MPI communicator context
- * over which computations are
- * parallelized. By default,
- * @p PETSC_COMM_SELF is used here,
- * but you can change this. Note that
- * for single processor (non-MPI)
- * versions, this parameter does not
+ * Constructor. In contrast to deal.II's own solvers, there is no need to
+ * give a vector memory object. However, PETSc solvers want to have an MPI
+ * communicator context over which computations are parallelized. By
+ * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+ * that for single processor (non-MPI) versions, this parameter does not
* have any effect.
*
- * The last argument takes a structure
- * with additional, solver dependent
+ * The last argument takes a structure with additional, solver dependent
* flags for tuning.
*
- * Note that the communicator used here
- * must match the communicator used in
- * the system matrix, solution, and
- * right hand side object of the solve
- * to be done with this
- * solver. Otherwise, PETSc will
- * generate hard to track down errors,
- * see the documentation of the
- * SolverBase class.
+ * Note that the communicator used here must match the communicator used
+ * in the system matrix, solution, and right hand side object of the solve
+ * to be done with this solver. Otherwise, PETSc will generate hard to
+ * track down errors, see the documentation of the SolverBase class.
*/
SolverCGS (SolverControl &cn,
const MPI_Comm &mpi_communicator = PETSC_COMM_SELF,
protected:
/**
- * Store a copy of the flags for this
- * particular solver.
+ * Store a copy of the flags for this particular solver.
*/
const AdditionalData additional_data;
/**
- * Function that takes a Krylov
- * Subspace Solver context object, and
- * sets the type of solver that is
- *appropriate for this class.
+ * Function that takes a Krylov Subspace Solver context object, and sets
+ * the type of solver that is appropriate for this class.
*/
virtual void set_solver_type (KSP &ksp) const;
};
/**
- * An implementation of the solver interface using the PETSc TFQMR
- * solver.
+ * An implementation of the solver interface using the PETSc TFQMR solver.
*
* @ingroup PETScWrappers
* @author Wolfgang Bangerth, 2004
{
public:
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
{};
/**
- * Constructor. In contrast to
- * deal.II's own solvers, there is no
- * need to give a vector memory
- * object. However, PETSc solvers want
- * to have an MPI communicator context
- * over which computations are
- * parallelized. By default,
- * @p PETSC_COMM_SELF is used here,
- * but you can change this. Note that
- * for single processor (non-MPI)
- * versions, this parameter does not
+ * Constructor. In contrast to deal.II's own solvers, there is no need to
+ * give a vector memory object. However, PETSc solvers want to have an MPI
+ * communicator context over which computations are parallelized. By
+ * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+ * that for single processor (non-MPI) versions, this parameter does not
* have any effect.
*
- * The last argument takes a structure
- * with additional, solver dependent
+ * The last argument takes a structure with additional, solver dependent
* flags for tuning.
*
- * Note that the communicator used here
- * must match the communicator used in
- * the system matrix, solution, and
- * right hand side object of the solve
- * to be done with this
- * solver. Otherwise, PETSc will
- * generate hard to track down errors,
- * see the documentation of the
- * SolverBase class.
+ * Note that the communicator used here must match the communicator used
+ * in the system matrix, solution, and right hand side object of the solve
+ * to be done with this solver. Otherwise, PETSc will generate hard to
+ * track down errors, see the documentation of the SolverBase class.
*/
SolverTFQMR (SolverControl &cn,
const MPI_Comm &mpi_communicator = PETSC_COMM_SELF,
protected:
/**
- * Store a copy of the flags for this
- * particular solver.
+ * Store a copy of the flags for this particular solver.
*/
const AdditionalData additional_data;
/**
- * Function that takes a Krylov
- * Subspace Solver context object, and
- * sets the type of solver that is
- *appropriate for this class.
+ * Function that takes a Krylov Subspace Solver context object, and sets
+ * the type of solver that is appropriate for this class.
*/
virtual void set_solver_type (KSP &ksp) const;
};
* An implementation of the solver interface using the PETSc TFQMR-2 solver
* (called TCQMR in PETSc). Note that this solver had a serious bug in
* versions up to and including PETSc 2.1.6, in that it did not check
- * convergence and always returned an error code. Thus, this class will abort
- * with an error indicating failure to converge with PETSc 2.1.6 and
+ * convergence and always returned an error code. Thus, this class will
+ * abort with an error indicating failure to converge with PETSc 2.1.6 and
* prior. This should be fixed in later versions of PETSc, though.
*
* @ingroup PETScWrappers
{
public:
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
{};
/**
- * Constructor. In contrast to
- * deal.II's own solvers, there is no
- * need to give a vector memory
- * object. However, PETSc solvers want
- * to have an MPI communicator context
- * over which computations are
- * parallelized. By default,
- * @p PETSC_COMM_SELF is used here,
- * but you can change this. Note that
- * for single processor (non-MPI)
- * versions, this parameter does not
+ * Constructor. In contrast to deal.II's own solvers, there is no need to
+ * give a vector memory object. However, PETSc solvers want to have an MPI
+ * communicator context over which computations are parallelized. By
+ * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+ * that for single processor (non-MPI) versions, this parameter does not
* have any effect.
*
- * The last argument takes a structure
- * with additional, solver dependent
+ * The last argument takes a structure with additional, solver dependent
* flags for tuning.
*
- * Note that the communicator used here
- * must match the communicator used in
- * the system matrix, solution, and
- * right hand side object of the solve
- * to be done with this
- * solver. Otherwise, PETSc will
- * generate hard to track down errors,
- * see the documentation of the
- * SolverBase class.
+ * Note that the communicator used here must match the communicator used
+ * in the system matrix, solution, and right hand side object of the solve
+ * to be done with this solver. Otherwise, PETSc will generate hard to
+ * track down errors, see the documentation of the SolverBase class.
*/
SolverTCQMR (SolverControl &cn,
const MPI_Comm &mpi_communicator = PETSC_COMM_SELF,
protected:
/**
- * Store a copy of the flags for this
- * particular solver.
+ * Store a copy of the flags for this particular solver.
*/
const AdditionalData additional_data;
/**
- * Function that takes a Krylov
- * Subspace Solver context object, and
- * sets the type of solver that is
- *appropriate for this class.
+ * Function that takes a Krylov Subspace Solver context object, and sets
+ * the type of solver that is appropriate for this class.
*/
virtual void set_solver_type (KSP &ksp) const;
};
/**
- * An implementation of the solver interface using the PETSc CR
- * solver.
+ * An implementation of the solver interface using the PETSc CR solver.
*
* @ingroup PETScWrappers
* @author Wolfgang Bangerth, 2004
{
public:
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
{};
/**
- * Constructor. In contrast to
- * deal.II's own solvers, there is no
- * need to give a vector memory
- * object. However, PETSc solvers want
- * to have an MPI communicator context
- * over which computations are
- * parallelized. By default,
- * @p PETSC_COMM_SELF is used here,
- * but you can change this. Note that
- * for single processor (non-MPI)
- * versions, this parameter does not
+ * Constructor. In contrast to deal.II's own solvers, there is no need to
+ * give a vector memory object. However, PETSc solvers want to have an MPI
+ * communicator context over which computations are parallelized. By
+ * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+ * that for single processor (non-MPI) versions, this parameter does not
* have any effect.
*
- * The last argument takes a structure
- * with additional, solver dependent
+ * The last argument takes a structure with additional, solver dependent
* flags for tuning.
*
- * Note that the communicator used here
- * must match the communicator used in
- * the system matrix, solution, and
- * right hand side object of the solve
- * to be done with this
- * solver. Otherwise, PETSc will
- * generate hard to track down errors,
- * see the documentation of the
- * SolverBase class.
+ * Note that the communicator used here must match the communicator used
+ * in the system matrix, solution, and right hand side object of the solve
+ * to be done with this solver. Otherwise, PETSc will generate hard to
+ * track down errors, see the documentation of the SolverBase class.
*/
SolverCR (SolverControl &cn,
const MPI_Comm &mpi_communicator = PETSC_COMM_SELF,
protected:
/**
- * Store a copy of the flags for this
- * particular solver.
+ * Store a copy of the flags for this particular solver.
*/
const AdditionalData additional_data;
/**
- * Function that takes a Krylov
- * Subspace Solver context object, and
- * sets the type of solver that is
- *appropriate for this class.
+ * Function that takes a Krylov Subspace Solver context object, and sets
+ * the type of solver that is appropriate for this class.
*/
virtual void set_solver_type (KSP &ksp) const;
};
{
public:
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
{};
/**
- * Constructor. In contrast to
- * deal.II's own solvers, there is no
- * need to give a vector memory
- * object. However, PETSc solvers want
- * to have an MPI communicator context
- * over which computations are
- * parallelized. By default,
- * @p PETSC_COMM_SELF is used here,
- * but you can change this. Note that
- * for single processor (non-MPI)
- * versions, this parameter does not
+ * Constructor. In contrast to deal.II's own solvers, there is no need to
+ * give a vector memory object. However, PETSc solvers want to have an MPI
+ * communicator context over which computations are parallelized. By
+ * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+ * that for single processor (non-MPI) versions, this parameter does not
* have any effect.
*
- * The last argument takes a structure
- * with additional, solver dependent
+ * The last argument takes a structure with additional, solver dependent
* flags for tuning.
*
- * Note that the communicator used here
- * must match the communicator used in
- * the system matrix, solution, and
- * right hand side object of the solve
- * to be done with this
- * solver. Otherwise, PETSc will
- * generate hard to track down errors,
- * see the documentation of the
- * SolverBase class.
+ * Note that the communicator used here must match the communicator used
+ * in the system matrix, solution, and right hand side object of the solve
+ * to be done with this solver. Otherwise, PETSc will generate hard to
+ * track down errors, see the documentation of the SolverBase class.
*/
SolverLSQR (SolverControl &cn,
const MPI_Comm &mpi_communicator = PETSC_COMM_SELF,
protected:
/**
- * Store a copy of the flags for this
- * particular solver.
+ * Store a copy of the flags for this particular solver.
*/
const AdditionalData additional_data;
/**
- * Function that takes a Krylov
- * Subspace Solver context object, and
- * sets the type of solver that is
- *appropriate for this class.
+ * Function that takes a Krylov Subspace Solver context object, and sets
+ * the type of solver that is appropriate for this class.
*/
virtual void set_solver_type (KSP &ksp) const;
};
/**
- * An implementation of the solver interface using the PETSc PREONLY
- * solver. Actually this is NOT a real solution algorithm. solve() only
- * applies the preconditioner once and returns immediately. Its only purpose
- * is to provide a solver object, when the preconditioner should be used as a
- * real solver. It is very useful in conjunction with the complete LU
+ * An implementation of the solver interface using the PETSc PREONLY solver.
+ * Actually this is NOT a real solution algorithm. solve() only applies the
+ * preconditioner once and returns immediately. Its only purpose is to
+ * provide a solver object, when the preconditioner should be used as a real
+ * solver. It is very useful in conjunction with the complete LU
* decomposition preconditioner <tt> PreconditionLU </tt>, which in
* conjunction with this solver class becomes a direct solver.
*
{
public:
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
{};
/**
- * Constructor. In contrast to
- * deal.II's own solvers, there is no
- * need to give a vector memory
- * object. However, PETSc solvers want
- * to have an MPI communicator context
- * over which computations are
- * parallelized. By default,
- * @p PETSC_COMM_SELF is used here,
- * but you can change this. Note that
- * for single processor (non-MPI)
- * versions, this parameter does not
+ * Constructor. In contrast to deal.II's own solvers, there is no need to
+ * give a vector memory object. However, PETSc solvers want to have an MPI
+ * communicator context over which computations are parallelized. By
+ * default, @p PETSC_COMM_SELF is used here, but you can change this. Note
+ * that for single processor (non-MPI) versions, this parameter does not
* have any effect.
*
- * The last argument takes a structure
- * with additional, solver dependent
+ * The last argument takes a structure with additional, solver dependent
* flags for tuning.
*
- * Note that the communicator used here
- * must match the communicator used in
- * the system matrix, solution, and
- * right hand side object of the solve
- * to be done with this
- * solver. Otherwise, PETSc will
- * generate hard to track down errors,
- * see the documentation of the
- * SolverBase class.
+ * Note that the communicator used here must match the communicator used
+ * in the system matrix, solution, and right hand side object of the solve
+ * to be done with this solver. Otherwise, PETSc will generate hard to
+ * track down errors, see the documentation of the SolverBase class.
*/
SolverPreOnly (SolverControl &cn,
const MPI_Comm &mpi_communicator = PETSC_COMM_SELF,
protected:
/**
- * Store a copy of the flags for this
- * particular solver.
+ * Store a copy of the flags for this particular solver.
*/
const AdditionalData additional_data;
/**
- * Function that takes a Krylov
- * Subspace Solver context object, and
- * sets the type of solver that is
- * appropriate for this class.
+ * Function that takes a Krylov Subspace Solver context object, and sets
+ * the type of solver that is appropriate for this class.
*/
virtual void set_solver_type (KSP &ksp) const;
};
* An implementation of the solver interface using the sparse direct MUMPS
* solver through PETSc. This class has the usual interface of all other
* solver classes but it is of course different in that it doesn't implement
- * an iterative solver. As a consequence, things like the SolverControl object
- * have no particular meaning here.
+ * an iterative solver. As a consequence, things like the SolverControl
+ * object have no particular meaning here.
*
- * MUMPS allows to make use of symmetry in this matrix. In this class this is
- * made possible by the set_symmetric_mode() function. If your matrix is
+ * MUMPS allows to make use of symmetry in this matrix. In this class this
+ * is made possible by the set_symmetric_mode() function. If your matrix is
* symmetric, you can use this class as follows:
* @code
* SolverControl cn;
* solver.solve(system_matrix, solution, system_rhs);
* @endcode
*
- * @note The class internally calls KSPSetFromOptions thus you are
- * able to use all the PETSc parameters for MATSOLVERMUMPS package.
- * See http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MATSOLVERMUMPS.html
+ * @note The class internally calls KSPSetFromOptions thus you are able to
+ * use all the PETSc parameters for MATSOLVERMUMPS package. See
+ * http://www.mcs.anl.gov/petsc/petsc-
+ * current/docs/manualpages/Mat/MATSOLVERMUMPS.html
*
* @ingroup PETScWrappers
* @author Daniel Brauss, Alexander Grayver, 2012
{
public:
/**
- * Standardized data structure
- * to pipe additional data to
- * the solver.
+ * Standardized data structure to pipe additional data to the solver.
*/
struct AdditionalData
{};
const AdditionalData &data = AdditionalData());
/**
- * The method to solve the
- * linear system.
+ * The method to solve the linear system.
*/
void solve (const MatrixBase &A,
VectorBase &x,
const VectorBase &b);
/**
- * The method allows to take advantage
- * if the system matrix is symmetric by
- * using LDL^T decomposition instead of
- * more expensive LU. The argument
- * indicates whether the matrix is
- * symmetric or not.
- */
+ * The method allows to take advantage if the system matrix is symmetric
+ * by using LDL^T decomposition instead of more expensive LU. The argument
+ * indicates whether the matrix is symmetric or not.
+ */
void set_symmetric_mode (const bool flag);
protected:
/**
- * Store a copy of flags for this
- * particular solver.
+ * Store a copy of flags for this particular solver.
*/
const AdditionalData additional_data;
private:
/**
- * A function that is used in PETSc
- * as a callback to check convergence.
- * It takes the information provided
- * from PETSc and checks it against
- * deal.II's own SolverControl objects
- * to see if convergence has been reached.
+ * A function that is used in PETSc as a callback to check convergence. It
+ * takes the information provided from PETSc and checks it against
+ * deal.II's own SolverControl objects to see if convergence has been
+ * reached.
*/
static
PetscErrorCode convergence_test (KSP ksp,
void *solver_control);
/**
- * A structure that contains the
- * PETSc solver and preconditioner
- * objects. Since the solve member
- * function in the base is not used
- * here, the private SolverData struct
- * located in the base could not be used
- * either.
+ * A structure that contains the PETSc solver and preconditioner objects.
+ * Since the solve member function in the base is not used here, the
+ * private SolverData struct located in the base could not be used either.
*/
struct SolverDataMUMPS
{
std_cxx11::shared_ptr<SolverDataMUMPS> solver_data;
/**
- * Flag specifies whether matrix
- * being factorized is symmetric
- * or not. It influences the type
- * of the used preconditioner
- * (PCLU or PCCHOLESKY)
+ * Flag specifies whether matrix being factorized is symmetric or not. It
+ * influences the type of the used preconditioner (PCLU or PCCHOLESKY)
*/
bool symmetric_mode;
};
namespace PETScWrappers
{
/**
- * Implementation of a sequential sparse matrix class based on PETSC. All the
- * functionality is actually in the base class, except for the calls to
- * generate a sequential sparse matrix. This is possible since PETSc only works
- * on an abstract matrix type and internally distributes to functions that do
- * the actual work depending on the actual matrix type (much like using
- * virtual functions). Only the functions creating a matrix of specific type
- * differ, and are implemented in this particular class.
+ * Implementation of a sequential sparse matrix class based on PETSC. All
+ * the functionality is actually in the base class, except for the calls to
+ * generate a sequential sparse matrix. This is possible since PETSc only
+ * works on an abstract matrix type and internally distributes to functions
+ * that do the actual work depending on the actual matrix type (much like
+ * using virtual functions). Only the functions creating a matrix of
+ * specific type differ, and are implemented in this particular class.
*
* @ingroup PETScWrappers
* @ingroup Matrix1
public:
/**
- * A structure that describes some of
- * the traits of this class in terms of
- * its run-time behavior. Some other
- * classes (such as the block matrix
- * classes) that take one or other of
- * the matrix classes as its template
- * parameters can tune their behavior
- * based on the variables in this
+ * A structure that describes some of the traits of this class in terms of
+ * its run-time behavior. Some other classes (such as the block matrix
+ * classes) that take one or other of the matrix classes as its template
+ * parameters can tune their behavior based on the variables in this
* class.
*/
struct Traits
{
/**
- * It is safe to elide additions of
- * zeros to individual elements of
- * this matrix.
+ * It is safe to elide additions of zeros to individual elements of this
+ * matrix.
*/
static const bool zero_addition_can_be_elided = true;
};
/**
- * Default constructor. Create an empty
- * matrix.
+ * Default constructor. Create an empty matrix.
*/
SparseMatrix ();
/**
- * Create a sparse matrix of dimensions
- * @p m times @p n, with an
- * initial guess of
- * @p n_nonzero_per_row nonzero
- * elements per row. PETSc is able to
- * cope with the situation that more
- * than this number of elements is
- * later allocated for a row, but this
- * involves copying data, and is thus
+ * Create a sparse matrix of dimensions @p m times @p n, with an initial
+ * guess of @p n_nonzero_per_row nonzero elements per row. PETSc is able
+ * to cope with the situation that more than this number of elements is
+ * later allocated for a row, but this involves copying data, and is thus
* expensive.
*
- * The @p is_symmetric flag determines
- * whether we should tell PETSc that
- * the matrix is going to be symmetric
- * (as indicated by the call
- * <tt>MatSetOption(mat,
- * MAT_SYMMETRIC)</tt>. Note that the
- * PETSc documentation states that one
- * cannot form an ILU decomposition of
- * a matrix for which this flag has
- * been set to @p true, only an
- * ICC. The default value of this flag
- * is @p false.
+ * The @p is_symmetric flag determines whether we should tell PETSc that
+ * the matrix is going to be symmetric (as indicated by the call
+ * <tt>MatSetOption(mat, MAT_SYMMETRIC)</tt>. Note that the PETSc
+ * documentation states that one cannot form an ILU decomposition of a
+ * matrix for which this flag has been set to @p true, only an ICC. The
+ * default value of this flag is @p false.
*/
SparseMatrix (const size_type m,
const size_type n,
const bool is_symmetric = false);
/**
- * Initialize a rectangular matrix with
- * @p m rows and @p n
- * columns. The maximal number of
- * nonzero entries for each row
- * separately is given by the
- * @p row_lengths array.
+ * Initialize a rectangular matrix with @p m rows and @p n columns. The
+ * maximal number of nonzero entries for each row separately is given by
+ * the @p row_lengths array.
*
- * Just as for the other constructors:
- * PETSc is able to cope with the
- * situation that more than this number
- * of elements is later allocated for a
- * row, but this involves copying data,
- * and is thus expensive.
+ * Just as for the other constructors: PETSc is able to cope with the
+ * situation that more than this number of elements is later allocated for
+ * a row, but this involves copying data, and is thus expensive.
*
- * The @p is_symmetric flag determines
- * whether we should tell PETSc that
- * the matrix is going to be symmetric
- * (as indicated by the call
- * <tt>MatSetOption(mat,
- * MAT_SYMMETRIC)</tt>. Note that the
- * PETSc documentation states that one
- * cannot form an ILU decomposition of
- * a matrix for which this flag has
- * been set to @p true, only an
- * ICC. The default value of this flag
- * is @p false.
+ * The @p is_symmetric flag determines whether we should tell PETSc that
+ * the matrix is going to be symmetric (as indicated by the call
+ * <tt>MatSetOption(mat, MAT_SYMMETRIC)</tt>. Note that the PETSc
+ * documentation states that one cannot form an ILU decomposition of a
+ * matrix for which this flag has been set to @p true, only an ICC. The
+ * default value of this flag is @p false.
*/
SparseMatrix (const size_type m,
const size_type n,
const bool is_symmetric = false);
/**
- * Initialize a sparse matrix using the
- * given sparsity pattern.
+ * Initialize a sparse matrix using the given sparsity pattern.
*
- * Note that PETSc can be very slow
- * if you do not provide it with a
- * good estimate of the lengths of
- * rows. Using the present function
- * is a very efficient way to do
- * this, as it uses the exact number
- * of nonzero entries for each row of
- * the matrix by using the given
- * sparsity pattern argument. If the
- * @p preset_nonzero_locations flag
- * is @p true, this function in
- * addition not only sets the correct
- * row sizes up front, but also
- * pre-allocated the correct nonzero
- * entries in the matrix.
+ * Note that PETSc can be very slow if you do not provide it with a good
+ * estimate of the lengths of rows. Using the present function is a very
+ * efficient way to do this, as it uses the exact number of nonzero
+ * entries for each row of the matrix by using the given sparsity pattern
+ * argument. If the @p preset_nonzero_locations flag is @p true, this
+ * function in addition not only sets the correct row sizes up front, but
+ * also pre-allocated the correct nonzero entries in the matrix.
*
- * PETsc allows to later add
- * additional nonzero entries to a
- * matrix, by simply writing to these
- * elements. However, this will then
- * lead to additional memory
- * allocations which are very
- * inefficient and will greatly slow
- * down your program. It is therefore
- * significantly more efficient to
- * get memory allocation right from
- * the start.
+ * PETsc allows to later add additional nonzero entries to a matrix, by
+ * simply writing to these elements. However, this will then lead to
+ * additional memory allocations which are very inefficient and will
+ * greatly slow down your program. It is therefore significantly more
+ * efficient to get memory allocation right from the start.
*/
template <typename SparsityType>
explicit SparseMatrix (const SparsityType &sparsity_pattern,
const bool preset_nonzero_locations = true);
/**
- * This operator assigns a scalar to
- * a matrix. Since this does usually
- * not make much sense (should we set
- * all matrix entries to this value?
- * Only the nonzero entries of the
- * sparsity pattern?), this operation
- * is only allowed if the actual
- * value to be assigned is zero. This
- * operator only exists to allow for
- * the obvious notation
- * <tt>matrix=0</tt>, which sets all
- * elements of the matrix to zero,
- * but keep the sparsity pattern
+ * This operator assigns a scalar to a matrix. Since this does usually not
+ * make much sense (should we set all matrix entries to this value? Only
+ * the nonzero entries of the sparsity pattern?), this operation is only
+ * allowed if the actual value to be assigned is zero. This operator only
+ * exists to allow for the obvious notation <tt>matrix=0</tt>, which sets
+ * all elements of the matrix to zero, but keep the sparsity pattern
* previously used.
*/
SparseMatrix &operator = (const double d);
/**
- * Throw away the present matrix and
- * generate one that has the same
- * properties as if it were created by
- * the constructor of this class with
- * the same argument list as the
- * present function.
+ * Throw away the present matrix and generate one that has the same
+ * properties as if it were created by the constructor of this class with
+ * the same argument list as the present function.
*/
void reinit (const size_type m,
const size_type n,
const bool is_symmetric = false);
/**
- * Throw away the present matrix and
- * generate one that has the same
- * properties as if it were created by
- * the constructor of this class with
- * the same argument list as the
- * present function.
+ * Throw away the present matrix and generate one that has the same
+ * properties as if it were created by the constructor of this class with
+ * the same argument list as the present function.
*/
void reinit (const size_type m,
const size_type n,
const bool is_symmetric = false);
/**
- * Initialize a sparse matrix using the
- * given sparsity pattern.
+ * Initialize a sparse matrix using the given sparsity pattern.
*
- * Note that PETSc can be very slow
- * if you do not provide it with a
- * good estimate of the lengths of
- * rows. Using the present function
- * is a very efficient way to do
- * this, as it uses the exact number
- * of nonzero entries for each row of
- * the matrix by using the given
- * sparsity pattern argument. If the
- * @p preset_nonzero_locations flag
- * is @p true, this function in
- * addition not only sets the correct
- * row sizes up front, but also
- * pre-allocated the correct nonzero
- * entries in the matrix.
+ * Note that PETSc can be very slow if you do not provide it with a good
+ * estimate of the lengths of rows. Using the present function is a very
+ * efficient way to do this, as it uses the exact number of nonzero
+ * entries for each row of the matrix by using the given sparsity pattern
+ * argument. If the @p preset_nonzero_locations flag is @p true, this
+ * function in addition not only sets the correct row sizes up front, but
+ * also pre-allocated the correct nonzero entries in the matrix.
*
- * PETsc allows to later add
- * additional nonzero entries to a
- * matrix, by simply writing to these
- * elements. However, this will then
- * lead to additional memory
- * allocations which are very
- * inefficient and will greatly slow
- * down your program. It is therefore
- * significantly more efficient to
- * get memory allocation right from
- * the start.
+ * PETsc allows to later add additional nonzero entries to a matrix, by
+ * simply writing to these elements. However, this will then lead to
+ * additional memory allocations which are very inefficient and will
+ * greatly slow down your program. It is therefore significantly more
+ * efficient to get memory allocation right from the start.
*
- * Despite the fact that it would
- * seem to be an obvious win, setting
- * the @p preset_nonzero_locations
- * flag to @p true doesn't seem to
- * accelerate program. Rather on the
- * contrary, it seems to be able to
- * slow down entire programs
- * somewhat. This is suprising, since
- * we can use efficient function
- * calls into PETSc that allow to
- * create multiple entries at once;
- * nevertheless, given the fact that
- * it is inefficient, the respective
- * flag has a default value equal to
- * @p false.
+ * Despite the fact that it would seem to be an obvious win, setting the
+ * @p preset_nonzero_locations flag to @p true doesn't seem to accelerate
+ * program. Rather on the contrary, it seems to be able to slow down
+ * entire programs somewhat. This is suprising, since we can use efficient
+ * function calls into PETSc that allow to create multiple entries at
+ * once; nevertheless, given the fact that it is inefficient, the
+ * respective flag has a default value equal to @p false.
*/
template <typename SparsityType>
void reinit (const SparsityType &sparsity_pattern,
const bool preset_nonzero_locations = true);
/**
- * Return a reference to the MPI
- * communicator object in use with this
- * matrix. Since this is a sequential
- * matrix, it returns the MPI_COMM_SELF
+ * Return a reference to the MPI communicator object in use with this
+ * matrix. Since this is a sequential matrix, it returns the MPI_COMM_SELF
* communicator.
*/
virtual const MPI_Comm &get_mpi_communicator () const;
/**
- * Return the square of the norm
- * of the vector $v$ with respect
- * to the norm induced by this
- * matrix,
- * i.e. $\left(v,Mv\right)$. This
- * is useful, e.g. in the finite
- * element context, where the
- * $L_2$ norm of a function
- * equals the matrix norm with
- * respect to the mass matrix of
- * the vector representing the
- * nodal values of the finite
- * element function.
+ * Return the square of the norm of the vector $v$ with respect to the
+ * norm induced by this matrix, i.e. $\left(v,Mv\right)$. This is useful,
+ * e.g. in the finite element context, where the $L_2$ norm of a function
+ * equals the matrix norm with respect to the mass matrix of the vector
+ * representing the nodal values of the finite element function.
*
- * Obviously, the matrix needs to
- * be quadratic for this operation.
+ * Obviously, the matrix needs to be quadratic for this operation.
*
- * The implementation of this function
- * is not as efficient as the one in
- * the @p MatrixBase class used in
- * deal.II (i.e. the original one, not
- * the PETSc wrapper class) since PETSc
- * doesn't support this operation and
+ * The implementation of this function is not as efficient as the one in
+ * the @p MatrixBase class used in deal.II (i.e. the original one, not the
+ * PETSc wrapper class) since PETSc doesn't support this operation and
* needs a temporary vector.
*/
PetscScalar matrix_norm_square (const VectorBase &v) const;
/**
- * Compute the matrix scalar
- * product $\left(u,Mv\right)$.
+ * Compute the matrix scalar product $\left(u,Mv\right)$.
*
- * The implementation of this function
- * is not as efficient as the one in
- * the @p MatrixBase class used in
- * deal.II (i.e. the original one, not
- * the PETSc wrapper class) since PETSc
- * doesn't support this operation and
+ * The implementation of this function is not as efficient as the one in
+ * the @p MatrixBase class used in deal.II (i.e. the original one, not the
+ * PETSc wrapper class) since PETSc doesn't support this operation and
* needs a temporary vector.
*/
PetscScalar matrix_scalar_product (const VectorBase &u,
SparseMatrix &operator= (const SparseMatrix &);
/**
- * Do the actual work for the
- * respective reinit() function and the
- * matching constructor, i.e. create a
- * matrix. Getting rid of the previous
+ * Do the actual work for the respective reinit() function and the
+ * matching constructor, i.e. create a matrix. Getting rid of the previous
* matrix is left to the caller.
*/
void do_reinit (const size_type m,
const bool preset_nonzero_locations);
/**
- * To allow calling protected
- * prepare_add() and
- * prepare_set().
+ * To allow calling protected prepare_add() and prepare_set().
*/
friend class BlockMatrixBase<SparseMatrix>;
};
/**
* Implementation of a sequential vector class based on PETSC. All the
* functionality is actually in the base class, except for the calls to
- * generate a sequential vector. This is possible since PETSc only works on an
- * abstract vector type and internally distributes to functions that do the
- * actual work depending on the actual vector type (much like using virtual
- * functions). Only the functions creating a vector of specific type differ,
- * and are implemented in this particular class.
+ * generate a sequential vector. This is possible since PETSc only works on
+ * an abstract vector type and internally distributes to functions that do
+ * the actual work depending on the actual vector type (much like using
+ * virtual functions). Only the functions creating a vector of specific type
+ * differ, and are implemented in this particular class.
*
* @ingroup Vectors
* @author Wolfgang Bangerth, 2004
typedef types::global_dof_index size_type;
/**
- * A variable that indicates whether this vector
- * supports distributed data storage. If true, then
- * this vector also needs an appropriate compress()
- * function that allows communicating recent set or
- * add operations to individual elements to be communicated
- * to other processors.
+ * A variable that indicates whether this vector supports distributed data
+ * storage. If true, then this vector also needs an appropriate compress()
+ * function that allows communicating recent set or add operations to
+ * individual elements to be communicated to other processors.
*
- * For the current class, the variable equals
- * false, since it does not support parallel data storage.
- * If you do need parallel data storage, use
- * PETScWrappers::MPI::Vector.
+ * For the current class, the variable equals false, since it does not
+ * support parallel data storage. If you do need parallel data storage,
+ * use PETScWrappers::MPI::Vector.
*/
static const bool supports_distributed_data = false;
/**
- * Default constructor. Initialize the
- * vector as empty.
+ * Default constructor. Initialize the vector as empty.
*/
Vector ();
/**
- * Constructor. Set dimension to
- * @p n and initialize all
- * elements with zero.
+ * Constructor. Set dimension to @p n and initialize all elements with
+ * zero.
*
- * The constructor is made explicit to
- * avoid accidents like this:
- * <tt>v=0;</tt>. Presumably, the user wants
- * to set every element of the vector to
- * zero, but instead, what happens is
- * this call: <tt>v=Vector@<number@>(0);</tt>,
- * i.e. the vector is replaced by one of
+ * The constructor is made explicit to avoid accidents like this:
+ * <tt>v=0;</tt>. Presumably, the user wants to set every element of the
+ * vector to zero, but instead, what happens is this call:
+ * <tt>v=Vector@<number@>(0);</tt>, i.e. the vector is replaced by one of
* length zero.
*/
explicit Vector (const size_type n);
/**
- * Copy-constructor from deal.II
- * vectors. Sets the dimension to that
- * of the given vector, and copies all
- * elements.
+ * Copy-constructor from deal.II vectors. Sets the dimension to that of
+ * the given vector, and copies all elements.
*/
template <typename Number>
explicit Vector (const dealii::Vector<Number> &v);
/**
- * Construct it from an existing PETSc
- * Vector of type Vec. Note: this does
- * not copy the contents and just keeps
- * a pointer. You need to make sure the
- * vector is not used twice at the same
- * time or destroyed while in use. This
- * class does not destroy the PETSc
- * object. Handle with care!
+ * Construct it from an existing PETSc Vector of type Vec. Note: this does
+ * not copy the contents and just keeps a pointer. You need to make sure
+ * the vector is not used twice at the same time or destroyed while in
+ * use. This class does not destroy the PETSc object. Handle with care!
*/
explicit Vector (const Vec &v);
/**
- * Copy-constructor the values from a
- * PETSc wrapper vector class.
+ * Copy-constructor the values from a PETSc wrapper vector class.
*/
Vector (const Vector &v);
/**
- * Copy-constructor: copy the values
- * from a PETSc wrapper parallel vector
+ * Copy-constructor: copy the values from a PETSc wrapper parallel vector
* class.
*
- * Note that due to the communication
- * model of MPI, @em all processes have
- * to actually perform this operation,
- * even if they do not use the
- * result. It is not sufficient if only
- * one processor tries to copy the
- * elements from the other processors
- * over to its own process space.
+ * Note that due to the communication model of MPI, @em all processes have
+ * to actually perform this operation, even if they do not use the result.
+ * It is not sufficient if only one processor tries to copy the elements
+ * from the other processors over to its own process space.
*/
explicit Vector (const MPI::Vector &v);
/**
- * Copy the given vector. Resize the
- * present vector if necessary.
+ * Copy the given vector. Resize the present vector if necessary.
*/
Vector &operator = (const Vector &v);
/**
- * Copy all the elements of the
- * parallel vector @p v into this
- * local vector. Note that due to the
- * communication model of MPI, @em all
- * processes have to actually perform
- * this operation, even if they do not
- * use the result. It is not sufficient
- * if only one processor tries to copy
- * the elements from the other
- * processors over to its own process
+ * Copy all the elements of the parallel vector @p v into this local
+ * vector. Note that due to the communication model of MPI, @em all
+ * processes have to actually perform this operation, even if they do not
+ * use the result. It is not sufficient if only one processor tries to
+ * copy the elements from the other processors over to its own process
* space.
*/
Vector &operator = (const MPI::Vector &v);
/**
- * Set all components of the vector to
- * the given number @p s. Simply pass
- * this down to the base class, but we
- * still need to declare this function
- * to make the example given in the
- * discussion about making the
+ * Set all components of the vector to the given number @p s. Simply pass
+ * this down to the base class, but we still need to declare this function
+ * to make the example given in the discussion about making the
* constructor explicit work.
*
- * Since the semantics of assigning a
- * scalar to a vector are not
- * immediately clear, this operator
- * should really only be used if you
- * want to set the entire vector to
- * zero. This allows the intuitive
- * notation <tt>v=0</tt>. Assigning
- * other values is deprecated and may
- * be disallowed in the future.
+ * Since the semantics of assigning a scalar to a vector are not
+ * immediately clear, this operator should really only be used if you want
+ * to set the entire vector to zero. This allows the intuitive notation
+ * <tt>v=0</tt>. Assigning other values is deprecated and may be
+ * disallowed in the future.
*/
Vector &operator = (const PetscScalar s);
/**
- * Copy the values of a deal.II vector
- * (as opposed to those of the PETSc
- * vector wrapper class) into this
- * object.
+ * Copy the values of a deal.II vector (as opposed to those of the PETSc
+ * vector wrapper class) into this object.
*/
template <typename number>
Vector &operator = (const dealii::Vector<number> &v);
/**
- * Change the dimension of the vector
- * to @p N. It is unspecified how
- * resizing the vector affects the
- * memory allocation of this object;
- * i.e., it is not guaranteed that
- * resizing it to a smaller size
- * actually also reduces memory
- * consumption, or if for efficiency
- * the same amount of memory is used
- * for less data.
+ * Change the dimension of the vector to @p N. It is unspecified how
+ * resizing the vector affects the memory allocation of this object; i.e.,
+ * it is not guaranteed that resizing it to a smaller size actually also
+ * reduces memory consumption, or if for efficiency the same amount of
+ * memory is used for less data.
*
- * If @p fast is false, the vector is
- * filled by zeros. Otherwise, the
- * elements are left an unspecified
- * state.
+ * If @p fast is false, the vector is filled by zeros. Otherwise, the
+ * elements are left an unspecified state.
*/
void reinit (const size_type N,
const bool fast = false);
/**
- * Change the dimension to that of the
- * vector @p v. The same applies as
+ * Change the dimension to that of the vector @p v. The same applies as
* for the other reinit() function.
*
- * The elements of @p v are not
- * copied, i.e. this function is the
- * same as calling <tt>reinit (v.size(),
- * fast)</tt>.
+ * The elements of @p v are not copied, i.e. this function is the same as
+ * calling <tt>reinit (v.size(), fast)</tt>.
*/
void reinit (const Vector &v,
const bool fast = false);
protected:
/**
- * Create a vector of length @p n. For
- * this class, we create a sequential
- * vector. @p n denotes the total
- * size of the vector to be
- * created.
+ * Create a vector of length @p n. For this class, we create a sequential
+ * vector. @p n denotes the total size of the vector to be created.
*/
void create_vector (const size_type n);
};
/**
- * Global function @p swap which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two vectors.
+ * Global function @p swap which overloads the default implementation of the
+ * C++ standard library which uses a temporary object. The function simply
+ * exchanges the data of the two vectors.
*
* @relates PETScWrappers::Vector
* @author Wolfgang Bangerth, 2004
namespace internal
{
/**
- * Since access to PETSc vectors only
- * goes through functions, rather than by
- * obtaining a reference to a vector
- * element, we need a wrapper class that
- * acts as if it was a reference, and
- * basically redirects all accesses (read
- * and write) to member functions of this
- * class.
+ * Since access to PETSc vectors only goes through functions, rather than
+ * by obtaining a reference to a vector element, we need a wrapper class
+ * that acts as if it was a reference, and basically redirects all
+ * accesses (read and write) to member functions of this class.
*
- * This class implements such a wrapper:
- * it is initialized with a vector and an
- * element within it, and has a
- * conversion operator to extract the
- * scalar value of this element. It also
- * has a variety of assignment operator
- * for writing to this one element.
+ * This class implements such a wrapper: it is initialized with a vector
+ * and an element within it, and has a conversion operator to extract the
+ * scalar value of this element. It also has a variety of assignment
+ * operator for writing to this one element.
* @ingroup PETScWrappers
*/
class VectorReference
private:
/**
- * Constructor. It is made private so
- * as to only allow the actual vector
+ * Constructor. It is made private so as to only allow the actual vector
* class to create it.
*/
VectorReference (const VectorBase &vector,
public:
/**
- * This looks like a copy operator,
- * but does something different than
- * usual. In particular, it does not
- * copy the member variables of this
- * reference. Rather, it handles the
- * situation where we have two
- * vectors @p v and @p w, and assign
- * elements like in
- * <tt>v(i)=w(i)</tt>. Here, both
- * left and right hand side of the
- * assignment have data type
- * VectorReference, but what we
- * really mean is to assign the
- * vector elements represented by the
- * two references. This operator
- * implements this operation. Note
- * also that this allows us to make
- * the assignment operator const.
+ * This looks like a copy operator, but does something different than
+ * usual. In particular, it does not copy the member variables of this
+ * reference. Rather, it handles the situation where we have two vectors
+ * @p v and @p w, and assign elements like in <tt>v(i)=w(i)</tt>. Here,
+ * both left and right hand side of the assignment have data type
+ * VectorReference, but what we really mean is to assign the vector
+ * elements represented by the two references. This operator implements
+ * this operation. Note also that this allows us to make the assignment
+ * operator const.
*/
const VectorReference &operator = (const VectorReference &r) const;
/**
- * The same function as above, but
- * for non-const reference
- * objects. The function is needed
- * since the compiler might otherwise
- * automatically generate a copy
- * operator for non-const objects.
+ * The same function as above, but for non-const reference objects. The
+ * function is needed since the compiler might otherwise automatically
+ * generate a copy operator for non-const objects.
*/
VectorReference &operator = (const VectorReference &r);
/**
- * Set the referenced element of the
- * vector to <tt>s</tt>.
+ * Set the referenced element of the vector to <tt>s</tt>.
*/
const VectorReference &operator = (const PetscScalar &s) const;
/**
- * Add <tt>s</tt> to the referenced
- * element of the vector.
+ * Add <tt>s</tt> to the referenced element of the vector.
*/
const VectorReference &operator += (const PetscScalar &s) const;
/**
- * Subtract <tt>s</tt> from the
- * referenced element of the vector.
+ * Subtract <tt>s</tt> from the referenced element of the vector.
*/
const VectorReference &operator -= (const PetscScalar &s) const;
/**
- * Multiply the referenced element of
- * the vector by <tt>s</tt>.
+ * Multiply the referenced element of the vector by <tt>s</tt>.
*/
const VectorReference &operator *= (const PetscScalar &s) const;
/**
- * Divide the referenced element of
- * the vector by <tt>s</tt>.
+ * Divide the referenced element of the vector by <tt>s</tt>.
*/
const VectorReference &operator /= (const PetscScalar &s) const;
/**
- * Convert the reference to an actual
- * value, i.e. return the value of
- * the referenced element of the
- * vector.
+ * Convert the reference to an actual value, i.e. return the value of
+ * the referenced element of the vector.
*/
operator PetscScalar () const;
private:
/**
- * Point to the vector we are
- * referencing.
+ * Point to the vector we are referencing.
*/
const VectorBase &vector;
/**
- * Index of the referenced element of
- * the vector.
+ * Index of the referenced element of the vector.
*/
const size_type index;
/**
- * Make the vector class a friend, so
- * that it can create objects of the
+ * Make the vector class a friend, so that it can create objects of the
* present type.
*/
friend class ::dealii::PETScWrappers::VectorBase;
/**
- * Base class for all vector classes that are implemented on top of the PETSc
- * vector types. Since in PETSc all vector types (i.e. sequential and parallel
- * ones) are built by filling the contents of an abstract object that is only
- * referenced through a pointer of a type that is independent of the actual
- * vector type, we can implement almost all functionality of vectors in this
- * base class. Derived classes will then only have to provide the
- * functionality to create one or the other kind of vector.
+ * Base class for all vector classes that are implemented on top of the
+ * PETSc vector types. Since in PETSc all vector types (i.e. sequential and
+ * parallel ones) are built by filling the contents of an abstract object
+ * that is only referenced through a pointer of a type that is independent
+ * of the actual vector type, we can implement almost all functionality of
+ * vectors in this base class. Derived classes will then only have to
+ * provide the functionality to create one or the other kind of vector.
*
- * The interface of this class is modeled after the existing Vector
- * class in deal.II. It has almost the same member functions, and is often
+ * The interface of this class is modeled after the existing Vector class in
+ * deal.II. It has almost the same member functions, and is often
* exchangable. However, since PETSc only supports a single scalar type
* (either double, float, or a complex data type), it is not templated, and
- * only works with whatever your PETSc installation has defined the data type
- * @p PetscScalar to.
+ * only works with whatever your PETSc installation has defined the data
+ * type @p PetscScalar to.
*
* Note that PETSc only guarantees that operations do what you expect if the
* functions @p VecAssemblyBegin and @p VecAssemblyEnd have been called
{
public:
/**
- * Declare some of the standard types
- * used in all containers. These types
- * parallel those in the <tt>C++</tt>
- * standard libraries <tt>vector<...></tt>
- * class.
+ * Declare some of the standard types used in all containers. These types
+ * parallel those in the <tt>C++</tt> standard libraries
+ * <tt>vector<...></tt> class.
*/
typedef PetscScalar value_type;
typedef PetscReal real_type;
typedef const internal::VectorReference const_reference;
/**
- * Default constructor. It doesn't do
- * anything, derived classes will have
+ * Default constructor. It doesn't do anything, derived classes will have
* to initialize the data.
*/
VectorBase ();
/**
- * Copy constructor. Sets the dimension
- * to that of the given vector, and
+ * Copy constructor. Sets the dimension to that of the given vector, and
* copies all elements.
*/
VectorBase (const VectorBase &v);
/**
- * Initialize a Vector from a PETSc Vec
- * object. Note that we do not copy the
- * vector and we do not attain
- * ownership, so we do not destroy the
+ * Initialize a Vector from a PETSc Vec object. Note that we do not copy
+ * the vector and we do not attain ownership, so we do not destroy the
* PETSc object in the destructor.
*/
explicit VectorBase (const Vec &v);
virtual ~VectorBase ();
/**
- * Compress the underlying
- * representation of the PETSc object,
- * i.e. flush the buffers of the vector
- * object if it has any. This function
- * is necessary after writing into a
- * vector element-by-element and before
+ * Compress the underlying representation of the PETSc object, i.e. flush
+ * the buffers of the vector object if it has any. This function is
+ * necessary after writing into a vector element-by-element and before
* anything else can be done on it.
*
- * See @ref GlossCompress "Compressing distributed objects"
- * for more information.
+ * See @ref GlossCompress "Compressing distributed objects" for more
+ * information.
*/
void compress (::dealii::VectorOperation::values operation);
void compress () DEAL_II_DEPRECATED;
/**
- * Set all components of the vector to
- * the given number @p s. Simply pass
- * this down to the individual block
- * objects, but we still need to declare
- * this function to make the example
- * given in the discussion about making
+ * Set all components of the vector to the given number @p s. Simply pass
+ * this down to the individual block objects, but we still need to declare
+ * this function to make the example given in the discussion about making
* the constructor explicit work.
*
*
- * Since the semantics of assigning a
- * scalar to a vector are not
- * immediately clear, this operator
- * should really only be used if you
- * want to set the entire vector to
- * zero. This allows the intuitive
- * notation <tt>v=0</tt>. Assigning
- * other values is deprecated and may
- * be disallowed in the future.
+ * Since the semantics of assigning a scalar to a vector are not
+ * immediately clear, this operator should really only be used if you want
+ * to set the entire vector to zero. This allows the intuitive notation
+ * <tt>v=0</tt>. Assigning other values is deprecated and may be
+ * disallowed in the future.
*/
VectorBase &operator = (const PetscScalar s);
/**
- * Test for equality. This function
- * assumes that the present vector and
- * the one to compare with have the same
- * size already, since comparing vectors
- * of different sizes makes not much
- * sense anyway.
+ * Test for equality. This function assumes that the present vector and
+ * the one to compare with have the same size already, since comparing
+ * vectors of different sizes makes not much sense anyway.
*/
bool operator == (const VectorBase &v) const;
/**
- * Test for inequality. This function
- * assumes that the present vector and
- * the one to compare with have the same
- * size already, since comparing vectors
- * of different sizes makes not much
- * sense anyway.
+ * Test for inequality. This function assumes that the present vector and
+ * the one to compare with have the same size already, since comparing
+ * vectors of different sizes makes not much sense anyway.
*/
bool operator != (const VectorBase &v) const;
/**
- * Return the global dimension of the
- * vector.
+ * Return the global dimension of the vector.
*/
size_type size () const;
/**
- * Return the local dimension of the
- * vector, i.e. the number of elements
- * stored on the present MPI
- * process. For sequential vectors,
- * this number is the same as size(),
- * but for parallel vectors it may be
- * smaller.
+ * Return the local dimension of the vector, i.e. the number of elements
+ * stored on the present MPI process. For sequential vectors, this number
+ * is the same as size(), but for parallel vectors it may be smaller.
*
- * To figure out which elements
- * exactly are stored locally,
- * use local_range().
+ * To figure out which elements exactly are stored locally, use
+ * local_range().
*/
size_type local_size () const;
/**
- * Return a pair of indices
- * indicating which elements of
- * this vector are stored
- * locally. The first number is
- * the index of the first
- * element stored, the second
- * the index of the one past
- * the last one that is stored
- * locally. If this is a
- * sequential vector, then the
- * result will be the pair
- * (0,N), otherwise it will be
- * a pair (i,i+n), where
+ * Return a pair of indices indicating which elements of this vector are
+ * stored locally. The first number is the index of the first element
+ * stored, the second the index of the one past the last one that is
+ * stored locally. If this is a sequential vector, then the result will be
+ * the pair (0,N), otherwise it will be a pair (i,i+n), where
* <tt>n=local_size()</tt>.
*/
std::pair<size_type, size_type>
local_range () const;
/**
- * Return whether @p index is
- * in the local range or not,
- * see also local_range().
+ * Return whether @p index is in the local range or not, see also
+ * local_range().
*/
bool in_local_range (const size_type index) const;
/**
- * Return an index set that describes which elements of this vector
- * are owned by the current processor. Note that this index set does
- * not include elements this vector may store locally as ghost
- * elements but that are in fact owned by another processor.
- * As a consequence, the index sets returned on different
- * processors if this is a distributed vector will form disjoint
- * sets that add up to the complete index set.
- * Obviously, if a vector is created on only one processor, then
- * the result would satisfy
+ * Return an index set that describes which elements of this vector are
+ * owned by the current processor. Note that this index set does not
+ * include elements this vector may store locally as ghost elements but
+ * that are in fact owned by another processor. As a consequence, the
+ * index sets returned on different processors if this is a distributed
+ * vector will form disjoint sets that add up to the complete index set.
+ * Obviously, if a vector is created on only one processor, then the
+ * result would satisfy
* @code
* vec.locally_owned_elements() == complete_index_set (vec.size())
* @endcode
IndexSet locally_owned_elements () const;
/**
- * Return if the vector contains ghost
- * elements.
+ * Return if the vector contains ghost elements.
*
* @see @ref GlossGhostedVector "vectors with ghost elements"
*/
bool has_ghost_elements() const;
/**
- * Provide access to a given element,
- * both read and write.
+ * Provide access to a given element, both read and write.
*/
reference
operator () (const size_type index);
/**
- * Provide read-only access to an
- * element.
+ * Provide read-only access to an element.
*/
PetscScalar
operator () (const size_type index) const;
/**
- * Provide access to a given
- * element, both read and write.
+ * Provide access to a given element, both read and write.
*
* Exactly the same as operator().
*/
operator [] (const size_type index);
/**
- * Provide read-only access to an
- * element. This is equivalent to
- * the <code>el()</code> command.
+ * Provide read-only access to an element. This is equivalent to the
+ * <code>el()</code> command.
*
* Exactly the same as operator().
*/
operator [] (const size_type index) const;
/**
- * A collective set operation: instead
- * of setting individual elements of a
- * vector, this function allows to set
- * a whole set of elements at once. The
- * indices of the elements to be set
- * are stated in the first argument,
- * the corresponding values in the
- * second.
+ * A collective set operation: instead of setting individual elements of a
+ * vector, this function allows to set a whole set of elements at once.
+ * The indices of the elements to be set are stated in the first argument,
+ * the corresponding values in the second.
*/
void set (const std::vector<size_type> &indices,
const std::vector<PetscScalar> &values);
/**
- * A collective get operation: instead
- * of getting individual elements of a
- * vector, this function allows to get
- * a whole set of elements at once. The
- * indices of the elements to be read
- * are stated in the first argument,
- * the corresponding values are returned in the
- * second.
+ * A collective get operation: instead of getting individual elements of a
+ * vector, this function allows to get a whole set of elements at once.
+ * The indices of the elements to be read are stated in the first
+ * argument, the corresponding values are returned in the second.
*/
void extract_subvector_to (const std::vector<size_type> &indices,
std::vector<PetscScalar> &values) const;
/**
- * Just as the above, but with pointers.
- * Useful in minimizing copying of data around.
+ * Just as the above, but with pointers. Useful in minimizing copying of
+ * data around.
*/
template <typename ForwardIterator, typename OutputIterator>
void extract_subvector_to (const ForwardIterator indices_begin,
OutputIterator values_begin) const;
/**
- * A collective add operation: This
- * function adds a whole set of values
- * stored in @p values to the vector
- * components specified by @p indices.
+ * A collective add operation: This function adds a whole set of values
+ * stored in @p values to the vector components specified by @p indices.
*/
void add (const std::vector<size_type> &indices,
const std::vector<PetscScalar> &values);
/**
- * This is a second collective
- * add operation. As a
- * difference, this function
- * takes a deal.II vector of
- * values.
+ * This is a second collective add operation. As a difference, this
+ * function takes a deal.II vector of values.
*/
void add (const std::vector<size_type> &indices,
const ::dealii::Vector<PetscScalar> &values);
/**
- * Take an address where
- * <tt>n_elements</tt> are stored
- * contiguously and add them into
- * the vector. Handles all cases
- * which are not covered by the
- * other two <tt>add()</tt>
- * functions above.
+ * Take an address where <tt>n_elements</tt> are stored contiguously and
+ * add them into the vector. Handles all cases which are not covered by
+ * the other two <tt>add()</tt> functions above.
*/
void add (const size_type n_elements,
const size_type *indices,
const PetscScalar *values);
/**
- * Return the scalar product of two
- * vectors. The vectors must have the
+ * Return the scalar product of two vectors. The vectors must have the
* same size.
*/
PetscScalar operator * (const VectorBase &vec) const;
PetscScalar mean_value () const;
/**
- * $l_1$-norm of the vector.
- * The sum of the absolute values.
+ * $l_1$-norm of the vector. The sum of the absolute values.
*/
real_type l1_norm () const;
/**
- * $l_2$-norm of the vector. The
- * square root of the sum of the
- * squares of the elements.
+ * $l_2$-norm of the vector. The square root of the sum of the squares of
+ * the elements.
*/
real_type l2_norm () const;
/**
- * $l_p$-norm of the vector. The
- * pth root of the sum of the pth
- * powers of the absolute values
- * of the elements.
+ * $l_p$-norm of the vector. The pth root of the sum of the pth powers of
+ * the absolute values of the elements.
*/
real_type lp_norm (const real_type p) const;
/**
- * $l_\infty$-norm of the vector. Return the value of the vector
- * element with the maximum absolute value.
+ * $l_\infty$-norm of the vector. Return the value of the vector element
+ * with the maximum absolute value.
*/
real_type linfty_norm () const;
const VectorBase &W);
/**
- * Normalize vector by dividing by the $l_2$-norm of the
- * vector. Return the vector norm before normalization.
+ * Normalize vector by dividing by the $l_2$-norm of the vector. Return
+ * the vector norm before normalization.
*/
real_type normalize () const;
VectorBase &conjugate ();
/**
- * A collective piecewise
- * multiply operation on
- * <code>this</code> vector
- * with itself. TODO: The model
- * for this function should be
- * similer to add ().
+ * A collective piecewise multiply operation on <code>this</code> vector
+ * with itself. TODO: The model for this function should be similer to add
+ * ().
*/
VectorBase &mult ();
/**
- * Same as above, but a
- * collective piecewise
- * multiply operation of
- * <code>this</code> vector
- * with <b>v</b>.
+ * Same as above, but a collective piecewise multiply operation of
+ * <code>this</code> vector with <b>v</b>.
*/
VectorBase &mult (const VectorBase &v);
/**
- * Same as above, but a
- * collective piecewise
- * multiply operation of
+ * Same as above, but a collective piecewise multiply operation of
* <b>u</b> with <b>v</b>.
*/
VectorBase &mult (const VectorBase &u,
const VectorBase &v);
/**
- * Return whether the vector contains only elements with value
- * zero. This is a collective operation. This function is expensive, because
+ * Return whether the vector contains only elements with value zero. This
+ * is a collective operation. This function is expensive, because
* potentially all elements have to be checked.
*/
bool all_zero () const;
/**
- * Return @p true if the vector has no
- * negative entries, i.e. all entries
- * are zero or positive. This function
- * is used, for example, to check
- * whether refinement indicators are
- * really all positive (or zero).
+ * Return @p true if the vector has no negative entries, i.e. all entries
+ * are zero or positive. This function is used, for example, to check
+ * whether refinement indicators are really all positive (or zero).
*/
bool is_non_negative () const;
/**
- * Multiply the entire vector by a
- * fixed factor.
+ * Multiply the entire vector by a fixed factor.
*/
VectorBase &operator *= (const PetscScalar factor);
/**
- * Divide the entire vector by a
- * fixed factor.
+ * Divide the entire vector by a fixed factor.
*/
VectorBase &operator /= (const PetscScalar factor);
/**
- * Add the given vector to the present
- * one.
+ * Add the given vector to the present one.
*/
VectorBase &operator += (const VectorBase &V);
/**
- * Subtract the given vector from the
- * present one.
+ * Subtract the given vector from the present one.
*/
VectorBase &operator -= (const VectorBase &V);
/**
- * Addition of @p s to all
- * components. Note that @p s is a
- * scalar and not a vector.
+ * Addition of @p s to all components. Note that @p s is a scalar and not
+ * a vector.
*/
void add (const PetscScalar s);
/**
- * Simple vector addition, equal to the
- * <tt>operator +=</tt>.
+ * Simple vector addition, equal to the <tt>operator +=</tt>.
*/
void add (const VectorBase &V);
/**
- * Simple addition of a multiple of a
- * vector, i.e. <tt>*this += a*V</tt>.
+ * Simple addition of a multiple of a vector, i.e. <tt>*this += a*V</tt>.
*/
void add (const PetscScalar a, const VectorBase &V);
/**
- * Multiple addition of scaled vectors,
- * i.e. <tt>*this += a*V+b*W</tt>.
+ * Multiple addition of scaled vectors, i.e. <tt>*this += a*V+b*W</tt>.
*/
void add (const PetscScalar a, const VectorBase &V,
const PetscScalar b, const VectorBase &W);
/**
- * Scaling and simple vector addition,
- * i.e.
- * <tt>*this = s*(*this)+V</tt>.
+ * Scaling and simple vector addition, i.e. <tt>*this = s*(*this)+V</tt>.
*/
void sadd (const PetscScalar s,
const VectorBase &V);
/**
- * Scaling and simple addition, i.e.
- * <tt>*this = s*(*this)+a*V</tt>.
+ * Scaling and simple addition, i.e. <tt>*this = s*(*this)+a*V</tt>.
*/
void sadd (const PetscScalar s,
const PetscScalar a,
const VectorBase &W);
/**
- * Scaling and multiple addition.
- * <tt>*this = s*(*this)+a*V + b*W + c*X</tt>.
+ * Scaling and multiple addition. <tt>*this = s*(*this)+a*V + b*W +
+ * c*X</tt>.
*/
void sadd (const PetscScalar s,
const PetscScalar a,
const VectorBase &X);
/**
- * Scale each element of this
- * vector by the corresponding
- * element in the argument. This
- * function is mostly meant to
- * simulate multiplication (and
- * immediate re-assignment) by a
- * diagonal scaling matrix.
+ * Scale each element of this vector by the corresponding element in the
+ * argument. This function is mostly meant to simulate multiplication (and
+ * immediate re-assignment) by a diagonal scaling matrix.
*/
void scale (const VectorBase &scaling_factors);
const PetscScalar b, const VectorBase &W);
/**
- * Compute the elementwise ratio of the
- * two given vectors, that is let
- * <tt>this[i] = a[i]/b[i]</tt>. This is
- * useful for example if you want to
- * compute the cellwise ratio of true to
- * estimated error.
+ * Compute the elementwise ratio of the two given vectors, that is let
+ * <tt>this[i] = a[i]/b[i]</tt>. This is useful for example if you want to
+ * compute the cellwise ratio of true to estimated error.
*
- * This vector is appropriately
- * scaled to hold the result.
+ * This vector is appropriately scaled to hold the result.
*
- * If any of the <tt>b[i]</tt> is
- * zero, the result is
- * undefined. No attempt is made
- * to catch such situations.
+ * If any of the <tt>b[i]</tt> is zero, the result is undefined. No
+ * attempt is made to catch such situations.
*/
void ratio (const VectorBase &a,
const VectorBase &b);
/**
- * Updates the ghost values of this
- * vector. As ghosted vectors are now read-only and assignments
- * from a non-ghosted vector update the ghost values automatically,
- * this method does not need to be called in user code.
+ * Updates the ghost values of this vector. As ghosted vectors are now
+ * read-only and assignments from a non-ghosted vector update the ghost
+ * values automatically, this method does not need to be called in user
+ * code.
* @deprecated: calling this method is no longer necessary.
*/
void update_ghost_values() const DEAL_II_DEPRECATED;
/**
- * Prints the PETSc vector object values
- * using PETSc internal vector viewer function
- * <tt>VecView</tt>. The default format prints
- * the vector's contents, including indices of
- * vector elements. For other valid view formats,
- * consult
- * http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/VecView.html
+ * Prints the PETSc vector object values using PETSc internal vector
+ * viewer function <tt>VecView</tt>. The default format prints the
+ * vector's contents, including indices of vector elements. For other
+ * valid view formats, consult http://www.mcs.anl.gov/petsc/petsc-
+ * current/docs/manualpages/Vec/VecView.html
*/
void write_ascii (const PetscViewerFormat format = PETSC_VIEWER_DEFAULT) ;
/**
- * Print to a
- * stream. @p precision denotes
- * the desired precision with
- * which values shall be printed,
- * @p scientific whether
- * scientific notation shall be
- * used. If @p across is
- * @p true then the vector is
- * printed in a line, while if
- * @p false then the elements
- * are printed on a separate line
- * each.
+ * Print to a stream. @p precision denotes the desired precision with
+ * which values shall be printed, @p scientific whether scientific
+ * notation shall be used. If @p across is @p true then the vector is
+ * printed in a line, while if @p false then the elements are printed on a
+ * separate line each.
*/
void print (std::ostream &out,
const unsigned int precision = 3,
const bool across = true) const;
/**
- * Swap the contents of this
- * vector and the other vector
- * @p v. One could do this
- * operation with a temporary
- * variable and copying over the
- * data elements, but this
- * function is significantly more
- * efficient since it only swaps
- * the pointers to the data of
- * the two vectors and therefore
- * does not need to allocate
- * temporary storage and move
- * data around.
+ * Swap the contents of this vector and the other vector @p v. One could
+ * do this operation with a temporary variable and copying over the data
+ * elements, but this function is significantly more efficient since it
+ * only swaps the pointers to the data of the two vectors and therefore
+ * does not need to allocate temporary storage and move data around.
*
- * This function is analog to the
- * the @p swap function of all C++
- * standard containers. Also,
- * there is a global function
- * <tt>swap(u,v)</tt> that simply calls
- * <tt>u.swap(v)</tt>, again in analogy
- * to standard functions.
+ * This function is analog to the the @p swap function of all C++ standard
+ * containers. Also, there is a global function <tt>swap(u,v)</tt> that
+ * simply calls <tt>u.swap(v)</tt>, again in analogy to standard
+ * functions.
*/
void swap (VectorBase &v);
/**
- * Conversion operator to gain access
- * to the underlying PETSc type. If you
- * do this, you cut this class off some
- * information it may need, so this
- * conversion operator should only be
- * used if you know what you do. In
- * particular, it should only be used
- * for read-only operations into the
+ * Conversion operator to gain access to the underlying PETSc type. If you
+ * do this, you cut this class off some information it may need, so this
+ * conversion operator should only be used if you know what you do. In
+ * particular, it should only be used for read-only operations into the
* vector.
*/
operator const Vec &() const;
/**
- * Estimate for the memory
- * consumption (not implemented
- * for this class).
+ * Estimate for the memory consumption (not implemented for this class).
*/
std::size_t memory_consumption () const;
/**
- * Return a reference to the MPI
- * communicator object in use with this
+ * Return a reference to the MPI communicator object in use with this
* object.
*/
virtual const MPI_Comm &get_mpi_communicator () const;
protected:
/**
- * A generic vector object in
- * PETSc. The actual type, a sequential
- * vector, is set in the constructor.
+ * A generic vector object in PETSc. The actual type, a sequential vector,
+ * is set in the constructor.
*/
Vec vector;
/**
- * Denotes if this vector has ghost
- * indices associated with it. This
- * means that at least one of the
- * processes in a parallel programm has
- * at least one ghost index.
+ * Denotes if this vector has ghost indices associated with it. This means
+ * that at least one of the processes in a parallel programm has at least
+ * one ghost index.
*/
bool ghosted;
/**
- * This vector contains the global
- * indices of the ghost values. The
- * location in this vector denotes the
- * local numbering, which is used in
+ * This vector contains the global indices of the ghost values. The
+ * location in this vector denotes the local numbering, which is used in
* PETSc.
*/
IndexSet ghost_indices;
/**
- * Store whether the last action was a
- * write or add operation. This
- * variable is @p mutable so that the
- * accessor classes can write to it,
- * even though the vector object they
- * refer to is constant.
+ * Store whether the last action was a write or add operation. This
+ * variable is @p mutable so that the accessor classes can write to it,
+ * even though the vector object they refer to is constant.
*/
mutable ::dealii::VectorOperation::values last_action;
friend class internal::VectorReference;
/**
- * Specifies if the vector is the owner
- * of the PETSc Vec. This is true if it
- * got created by this class and
- * determines if it gets destructed in
+ * Specifies if the vector is the owner of the PETSc Vec. This is true if
+ * it got created by this class and determines if it gets destructed in
* the destructor.
*/
bool attained_ownership;
/**
- * Collective set or add
- * operation: This function is
- * invoked by the collective @p
- * set and @p add with the
- * @p add_values flag set to the
+ * Collective set or add operation: This function is invoked by the
+ * collective @p set and @p add with the @p add_values flag set to the
* corresponding value.
*/
void do_set_add_operation (const size_type n_elements,
// ------------------- inline and template functions --------------
/**
- * Global function @p swap which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two vectors.
+ * Global function @p swap which overloads the default implementation of the
+ * C++ standard library which uses a temporary object. The function simply
+ * exchanges the data of the two vectors.
*
* @relates PETScWrappers::VectorBase
* @author Wolfgang Bangerth, 2004
*/
/**
- * Abstract class for use in iterations. This class provides the
- * interface required by LAC solver classes. It allows to use
- * different concrete matrix classes in the same context, as long as
- * they apply to the same vector class.
+ * Abstract class for use in iterations. This class provides the interface
+ * required by LAC solver classes. It allows to use different concrete matrix
+ * classes in the same context, as long as they apply to the same vector
+ * class.
*
* @author Guido Kanschat, 2000, 2001, 2002
*/
{
public:
/**
- * Value type of this
- * matrix. since the matrix
- * itself is unknown, we take the
- * value type of the
- * vector. Therefore, matrix
- * entries must be convertible to
- * vector entries.
+ * Value type of this matrix. since the matrix itself is unknown, we take
+ * the value type of the vector. Therefore, matrix entries must be
+ * convertible to vector entries.
*
- * This was defined to make this
- * matrix a possible template
- * argument to
+ * This was defined to make this matrix a possible template argument to
* BlockMatrixArray.
*/
typedef typename VECTOR::value_type value_type;
/**
- * Virtual destructor. Does
- * nothing except making sure that
- * the destructor of any derived
- * class is called whenever a pointer-to-base-class object is destroyed.
+ * Virtual destructor. Does nothing except making sure that the destructor
+ * of any derived class is called whenever a pointer-to-base-class object is
+ * destroyed.
*/
virtual ~PointerMatrixBase ();
const VECTOR &src) const = 0;
/**
- * Matrix-vector product, adding to
- * <tt>dst</tt>.
+ * Matrix-vector product, adding to <tt>dst</tt>.
*/
virtual void vmult_add (VECTOR &dst,
const VECTOR &src) const = 0;
/**
- * Transposed matrix-vector product,
- * adding to <tt>dst</tt>.
+ * Transposed matrix-vector product, adding to <tt>dst</tt>.
*/
virtual void Tvmult_add (VECTOR &dst,
const VECTOR &src) const = 0;
/**
- * A pointer to be used as a matrix. This class stores a pointer to a
- * matrix and can be used as a matrix itself in iterative methods.
+ * A pointer to be used as a matrix. This class stores a pointer to a matrix
+ * and can be used as a matrix itself in iterative methods.
*
- * The main purpose for the existence of this class is its base class,
- * which only has a vector as template argument. Therefore, this
- * interface provides an abstract base class for matrices.
+ * The main purpose for the existence of this class is its base class, which
+ * only has a vector as template argument. Therefore, this interface provides
+ * an abstract base class for matrices.
*
* @author Guido Kanschat 2000, 2001, 2002
*/
{
public:
/**
- * Constructor. The pointer in the
- * argument is stored in this
- * class. As usual, the lifetime of
- * <tt>*M</tt> must be longer than the
- * one of the PointerMatrix.
+ * Constructor. The pointer in the argument is stored in this class. As
+ * usual, the lifetime of <tt>*M</tt> must be longer than the one of the
+ * PointerMatrix.
*
- * If <tt>M</tt> is zero, no
- * matrix is stored.
+ * If <tt>M</tt> is zero, no matrix is stored.
*/
PointerMatrix (const MATRIX *M=0);
* Constructor.
*
* This class internally stores a pointer to a matrix via a SmartPointer
- * object. The SmartPointer class allows to associate a name with the
- * object pointed to that identifies the object that has the pointer,
- * in order to identify objects that still refer to the object pointed to.
- * The @p name argument to this function
- * is used to this end, i.e., you can in essence assign a name to
- * the current PointerMatrix object.
+ * object. The SmartPointer class allows to associate a name with the object
+ * pointed to that identifies the object that has the pointer, in order to
+ * identify objects that still refer to the object pointed to. The @p name
+ * argument to this function is used to this end, i.e., you can in essence
+ * assign a name to the current PointerMatrix object.
*/
PointerMatrix(const char *name);
/**
- * Constructor. <tt>M</tt> points
- * to a matrix which must live
- * longer than the
- * PointerMatrix.
+ * Constructor. <tt>M</tt> points to a matrix which must live longer than
+ * the PointerMatrix.
*
* This class internally stores a pointer to a matrix via a SmartPointer
- * object. The SmartPointer class allows to associate a name with the
- * object pointed to that identifies the object that has the pointer,
- * in order to identify objects that still refer to the object pointed to.
- * The @p name argument to this function
- * is used to this end, i.e., you can in essence assign a name to
- * the current PointerMatrix object.
+ * object. The SmartPointer class allows to associate a name with the object
+ * pointed to that identifies the object that has the pointer, in order to
+ * identify objects that still refer to the object pointed to. The @p name
+ * argument to this function is used to this end, i.e., you can in essence
+ * assign a name to the current PointerMatrix object.
*/
PointerMatrix(const MATRIX *M,
const char *name);
virtual void clear();
/**
- * Return whether the object is
- * empty.
+ * Return whether the object is empty.
*/
bool empty () const;
/**
- * Assign a new matrix
- * pointer. Deletes the old pointer
- * and releases its matrix.
- * @see SmartPointer
+ * Assign a new matrix pointer. Deletes the old pointer and releases its
+ * matrix. @see SmartPointer
*/
const PointerMatrix &operator= (const MATRIX *M);
const VECTOR &src) const;
/**
- * Matrix-vector product, adding to
- * <tt>dst</tt>.
+ * Matrix-vector product, adding to <tt>dst</tt>.
*/
virtual void vmult_add (VECTOR &dst,
const VECTOR &src) const;
/**
- * Transposed matrix-vector product,
- * adding to <tt>dst</tt>.
+ * Transposed matrix-vector product, adding to <tt>dst</tt>.
*/
virtual void Tvmult_add (VECTOR &dst,
const VECTOR &src) const;
/**
- * A pointer to be used as a matrix. This class stores a pointer to a
- * matrix and can be used as a matrix itself in iterative methods.
+ * A pointer to be used as a matrix. This class stores a pointer to a matrix
+ * and can be used as a matrix itself in iterative methods.
*
- * The main purpose for the existence of this class is its base class,
- * which only has a vector as template argument. Therefore, this
- * interface provides an abstract base class for matrices.
+ * The main purpose for the existence of this class is its base class, which
+ * only has a vector as template argument. Therefore, this interface provides
+ * an abstract base class for matrices.
*
- * This class differs form PointerMatrix by its additional
- * VectorMemory object and by the fact that it implements the
- * functions vmult_add() and Tvmult_add() only using vmult() and
- * Tvmult() of the MATRIX.
+ * This class differs form PointerMatrix by its additional VectorMemory object
+ * and by the fact that it implements the functions vmult_add() and
+ * Tvmult_add() only using vmult() and Tvmult() of the MATRIX.
*
* @author Guido Kanschat 2006
*/
{
public:
/**
- * Constructor. The pointer in the
- * argument is stored in this
- * class. As usual, the lifetime of
- * <tt>*M</tt> must be longer than the
- * one of the PointerMatrixAux.
+ * Constructor. The pointer in the argument is stored in this class. As
+ * usual, the lifetime of <tt>*M</tt> must be longer than the one of the
+ * PointerMatrixAux.
*
- * If <tt>M</tt> is zero, no
- * matrix is stored.
+ * If <tt>M</tt> is zero, no matrix is stored.
*
- * If <tt>mem</tt> is zero, then
- * GrowingVectorMemory
- * is used.
+ * If <tt>mem</tt> is zero, then GrowingVectorMemory is used.
*/
PointerMatrixAux (VectorMemory<VECTOR> *mem = 0,
const MATRIX *M=0);
/**
- * Constructor not using a
- * matrix.
+ * Constructor not using a matrix.
*
* This class internally stores a pointer to a matrix via a SmartPointer
- * object. The SmartPointer class allows to associate a name with the
- * object pointed to that identifies the object that has the pointer,
- * in order to identify objects that still refer to the object pointed to.
- * The @p name argument to this function
- * is used to this end, i.e., you can in essence assign a name to
- * the current PointerMatrix object.
+ * object. The SmartPointer class allows to associate a name with the object
+ * pointed to that identifies the object that has the pointer, in order to
+ * identify objects that still refer to the object pointed to. The @p name
+ * argument to this function is used to this end, i.e., you can in essence
+ * assign a name to the current PointerMatrix object.
*/
PointerMatrixAux(VectorMemory<VECTOR> *mem,
const char *name);
/**
- * Constructor. <tt>M</tt> points
- * to a matrix which must live
- * longer than the
- * PointerMatrixAux.
+ * Constructor. <tt>M</tt> points to a matrix which must live longer than
+ * the PointerMatrixAux.
*
* This class internally stores a pointer to a matrix via a SmartPointer
- * object. The SmartPointer class allows to associate a name with the
- * object pointed to that identifies the object that has the pointer,
- * in order to identify objects that still refer to the object pointed to.
- * The @p name argument to this function
- * is used to this end, i.e., you can in essence assign a name to
- * the current PointerMatrix object.
+ * object. The SmartPointer class allows to associate a name with the object
+ * pointed to that identifies the object that has the pointer, in order to
+ * identify objects that still refer to the object pointed to. The @p name
+ * argument to this function is used to this end, i.e., you can in essence
+ * assign a name to the current PointerMatrix object.
*/
PointerMatrixAux(VectorMemory<VECTOR> *mem,
const MATRIX *M,
virtual void clear();
/**
- * Return whether the object is
- * empty.
+ * Return whether the object is empty.
*/
bool empty () const;
/**
- * Assign a new VectorMemory
- * object for getting auxiliary
- * vectors.
+ * Assign a new VectorMemory object for getting auxiliary vectors.
*/
void set_memory(VectorMemory<VECTOR> *mem);
/**
- * Assign a new matrix
- * pointer. Deletes the old pointer
- * and releases its matrix.
- * @see SmartPointer
+ * Assign a new matrix pointer. Deletes the old pointer and releases its
+ * matrix. @see SmartPointer
*/
const PointerMatrixAux &operator= (const MATRIX *M);
const VECTOR &src) const;
/**
- * Matrix-vector product, adding to
- * <tt>dst</tt>.
+ * Matrix-vector product, adding to <tt>dst</tt>.
*/
virtual void vmult_add (VECTOR &dst,
const VECTOR &src) const;
/**
- * Transposed matrix-vector product,
- * adding to <tt>dst</tt>.
+ * Transposed matrix-vector product, adding to <tt>dst</tt>.
*/
virtual void Tvmult_add (VECTOR &dst,
const VECTOR &src) const;
mutable GrowingVectorMemory<VECTOR> my_memory;
/**
- * Object for getting the
- * auxiliary vector.
+ * Object for getting the auxiliary vector.
*/
mutable SmartPointer<VectorMemory<VECTOR>,PointerMatrixAux<MATRIX,VECTOR> > mem;
/**
- * Implement matrix multiplications for a vector using the
- * PointerMatrixBase functionality. Objects of this
- * class can be used in block matrices.
+ * Implement matrix multiplications for a vector using the PointerMatrixBase
+ * functionality. Objects of this class can be used in block matrices.
*
- * Implements a matrix with image dimension 1 by using the scalar
- * product (#vmult()) and scalar multiplication (#Tvmult()) functions
- * of the Vector class.
+ * Implements a matrix with image dimension 1 by using the scalar product
+ * (#vmult()) and scalar multiplication (#Tvmult()) functions of the Vector
+ * class.
*
* @author Guido Kanschat, 2006
*/
{
public:
/**
- * Constructor. The pointer in the
- * argument is stored in this
- * class. As usual, the lifetime of
- * <tt>*M</tt> must be longer than the
- * one of the PointerMatrix.
+ * Constructor. The pointer in the argument is stored in this class. As
+ * usual, the lifetime of <tt>*M</tt> must be longer than the one of the
+ * PointerMatrix.
*
- * If <tt>M</tt> is zero, no
- * matrix is stored.
+ * If <tt>M</tt> is zero, no matrix is stored.
*/
PointerMatrixVector (const Vector<number> *M=0);
* Constructor.
*
* This class internally stores a pointer to a matrix via a SmartPointer
- * object. The SmartPointer class allows to associate a name with the
- * object pointed to that identifies the object that has the pointer,
- * in order to identify objects that still refer to the object pointed to.
- * The @p name argument to this function
- * is used to this end, i.e., you can in essence assign a name to
- * the current PointerMatrix object.
+ * object. The SmartPointer class allows to associate a name with the object
+ * pointed to that identifies the object that has the pointer, in order to
+ * identify objects that still refer to the object pointed to. The @p name
+ * argument to this function is used to this end, i.e., you can in essence
+ * assign a name to the current PointerMatrix object.
*/
PointerMatrixVector (const char *name);
/**
- * Constructor. <tt>M</tt> points
- * to a matrix which must live
- * longer than the
- * PointerMatrix.
+ * Constructor. <tt>M</tt> points to a matrix which must live longer than
+ * the PointerMatrix.
*
* This class internally stores a pointer to a matrix via a SmartPointer
- * object. The SmartPointer class allows to associate a name with the
- * object pointed to that identifies the object that has the pointer,
- * in order to identify objects that still refer to the object pointed to.
- * The @p name argument to this function
- * is used to this end, i.e., you can in essence assign a name to
- * the current PointerMatrix object.
+ * object. The SmartPointer class allows to associate a name with the object
+ * pointed to that identifies the object that has the pointer, in order to
+ * identify objects that still refer to the object pointed to. The @p name
+ * argument to this function is used to this end, i.e., you can in essence
+ * assign a name to the current PointerMatrix object.
*/
PointerMatrixVector (const Vector<number> *M,
const char *name);
virtual void clear();
/**
- * Return whether the object is
- * empty.
+ * Return whether the object is empty.
*/
bool empty () const;
/**
- * Assign a new matrix
- * pointer. Deletes the old pointer
- * and releases its matrix.
- * @see SmartPointer
+ * Assign a new matrix pointer. Deletes the old pointer and releases its
+ * matrix. @see SmartPointer
*/
const PointerMatrixVector &operator= (const Vector<number> *M);
/**
- * Matrix-vector product,
- * actually the scalar product of
- * <tt>src</tt> and the vector
- * representing this matrix.
+ * Matrix-vector product, actually the scalar product of <tt>src</tt> and
+ * the vector representing this matrix.
*
- * The dimension of <tt>dst</tt>
- * is 1, while that of
- * <tt>src</tt> is the size of
- * the vector representing this
- * matrix.
+ * The dimension of <tt>dst</tt> is 1, while that of <tt>src</tt> is the
+ * size of the vector representing this matrix.
*/
virtual void vmult (Vector<number> &dst,
const Vector<number> &src) const;
/**
- * Transposed matrix-vector
- * product, actually the
- * multiplication of the vector
- * representing this matrix with
- * <tt>src(0)</tt>.
+ * Transposed matrix-vector product, actually the multiplication of the
+ * vector representing this matrix with <tt>src(0)</tt>.
*
- * The dimension of <tt>drc</tt>
- * is 1, while that of
- * <tt>dst</tt> is the size of
- * the vector representing this
- * matrix.
+ * The dimension of <tt>drc</tt> is 1, while that of <tt>dst</tt> is the
+ * size of the vector representing this matrix.
*/
virtual void Tvmult (Vector<number> &dst,
const Vector<number> &src) const;
/**
- * Matrix-vector product, adding to
- * <tt>dst</tt>.
+ * Matrix-vector product, adding to <tt>dst</tt>.
*
- * The dimension of <tt>dst</tt>
- * is 1, while that of
- * <tt>src</tt> is the size of
- * the vector representing this
- * matrix.
+ * The dimension of <tt>dst</tt> is 1, while that of <tt>src</tt> is the
+ * size of the vector representing this matrix.
*/
virtual void vmult_add (Vector<number> &dst,
const Vector<number> &src) const;
/**
- * Transposed matrix-vector product,
- * adding to <tt>dst</tt>.
+ * Transposed matrix-vector product, adding to <tt>dst</tt>.
*
- * The dimension of <tt>src</tt>
- * is 1, while that of
- * <tt>dst</tt> is the size of
- * the vector representing this
- * matrix.
+ * The dimension of <tt>src</tt> is 1, while that of <tt>dst</tt> is the
+ * size of the vector representing this matrix.
*/
virtual void Tvmult_add (Vector<number> &dst,
const Vector<number> &src) const;
/**
- * This function helps you creating a PointerMatrixBase object if you
- * do not want to provide the full template arguments of
- * PointerMatrix or PointerMatrixAux.
+ * This function helps you creating a PointerMatrixBase object if you do not
+ * want to provide the full template arguments of PointerMatrix or
+ * PointerMatrixAux.
*
- * Note that this function by default creates a PointerMatrixAux,
- * emulating the functions <tt>vmult_add</tt> and <tt>Tvmult_add</tt>,
- * using an auxiliary vector. It is overloaded for the library matrix
- * classes implementing these functions themselves. If you have such a
- * class, you should overload the function in order to save memory and
- * time.
+ * Note that this function by default creates a PointerMatrixAux, emulating
+ * the functions <tt>vmult_add</tt> and <tt>Tvmult_add</tt>, using an
+ * auxiliary vector. It is overloaded for the library matrix classes
+ * implementing these functions themselves. If you have such a class, you
+ * should overload the function in order to save memory and time.
*
* The result is a PointerMatrixBase* pointing to <tt>matrix</tt>. The
- * <TT>VECTOR</tt> argument is a dummy just used to determine the
- * template arguments.
+ * <TT>VECTOR</tt> argument is a dummy just used to determine the template
+ * arguments.
*
- * @relates PointerMatrixBase
- * @relates PointerMatrixAux
+ * @relates PointerMatrixBase @relates PointerMatrixAux
*/
template <class VECTOR, class MATRIX>
inline
/**
* Specialized version for IdentityMatrix.
*
- * @relates PointerMatrixBase
- * @relates PointerMatrix
+ * @relates PointerMatrixBase @relates PointerMatrix
*/
template <typename numberv>
PointerMatrixBase<Vector<numberv> > *
/**
* Specialized version for FullMatrix.
*
- * @relates PointerMatrixBase
- * @relates PointerMatrix
+ * @relates PointerMatrixBase @relates PointerMatrix
*/
template <typename numberv, typename numberm>
PointerMatrixBase<Vector<numberv> > *
/**
* Specialized version for LAPACKFullMatrix.
*
- * @relates PointerMatrixBase
- * @relates PointerMatrix
+ * @relates PointerMatrixBase @relates PointerMatrix
*/
template <typename numberv, typename numberm>
PointerMatrixBase<Vector<numberv> > *
/**
* Specialized version for SparseMatrix.
*
- * @relates PointerMatrixBase
- * @relates PointerMatrix
+ * @relates PointerMatrixBase @relates PointerMatrix
*/
template <typename numberv, typename numberm>
PointerMatrixBase<Vector<numberv> > *
/**
* Specialized version for BlockSparseMatrix.
*
- * @relates PointerMatrixBase
- * @relates PointerMatrix
+ * @relates PointerMatrixBase @relates PointerMatrix
*/
template <class VECTOR, typename numberm>
PointerMatrixBase<VECTOR> *
/**
* Specialized version for SparseMatrixEZ.
*
- * @relates PointerMatrixBase
- * @relates PointerMatrix
+ * @relates PointerMatrixBase @relates PointerMatrix
*/
template <typename numberv, typename numberm>
PointerMatrixBase<Vector<numberv> > *
/**
* Specialized version for BlockSparseMatrixEZ.
*
- * @relates PointerMatrixBase
- * @relates PointerMatrix
+ * @relates PointerMatrixBase @relates PointerMatrix
*/
template <class VECTOR, typename numberm>
PointerMatrixBase<VECTOR> *
/**
* Specialized version for BlockMatrixArray.
*
- * @relates PointerMatrixBase
- * @relates PointerMatrix
+ * @relates PointerMatrixBase @relates PointerMatrix
*/
template <typename numberv, typename numberm>
PointerMatrixBase<BlockVector<numberv> > *
/**
* Specialized version for TridiagonalMatrix.
*
- * @relates PointerMatrixBase
- * @relates PointerMatrix
+ * @relates PointerMatrixBase @relates PointerMatrix
*/
template <typename numberv, typename numberm>
PointerMatrixBase<Vector<numberv> > *
/**
- * No preconditioning. This class helps you, if you want to use a
- * linear solver without preconditioning. All solvers in LAC require a
- * preconditioner. Therefore, you must use the identity provided here
- * to avoid preconditioning. It can be used in the following way:
+ * No preconditioning. This class helps you, if you want to use a linear
+ * solver without preconditioning. All solvers in LAC require a
+ * preconditioner. Therefore, you must use the identity provided here to avoid
+ * preconditioning. It can be used in the following way:
*
- @code
- SolverControl solver_control (1000, 1e-12);
- SolverCG<> cg (solver_control);
- cg.solve (system_matrix, solution, system_rhs,
- PreconditionIdentity());
- @endcode
+ * @code
+ * SolverControl solver_control (1000, 1e-12);
+ * SolverCG<> cg (solver_control);
+ * cg.solve (system_matrix, solution, system_rhs,
+ * PreconditionIdentity());
+ * @endcode
*
- * See the step-3 tutorial program for an example and
- * additional explanations.
+ * See the step-3 tutorial program for an example and additional explanations.
*
- * Alternatively, the IdentityMatrix class can be used to precondition
- * in this way.
+ * Alternatively, the IdentityMatrix class can be used to precondition in this
+ * way.
*
* @author Guido Kanschat, 1999
*/
/**
- * Preconditioning with Richardson's method. This preconditioner just
- * scales the vector with a constant relaxation factor provided by the
- * AdditionalData object.
+ * Preconditioning with Richardson's method. This preconditioner just scales
+ * the vector with a constant relaxation factor provided by the AdditionalData
+ * object.
*
- * In Krylov-space methods, this preconditioner should not have any
- * effect. Using SolverRichardson, the two relaxation parameters will
- * be just multiplied. Still, this class is useful in multigrid
- * smoother objects (MGSmootherRelaxation).
+ * In Krylov-space methods, this preconditioner should not have any effect.
+ * Using SolverRichardson, the two relaxation parameters will be just
+ * multiplied. Still, this class is useful in multigrid smoother objects
+ * (MGSmootherRelaxation).
*
* @author Guido Kanschat, 2005
*/
* Preconditioner using a matrix-builtin function. This class forms a
* preconditioner suitable for the LAC solver classes. Since many
* preconditioning methods are based on matrix entries, these have to be
- * implemented as member functions of the underlying matrix
- * implementation. This class now is intended to allow easy access to these
- * member functions from LAC solver classes.
+ * implemented as member functions of the underlying matrix implementation.
+ * This class now is intended to allow easy access to these member functions
+ * from LAC solver classes.
*
- * It seems that all builtin preconditioners have a relaxation
- * parameter, so please use PreconditionRelaxation for these.
+ * It seems that all builtin preconditioners have a relaxation parameter, so
+ * please use PreconditionRelaxation for these.
*
- * You will usually not want to create a named object of this type,
- * although possible. The most common use is like this:
+ * You will usually not want to create a named object of this type, although
+ * possible. The most common use is like this:
* @code
* SolverGMRES<SparseMatrix<double>,
* Vector<double> > gmres(control,memory,500);
* PreconditionUseMatrix<SparseMatrix<double>,Vector<double> >
* (matrix,&SparseMatrix<double>::template precondition_Jacobi<double>));
* @endcode
- * This creates an unnamed object to be passed as the fourth parameter to
- * the solver function of the SolverGMRES class. It assumes that the
- * SparseMatrix class has a function <tt>precondition_Jacobi</tt> taking two
- * vectors (source and destination) as parameters (Actually, there is no
- * function like that, the existing function takes a third parameter,
- * denoting the relaxation parameter; this example is therefore only meant to
- * illustrate the general idea).
+ * This creates an unnamed object to be passed as the fourth parameter to the
+ * solver function of the SolverGMRES class. It assumes that the SparseMatrix
+ * class has a function <tt>precondition_Jacobi</tt> taking two vectors
+ * (source and destination) as parameters (Actually, there is no function like
+ * that, the existing function takes a third parameter, denoting the
+ * relaxation parameter; this example is therefore only meant to illustrate
+ * the general idea).
*
- * Note that due to the default template parameters, the above example
- * could be written shorter as follows:
+ * Note that due to the default template parameters, the above example could
+ * be written shorter as follows:
* @code
* ...
* gmres.solve (matrix, solution, right_hand_side,
/**
- * Base class for other preconditioners.
- * Here, only some common features Jacobi, SOR and SSOR preconditioners
- * are implemented. For preconditioning, refer to derived classes.
+ * Base class for other preconditioners. Here, only some common features
+ * Jacobi, SOR and SSOR preconditioners are implemented. For preconditioning,
+ * refer to derived classes.
*
* @author Guido Kanschat, 2000
*/
/**
- * Jacobi preconditioner using matrix built-in function. The
- * <tt>MATRIX</tt> class used is required to have a function
- * <tt>precondition_Jacobi(VECTOR&, const VECTOR&, double</tt>)
+ * Jacobi preconditioner using matrix built-in function. The <tt>MATRIX</tt>
+ * class used is required to have a function <tt>precondition_Jacobi(VECTOR&,
+ * const VECTOR&, double</tt>)
*
* @code
* // Declare related objects
* SOR preconditioner using matrix built-in function.
*
* Assuming the matrix <i>A = D + L + U</i> is split into its diagonal
- * <i>D</i> as well as the strict lower and upper triangles <i>L</i>
- * and <i>U</i>, then the SOR preconditioner with relaxation parameter
- * <i>r</i> is
+ * <i>D</i> as well as the strict lower and upper triangles <i>L</i> and
+ * <i>U</i>, then the SOR preconditioner with relaxation parameter <i>r</i> is
* @f[
* P^{-1} = r (D+rL)^{-1}.
* @f]
- * It is this operator <i>P<sup>-1</sup></i>, which is implemented by
- * vmult() through forward substitution. Analogously, Tvmult()
- * implements the operation of <i>r(D+rU)<sup>-1</sup></i>.
+ * It is this operator <i>P<sup>-1</sup></i>, which is implemented by vmult()
+ * through forward substitution. Analogously, Tvmult() implements the
+ * operation of <i>r(D+rU)<sup>-1</sup></i>.
*
* The SOR iteration itself can be directly written as
* @f[
* x^{k+1} = x^k - r D^{-1} \bigl(L x^{k+1} + U x^k - b\bigr).
* @f]
- * Using the right hand side <i>b</i> and the previous iterate
- * <i>x</i>, this is the operation implemented by step().
+ * Using the right hand side <i>b</i> and the previous iterate <i>x</i>, this
+ * is the operation implemented by step().
*
- * The MATRIX
- * class used is required to have functions
+ * The MATRIX class used is required to have functions
* <tt>precondition_SOR(VECTOR&, const VECTOR&, double)</tt> and
* <tt>precondition_TSOR(VECTOR&, const VECTOR&, double)</tt>.
*
/**
- * SSOR preconditioner using matrix built-in function. The
- * <tt>MATRIX</tt> class used is required to have a function
- * <tt>precondition_SSOR(VECTOR&, const VECTOR&, double)</tt>
+ * SSOR preconditioner using matrix built-in function. The <tt>MATRIX</tt>
+ * class used is required to have a function <tt>precondition_SSOR(VECTOR&,
+ * const VECTOR&, double)</tt>
*
* @code
* // Declare related objects
/**
* Permuted SOR preconditioner using matrix built-in function. The
- * <tt>MATRIX</tt> class used is required to have functions
- * <tt>PSOR(VECTOR&, const VECTOR&, double)</tt> and
- * <tt>TPSOR(VECTOR&, const VECTOR&, double)</tt>.
+ * <tt>MATRIX</tt> class used is required to have functions <tt>PSOR(VECTOR&,
+ * const VECTOR&, double)</tt> and <tt>TPSOR(VECTOR&, const VECTOR&,
+ * double)</tt>.
*
* @code
* // Declare related objects
/**
- * @deprecated This class has been superseded by IterativeInverse,
- * which is more flexible and easier to use.
+ * @deprecated This class has been superseded by IterativeInverse, which is
+ * more flexible and easier to use.
*
- * Preconditioner using an iterative solver. This preconditioner uses
- * a fully initialized LAC iterative solver for the approximate
- * inverse of the matrix. Naturally, this solver needs another
- * preconditionig method.
+ * Preconditioner using an iterative solver. This preconditioner uses a fully
+ * initialized LAC iterative solver for the approximate inverse of the matrix.
+ * Naturally, this solver needs another preconditionig method.
*
- * Usually, the use of ReductionControl is preferred over the use of
- * the basic SolverControl in defining this solver.
+ * Usually, the use of ReductionControl is preferred over the use of the basic
+ * SolverControl in defining this solver.
*
- * Krylov space methods like SolverCG or SolverBicgstab
- * become inefficient if soution down to machine accuracy is
- * needed. This is due to the fact, that round-off errors spoil the
- * orthogonality of the vector sequences. Therefore, a nested
- * iteration of two methods is proposed: The outer method is
- * SolverRichardson, since it is robust with respect to round-of
- * errors. The inner loop is an appropriate Krylov space method, since
- * it is fast.
+ * Krylov space methods like SolverCG or SolverBicgstab become inefficient if
+ * soution down to machine accuracy is needed. This is due to the fact, that
+ * round-off errors spoil the orthogonality of the vector sequences.
+ * Therefore, a nested iteration of two methods is proposed: The outer method
+ * is SolverRichardson, since it is robust with respect to round-of errors.
+ * The inner loop is an appropriate Krylov space method, since it is fast.
*
* @code
* // Declare related objects
* Vector<double> x;
* Vector<double> b;
* GrowingVectorMemory<Vector<double> > mem;
-
+ *
* ReductionControl inner_control (10, 1.e-30, 1.e-2)
* SolverCG<Vector<double> > inner_iteration (inner_control, mem);
* PreconditionSSOR <SparseMatrix<double> > inner_precondition;
* outer_iteration.solve (A, x, b, precondition);
* @endcode
*
- * Each time we call the inner loop, reduction of the residual by a
- * factor <tt>1.e-2</tt> is attempted. Since the right hand side vector of
- * the inner iteration is the residual of the outer loop, the relative
- * errors are far from machine accuracy, even if the errors of the
- * outer loop are in the range of machine accuracy.
+ * Each time we call the inner loop, reduction of the residual by a factor
+ * <tt>1.e-2</tt> is attempted. Since the right hand side vector of the inner
+ * iteration is the residual of the outer loop, the relative errors are far
+ * from machine accuracy, even if the errors of the outer loop are in the
+ * range of machine accuracy.
*
* @author Guido Kanschat, 1999
*/
/**
* @deprecated Use ProductMatrix instead.
*
- * Matrix with preconditioner.
- * Given a matrix $A$ and a preconditioner $P$, this class implements a new matrix
- * with the matrix-vector product $PA$. It needs an auxiliary vector for that.
+ * Matrix with preconditioner. Given a matrix $A$ and a preconditioner $P$,
+ * this class implements a new matrix with the matrix-vector product $PA$. It
+ * needs an auxiliary vector for that.
*
- * By this time, this is considered a temporary object to be plugged
- * into eigenvalue solvers. Therefore, no SmartPointer is used for
- * <tt>A</tt> and <tt>P</tt>.
+ * By this time, this is considered a temporary object to be plugged into
+ * eigenvalue solvers. Therefore, no SmartPointer is used for <tt>A</tt> and
+ * <tt>P</tt>.
*
* @author Guido Kanschat, 2000
*/
/**
- * Preconditioning with a Chebyshev polynomial for symmetric positive
- * definite matrices. This preconditioner is similar to a Jacobi
- * preconditioner if the degree variable is set to one, otherwise some
- * higher order polynomial corrections are used. This preconditioner needs
- * access to the diagonal of the matrix its acts on and needs a respective
- * <tt>vmult</tt> implemention. However, it does not need to explicitly know
- * the matrix entries.
+ * Preconditioning with a Chebyshev polynomial for symmetric positive definite
+ * matrices. This preconditioner is similar to a Jacobi preconditioner if the
+ * degree variable is set to one, otherwise some higher order polynomial
+ * corrections are used. This preconditioner needs access to the diagonal of
+ * the matrix its acts on and needs a respective <tt>vmult</tt> implemention.
+ * However, it does not need to explicitly know the matrix entries.
*
* This class is useful e.g. in multigrid smoother objects, since it is
* trivially %parallel (assuming that matrix-vector products are %parallel).
/**
* Base class for actual block preconditioners. This class assumes the
- * <tt>MATRIX</tt> consisting of invertible blocks of @p blocksize on
- * the diagonal and provides the inversion of the diagonal blocks of
- * the matrix. It is not necessary for this class that the matrix be
- * block diagonal; rather, it applies to
- * matrices of arbitrary structure with the minimal property of having
- * invertible blocks on the diagonal. Still the matrix must have
- * access to single matrix entries. Therefore, BlockMatrixArray and similar
- * classes are not a possible matrix class template arguments.
+ * <tt>MATRIX</tt> consisting of invertible blocks of @p blocksize on the
+ * diagonal and provides the inversion of the diagonal blocks of the matrix.
+ * It is not necessary for this class that the matrix be block diagonal;
+ * rather, it applies to matrices of arbitrary structure with the minimal
+ * property of having invertible blocks on the diagonal. Still the matrix must
+ * have access to single matrix entries. Therefore, BlockMatrixArray and
+ * similar classes are not a possible matrix class template arguments.
*
- * The block matrix structure used by this class is given, e.g., for
- * the DG method for the transport equation. For a downstream
- * numbering the matrices even have got a block lower left matrix
- * structure, i.e. the matrices are empty above the diagonal blocks.
+ * The block matrix structure used by this class is given, e.g., for the DG
+ * method for the transport equation. For a downstream numbering the matrices
+ * even have got a block lower left matrix structure, i.e. the matrices are
+ * empty above the diagonal blocks.
*
- * @note This class is intended to be used for matrices whose structure
- * is given by local contributions from disjoint cells, such as for DG
- * methods. It is not intended for problems where the block structure
- * results from different physical variables such as in the Stokes
- * equations considered in step-22.
+ * @note This class is intended to be used for matrices whose structure is
+ * given by local contributions from disjoint cells, such as for DG methods.
+ * It is not intended for problems where the block structure results from
+ * different physical variables such as in the Stokes equations considered in
+ * step-22.
*
- * For all matrices that are empty above and below the diagonal blocks
- * (i.e. for all block diagonal matrices) the @p BlockJacobi
- * preconditioner is a direct solver. For all matrices that are empty
- * only above the diagonal blocks (e.g. the matrices one gets by the
- * DG method with downstream numbering) @p BlockSOR is a direct
- * solver.
+ * For all matrices that are empty above and below the diagonal blocks (i.e.
+ * for all block diagonal matrices) the @p BlockJacobi preconditioner is a
+ * direct solver. For all matrices that are empty only above the diagonal
+ * blocks (e.g. the matrices one gets by the DG method with downstream
+ * numbering) @p BlockSOR is a direct solver.
*
- * This first implementation of the @p PreconditionBlock assumes the
- * matrix has blocks each of the same block size. Varying block sizes
- * within the matrix must still be implemented if needed.
+ * This first implementation of the @p PreconditionBlock assumes the matrix
+ * has blocks each of the same block size. Varying block sizes within the
+ * matrix must still be implemented if needed.
*
- * The first template parameter denotes the type of number
- * representation in the sparse matrix, the second denotes the type of
- * number representation in which the inverted diagonal block matrices
- * are stored within this class by <tt>invert_diagblocks()</tt>. If you
- * don't want to use the block inversion as an exact solver, but
- * rather as a preconditioner, you may probably want to store the
- * inverted blocks with less accuracy than the original matrix; for
- * example, <tt>number==double, inverse_type=float</tt> might be a viable
+ * The first template parameter denotes the type of number representation in
+ * the sparse matrix, the second denotes the type of number representation in
+ * which the inverted diagonal block matrices are stored within this class by
+ * <tt>invert_diagblocks()</tt>. If you don't want to use the block inversion
+ * as an exact solver, but rather as a preconditioner, you may probably want
+ * to store the inverted blocks with less accuracy than the original matrix;
+ * for example, <tt>number==double, inverse_type=float</tt> might be a viable
* choice.
*
* @see @ref GlossBlockLA "Block (linear algebra)"
{
public:
/**
- * Constructor. Block size
- * must be given since there
- * is no reasonable default
- * parameter.
+ * Constructor. Block size must be given since there is no reasonable
+ * default parameter.
*/
AdditionalData (const size_type block_size,
const double relaxation = 1.,
bool invert_diagonal;
/**
- * Assume all diagonal blocks
- * are equal to save memory.
+ * Assume all diagonal blocks are equal to save memory.
*/
bool same_diagonal;
/**
- * Choose the inversion
- * method for the blocks.
+ * Choose the inversion method for the blocks.
*/
typename PreconditionBlockBase<inverse_type>::Inversion inversion;
/**
- * The if #inversion is SVD,
- * the threshold below which
- * a singular value will be
- * considered zero and thus
- * not inverted. This
- * parameter is used in the
- * call to LAPACKFullMatrix::compute_inverse_svd().
+ * The if #inversion is SVD, the threshold below which a singular value
+ * will be considered zero and thus not inverted. This parameter is used
+ * in the call to LAPACKFullMatrix::compute_inverse_svd().
*/
double threshold;
};
~PreconditionBlock();
/**
- * Initialize matrix and block
- * size. We store the matrix and
- * the block size in the
- * preconditioner object. In a
- * second step, the inverses of
- * the diagonal blocks may be
- * computed.
+ * Initialize matrix and block size. We store the matrix and the block size
+ * in the preconditioner object. In a second step, the inverses of the
+ * diagonal blocks may be computed.
*
- * Additionally, a relaxation
- * parameter for derived classes
- * may be provided.
+ * Additionally, a relaxation parameter for derived classes may be provided.
*/
void initialize (const MATRIX &A,
const AdditionalData parameters);
protected:
/**
- * Initialize matrix and block
- * size for permuted
- * preconditioning. Additionally
- * to the parameters of the other
- * initalize() function, we hand
- * over two index vectors with
- * the permutation and its
- * inverse. For the meaning of
- * these vectors see
- * PreconditionBlockSOR.
+ * Initialize matrix and block size for permuted preconditioning.
+ * Additionally to the parameters of the other initalize() function, we hand
+ * over two index vectors with the permutation and its inverse. For the
+ * meaning of these vectors see PreconditionBlockSOR.
*
- * In a second step, the inverses
- * of the diagonal blocks may be
- * computed. Make sure you use
- * invert_permuted_diagblocks()
- * to yield consistent data.
+ * In a second step, the inverses of the diagonal blocks may be computed.
+ * Make sure you use invert_permuted_diagblocks() to yield consistent data.
*
- * Additionally, a relaxation
- * parameter for derived classes
- * may be provided.
+ * Additionally, a relaxation parameter for derived classes may be provided.
*/
void initialize (const MATRIX &A,
const std::vector<size_type> &permutation,
const AdditionalData parameters);
/**
- * Set either the permutation of
- * rows or the permutation of
- * blocks, depending on the size
- * of the vector.
+ * Set either the permutation of rows or the permutation of blocks,
+ * depending on the size of the vector.
*
- * If the size of the permutation
- * vectors is equal to the
- * dimension of the linear
- * system, it is assumed that
- * rows are permuted
- * individually. In this case,
- * set_permutation() must be
- * called before initialize(),
- * since the diagonal blocks are
- * built from the permuted
- * entries of the matrix.
+ * If the size of the permutation vectors is equal to the dimension of the
+ * linear system, it is assumed that rows are permuted individually. In this
+ * case, set_permutation() must be called before initialize(), since the
+ * diagonal blocks are built from the permuted entries of the matrix.
*
- * If the size of the permutation
- * vector is not equal to the
- * dimension of the system, the
- * diagonal blocks are computed
- * from the unpermuted
- * entries. Instead, the
- * relaxation methods step() and
- * Tstep() are executed applying
- * the blocks in the order given
- * by the permutation
- * vector. They will throw an
- * exception if length of this
- * vector is not equal to the
- * number of blocks.
+ * If the size of the permutation vector is not equal to the dimension of
+ * the system, the diagonal blocks are computed from the unpermuted entries.
+ * Instead, the relaxation methods step() and Tstep() are executed applying
+ * the blocks in the order given by the permutation vector. They will throw
+ * an exception if length of this vector is not equal to the number of
+ * blocks.
*
- * @note Permutation of blocks
- * can only be applied to the
- * relaxation operators step()
- * and Tstep(), not to the
- * preconditioning operators
+ * @note Permutation of blocks can only be applied to the relaxation
+ * operators step() and Tstep(), not to the preconditioning operators
* vmult() and Tvmult().
*
- * @note It is safe to call
- * set_permutation() before
- * initialize(), while the other
- * order is only admissible for
- * block permutation.
+ * @note It is safe to call set_permutation() before initialize(), while the
+ * other order is only admissible for block permutation.
*/
void set_permutation(const std::vector<size_type> &permutation,
const std::vector<size_type> &inverse_permutation);
/**
- * Replacement of
- * invert_diagblocks() for
- * permuted preconditioning.
+ * Replacement of invert_diagblocks() for permuted preconditioning.
*/
void invert_permuted_diagblocks(
const std::vector<size_type> &permutation,
const std::vector<size_type> &inverse_permutation);
public:
/**
- * Deletes the inverse diagonal
- * block matrices if existent,
- * sets the blocksize to 0, hence
- * leaves the class in the state
- * that it had directly after
- * calling the constructor.
+ * Deletes the inverse diagonal block matrices if existent, sets the
+ * blocksize to 0, hence leaves the class in the state that it had directly
+ * after calling the constructor.
*/
void clear();
bool empty () const;
/**
- * Read-only access to entries.
- * This function is only possible
- * if the inverse diagonal blocks
- * are stored.
+ * Read-only access to entries. This function is only possible if the
+ * inverse diagonal blocks are stored.
*/
value_type el(size_type i,
size_type j) const;
/**
- * Stores the inverse of the
- * diagonal blocks in
- * @p inverse. This costs some
- * additional memory - for DG
- * methods about 1/3 (for double
- * inverses) or 1/6 (for float
- * inverses) of that used for the
- * matrix - but it makes the
+ * Stores the inverse of the diagonal blocks in @p inverse. This costs some
+ * additional memory - for DG methods about 1/3 (for double inverses) or 1/6
+ * (for float inverses) of that used for the matrix - but it makes the
* preconditioning much faster.
*
- * It is not allowed to call this
- * function twice (will produce
- * an error) before a call of
- * <tt>clear(...)</tt> because at the
- * second time there already
- * exist the inverse matrices.
+ * It is not allowed to call this function twice (will produce an error)
+ * before a call of <tt>clear(...)</tt> because at the second time there
+ * already exist the inverse matrices.
*
- * After this function is called,
- * the lock on the matrix given
- * through the @p use_matrix
- * function is released, i.e. you
- * may overwrite of delete it.
- * You may want to do this in
- * case you use this matrix to
- * precondition another matrix.
+ * After this function is called, the lock on the matrix given through the
+ * @p use_matrix function is released, i.e. you may overwrite of delete it.
+ * You may want to do this in case you use this matrix to precondition
+ * another matrix.
*/
void invert_diagblocks();
/**
- * Perform one block relaxation
- * step in forward numbering.
+ * Perform one block relaxation step in forward numbering.
*
- * Depending on the arguments @p
- * dst and @p pref, this performs
- * an SOR step (both reference
- * the same vector) of a Jacobi
- * step (botha different
- * vectors). For the Jacobi step,
- * the calling function must copy
- * @p dst to @p pref after this.
+ * Depending on the arguments @p dst and @p pref, this performs an SOR step
+ * (both reference the same vector) of a Jacobi step (botha different
+ * vectors). For the Jacobi step, the calling function must copy @p dst to
+ * @p pref after this.
*
- * @note If a permutation is set,
- * it is automatically honored by
- * this function.
+ * @note If a permutation is set, it is automatically honored by this
+ * function.
*/
template <typename number2>
void forward_step (
const bool transpose_diagonal) const;
/**
- * Perform one block relaxation
- * step in backward numbering.
+ * Perform one block relaxation step in backward numbering.
*
- * Depending on the arguments @p
- * dst and @p pref, this performs
- * an SOR step (both reference
- * the same vector) of a Jacobi
- * step (botha different
- * vectors). For the Jacobi step,
- * the calling function must copy
- * @p dst to @p pref after this.
+ * Depending on the arguments @p dst and @p pref, this performs an SOR step
+ * (both reference the same vector) of a Jacobi step (botha different
+ * vectors). For the Jacobi step, the calling function must copy @p dst to
+ * @p pref after this.
*
- * @note If a permutation is set,
- * it is automatically honored by
- * this function.
+ * @note If a permutation is set, it is automatically honored by this
+ * function.
*/
template <typename number2>
void backward_step (
size_type block_size () const;
/**
- * @deprecated Use size()
- * instead.
+ * @deprecated Use size() instead.
*
- * The number of blocks of the
- * matrix.
+ * The number of blocks of the matrix.
*/
unsigned int n_blocks() const DEAL_II_DEPRECATED;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
- * For non-overlapping block
- * preconditioners, the block
- * size must divide the matrix
- * size. If not, this exception
- * gets thrown.
+ * For non-overlapping block preconditioners, the block size must divide the
+ * matrix size. If not, this exception gets thrown.
*/
DeclException2 (ExcWrongBlockSize,
int, int,
protected:
/**
- * Size of the blocks. Each
- * diagonal block is assumed to
- * be of the same size.
+ * Size of the blocks. Each diagonal block is assumed to be of the same
+ * size.
*/
size_type blocksize;
/**
- * Pointer to the matrix. Make
- * sure that the matrix exists as
- * long as this class needs it,
- * i.e. until calling
- * @p invert_diagblocks, or (if
- * the inverse matrices should
- * not be stored) until the last
- * call of the preconditoining
- * @p vmult function of the
- * derived classes.
+ * Pointer to the matrix. Make sure that the matrix exists as long as this
+ * class needs it, i.e. until calling @p invert_diagblocks, or (if the
+ * inverse matrices should not be stored) until the last call of the
+ * preconditoining @p vmult function of the derived classes.
*/
SmartPointer<const MATRIX,PreconditionBlock<MATRIX,inverse_type> > A;
/**
- * Relaxation parameter to be
- * used by derived classes.
+ * Relaxation parameter to be used by derived classes.
*/
double relaxation;
std::vector<size_type> inverse_permutation;
/**
- * Flag for diagonal compression.
- * @ref set_same_diagonal()
+ * Flag for diagonal compression. @ref set_same_diagonal()
*/
};
/**
- * Block Jacobi preconditioning.
- * See PreconditionBlock for requirements on the matrix.
+ * Block Jacobi preconditioning. See PreconditionBlock for requirements on the
+ * matrix.
*
* @note Instantiations for this template are provided for <tt>@<float@> and
* @<double@></tt>; others can be generated in application programs (see the
{
public:
/**
- * Constructor. Since we use
- * accessors only for read
- * access, a const matrix
- * pointer is sufficient.
+ * Constructor. Since we use accessors only for read access, a const
+ * matrix pointer is sufficient.
*/
Accessor (const PreconditionBlockJacobi<MATRIX, inverse_type> *matrix,
const size_type row);
/**
- * Row number of the element
- * represented by this
- * object.
+ * Row number of the element represented by this object.
*/
size_type row() const;
/**
- * Column number of the
- * element represented by
- * this object.
+ * Column number of the element represented by this object.
*/
size_type column() const;
const PreconditionBlockJacobi<MATRIX, inverse_type> *matrix;
/**
- * Save block size here
- * for further reference.
+ * Save block size here for further reference.
*/
size_type bs;
typename FullMatrix<inverse_type>::const_iterator b_end;
/**
- * Make enclosing class a
- * friend.
+ * Make enclosing class a friend.
*/
friend class const_iterator;
};
const Accessor *operator-> () const;
/**
- * Comparison. True, if
- * both iterators point to
- * the same matrix
- * position.
+ * Comparison. True, if both iterators point to the same matrix position.
*/
bool operator == (const const_iterator &) const;
/**
bool operator != (const const_iterator &) const;
/**
- * Comparison
- * operator. Result is true
- * if either the first row
- * number is smaller or if
- * the row numbers are
- * equal and the first
- * index is smaller.
+ * Comparison operator. Result is true if either the first row number is
+ * smaller or if the row numbers are equal and the first index is smaller.
*/
bool operator < (const const_iterator &) const;
private:
/**
- * Store an object of the
- * accessor class.
+ * Store an object of the accessor class.
*/
Accessor accessor;
};
using PreconditionBlock<MATRIX, inverse_type>::set_permutation;
/**
- * Execute block Jacobi
- * preconditioning.
+ * Execute block Jacobi preconditioning.
*
- * This function will
- * automatically use the inverse
- * matrices if they exist, if not
- * then BlockJacobi will need
- * much time inverting the
- * diagonal block matrices in
- * each preconditioning step.
+ * This function will automatically use the inverse matrices if they exist,
+ * if not then BlockJacobi will need much time inverting the diagonal block
+ * matrices in each preconditioning step.
*/
template <typename number2>
void vmult (Vector<number2> &, const Vector<number2> &) const;
template <typename number2>
void Tvmult (Vector<number2> &, const Vector<number2> &) const;
/**
- * Execute block Jacobi
- * preconditioning, adding to @p dst.
+ * Execute block Jacobi preconditioning, adding to @p dst.
*
- * This function will
- * automatically use the inverse
- * matrices if they exist, if not
- * then BlockJacobi will need
- * much time inverting the
- * diagonal block matrices in
- * each preconditioning step.
+ * This function will automatically use the inverse matrices if they exist,
+ * if not then BlockJacobi will need much time inverting the diagonal block
+ * matrices in each preconditioning step.
*/
template <typename number2>
void vmult_add (Vector<number2> &, const Vector<number2> &) const;
/**
- * Same as @p vmult_add, since
- * Jacobi is symmetric.
+ * Same as @p vmult_add, since Jacobi is symmetric.
*/
template <typename number2>
void Tvmult_add (Vector<number2> &, const Vector<number2> &) const;
/**
- * Perform one step of the Jacobi
- * iteration.
+ * Perform one step of the Jacobi iteration.
*/
template <typename number2>
void step (Vector<number2> &dst, const Vector<number2> &rhs) const;
/**
- * Perform one step of the Jacobi
- * iteration.
+ * Perform one step of the Jacobi iteration.
*/
template <typename number2>
void Tstep (Vector<number2> &dst, const Vector<number2> &rhs) const;
/**
- * STL-like iterator with the
- * first entry.
+ * STL-like iterator with the first entry.
*/
const_iterator begin () const;
const_iterator end () const;
/**
- * STL-like iterator with the
- * first entry of row @p r.
+ * STL-like iterator with the first entry of row @p r.
*/
const_iterator begin (const size_type r) const;
private:
/**
- * Actual implementation of the
- * preconditioner.
+ * Actual implementation of the preconditioner.
*
- * Depending on @p adding, the
- * result of preconditioning is
- * added to the destination vector.
+ * Depending on @p adding, the result of preconditioning is added to the
+ * destination vector.
*/
template <typename number2>
void do_vmult (Vector<number2> &,
/**
* Block SOR preconditioning.
*
- * The functions @p vmult and @p Tvmult execute a (transposed)
- * block-SOR step, based on the blocks in PreconditionBlock. The
- * elements outside the diagonal blocks may be distributed
- * arbitrarily.
+ * The functions @p vmult and @p Tvmult execute a (transposed) block-SOR step,
+ * based on the blocks in PreconditionBlock. The elements outside the diagonal
+ * blocks may be distributed arbitrarily.
*
- * See PreconditionBlock for requirements on the matrix. The blocks
- * used in this class must be contiguous and non-overlapping. An
- * overlapping Schwarz relaxation method can be found in
- * RelaxationBlockSOR; that class does not offer preconditioning,
- * though.
+ * See PreconditionBlock for requirements on the matrix. The blocks used in
+ * this class must be contiguous and non-overlapping. An overlapping Schwarz
+ * relaxation method can be found in RelaxationBlockSOR; that class does not
+ * offer preconditioning, though.
*
* <h3>Permutations</h3>
*
- * Optionally, the entries of the source vector can be treated in the
- * order of the indices in the permutation vector set by
- * #set_permutation (or the opposite order for Tvmult()). The inverse
- * permutation is used for storing elements back into this
- * vector. This functionality is automatically enabled after a call to
- * set_permutation() with vectors of nonzero size.
+ * Optionally, the entries of the source vector can be treated in the order of
+ * the indices in the permutation vector set by #set_permutation (or the
+ * opposite order for Tvmult()). The inverse permutation is used for storing
+ * elements back into this vector. This functionality is automatically enabled
+ * after a call to set_permutation() with vectors of nonzero size.
*
- * @note The diagonal blocks, like the matrix, are not permuted!
- * Therefore, the permutation vector can only swap whole blocks. It
- * may not change the order inside blocks or swap single indices
- * between blocks.
+ * @note The diagonal blocks, like the matrix, are not permuted! Therefore,
+ * the permutation vector can only swap whole blocks. It may not change the
+ * order inside blocks or swap single indices between blocks.
*
* <h3>Instantiations</h3>
*
using PreconditionBlockBase<inverse_type>::log_statistics;
/**
- * Execute block SOR
- * preconditioning.
+ * Execute block SOR preconditioning.
*
- * This function will
- * automatically use the inverse
- * matrices if they exist, if not
- * then BlockSOR will waste much
- * time inverting the diagonal
- * block matrices in each
- * preconditioning step.
+ * This function will automatically use the inverse matrices if they exist,
+ * if not then BlockSOR will waste much time inverting the diagonal block
+ * matrices in each preconditioning step.
*
- * For matrices which are empty
- * above the diagonal blocks
- * BlockSOR is a direct solver.
+ * For matrices which are empty above the diagonal blocks BlockSOR is a
+ * direct solver.
*/
template <typename number2>
void vmult (Vector<number2> &, const Vector<number2> &) const;
/**
- * Execute block SOR
- * preconditioning.
+ * Execute block SOR preconditioning.
*
- * Warning: this function
- * performs normal @p vmult
- * without adding. The reason for
- * its existence is that
- * BlockMatrixArray
- * requires the adding version by
- * default. On the other hand,
- * adding requires an additional
- * auxiliary vector, which is not
- * desirable.
+ * Warning: this function performs normal @p vmult without adding. The
+ * reason for its existence is that BlockMatrixArray requires the adding
+ * version by default. On the other hand, adding requires an additional
+ * auxiliary vector, which is not desirable.
*
* @see vmult
*/
/**
* Backward application of vmult().
*
- * In the current implementation,
- * this is not the transpose of
- * vmult(). It is a
- * transposed Gauss-Seidel
- * algorithm applied to the whole
- * matrix, but the diagonal
- * blocks being inverted are not
- * transposed. Therefore, it is
- * the transposed, if the
- * diagonal blocks are symmetric.
+ * In the current implementation, this is not the transpose of vmult(). It
+ * is a transposed Gauss-Seidel algorithm applied to the whole matrix, but
+ * the diagonal blocks being inverted are not transposed. Therefore, it is
+ * the transposed, if the diagonal blocks are symmetric.
*/
template <typename number2>
void Tvmult (Vector<number2> &, const Vector<number2> &) const;
/**
- * Execute backward block SOR
- * preconditioning.
+ * Execute backward block SOR preconditioning.
*
- * Warning: this function
- * performs normal @p vmult
- * without adding. The reason for
- * its existence is that
- * BlockMatrixArray
- * requires the adding version by
- * default. On the other hand,
- * adding requires an additional
- * auxiliary vector, which is not
- * desirable.
+ * Warning: this function performs normal @p vmult without adding. The
+ * reason for its existence is that BlockMatrixArray requires the adding
+ * version by default. On the other hand, adding requires an additional
+ * auxiliary vector, which is not desirable.
*
* @see vmult
*/
void Tvmult_add (Vector<number2> &, const Vector<number2> &) const;
/**
- * Perform one step of the SOR
- * iteration.
+ * Perform one step of the SOR iteration.
*/
template <typename number2>
void step (Vector<number2> &dst, const Vector<number2> &rhs) const;
/**
- * Perform one step of the
- * transposed SOR iteration.
+ * Perform one step of the transposed SOR iteration.
*/
template <typename number2>
void Tstep (Vector<number2> &dst, const Vector<number2> &rhs) const;
protected:
/**
- * Constructor to be used by
- * PreconditionBlockSSOR.
+ * Constructor to be used by PreconditionBlockSSOR.
*/
PreconditionBlockSOR(bool store);
/**
- * Implementation of the forward
- * substitution loop called by
- * vmult() and vmult_add().
+ * Implementation of the forward substitution loop called by vmult() and
+ * vmult_add().
*
- * If a #permutation is set by
- * set_permutation(), it will
- * automatically be honored by
- * this function.
+ * If a #permutation is set by set_permutation(), it will automatically be
+ * honored by this function.
*
- * The parameter @p adding does
- * not have any function, yet.
+ * The parameter @p adding does not have any function, yet.
*/
template <typename number2>
void forward (Vector<number2> &,
const bool adding) const;
/**
- * Implementation of the backward
- * substitution loop called by
- * Tvmult() and Tvmult_add().
+ * Implementation of the backward substitution loop called by Tvmult() and
+ * Tvmult_add().
*
- * If a #permutation is set by
- * set_permutation(), it will
- * automatically be honored by
- * this function.
+ * If a #permutation is set by set_permutation(), it will automatically be
+ * honored by this function.
*
- * The parameter @p adding does
- * not have any function, yet.
+ * The parameter @p adding does not have any function, yet.
*/
template <typename number2>
void backward (Vector<number2> &,
/**
* Block SSOR preconditioning.
*
- * The functions @p vmult and @p Tvmult execute a block-SSOR step,
- * based on the implementation in PreconditionBlockSOR. This
- * class requires storage of the diagonal blocks and their inverses.
+ * The functions @p vmult and @p Tvmult execute a block-SSOR step, based on
+ * the implementation in PreconditionBlockSOR. This class requires storage of
+ * the diagonal blocks and their inverses.
*
- * See PreconditionBlock for requirements on the matrix. The blocks
- * used in this class must be contiguous and non-overlapping. An
- * overlapping Schwarz relaxation method can be found in
- * RelaxationBlockSSOR; that class does not offer preconditioning,
- * though.
+ * See PreconditionBlock for requirements on the matrix. The blocks used in
+ * this class must be contiguous and non-overlapping. An overlapping Schwarz
+ * relaxation method can be found in RelaxationBlockSSOR; that class does not
+ * offer preconditioning, though.
*
* @note Instantiations for this template are provided for <tt>@<float@> and
* @<double@></tt>; others can be generated in application programs (see the
// which we want to keep
// accessible.
/**
- * Make initialization function
- * publicly available.
+ * Make initialization function publicly available.
*/
using PreconditionBlockSOR<MATRIX,inverse_type>::initialize;
using PreconditionBlockSOR<MATRIX,inverse_type>::clear;
using PreconditionBlockSOR<MATRIX,inverse_type>::invert_diagblocks;
/**
- * Execute block SSOR
- * preconditioning.
+ * Execute block SSOR preconditioning.
*
- * This function will
- * automatically use the inverse
- * matrices if they exist, if not
- * then BlockSOR will waste much
- * time inverting the diagonal
- * block matrices in each
- * preconditioning step.
+ * This function will automatically use the inverse matrices if they exist,
+ * if not then BlockSOR will waste much time inverting the diagonal block
+ * matrices in each preconditioning step.
*/
template <typename number2>
void vmult (Vector<number2> &, const Vector<number2> &) const;
void Tvmult (Vector<number2> &, const Vector<number2> &) const;
/**
- * Perform one step of the SOR
- * iteration.
+ * Perform one step of the SOR iteration.
*/
template <typename number2>
void step (Vector<number2> &dst, const Vector<number2> &rhs) const;
/**
- * Perform one step of the
- * transposed SOR iteration.
+ * Perform one step of the transposed SOR iteration.
*/
template <typename number2>
void Tstep (Vector<number2> &dst, const Vector<number2> &rhs) const;
template <typename number> class Vector;
/**
- * A class storing the inverse diagonal blocks for block
- * preconditioners and block relaxation methods.
+ * A class storing the inverse diagonal blocks for block preconditioners and
+ * block relaxation methods.
*
- * This class does the book keeping for preconditioners and relaxation
- * methods based on inverting blocks on the diagonal of a matrix.
- * It allows us to either store all diagonal blocks and their
- * inverses or the same block for each entry, and it keeps track of
- * the choice. Thus, after initializing it and filling the inverse
- * diagonal blocks correctly, a derived class can use inverse() with
- * an integer argument referring to the block number.
+ * This class does the book keeping for preconditioners and relaxation methods
+ * based on inverting blocks on the diagonal of a matrix. It allows us to
+ * either store all diagonal blocks and their inverses or the same block for
+ * each entry, and it keeps track of the choice. Thus, after initializing it
+ * and filling the inverse diagonal blocks correctly, a derived class can use
+ * inverse() with an integer argument referring to the block number.
*
- * Additionally, it allows the storage of the original diagonal
- * blocks, not only the inverses. These are for instance used in the
- * intermediate step of the SSOR preconditioner.
+ * Additionally, it allows the storage of the original diagonal blocks, not
+ * only the inverses. These are for instance used in the intermediate step of
+ * the SSOR preconditioner.
*
* @author Guido Kanschat
* @date 2010
typedef types::global_dof_index size_type;
/**
- * Choose a method for inverting
- * the blocks, and thus the data
- * type for the inverses.
+ * Choose a method for inverting the blocks, and thus the data type for the
+ * inverses.
*/
enum Inversion
{
/**
- * Use the standard
- * Gauss-Jacobi method
- * implemented in FullMatrix::inverse().
+ * Use the standard Gauss-Jacobi method implemented in
+ * FullMatrix::inverse().
*/
gauss_jordan,
/**
- * Use QR decomposition of
- * the Householder class.
+ * Use QR decomposition of the Householder class.
*/
householder,
/**
- * Use the singular value
- * decomposition of LAPACKFullMatrix.
+ * Use the singular value decomposition of LAPACKFullMatrix.
*/
svd
};
/**
- * Constructor initializing
- * default values.
+ * Constructor initializing default values.
*/
PreconditionBlockBase(bool store_diagonals = false,
Inversion method = gauss_jordan);
~PreconditionBlockBase();
/**
- * Deletes the inverse diagonal
- * block matrices if existent hence
- * leaves the class in the state
- * that it had directly after
- * calling the constructor.
+ * Deletes the inverse diagonal block matrices if existent hence leaves the
+ * class in the state that it had directly after calling the constructor.
*/
void clear();
/**
- * Resize to this number of
- * diagonal blocks with the given
- * block size. If
- * <tt>compress</tt> is true,
- * then only one block will be
- * stored.
+ * Resize to this number of diagonal blocks with the given block size. If
+ * <tt>compress</tt> is true, then only one block will be stored.
*/
void reinit(unsigned int nblocks, size_type blocksize, bool compress,
Inversion method = gauss_jordan);
/**
- * Tell the class that inverses
- * are computed.
+ * Tell the class that inverses are computed.
*/
void inverses_computed(bool are_they);
/**
- * Use only the inverse of the
- * first diagonal block to save
- * memory and computation time.
+ * Use only the inverse of the first diagonal block to save memory and
+ * computation time.
*
- * Possible applications:
- * computing on a cartesian grid,
- * all diagonal blocks are the
- * same or all diagonal blocks
- * are at least similar and
- * inversion of one of them still
- * yields a preconditioner.
+ * Possible applications: computing on a cartesian grid, all diagonal blocks
+ * are the same or all diagonal blocks are at least similar and inversion of
+ * one of them still yields a preconditioner.
*/
void set_same_diagonal ();
/**
- * Does the matrix use only one
- * diagonal block?
+ * Does the matrix use only one diagonal block?
*/
bool same_diagonal () const;
/**
- * Check, whether diagonal blocks
- * (not their inverses)
- * should be stored.
+ * Check, whether diagonal blocks (not their inverses) should be stored.
*/
bool store_diagonals() const;
/**
- * Return true, if inverses are
- * ready for use.
+ * Return true, if inverses are ready for use.
*/
bool inverses_ready () const;
unsigned int size() const;
/**
- * Read-only access to entries.
- * This function is only possible
- * if the inverse diagonal blocks
- * are stored.
+ * Read-only access to entries. This function is only possible if the
+ * inverse diagonal blocks are stored.
*/
number el(size_type i, size_type j) const;
/**
- * Multiply with the inverse
- * block at position <tt>i</tt>.
+ * Multiply with the inverse block at position <tt>i</tt>.
*/
template <typename number2>
void inverse_vmult(size_type i, Vector<number2> &dst, const Vector<number2> &src) const;
/**
- * Multiply with the transposed inverse
- * block at position <tt>i</tt>.
+ * Multiply with the transposed inverse block at position <tt>i</tt>.
*/
template <typename number2>
void inverse_Tvmult(size_type i, Vector<number2> &dst, const Vector<number2> &src) const;
/**
- * Access to the inverse diagonal
- * blocks if Inversion is #gauss_jordan.
+ * Access to the inverse diagonal blocks if Inversion is #gauss_jordan.
*/
FullMatrix<number> &inverse (size_type i);
/**
- * Access to the inverse diagonal
- * blocks if Inversion is #householder.
+ * Access to the inverse diagonal blocks if Inversion is #householder.
*/
Householder<number> &inverse_householder (size_type i);
/**
- * Access to the inverse diagonal
- * blocks if Inversion is #householder.
+ * Access to the inverse diagonal blocks if Inversion is #householder.
*/
LAPACKFullMatrix<number> &inverse_svd (size_type i);
/**
- * Access to the inverse diagonal
- * blocks.
+ * Access to the inverse diagonal blocks.
*/
const FullMatrix<number> &inverse (size_type i) const;
/**
- * Access to the inverse diagonal
- * blocks if Inversion is #householder.
+ * Access to the inverse diagonal blocks if Inversion is #householder.
*/
const Householder<number> &inverse_householder (size_type i) const;
/**
- * Access to the inverse diagonal
- * blocks if Inversion is #householder.
+ * Access to the inverse diagonal blocks if Inversion is #householder.
*/
const LAPACKFullMatrix<number> &inverse_svd (size_type i) const;
/**
- * Access to the diagonal
- * blocks.
+ * Access to the diagonal blocks.
*/
FullMatrix<number> &diagonal (size_type i);
/**
- * Access to the diagonal
- * blocks.
+ * Access to the diagonal blocks.
*/
const FullMatrix<number> &diagonal (size_type i) const;
/**
- * Print some statistics about
- * the inverses to @p deallog. Output depends
- * on #Inversion. It is richest
- * for svd, where we obtain
- * statistics on extremal
- * singular values and condition
- * numbers.
+ * Print some statistics about the inverses to @p deallog. Output depends on
+ * #Inversion. It is richest for svd, where we obtain statistics on extremal
+ * singular values and condition numbers.
*/
void log_statistics () const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
/**
- * You are trying to access a
- * diagonal block (not its
- * inverse), but you decided not
- * to store the diagonal blocks.
+ * You are trying to access a diagonal block (not its inverse), but you
+ * decided not to store the diagonal blocks.
*/
DeclException0 (ExcDiagonalsNotStored);
/**
- * You are accessing a diagonal
- * block, assuming that it has a certain
- * type. But, the method used for
- * inverting the diagonal blocks
- * does not use this type
+ * You are accessing a diagonal block, assuming that it has a certain type.
+ * But, the method used for inverting the diagonal blocks does not use this
+ * type
*/
DeclException0 (ExcInverseNotAvailable);
private:
/**
- * The number of (inverse)
- * diagonal blocks, if only one
- * is stored.
+ * The number of (inverse) diagonal blocks, if only one is stored.
*/
unsigned int n_diagonal_blocks;
/**
- * Storage of the inverse
- * matrices of the diagonal
- * blocks matrices as
- * <tt>FullMatrix<number></tt>
- * matrices, if Inversion
- * #gauss_jordan is used. Using
- * <tt>number=float</tt> saves
- * memory in comparison with
- * <tt>number=double</tt>, but
- * may introduce numerical instability.
+ * Storage of the inverse matrices of the diagonal blocks matrices as
+ * <tt>FullMatrix<number></tt> matrices, if Inversion #gauss_jordan is used.
+ * Using <tt>number=float</tt> saves memory in comparison with
+ * <tt>number=double</tt>, but may introduce numerical instability.
*/
std::vector<FullMatrix<number> > var_inverse_full;
/**
- * Storage of the inverse
- * matrices of the diagonal
- * blocks matrices as
- * <tt>Householder</tt>
- * matrices if Inversion
- * #householder is used. Using
- * <tt>number=float</tt> saves
- * memory in comparison with
- * <tt>number=double</tt>, but
- * may introduce numerical instability.
+ * Storage of the inverse matrices of the diagonal blocks matrices as
+ * <tt>Householder</tt> matrices if Inversion #householder is used. Using
+ * <tt>number=float</tt> saves memory in comparison with
+ * <tt>number=double</tt>, but may introduce numerical instability.
*/
std::vector<Householder<number> > var_inverse_householder;
/**
- * Storage of the inverse
- * matrices of the diagonal
- * blocks matrices as
- * <tt>LAPACKFullMatrix</tt>
- * matrices if Inversion
- * #svd is used. Using
- * <tt>number=float</tt> saves
- * memory in comparison with
- * <tt>number=double</tt>, but
- * may introduce numerical instability.
+ * Storage of the inverse matrices of the diagonal blocks matrices as
+ * <tt>LAPACKFullMatrix</tt> matrices if Inversion #svd is used. Using
+ * <tt>number=float</tt> saves memory in comparison with
+ * <tt>number=double</tt>, but may introduce numerical instability.
*/
std::vector<LAPACKFullMatrix<number> > var_inverse_svd;
/**
- * This is true, if the field
- * #var_diagonal is to be used.
+ * This is true, if the field #var_diagonal is to be used.
*/
bool var_store_diagonals;
/**
- * This is true, if only one
- * inverse is stored.
+ * This is true, if only one inverse is stored.
*/
bool var_same_diagonal;
/**
- * The inverse matrices are
- * usable. Set by the parent
- * class via inverses_computed().
+ * The inverse matrices are usable. Set by the parent class via
+ * inverses_computed().
*/
bool var_inverses_ready;
};
*/
/**
- * Selects the preconditioner. The constructor of this class takes
- * the name of the preconditioning and the damping parameter
- * @p omega of the preconditioning and the @p use_matrix function takes
- * the matrix that is used
- * by the matrix-builtin precondition functions. Each time, the <tt>operator()</tt> function
- * is called, this preselected preconditioner, this matrix and
- * this @p omega is used
- * for the preconditioning. This class is designed for being used as
- * argument of the @p solve function of a @p Solver and it covers the
- * selection of all matrix-builtin precondition functions. The selection
- * of other preconditioners, like BlockSOR or ILU should be handled in
- * derived classes by the user.
+ * Selects the preconditioner. The constructor of this class takes the name of
+ * the preconditioning and the damping parameter @p omega of the
+ * preconditioning and the @p use_matrix function takes the matrix that is
+ * used by the matrix-builtin precondition functions. Each time, the
+ * <tt>operator()</tt> function is called, this preselected preconditioner,
+ * this matrix and this @p omega is used for the preconditioning. This class
+ * is designed for being used as argument of the @p solve function of a @p
+ * Solver and it covers the selection of all matrix-builtin precondition
+ * functions. The selection of other preconditioners, like BlockSOR or ILU
+ * should be handled in derived classes by the user.
*
- * <h3>Usage</h3>
- * The simplest use of this class is the following:
+ * <h3>Usage</h3> The simplest use of this class is the following:
* @code
* // generate a @p SolverControl and
* // a @p VectorMemory
*
* solver_selector.solve(A,x,b,preconditioning);
* @endcode
- * Now the use of the @p SolverSelector in combination with the @p PreconditionSelector
- * allows the user to select both, the solver and the preconditioner, at the
- * beginning of his program and each time the
- * solver is started (that is several times e.g. in a nonlinear iteration) this
+ * Now the use of the @p SolverSelector in combination with the @p
+ * PreconditionSelector allows the user to select both, the solver and the
+ * preconditioner, at the beginning of his program and each time the solver is
+ * started (that is several times e.g. in a nonlinear iteration) this
* preselected solver and preconditioner is called.
*
* @author Ralf Hartmann, 1999
public:
/**
- * Constructor. @p omega denotes
- * the damping parameter of
- * the preconditioning.
+ * Constructor. @p omega denotes the damping parameter of the
+ * preconditioning.
*/
PreconditionSelector(const std::string &preconditioning,
const typename VECTOR::value_type &omega=1.);
virtual ~PreconditionSelector();
/**
- * Takes the matrix that is needed
- * for preconditionings that involves a
- * matrix. e.g. for @p precondition_jacobi,
- * <tt>~_sor</tt>, <tt>~_ssor</tt>.
+ * Takes the matrix that is needed for preconditionings that involves a
+ * matrix. e.g. for @p precondition_jacobi, <tt>~_sor</tt>, <tt>~_ssor</tt>.
*/
void use_matrix(const MATRIX &M);
/**
- * Precondition procedure. Calls the
- * preconditioning that was specified in
+ * Precondition procedure. Calls the preconditioning that was specified in
* the constructor.
*/
virtual void vmult (VECTOR &dst, const VECTOR &src) const;
/**
- * Get the names of all implemented
- * preconditionings.
+ * Get the names of all implemented preconditionings.
*/
static std::string get_precondition_names();
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
protected:
/**
- * Stores the name of the
- * preconditioning.
+ * Stores the name of the preconditioning.
*/
std::string preconditioning;
private:
/**
- * Matrix that is used for the
- * matrix-builtin preconditioning function.
- * cf. also @p PreconditionUseMatrix.
+ * Matrix that is used for the matrix-builtin preconditioning function. cf.
+ * also @p PreconditionUseMatrix.
*/
SmartPointer<const MATRIX,PreconditionSelector<MATRIX,VECTOR> > A;
/**
- * Stores the damping parameter
- * of the preconditioner.
+ * Stores the damping parameter of the preconditioner.
*/
const typename VECTOR::value_type omega;
};
DEAL_II_NAMESPACE_OPEN
/**
- * @warning The part of the interface based on BlockList may change in
- * a future release.
+ * @warning The part of the interface based on BlockList may change in a
+ * future release.
*
- * Base class for the implementation of overlapping, multiplicative
- * Schwarz relaxation methods and smoothers.
+ * Base class for the implementation of overlapping, multiplicative Schwarz
+ * relaxation methods and smoothers.
*
- * This class uses the infrastructure provided by
- * PreconditionBlockBase. It adds functions to initialize with a block
- * list and to do the relaxation step. The actual relaxation method
- * with the interface expected by SolverRelaxation and
- * MGSmootherRelaxation is in the derived classes.
+ * This class uses the infrastructure provided by PreconditionBlockBase. It
+ * adds functions to initialize with a block list and to do the relaxation
+ * step. The actual relaxation method with the interface expected by
+ * SolverRelaxation and MGSmootherRelaxation is in the derived classes.
*
* This class allows for more general relaxation methods than
- * PreconditionBlock, since the index sets may be arbitrary and
- * overlapping, while there only contiguous, disjoint sets of equal
- * size are allowed. As a drawback, this class cannot be used as a
- * preconditioner, since its implementation relies on a straight
- * forward implementation of the Gauss-Seidel process.
+ * PreconditionBlock, since the index sets may be arbitrary and overlapping,
+ * while there only contiguous, disjoint sets of equal size are allowed. As a
+ * drawback, this class cannot be used as a preconditioner, since its
+ * implementation relies on a straight forward implementation of the Gauss-
+ * Seidel process.
*
* @ingroup Preconditioners
* @author Guido Kanschat
typename PreconditionBlockBase<inverse_type>::Inversion inversion;
/**
- * The if #inversion is SVD, the threshold below which a singular
- * value will be considered zero and thus not inverted. This
- * parameter is used in the call to
- * LAPACKFullMatrix::compute_inverse_svd().
+ * The if #inversion is SVD, the threshold below which a singular value
+ * will be considered zero and thus not inverted. This parameter is used
+ * in the call to LAPACKFullMatrix::compute_inverse_svd().
*/
double threshold;
/**
- * The order in which blocks should be traversed. This vector can
- * initiate several modes of execution:
+ * The order in which blocks should be traversed. This vector can initiate
+ * several modes of execution:
*
* <ol>
*
- * <li>If the length of the vector is zero, then the relaxation
- * method will be executed from first to last block.</li>
+ * <li>If the length of the vector is zero, then the relaxation method
+ * will be executed from first to last block.</li>
*
- * <li> If the length is one, then the inner vector must have the
- * same size as the number of blocks. The relaxation method is
- * applied in the order given in this vector.</li>
+ * <li> If the length is one, then the inner vector must have the same
+ * size as the number of blocks. The relaxation method is applied in the
+ * order given in this vector.</li>
*
- * <li> If the outer vector has length greater one, then the
- * relaxation method is applied several times, each time in the
- * order given by the inner vector of the corresponding
- * index. This mode can for instance be used for ADI methods and
- * similar direction sweeps.</li>
+ * <li> If the outer vector has length greater one, then the relaxation
+ * method is applied several times, each time in the order given by the
+ * inner vector of the corresponding index. This mode can for instance be
+ * used for ADI methods and similar direction sweeps.</li>
*
* </ol>
*/
};
/**
- * Initialize matrix and block size. We store the matrix and the
- * block size in the preconditioner object. In a second step, the
- * inverses of the diagonal blocks may be computed.
+ * Initialize matrix and block size. We store the matrix and the block size
+ * in the preconditioner object. In a second step, the inverses of the
+ * diagonal blocks may be computed.
*
- * Additionally, a relaxation parameter for derived classes may be
- * provided.
+ * Additionally, a relaxation parameter for derived classes may be provided.
*/
void initialize (const MATRIX &A,
const AdditionalData ¶meters);
/**
* Deletes the inverse diagonal block matrices if existent, sets the
- * blocksize to 0, hence leaves the class in the state that it had
- * directly after calling the constructor.
+ * blocksize to 0, hence leaves the class in the state that it had directly
+ * after calling the constructor.
*/
void clear();
bool empty () const;
/**
- * Read-only access to entries. This function is only possible if
- * the inverse diagonal blocks are stored.
+ * Read-only access to entries. This function is only possible if the
+ * inverse diagonal blocks are stored.
*/
value_type el(size_type i,
size_type j) const;
/**
- * Stores the inverse of the diagonal blocks in @p inverse. This
- * costs some additional memory - for DG methods about 1/3 (for
- * double inverses) or 1/6 (for float inverses) of that used for the
- * matrix - but it makes the preconditioning much faster.
+ * Stores the inverse of the diagonal blocks in @p inverse. This costs some
+ * additional memory - for DG methods about 1/3 (for double inverses) or 1/6
+ * (for float inverses) of that used for the matrix - but it makes the
+ * preconditioning much faster.
*
- * It is not allowed to call this function twice (will produce an
- * error) before a call of <tt>clear(...)</tt> because at the second
- * time there already exist the inverse matrices.
+ * It is not allowed to call this function twice (will produce an error)
+ * before a call of <tt>clear(...)</tt> because at the second time there
+ * already exist the inverse matrices.
*
- * After this function is called, the lock on the matrix given
- * through the @p use_matrix function is released, i.e. you may
- * overwrite of delete it. You may want to do this in case you use
- * this matrix to precondition another matrix.
+ * After this function is called, the lock on the matrix given through the
+ * @p use_matrix function is released, i.e. you may overwrite of delete it.
+ * You may want to do this in case you use this matrix to precondition
+ * another matrix.
*/
void invert_diagblocks();
/**
* Perform one block relaxation step.
*
- * Depending on the arguments @p dst and @p pref, this performs an
- * SOR step (both reference the same vector) of a Jacobi step (both
- * are different vectors). For the Jacobi step, the calling function
- * must copy @p dst to @p pref after this.
+ * Depending on the arguments @p dst and @p pref, this performs an SOR step
+ * (both reference the same vector) of a Jacobi step (both are different
+ * vectors). For the Jacobi step, the calling function must copy @p dst to
+ * @p pref after this.
*/
template <typename number2>
void do_step (
const Vector<number2> &src,
const bool backward) const;
/**
- * Pointer to the matrix. Make sure that the matrix exists as long
- * as this class needs it, i.e. until calling @p invert_diagblocks,
- * or (if the inverse matrices should not be stored) until the last
- * call of the preconditoining @p vmult function of the derived
- * classes.
+ * Pointer to the matrix. Make sure that the matrix exists as long as this
+ * class needs it, i.e. until calling @p invert_diagblocks, or (if the
+ * inverse matrices should not be stored) until the last call of the
+ * preconditoining @p vmult function of the derived classes.
*/
SmartPointer<const MATRIX,RelaxationBlock<MATRIX,inverse_type> > A;
/**
- * Block Jacobi (additive Schwarz) method with possibly overlapping
- * blocks.
+ * Block Jacobi (additive Schwarz) method with possibly overlapping blocks.
*
* This class implements the step() and Tstep() functions expected by
- * SolverRelaxation and MGSmootherRelaxation. They perform an additive
- * Schwarz method on the blocks provided in the BlockList of
- * AdditionalData. Differing from PreconditionBlockJacobi, these
- * blocks may be of varying size, non-contiguous, and overlapping. On
- * the other hand, this class does not implement the preconditioner
- * interface expected by Solver objects.
+ * SolverRelaxation and MGSmootherRelaxation. They perform an additive Schwarz
+ * method on the blocks provided in the BlockList of AdditionalData. Differing
+ * from PreconditionBlockJacobi, these blocks may be of varying size, non-
+ * contiguous, and overlapping. On the other hand, this class does not
+ * implement the preconditioner interface expected by Solver objects.
*
* @ingroup Preconditioners
* @author Guido Kanschat
using typename RelaxationBlock<MATRIX,inverse_type>::AdditionalData;
/**
- * Make initialization function
- * publicly available.
+ * Make initialization function publicly available.
*/
using RelaxationBlock<MATRIX, inverse_type>::initialize;
using RelaxationBlock<MATRIX, inverse_type>::inverse_svd;
using PreconditionBlockBase<inverse_type>::log_statistics;
/**
- * Perform one step of the Jacobi iteration.
- */
+ * Perform one step of the Jacobi iteration.
+ */
template <typename number2>
void step (Vector<number2> &dst, const Vector<number2> &rhs) const;
* Block Gauss-Seidel method with possibly overlapping blocks.
*
* This class implements the step() and Tstep() functions expected by
- * SolverRelaxation and MGSmootherRelaxation. They perform a
- * multiplicative Schwarz method on the blocks provided in the
- * BlockList of AdditionalData. Differing from PreconditionBlockSOR,
- * these blocks may be of varying size, non-contiguous, and
- * overlapping. On the other hand, this class does not implement the
- * preconditioner interface expected by Solver objects.
+ * SolverRelaxation and MGSmootherRelaxation. They perform a multiplicative
+ * Schwarz method on the blocks provided in the BlockList of AdditionalData.
+ * Differing from PreconditionBlockSOR, these blocks may be of varying size,
+ * non-contiguous, and overlapping. On the other hand, this class does not
+ * implement the preconditioner interface expected by Solver objects.
*
* @ingroup Preconditioners
* @author Guido Kanschat
using typename RelaxationBlock<MATRIX,inverse_type>::AdditionalData;
/**
- * Make initialization function
- * publicly available.
+ * Make initialization function publicly available.
*/
using RelaxationBlock<MATRIX, inverse_type>::initialize;
* Symmetric block Gauss-Seidel method with possibly overlapping blocks.
*
* This class implements the step() and Tstep() functions expected by
- * SolverRelaxation and MGSmootherRelaxation. They perform a
- * multiplicative Schwarz method on the blocks provided in the
- * BlockList of AdditionalData in symmetric fashion. Differing from
- * PreconditionBlockSSOR, these blocks may be of varying size,
- * non-contiguous, and overlapping. On the other hand, this class does
- * not implement the preconditioner interface expected by Solver
- * objects.
+ * SolverRelaxation and MGSmootherRelaxation. They perform a multiplicative
+ * Schwarz method on the blocks provided in the BlockList of AdditionalData in
+ * symmetric fashion. Differing from PreconditionBlockSSOR, these blocks may
+ * be of varying size, non-contiguous, and overlapping. On the other hand,
+ * this class does not implement the preconditioner interface expected by
+ * Solver objects.
*
* @ingroup Preconditioners
* @author Guido Kanschat
/**
* Schur complement of a block matrix.
*
- * Given a non-singular matrix @p A (often positive definite) and a
- * positive semi-definite matrix @p C as well as matrices @p B and
- * @p Dt of full rank, this class implements a new matrix, the Schur
- * complement a the system of equations of the structure
+ * Given a non-singular matrix @p A (often positive definite) and a positive
+ * semi-definite matrix @p C as well as matrices @p B and @p Dt of full rank,
+ * this class implements a new matrix, the Schur complement a the system of
+ * equations of the structure
*
* @verbatim
* / \ / \ / \
*
* The data handed to the Schur matrix are as follows:
*
- * @p A: the inverse of @p A is stored, instead of @p A. This
- * allows the application to use the most efficient form of inversion,
- * iterative or direct.
+ * @p A: the inverse of @p A is stored, instead of @p A. This allows the
+ * application to use the most efficient form of inversion, iterative or
+ * direct.
*
* @p B, @p C: these matrices are stored "as is".
*
- * @p Dt: the computation of the Schur complement involves the
- * function @p Tvmult of the matrix @p Dt, not @p vmult! This way,
- * it is sufficient to build only one matrix @p B for the symmetric
- * Schur complement and use it twice.
+ * @p Dt: the computation of the Schur complement involves the function @p
+ * Tvmult of the matrix @p Dt, not @p vmult! This way, it is sufficient to
+ * build only one matrix @p B for the symmetric Schur complement and use it
+ * twice.
*
- * All matrices involved are of arbitrary type and vectors are
- * BlockVectors. This way, @p SchurMatrix can be coupled with
- * any matrix classes providing @p vmult and @p Tvmult and can be
- * even nested. Since SmartPointers of matrices are stored, the
- * matrix blocks should be derived from Subscriptor.
+ * All matrices involved are of arbitrary type and vectors are BlockVectors.
+ * This way, @p SchurMatrix can be coupled with any matrix classes providing
+ * @p vmult and @p Tvmult and can be even nested. Since SmartPointers of
+ * matrices are stored, the matrix blocks should be derived from Subscriptor.
*
- * Since the Schur complement of a matrix corresponds to a Gaussian
- * block elimination, the right hand side of the condensed system must
- * be preprocessed. Furthermore, the eliminated variable must be
- * reconstructed after solving.
+ * Since the Schur complement of a matrix corresponds to a Gaussian block
+ * elimination, the right hand side of the condensed system must be
+ * preprocessed. Furthermore, the eliminated variable must be reconstructed
+ * after solving.
*
* @verbatim
* g = g + B A-inverse f
* u = A-inverse (f - D-transpose p)
* @endverbatim
*
- * Applying these transformations, the solution of the system above by a
- * @p SchurMatrix @p schur is coded as follows:
+ * Applying these transformations, the solution of the system above by a @p
+ * SchurMatrix @p schur is coded as follows:
*
* @code
* schur.prepare_rhs (g, f);
public:
/**
- * Constructor. This constructor
- * receives all the matrices
- * needed. Furthermore, it gets a
- * reference to a memory structure
- * for obtaining block vectors.
+ * Constructor. This constructor receives all the matrices needed.
+ * Furthermore, it gets a reference to a memory structure for obtaining
+ * block vectors.
*
- * Optionally, the length of the
- * @p u-vector can be provided.
+ * Optionally, the length of the @p u-vector can be provided.
*
- * For the meaning of the matrices
- * see the class documentation.
+ * For the meaning of the matrices see the class documentation.
*/
SchurMatrix(const MA_inverse &Ainv,
const MB &B,
const std::vector<unsigned int> &signature = std::vector<unsigned int>(0));
/**
- * Do block elimination of the
- * right hand side. Given right
- * hand sides for both components
- * of the block system, this
- * function provides the right hand
- * side for the Schur complement.
+ * Do block elimination of the right hand side. Given right hand sides for
+ * both components of the block system, this function provides the right
+ * hand side for the Schur complement.
*
- * The result is stored in the
- * first argument, which is also
- * part of the input data. If it is
- * necessary to conserve the data,
- * @p dst must be copied before
- * calling this function. This is
- * reasonable, since in many cases,
- * only the pre-processed right
- * hand side is needed.
+ * The result is stored in the first argument, which is also part of the
+ * input data. If it is necessary to conserve the data, @p dst must be
+ * copied before calling this function. This is reasonable, since in many
+ * cases, only the pre-processed right hand side is needed.
*/
void prepare_rhs (BlockVector<double> &dst,
const BlockVector<double> &src) const;
/**
- * Multiplication with the Schur
- * complement.
+ * Multiplication with the Schur complement.
*/
void vmult (BlockVector<double> &dst,
const BlockVector<double> &src) const;
// void Tmult(BlockVector<double>& dst, const BlockVector<double>& src) const;
/**
- * Computation of the residual of
- * the Schur complement.
+ * Computation of the residual of the Schur complement.
*/
double residual (BlockVector<double> &dst,
const BlockVector<double> &src,
const BlockVector<double> &rhs) const;
/**
- * Compute the eliminated variable
- * from the solution of the Schur
- * complement problem.
+ * Compute the eliminated variable from the solution of the Schur complement
+ * problem.
*/
void postprocess (BlockVector<double> &dst,
const BlockVector<double> &src,
const BlockVector<double> &rhs) const;
/**
- * Select debugging information for
- * log-file. Debug level 1 is
- * defined and writes the norm of
- * every vector before and after
- * each operation. Debug level 0
- * turns off debugging information.
+ * Select debugging information for log-file. Debug level 1 is defined and
+ * writes the norm of every vector before and after each operation. Debug
+ * level 0 turns off debugging information.
*/
void debug_level(unsigned int l);
private:
/**
* Matrix with shifted diagonal values.
*
- * Given a matrix <tt>A</tt>, this class implements a matrix-vector
- * product with <i>A+s I</i>, where <i>s</i> is a provided shift
- * parameter.
+ * Given a matrix <tt>A</tt>, this class implements a matrix-vector product
+ * with <i>A+s I</i>, where <i>s</i> is a provided shift parameter.
*
* @author Guido Kanschat, 2000, 2001
*/
{
public:
/**
- * Constructor. Provide the base
- * matrix and a shift parameter.
+ * Constructor. Provide the base matrix and a shift parameter.
*/
ShiftedMatrix (const MATRIX &A, const double sigma);
/**
- * Matrix with shifted diagonal values with respect to a certain scalar product.
+ * Matrix with shifted diagonal values with respect to a certain scalar
+ * product.
*
* Given a matrix <tt>A</tt>, this class implements a matrix-vector product
* with <i>A+s M</i>, where <i>s</i> is a provided shift parameter and
{
public:
/**
- * Constructor.
- * Provide the base matrix and a shift parameter.
+ * Constructor. Provide the base matrix and a shift parameter.
*/
ShiftedMatrixGeneralized (const MATRIX &A,
const MASSMATRIX &M,
DEAL_II_NAMESPACE_OPEN
/**
- * Base class for solver classes using the SLEPc solvers which are
- * selected based on flags passed to the eigenvalue problem solver
- * context. Derived classes set the right flags to set the right
- * solver. Note that: the <code>AdditionalData</code> structure is a
- * dummy structure that currently exists for backward/forward
- * compatibility only.
+ * Base class for solver classes using the SLEPc solvers which are selected
+ * based on flags passed to the eigenvalue problem solver context. Derived
+ * classes set the right flags to set the right solver. Note that: the
+ * <code>AdditionalData</code> structure is a dummy structure that currently
+ * exists for backward/forward compatibility only.
*
- * The SLEPc solvers are intended to be used for solving the
- * generalized eigenspectrum problem $(A-\lambda B)x=0$, for $x\neq0$;
- * where $A$ is a system matrix, $B$ is a mass matrix, and $\lambda,
- * x$ are a set of eigenvalues and eigenvectors respectively. The
- * emphasis is on methods and techniques appropriate for problems in
- * which the associated matrices are sparse. Most of the methods
- * offered by the SLEPc library are projection methods or other
- * methods with similar properties; and wrappers are provided to
- * interface to SLEPc solvers that handle both of these problem sets.
+ * The SLEPc solvers are intended to be used for solving the generalized
+ * eigenspectrum problem $(A-\lambda B)x=0$, for $x\neq0$; where $A$ is a
+ * system matrix, $B$ is a mass matrix, and $\lambda, x$ are a set of
+ * eigenvalues and eigenvectors respectively. The emphasis is on methods and
+ * techniques appropriate for problems in which the associated matrices are
+ * sparse. Most of the methods offered by the SLEPc library are projection
+ * methods or other methods with similar properties; and wrappers are provided
+ * to interface to SLEPc solvers that handle both of these problem sets.
*
- * SLEPcWrappers can be implemented in application codes in the
- * following way:
+ * SLEPcWrappers can be implemented in application codes in the following way:
* @code
* SolverControl solver_control (1000, 1e-9);
* SolverArnoldi system (solver_control, mpi_communicator);
* system.solve (A, B, lambda, x, size_of_spectrum);
* @endcode
- * for the generalized eigenvalue problem $Ax=B\lambda x$, where the
- * variable <code>const unsigned int size_of_spectrum</code> tells
- * SLEPc the number of eigenvector/eigenvalue pairs to solve
- * for. Additional options and solver parameters can be passed to the
- * SLEPc solvers before calling <code>solve()</code>. For example, if
- * the matrices of the general eigenspectrum problem are not hermitian
- * and the lower eigenvalues are wanted only, the following code can
- * be implemented before calling <code>solve()</code>:
+ * for the generalized eigenvalue problem $Ax=B\lambda x$, where the variable
+ * <code>const unsigned int size_of_spectrum</code> tells SLEPc the number of
+ * eigenvector/eigenvalue pairs to solve for. Additional options and solver
+ * parameters can be passed to the SLEPc solvers before calling
+ * <code>solve()</code>. For example, if the matrices of the general
+ * eigenspectrum problem are not hermitian and the lower eigenvalues are
+ * wanted only, the following code can be implemented before calling
+ * <code>solve()</code>:
* @code
* system.set_problem_type (EPS_NHEP);
* system.set_which_eigenpairs (EPS_SMALLEST_REAL);
*
* See also <code>step-36</code> for a hands-on example.
*
- * An alternative implementation to the one above is to use the API
- * internals directly within the application code. In this way the
- * calling sequence requires calling several of SolverBase functions
- * rather than just one. This freedom is intended for use of the
- * SLEPcWrappers that require a greater handle on the eigenvalue
- * problem solver context. See also the API of, for example:
- @code
- template <typename OutputVector>
- void
- SolverBase::solve (const PETScWrappers::MatrixBase &A,
- const PETScWrappers::MatrixBase &B,
- std::vector<PetscScalar> &eigenvalues,
- std::vector<OutputVector> &eigenvectors,
- const unsigned int n_eigenpairs)
- { ... }
- @endcode
+ * An alternative implementation to the one above is to use the API internals
+ * directly within the application code. In this way the calling sequence
+ * requires calling several of SolverBase functions rather than just one. This
+ * freedom is intended for use of the SLEPcWrappers that require a greater
+ * handle on the eigenvalue problem solver context. See also the API of, for
+ * example:
+ * @code
+ * template <typename OutputVector>
+ * void
+ * SolverBase::solve (const PETScWrappers::MatrixBase &A,
+ * const PETScWrappers::MatrixBase &B,
+ * std::vector<PetscScalar> &eigenvalues,
+ * std::vector<OutputVector> &eigenvectors,
+ * const unsigned int n_eigenpairs)
+ * { ... }
+ * @endcode
* as an example on how to do this.
*
- * For further information and explanations on handling the @ref
- * SLEPcWrappers "SLEPcWrappers", see also the @ref PETScWrappers
- * "PETScWrappers", on which they depend.
+ * For further information and explanations on handling the @ref SLEPcWrappers
+ * "SLEPcWrappers", see also the @ref PETScWrappers "PETScWrappers", on which
+ * they depend.
*
* @ingroup SLEPcWrappers
*
- * @author Toby D. Young 2008, 2009, 2010, 2011, 2013; and Rickard
- * Armiento 2008.
+ * @author Toby D. Young 2008, 2009, 2010, 2011, 2013; and Rickard Armiento
+ * 2008.
*
- * @note Various tweaks and enhancments contributed by Eloy Romero and
- * Jose E. Roman 2009, 2010.
+ * @note Various tweaks and enhancments contributed by Eloy Romero and Jose E.
+ * Roman 2009, 2010.
*/
namespace SLEPcWrappers
{
/**
- * Base class for solver classes using the SLEPc solvers. Since
- * solvers in SLEPc are selected based on flags passed to a generic
- * solver object, basically all the actual solver calls happen in
- * this class, and derived classes simply set the right flags to
- * select one solver or another, or to set certain parameters for
- * individual solvers.
+ * Base class for solver classes using the SLEPc solvers. Since solvers in
+ * SLEPc are selected based on flags passed to a generic solver object,
+ * basically all the actual solver calls happen in this class, and derived
+ * classes simply set the right flags to select one solver or another, or to
+ * set certain parameters for individual solvers.
*/
class SolverBase
{
virtual ~SolverBase ();
/**
- * Composite method that solves the eigensystem $Ax=\lambda
- * x$. The eigenvector sent in has to have at least one element
- * that we can use as a template when resizing, since we do not
- * know the parameters of the specific vector class used
- * (i.e. local_dofs for MPI vectors). However, while copying
- * eigenvectors, at least twice the memory size of
- * <tt>eigenvectors</tt> is being used (and can be more). To avoid
- * doing this, the fairly standard calling sequence executed here
- * is used: Initialise; Set up matrices for solving; Actually
- * solve the system; Gather the solution(s); and reset.
+ * Composite method that solves the eigensystem $Ax=\lambda x$. The
+ * eigenvector sent in has to have at least one element that we can use as
+ * a template when resizing, since we do not know the parameters of the
+ * specific vector class used (i.e. local_dofs for MPI vectors). However,
+ * while copying eigenvectors, at least twice the memory size of
+ * <tt>eigenvectors</tt> is being used (and can be more). To avoid doing
+ * this, the fairly standard calling sequence executed here is used:
+ * Initialise; Set up matrices for solving; Actually solve the system;
+ * Gather the solution(s); and reset.
*
- * @note Note that the number of converged eigenvectors can be
- * larger than the number of eigenvectors requested; this is due
- * to a round off error (success) of the eigenproblem solver
- * context. If this is found to be the case we simply do not
- * bother with more eigenpairs than requested, but handle that it
- * may be more than specified by ignoring any extras. By default
- * one eigenvector/eigenvalue pair is computed.
+ * @note Note that the number of converged eigenvectors can be larger than
+ * the number of eigenvectors requested; this is due to a round off error
+ * (success) of the eigenproblem solver context. If this is found to be
+ * the case we simply do not bother with more eigenpairs than requested,
+ * but handle that it may be more than specified by ignoring any extras.
+ * By default one eigenvector/eigenvalue pair is computed.
*/
template <typename OutputVector>
void
const unsigned int n_eigenpairs = 1);
/**
- * Same as above, but here a composite method for solving the
- * system $A x=\lambda B x$, for real matrices, vectors, and
- * values $A, B, x, \lambda$.
+ * Same as above, but here a composite method for solving the system $A
+ * x=\lambda B x$, for real matrices, vectors, and values $A, B, x,
+ * \lambda$.
*/
template <typename OutputVector>
void
const unsigned int n_eigenpairs = 1);
/**
- * Same as above, but here a composite method for solving the
- * system $A x=\lambda B x$ with real matrices $A, B$ and
- * imaginary eigenpairs $x, \lambda$.
+ * Same as above, but here a composite method for solving the system $A
+ * x=\lambda B x$ with real matrices $A, B$ and imaginary eigenpairs $x,
+ * \lambda$.
*/
template <typename OutputVector>
void
set_transformation (SLEPcWrappers::TransformationBase &this_transformation);
/**
- * Set target eigenvalues in the spectrum to be computed. By
- * default, no target is set.
+ * Set target eigenvalues in the spectrum to be computed. By default, no
+ * target is set.
*/
void
set_target_eigenvalue (const PetscScalar &this_target);
/**
- * Indicate which part of the spectrum is to be computed. By
- * default largest magnitude eigenvalues are computed.
+ * Indicate which part of the spectrum is to be computed. By default
+ * largest magnitude eigenvalues are computed.
*
* @note For other allowed values see the SLEPc documentation.
*/
set_which_eigenpairs (EPSWhich set_which);
/**
- * Specify the type of the eigenspectrum problem. This can be used
- * to exploit known symmetries of the matrices that make up the
- * standard/generalized eigenspectrum problem. By default a
- * non-Hermitian problem is assumed.
+ * Specify the type of the eigenspectrum problem. This can be used to
+ * exploit known symmetries of the matrices that make up the
+ * standard/generalized eigenspectrum problem. By default a non-Hermitian
+ * problem is assumed.
*
* @note For other allowed values see the SLEPc documentation.
*/
/**
* Take the information provided from SLEPc and checks it against
- * deal.II's own SolverControl objects to see if convergence has
- * been reached.
+ * deal.II's own SolverControl objects to see if convergence has been
+ * reached.
*/
void
get_solver_state (const SolverControl::State state);
protected:
/**
- * Reference to the object that controls convergence of the
- * iterative solver.
+ * Reference to the object that controls convergence of the iterative
+ * solver.
*/
SolverControl &solver_control;
const MPI_Comm mpi_communicator;
/**
- * Function that takes an Eigenvalue Problem Solver context
- * object, and sets the type of solver that is requested by the
- * derived class.
+ * Function that takes an Eigenvalue Problem Solver context object, and
+ * sets the type of solver that is requested by the derived class.
*/
virtual void set_solver_type (EPS &eps) const = 0;
EPS *get_eps ();
/**
- * Solve the linear system for <code>n_eigenpairs</code>
- * eigenstates. Parameter <code>n_converged</code> contains the
- * actual number of eigenstates that have converged; this can
- * be both fewer or more than n_eigenpairs, depending on the
- * SLEPc eigensolver used.
+ * Solve the linear system for <code>n_eigenpairs</code> eigenstates.
+ * Parameter <code>n_converged</code> contains the actual number of
+ * eigenstates that have converged; this can be both fewer or more than
+ * n_eigenpairs, depending on the SLEPc eigensolver used.
*/
void
solve (const unsigned int n_eigenpairs,
unsigned int *n_converged);
/**
- * Access the real parts of solutions for a solved eigenvector
- * problem, pair index solutions, $\text{index}\,\in\,0\hdots
+ * Access the real parts of solutions for a solved eigenvector problem,
+ * pair index solutions, $\text{index}\,\in\,0\hdots
* \text{n\_converged}-1$.
*/
void
/**
* Access the real and imaginary parts of solutions for a solved
- * eigenvector problem, pair index solutions,
- * $\text{index}\,\in\,0\hdots \text{n\_converged}-1$.
+ * eigenvector problem, pair index solutions, $\text{index}\,\in\,0\hdots
+ * \text{n\_converged}-1$.
*/
void
get_eigenpair (const unsigned int index,
PETScWrappers::VectorBase &imag_eigenvectors);
/**
- * Initialize solver for the linear system $Ax=\lambda x$. (Note:
- * this is required before calling solve ())
+ * Initialize solver for the linear system $Ax=\lambda x$. (Note: this is
+ * required before calling solve ())
*/
void
set_matrices (const PETScWrappers::MatrixBase &A);
/**
- * Same as above, but here initialize solver for the linear system
- * $A x=\lambda B x$.
+ * Same as above, but here initialize solver for the linear system $A
+ * x=\lambda B x$.
*/
void
set_matrices (const PETScWrappers::MatrixBase &A,
private:
/**
- * The matrix $A$ of the generalized eigenvalue problem
- * $Ax=B\lambda x$, or the standard eigenvalue problem $Ax=\lambda
- * x$.
+ * The matrix $A$ of the generalized eigenvalue problem $Ax=B\lambda x$,
+ * or the standard eigenvalue problem $Ax=\lambda x$.
*/
const PETScWrappers::MatrixBase *opA;
/**
- * The matrix $B$ of the generalized eigenvalue problem
- * $Ax=B\lambda x$.
+ * The matrix $B$ of the generalized eigenvalue problem $Ax=B\lambda x$.
*/
const PETScWrappers::MatrixBase *opB;
const PETScWrappers::VectorBase *initial_vector;
/**
- * Pointer to an an object that describes transformations that can
- * be applied to the eigenvalue problem.
+ * Pointer to an an object that describes transformations that can be
+ * applied to the eigenvalue problem.
*/
SLEPcWrappers::TransformationBase *transformation;
void *solver_control);
/**
- * Objects of this type are explicitly created, but are destroyed
- * when the surrounding solver object goes out of scope, or when
- * we assign a new value to the pointer to this object. The
- * respective Destroy functions are therefore written into the
- * destructor of this object, even though the object does not have
- * a constructor.
+ * Objects of this type are explicitly created, but are destroyed when the
+ * surrounding solver object goes out of scope, or when we assign a new
+ * value to the pointer to this object. The respective Destroy functions
+ * are therefore written into the destructor of this object, even though
+ * the object does not have a constructor.
*/
struct SolverData
{
};
/**
- * An implementation of the solver interface using the SLEPc
- * Krylov-Schur solver. Usage: All spectrum, all problem types,
- * complex.
+ * An implementation of the solver interface using the SLEPc Krylov-Schur
+ * solver. Usage: All spectrum, all problem types, complex.
*
* @ingroup SLEPcWrappers
*
public:
/**
- * Standardized data struct to pipe additional data to the solver,
- * should it be needed.
+ * Standardized data struct to pipe additional data to the solver, should
+ * it be needed.
*/
struct AdditionalData
{};
/**
- * SLEPc solvers will want to have an MPI communicator context
- * over which computations are parallelized. By default, this
- * carries the same behaviour has the PETScWrappers, but you can
- * change that.
+ * SLEPc solvers will want to have an MPI communicator context over which
+ * computations are parallelized. By default, this carries the same
+ * behaviour has the PETScWrappers, but you can change that.
*/
SolverKrylovSchur (SolverControl &cn,
const MPI_Comm &mpi_communicator = PETSC_COMM_SELF,
const AdditionalData additional_data;
/**
- * Function that takes a Eigenvalue Problem Solver context object,
- * and sets the type of solver that is appropriate for this class.
+ * Function that takes a Eigenvalue Problem Solver context object, and
+ * sets the type of solver that is appropriate for this class.
*/
virtual void set_solver_type (EPS &eps) const;
};
/**
- * An implementation of the solver interface using the SLEPc Arnoldi
- * solver. Usage: All spectrum, all problem types, complex.
+ * An implementation of the solver interface using the SLEPc Arnoldi solver.
+ * Usage: All spectrum, all problem types, complex.
*
* @ingroup SLEPcWrappers
*
{
public:
/**
- * Standardized data struct to pipe additional data to the solver,
- * should it be needed.
+ * Standardized data struct to pipe additional data to the solver, should
+ * it be needed.
*/
struct AdditionalData
{
};
/**
- * SLEPc solvers will want to have an MPI communicator context
- * over which computations are parallelized. By default, this
- * carries the same behaviour has the PETScWrappers, but you can
- * change that.
+ * SLEPc solvers will want to have an MPI communicator context over which
+ * computations are parallelized. By default, this carries the same
+ * behaviour has the PETScWrappers, but you can change that.
*/
SolverArnoldi (SolverControl &cn,
const MPI_Comm &mpi_communicator = PETSC_COMM_SELF,
const AdditionalData additional_data;
/**
- * Function that takes a Eigenvalue Problem Solver context object,
- * and sets the type of solver that is appropriate for this class.
+ * Function that takes a Eigenvalue Problem Solver context object, and
+ * sets the type of solver that is appropriate for this class.
*/
virtual void set_solver_type (EPS &eps) const;
};
/**
- * An implementation of the solver interface using the SLEPc Lanczos
- * solver. Usage: All spectrum, all problem types, complex.
+ * An implementation of the solver interface using the SLEPc Lanczos solver.
+ * Usage: All spectrum, all problem types, complex.
*
* @ingroup SLEPcWrappers
*
{
public:
/**
- * Standardized data struct to pipe additional data to the solver,
- * should it be needed.
+ * Standardized data struct to pipe additional data to the solver, should
+ * it be needed.
*/
struct AdditionalData
{};
/**
- * SLEPc solvers will want to have an MPI communicator context
- * over which computations are parallelized. By default, this
- * carries the same behaviour has the PETScWrappers, but you can
- * change that.
+ * SLEPc solvers will want to have an MPI communicator context over which
+ * computations are parallelized. By default, this carries the same
+ * behaviour has the PETScWrappers, but you can change that.
*/
SolverLanczos (SolverControl &cn,
const MPI_Comm &mpi_communicator = PETSC_COMM_SELF,
const AdditionalData additional_data;
/**
- * Function that takes a Eigenvalue Problem Solver context object,
- * and sets the type of solver that is appropriate for this class.
+ * Function that takes a Eigenvalue Problem Solver context object, and
+ * sets the type of solver that is appropriate for this class.
*/
virtual void set_solver_type (EPS &eps) const;
};
/**
- * An implementation of the solver interface using the SLEPc Power
- * solver. Usage: Largest values of spectrum only, all problem
- * types, complex.
+ * An implementation of the solver interface using the SLEPc Power solver.
+ * Usage: Largest values of spectrum only, all problem types, complex.
*
* @ingroup SLEPcWrappers
*
{
public:
/**
- * Standardized data struct to pipe additional data to the solver,
- * should it be needed.
+ * Standardized data struct to pipe additional data to the solver, should
+ * it be needed.
*/
struct AdditionalData
{};
/**
- * SLEPc solvers will want to have an MPI communicator context
- * over which computations are parallelized. By default, this
- * carries the same behaviour has the PETScWrappers, but you can
- * change that.
+ * SLEPc solvers will want to have an MPI communicator context over which
+ * computations are parallelized. By default, this carries the same
+ * behaviour has the PETScWrappers, but you can change that.
*/
SolverPower (SolverControl &cn,
const MPI_Comm &mpi_communicator = PETSC_COMM_SELF,
const AdditionalData additional_data;
/**
- * Function that takes a Eigenvalue Problem Solver context object,
- * and sets the type of solver that is appropriate for this class.
+ * Function that takes a Eigenvalue Problem Solver context object, and
+ * sets the type of solver that is appropriate for this class.
*/
virtual void set_solver_type (EPS &eps) const;
};
/**
- * An implementation of the solver interface using the SLEPc
- * Davidson solver. Usage (incomplete/untested): All problem types.
+ * An implementation of the solver interface using the SLEPc Davidson
+ * solver. Usage (incomplete/untested): All problem types.
*
* @ingroup SLEPcWrappers
*
{
public:
/**
- * Standardized data struct to pipe additional data to the solver,
- * should it be needed.
+ * Standardized data struct to pipe additional data to the solver, should
+ * it be needed.
*/
struct AdditionalData
{};
/**
- * SLEPc solvers will want to have an MPI communicator context
- * over which computations are parallelized. By default, this
- * carries the same behaviour has the PETScWrappers, but you can
- * change that.
+ * SLEPc solvers will want to have an MPI communicator context over which
+ * computations are parallelized. By default, this carries the same
+ * behaviour has the PETScWrappers, but you can change that.
*/
SolverGeneralizedDavidson (SolverControl &cn,
const MPI_Comm &mpi_communicator = PETSC_COMM_SELF,
const AdditionalData additional_data;
/**
- * Function that takes a Eigenvalue Problem Solver context object,
- * and sets the type of solver that is appropriate for this class.
+ * Function that takes a Eigenvalue Problem Solver context object, and
+ * sets the type of solver that is appropriate for this class.
*/
virtual void set_solver_type (EPS &eps) const;
};
/**
- * An implementation of the solver interface using the SLEPc
- * Jacobi-Davidson solver. Usage: All problem types.
+ * An implementation of the solver interface using the SLEPc Jacobi-Davidson
+ * solver. Usage: All problem types.
*
* @ingroup SLEPcWrappers
*
{
public:
/**
- * Standardized data struct to pipe additional data to the solver,
- * should it be needed.
+ * Standardized data struct to pipe additional data to the solver, should
+ * it be needed.
*/
struct AdditionalData
{};
/**
- * SLEPc solvers will want to have an MPI communicator context
- * over which computations are parallelized. By default, this
- * carries the same behaviour has the PETScWrappers, but you can
- * change that.
+ * SLEPc solvers will want to have an MPI communicator context over which
+ * computations are parallelized. By default, this carries the same
+ * behaviour has the PETScWrappers, but you can change that.
*/
SolverJacobiDavidson (SolverControl &cn,
const MPI_Comm &mpi_communicator = PETSC_COMM_SELF,
const AdditionalData additional_data;
/**
- * Function that takes a Eigenvalue Problem Solver context object,
- * and sets the type of solver that is appropriate for this class.
+ * Function that takes a Eigenvalue Problem Solver context object, and
+ * sets the type of solver that is appropriate for this class.
*/
virtual void set_solver_type (EPS &eps) const;
};
/**
- * An implementation of the solver interface using the SLEPc LAPACK
- * direct solver.
+ * An implementation of the solver interface using the SLEPc LAPACK direct
+ * solver.
*
* @ingroup SLEPcWrappers
*
public:
/**
- * Standardized data struct to pipe additional data to the solver,
- * should it be needed.
+ * Standardized data struct to pipe additional data to the solver, should
+ * it be needed.
*/
struct AdditionalData
{};
/**
- * SLEPc solvers will want to have an MPI communicator context
- * over which computations are parallelized. By default, this
- * carries the same behaviour has the PETScWrappers, but you can
- * change that.
+ * SLEPc solvers will want to have an MPI communicator context over which
+ * computations are parallelized. By default, this carries the same
+ * behaviour has the PETScWrappers, but you can change that.
*/
SolverLAPACK (SolverControl &cn,
const MPI_Comm &mpi_communicator = PETSC_COMM_SELF,
const AdditionalData additional_data;
/**
- * Function that takes a Eigenvalue Problem Solver context object,
- * and sets the type of solver that is appropriate for this class.
+ * Function that takes a Eigenvalue Problem Solver context object, and
+ * sets the type of solver that is appropriate for this class.
*/
virtual void set_solver_type (EPS &eps) const;
};
// --------------------------- inline and template functions -----------
/**
- * This is declared here to make it possible to take a std::vector
- * of different PETScWrappers vector types
+ * This is declared here to make it possible to take a std::vector of
+ * different PETScWrappers vector types
*/
// todo: The logic of these functions can be simplified without breaking backward compatibility...
{
/**
- * Base class for spectral transformation classes using the SLEPc
- * solvers which are selected based on flags passed to the spectral
- * transformation.
+ * Base class for spectral transformation classes using the SLEPc solvers
+ * which are selected based on flags passed to the spectral transformation.
*
- * <code>SLEPcWrappers::TransformationXXX</code>, where
- * <code>XXX</code> is your favourite transformation type, can then
- * be implemented in application codes in the following way for
- * <code>XXX=INVERT</code> with the solver object
- * <code>eigensolver</code>:
+ * <code>SLEPcWrappers::TransformationXXX</code>, where <code>XXX</code> is
+ * your favourite transformation type, can then be implemented in
+ * application codes in the following way for <code>XXX=INVERT</code> with
+ * the solver object <code>eigensolver</code>:
* @code
* // Set a transformation, this one shifts the eigenspectrum by 3.142..
* SLEPcWrappers::TransformationShift::AdditionalData additional_data (3.142);
*
* @ingroup SLEPcWrappers
* @author Toby D. Young 2009, 2013
- **/
+ */
class TransformationBase
{
public:
virtual ~TransformationBase ();
/**
- * Record the EPS object that is associated
- * to the spectral transformation
+ * Record the EPS object that is associated to the spectral transformation
*/
void set_context (EPS &eps);
/**
- * Set a flag to indicate how the
- * transformed matrices are being stored in
+ * Set a flag to indicate how the transformed matrices are being stored in
* the spectral transformations.
*
- * The possible values are given by the
- * enumerator STMatMode in the SLEPc library
- * http://www.grycap.upv.es/slepc/documentation/current/docs/manualpages/ST/STMatMode.html
+ * The possible values are given by the enumerator STMatMode in the SLEPc
+ * library http://www.grycap.upv.es/slepc/documentation/current/docs/manua
+ * lpages/ST/STMatMode.html
*/
void set_matrix_mode(const STMatMode mode);
private:
/**
- * Objects of this type are
- * explicitly created, but are
- * destroyed when the surrounding
- * solver object goes out of scope,
- * or when we assign a new value to
- * the pointer to this object. The
- * respective Destroy functions are
- * therefore written into the
- * destructor of this object, even
- * though the object does not have
- * a constructor.
+ * Objects of this type are explicitly created, but are destroyed when the
+ * surrounding solver object goes out of scope, or when we assign a new
+ * value to the pointer to this object. The respective Destroy functions
+ * are therefore written into the destructor of this object, even though
+ * the object does not have a constructor.
*/
struct TransformationData
{
~TransformationData ();
/**
- * Objects for Eigenvalue Problem
- * Solver.
+ * Objects for Eigenvalue Problem Solver.
*/
ST st;
};
};
/**
- * An implementation of the transformation interface using the SLEPc
- * Shift.
+ * An implementation of the transformation interface using the SLEPc Shift.
*
* @ingroup SLEPcWrappers
* @author Toby D. Young 2009
public:
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
{
/**
- * Constructor. By default, set the
- * shift parameter to zero.
+ * Constructor. By default, set the shift parameter to zero.
*/
AdditionalData (const double shift_parameter = 0);
protected:
/**
- * Store a copy of the flags for this
- * particular solver.
+ * Store a copy of the flags for this particular solver.
*/
const AdditionalData additional_data;
/**
- * Function that takes a Spectral
- * Transformation context object,
- * and sets the type of spectral
- * transformationthat is
- * appropriate for this class.
+ * Function that takes a Spectral Transformation context object, and sets
+ * the type of spectral transformationthat is appropriate for this class.
*/
virtual void set_transformation_type (ST &st) const;
};
/**
- * An implementation of the transformation interface using the SLEPc
- * Shift and Invert.
+ * An implementation of the transformation interface using the SLEPc Shift
+ * and Invert.
*
* @ingroup SLEPcWrappers
* @author Toby D. Young 2009
public:
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
{
/**
- * Constructor. By default, set the
- * shift parameter to zero.
+ * Constructor. By default, set the shift parameter to zero.
*/
AdditionalData (const double shift_parameter = 0);
protected:
/**
- * Store a copy of the flags for this
- * particular solver.
+ * Store a copy of the flags for this particular solver.
*/
const AdditionalData additional_data;
/**
- * Function that takes a Spectral
- * Transformation context object,
- * and sets the type of spectral
- * transformationthat is
- * appropriate for this class.
+ * Function that takes a Spectral Transformation context object, and sets
+ * the type of spectral transformationthat is appropriate for this class.
*/
virtual void set_transformation_type (ST &st) const;
};
/**
* An implementation of the transformation interface using the SLEPc
- * Spectrum Folding. This transformation type has been removed in
- * SLEPc 3.5.0 and thus cannot be used in the newer versions.
+ * Spectrum Folding. This transformation type has been removed in SLEPc
+ * 3.5.0 and thus cannot be used in the newer versions.
*
* @ingroup SLEPcWrappers
* @author Toby D. Young 2009
public:
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
{
/**
- * Constructor. By default, set the
- * shift parameter to zero.
+ * Constructor. By default, set the shift parameter to zero.
*/
AdditionalData (const double shift_parameter = 0);
protected:
/**
- * Store a copy of the flags for this
- * particular solver.
+ * Store a copy of the flags for this particular solver.
*/
const AdditionalData additional_data;
/**
- * Function that takes a Spectral
- * Transformation context object,
- * and sets the type of spectral
- * transformationthat is
- * appropriate for this class.
+ * Function that takes a Spectral Transformation context object, and sets
+ * the type of spectral transformationthat is appropriate for this class.
*/
virtual void set_transformation_type (ST &st) const;
};
/**
- * An implementation of the transformation interface using the SLEPc
- * Cayley.
+ * An implementation of the transformation interface using the SLEPc Cayley.
*
* @ingroup SLEPcWrappers
* @author Toby D. Young 2009
public:
/**
- * Standardized data struct to pipe
- * additional data to the solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
{
/**
- * Constructor. Requires two shift
- * parameters
+ * Constructor. Requires two shift parameters
*/
AdditionalData (const double shift_parameter = 0,
const double antishift_parameter = 0);
protected:
/**
- * Store a copy of the flags for this
- * particular solver.
+ * Store a copy of the flags for this particular solver.
*/
const AdditionalData additional_data;
/**
- * Function that takes a Spectral
- * Transformation context object,
- * and sets the type of spectral
- * transformationthat is
- * appropriate for this class.
+ * Function that takes a Spectral Transformation context object, and sets
+ * the type of spectral transformationthat is appropriate for this class.
*/
virtual void set_transformation_type (ST &st) const;
};
template <typename number> class Vector;
/**
- * A base class for iterative linear solvers. This class
- * provides interfaces to a memory pool and the objects that
- * determine whether a solver has converged.
+ * A base class for iterative linear solvers. This class provides interfaces
+ * to a memory pool and the objects that determine whether a solver has
+ * converged.
*
*
* <h3>Requirements common to derived solver classes</h3>
*
- * Since iterative solvers do not rely on any special structure of
- * matrices or the format of storage but only require that matrices
- * and vectors define certain operations such as matrix-vector
- * products, or scalar products between vectors, this class as well as
- * the derived classes and their member functions implementing concrete
- * linear solvers are templated on the types of matrices and vectors.
- * However, there are some common requirements a matrix or vector type
- * must fulfill to qualify as an acceptable type for the solvers in this
- * hierarchy. These requirements are listed below.
- *
- * The classes we show below are not any concrete class. Rather, they are intended to
- * form a `signature' which a concrete class has to conform to. Note
- * that the matrix and vector classes within this library of course
- * conform to this interface; therefore, SparseMatrix and Vector are
- * good examples for these classes as they provide the necessary
- * signatures of member functions.
+ * Since iterative solvers do not rely on any special structure of matrices or
+ * the format of storage but only require that matrices and vectors define
+ * certain operations such as matrix-vector products, or scalar products
+ * between vectors, this class as well as the derived classes and their member
+ * functions implementing concrete linear solvers are templated on the types
+ * of matrices and vectors. However, there are some common requirements a
+ * matrix or vector type must fulfill to qualify as an acceptable type for the
+ * solvers in this hierarchy. These requirements are listed below.
+ *
+ * The classes we show below are not any concrete class. Rather, they are
+ * intended to form a `signature' which a concrete class has to conform to.
+ * Note that the matrix and vector classes within this library of course
+ * conform to this interface; therefore, SparseMatrix and Vector are good
+ * examples for these classes as they provide the necessary signatures of
+ * member functions.
*
* @code
* class Matrix
* @endcode
*
* In addition, for some solvers there has to be a global function
- * <tt>swap(VECTOR &a, VECTOR &b)</tt> that exchanges the values of the two vectors.
+ * <tt>swap(VECTOR &a, VECTOR &b)</tt> that exchanges the values of the two
+ * vectors.
*
- * The preconditioners used must have the same interface as matrices,
- * i.e. in particular they have to provide a member function @p vmult
- * which denotes the application of the preconditioner.
+ * The preconditioners used must have the same interface as matrices, i.e. in
+ * particular they have to provide a member function @p vmult which denotes
+ * the application of the preconditioner.
*
*
* <h3>AdditionalData</h3>
*
* Several solvers need additional data, like the damping parameter @p omega
- * of the @p SolverRichardson class or the maximum number of temporary
- * vectors of @p SolverGMRES. To have a standardized way of constructing solvers,
- * each solver class has a <tt>struct AdditionalData</tt> as a member, and constructors
- * of all solver classes take such an argument. Some solvers need no additional data,
- * or may not at the current time. For these solvers the struct @p AdditionalData is
- * empty and calling the constructor may be done without giving the additional
- * structure as an argument as a default @p AdditionalData is set by default.
+ * of the @p SolverRichardson class or the maximum number of temporary vectors
+ * of @p SolverGMRES. To have a standardized way of constructing solvers,
+ * each solver class has a <tt>struct AdditionalData</tt> as a member, and
+ * constructors of all solver classes take such an argument. Some solvers need
+ * no additional data, or may not at the current time. For these solvers the
+ * struct @p AdditionalData is empty and calling the constructor may be done
+ * without giving the additional structure as an argument as a default @p
+ * AdditionalData is set by default.
*
* With this, creating a solver looks like
* @code
* SolverCG solver_cg (solver_control, vector_memory);
* @endcode
*
- * Using a unified constructor parameter list for all solvers supports
- * the @p SolverSelector class; the unified interface
- * enables us to use this class unchanged even if the number of types of
- * parameters to a certain solver changes and it is still possible in a simple
- * way to give these additional data to the @p SolverSelector object for each
- * solver which it may use.
+ * Using a unified constructor parameter list for all solvers supports the @p
+ * SolverSelector class; the unified interface enables us to use this class
+ * unchanged even if the number of types of parameters to a certain solver
+ * changes and it is still possible in a simple way to give these additional
+ * data to the @p SolverSelector object for each solver which it may use.
*
*
* <h3>Observing the progress of linear solver iterations</h3>
*
- * The Solver class, being the base class for all of the iterative solvers such
- * as SolverCG, SolverGMRES, etc, provides the facilities by which actual solver
- * implementations determine whether the iteration is converged, not yet
- * converged, or has failed. Typically, this is done using an object of type
- * SolverControl that is passed to the solver classes's constructors and from
- * them down to the constructor of this base class. Every one of the tutorial
- * programs that solves a linear problem (starting with step-3) uses this
- * method and it is described in detail there. However, the underlying mechanism
- * is more general and allows for many other uses to observe how the linear
- * solver iterations progress.
+ * The Solver class, being the base class for all of the iterative solvers
+ * such as SolverCG, SolverGMRES, etc, provides the facilities by which actual
+ * solver implementations determine whether the iteration is converged, not
+ * yet converged, or has failed. Typically, this is done using an object of
+ * type SolverControl that is passed to the solver classes's constructors and
+ * from them down to the constructor of this base class. Every one of the
+ * tutorial programs that solves a linear problem (starting with step-3) uses
+ * this method and it is described in detail there. However, the underlying
+ * mechanism is more general and allows for many other uses to observe how the
+ * linear solver iterations progress.
*
* The basic approach is that the iterative solvers invoke a <i>signal</i> at
- * the end of each iteration to determine whether the solution is converged.
- * A signal is a class that has, conceptually, a list of pointers to functions
+ * the end of each iteration to determine whether the solution is converged. A
+ * signal is a class that has, conceptually, a list of pointers to functions
* and every time the signal is invoked, each of these functions are called.
* In the language of signals, the functions called are called <i>slots</i>
- * and one can attach any number of slots to a signal.
- * (The implementation of signals and slots we use here is the one from the
- * BOOST.signals2 library.) A number of details may clarify what is happening
- * underneath:
- * - In reality, the signal object does not store pointers to functions, but
- * function objects as slots. Each slot must conform to a particular
- * signature: here, it is an object that can be called with three arguments
- * (the number of the current linear iteration, the current residual, and
- * the current iterate; more specifics are discussed in the documentation of
- * the connect() function). A pointer to a function with this argument list
- * satisfies the requirements, but you can also pass a member function
- * whose <code>this</code> argument has been bound using the
- * <code>std_cxx11::bind</code> mechanism (see the example below).
- * - Each of the slots will return a value that indicates whether
- * the iteration should continue, should stop because it has succeeded,
- * or stop because it has failed. The return type of slots is therefore
- * of type SolverControl::State. The returned values from all of the
- * slots will then have to be combined before they are returned to the
- * iterative solver that invoked the signal. The way this works is that
- * if at least one slot returned SolverControl::failure, then the
- * combined value is SolverControl::failure; otherwise, if at least
- * one slot returned SolverControl::iterate, then this is going to be
- * the return value of the signal; finally, only if all slots return
- * SolverControl::success will the signal's return value be
- * SolverControl::success.
- * - It may of course be that a particular
- * slot has been connected to the signal only to observe how the
- * solution or a specific part of it converges, but has no particular
- * opinion on whether the iteration should continue or not. In such
- * cases, the slot should just return SolverControl::success, which
- * is the weakest of all return values according to the rules laid
- * out above.
- *
- * Given all this, it should now be obvious how the SolverControl
- * object fits into this scheme: when a SolverControl object is passed
- * to the constructor of the current class, we simply connect the
- * SolverControl::check() function of that object as a slot to the
- * signal we maintain here. In other words, since a Solver object
- * is always constructed using a SolverControl object, there is
- * always at least one slot associated with the signal, namely the
+ * and one can attach any number of slots to a signal. (The implementation of
+ * signals and slots we use here is the one from the BOOST.signals2 library.)
+ * A number of details may clarify what is happening underneath: - In reality,
+ * the signal object does not store pointers to functions, but function
+ * objects as slots. Each slot must conform to a particular signature: here,
+ * it is an object that can be called with three arguments (the number of the
+ * current linear iteration, the current residual, and the current iterate;
+ * more specifics are discussed in the documentation of the connect()
+ * function). A pointer to a function with this argument list satisfies the
+ * requirements, but you can also pass a member function whose
+ * <code>this</code> argument has been bound using the
+ * <code>std_cxx11::bind</code> mechanism (see the example below). - Each of
+ * the slots will return a value that indicates whether the iteration should
+ * continue, should stop because it has succeeded, or stop because it has
+ * failed. The return type of slots is therefore of type SolverControl::State.
+ * The returned values from all of the slots will then have to be combined
+ * before they are returned to the iterative solver that invoked the signal.
+ * The way this works is that if at least one slot returned
+ * SolverControl::failure, then the combined value is SolverControl::failure;
+ * otherwise, if at least one slot returned SolverControl::iterate, then this
+ * is going to be the return value of the signal; finally, only if all slots
+ * return SolverControl::success will the signal's return value be
+ * SolverControl::success. - It may of course be that a particular slot has
+ * been connected to the signal only to observe how the solution or a specific
+ * part of it converges, but has no particular opinion on whether the
+ * iteration should continue or not. In such cases, the slot should just
+ * return SolverControl::success, which is the weakest of all return values
+ * according to the rules laid out above.
+ *
+ * Given all this, it should now be obvious how the SolverControl object fits
+ * into this scheme: when a SolverControl object is passed to the constructor
+ * of the current class, we simply connect the SolverControl::check() function
+ * of that object as a slot to the signal we maintain here. In other words,
+ * since a Solver object is always constructed using a SolverControl object,
+ * there is always at least one slot associated with the signal, namely the
* one that determines convergence.
*
- * On the other hand, using the connect() member function, it is
- * possible to connect any number of other slots to the signal to
- * observe whatever it is you want to observe. The connect() function
- * also returns an object that describes the connection from the
- * signal to the slot, and the corresponding BOOST functions then allow
- * you to disconnect the slot if you want.
+ * On the other hand, using the connect() member function, it is possible to
+ * connect any number of other slots to the signal to observe whatever it is
+ * you want to observe. The connect() function also returns an object that
+ * describes the connection from the signal to the slot, and the corresponding
+ * BOOST functions then allow you to disconnect the slot if you want.
*
- * An example may illuminate these issues. In the step-3 tutorial
- * program, let us add a member function as follows to the main class:
+ * An example may illuminate these issues. In the step-3 tutorial program, let
+ * us add a member function as follows to the main class:
* @code
* SolverControl::State
* Step3::write_intermediate_solution (const unsigned int iteration,
* return SolverControl::success;
* }
* @endcode
- * The function satisfies the signature necessary to be a slot for the
- * signal discussed above, with the exception that it is a member
- * function and consequently requires a <code>this</code> pointer.
- * What the function does is to take the vector given as last
- * argument and write it into a file in VTU format with a file
- * name derived from the number of the iteration.
- *
- * This function can then be hooked into the CG solver by modifying
- * the <code>Step3::solve()</code> function as follows:
+ * The function satisfies the signature necessary to be a slot for the signal
+ * discussed above, with the exception that it is a member function and
+ * consequently requires a <code>this</code> pointer. What the function does
+ * is to take the vector given as last argument and write it into a file in
+ * VTU format with a file name derived from the number of the iteration.
+ *
+ * This function can then be hooked into the CG solver by modifying the
+ * <code>Step3::solve()</code> function as follows:
* @code
* void Step3::solve ()
* {
* PreconditionIdentity());
* }
* @endcode
- * The use of <code>std_cxx11::bind</code> here ensures that we convert
- * the member function with its three arguments plus the <code>this</code>
- * pointer, to a function that only takes three arguments, by fixing
- * the implicit <code>this</code> argument of the function to the
+ * The use of <code>std_cxx11::bind</code> here ensures that we convert the
+ * member function with its three arguments plus the <code>this</code>
+ * pointer, to a function that only takes three arguments, by fixing the
+ * implicit <code>this</code> argument of the function to the
* <code>this</code> pointer in the current function.
*
- * It is well understood that the CG method is a smoothing iteration (in
- * the same way as the more commonly used Jacobi or SSOR iterations are
+ * It is well understood that the CG method is a smoothing iteration (in the
+ * same way as the more commonly used Jacobi or SSOR iterations are
* smoothers). The code above therefore allows to observe how the solution
- * becomes smoother and smoother in every iteration. This is best
- * observed by initializing the solution vector with randomly distributed
- * numbers in $[-1,1]$, using code such as
+ * becomes smoother and smoother in every iteration. This is best observed by
+ * initializing the solution vector with randomly distributed numbers in
+ * $[-1,1]$, using code such as
* @code
* for (unsigned int i=0; i<solution.size(); ++i)
* solution(i) = 2.*rand()/RAND_MAX-1;
* @endcode
- * Using this, the slot will then generate files that when visualized
- * look like this over the course of iterations zero to five:
- * <table>
- * <tr>
- * <td>
- * @image html "cg-monitor-smoothing-0.png"
- * </td>
- * <td>
- * @image html "cg-monitor-smoothing-1.png"
- * </td>
- * <td>
- * @image html "cg-monitor-smoothing-2.png"
- * </td>
- * </tr>
- * <tr>
- * <td>
- * @image html "cg-monitor-smoothing-3.png"
- * </td>
- * <td>
- * @image html "cg-monitor-smoothing-4.png"
- * </td>
- * <td>
- * @image html "cg-monitor-smoothing-5.png"
- * </td>
- * </tr>
- * </table>
+ * Using this, the slot will then generate files that when visualized look
+ * like this over the course of iterations zero to five: <table> <tr> <td>
+ * @image html "cg-monitor-smoothing-0.png" </td> <td> @image html "cg-
+ * monitor-smoothing-1.png" </td> <td> @image html "cg-monitor-
+ * smoothing-2.png" </td> </tr> <tr> <td> @image html "cg-monitor-
+ * smoothing-3.png" </td> <td> @image html "cg-monitor-smoothing-4.png" </td>
+ * <td> @image html "cg-monitor-smoothing-5.png" </td> </tr> </table>
*
* @ingroup Solvers
- * @author Wolfgang Bangerth, Guido Kanschat, Ralf Hartmann, 1997-2001, 2005, 2014
+ * @author Wolfgang Bangerth, Guido Kanschat, Ralf Hartmann, 1997-2001, 2005,
+ * 2014
*/
template <class VECTOR = Vector<double> >
class Solver : public Subscriptor
{
public:
/**
- * Constructor. Takes a control
- * object which evaluates the
- * conditions for convergence,
- * and an object that allows solvers to allocate
- * memory for temporary objects.
+ * Constructor. Takes a control object which evaluates the conditions for
+ * convergence, and an object that allows solvers to allocate memory for
+ * temporary objects.
*
- * Of both objects, a reference is
- * stored, so it is the user's
- * responsibility to guarantee that the
- * lifetime of the two arguments is at
- * least as long as that of the solver
- * object.
+ * Of both objects, a reference is stored, so it is the user's
+ * responsibility to guarantee that the lifetime of the two arguments is at
+ * least as long as that of the solver object.
*/
Solver (SolverControl &solver_control,
VectorMemory<VECTOR> &vector_memory);
/**
- * Constructor. Takes a control
- * object which evaluates the
- * conditions for convergence. In
- * contrast to the other
- * constructor, this constructor
- * designates an internal object of
- * type GrowingVectorMemory to
- * allocate memory.
+ * Constructor. Takes a control object which evaluates the conditions for
+ * convergence. In contrast to the other constructor, this constructor
+ * designates an internal object of type GrowingVectorMemory to allocate
+ * memory.
*
- * A reference to the control
- * object is stored, so it is the
- * user's responsibility to
- * guarantee that the lifetime of
- * the argument is at least
- * as long as that of the solver
- * object.
+ * A reference to the control object is stored, so it is the user's
+ * responsibility to guarantee that the lifetime of the argument is at least
+ * as long as that of the solver object.
*/
Solver (SolverControl &solver_control);
/**
* Connect a function object that will be called periodically within
- * iterative solvers. This function is used to attach monitors to
- * iterative solvers, either to determine when convergence has happened,
- * or simply to observe the progress of an iteration. See the documentation
- * of this class for more information.
+ * iterative solvers. This function is used to attach monitors to iterative
+ * solvers, either to determine when convergence has happened, or simply to
+ * observe the progress of an iteration. See the documentation of this class
+ * for more information.
*
- * @param slot A function object specified here will, with
- * each call, receive the number of the current iteration,
- * the value that is used to check for convergence (typically the residual
- * of the current iterate with respect to the linear system to be solved)
- * and the currently best available guess for the current iterate.
- * Note that some solvers do not update the approximate solution in every
- * iteration but only after convergence or failure has been determined
- * (GMRES is an example); in such cases, the vector passed as the last
- * argument to the signal is simply the best approximate at the time
- * the signal is called, but not the vector that will be returned if
- * the signal's return value indicates that the iteration should be
- * terminated. The function object must return a SolverControl::State
- * value that indicates whether the iteration should continue, has
- * failed, or has succeeded. The results of all connected functions
- * will then be combined to determine what should happen with the
- * iteration.
+ * @param slot A function object specified here will, with each call,
+ * receive the number of the current iteration, the value that is used to
+ * check for convergence (typically the residual of the current iterate with
+ * respect to the linear system to be solved) and the currently best
+ * available guess for the current iterate. Note that some solvers do not
+ * update the approximate solution in every iteration but only after
+ * convergence or failure has been determined (GMRES is an example); in such
+ * cases, the vector passed as the last argument to the signal is simply the
+ * best approximate at the time the signal is called, but not the vector
+ * that will be returned if the signal's return value indicates that the
+ * iteration should be terminated. The function object must return a
+ * SolverControl::State value that indicates whether the iteration should
+ * continue, has failed, or has succeeded. The results of all connected
+ * functions will then be combined to determine what should happen with the
+ * iteration.
*
* @return A connection object that represents the connection from the
- * signal to the function object. It can be used to disconnect the
- * function object again from the signal. See the documentation of
- * the BOOST Signals2 library for more information on connection
- * management.
+ * signal to the function object. It can be used to disconnect the function
+ * object again from the signal. See the documentation of the BOOST Signals2
+ * library for more information on connection management.
*/
boost::signals2::connection
connect (const std_cxx11::function<SolverControl::State (const unsigned int iteration,
protected:
/**
- * A static vector memory object
- * to be used whenever no such
- * object has been given to the
- * constructor.
+ * A static vector memory object to be used whenever no such object has been
+ * given to the constructor.
*/
mutable GrowingVectorMemory<VECTOR> static_vector_memory;
private:
/**
- * A class whose operator() combines two states indicating whether
- * we should continue iterating or stop, and returns a state that
- * dominates. The rules are:
- * - If one of the two states indicates failure, return failure.
- * - Otherwise, if one of the two states indicates to continue
- * iterating, then continue iterating.
- * - Otherwise, return success.
+ * A class whose operator() combines two states indicating whether we should
+ * continue iterating or stop, and returns a state that dominates. The rules
+ * are: - If one of the two states indicates failure, return failure. -
+ * Otherwise, if one of the two states indicates to continue iterating, then
+ * continue iterating. - Otherwise, return success.
*/
struct StateCombiner
{
protected:
/**
- * A signal that iterative solvers can execute at the end of every
- * iteration (or in an otherwise periodic fashion) to find out whether
- * we should continue iterating or not. The signal may call one or
- * more slots that each will make this determination by themselves,
- * and the result over all slots (function calls) will be determined
- * by the StateCombiner object.
+ * A signal that iterative solvers can execute at the end of every iteration
+ * (or in an otherwise periodic fashion) to find out whether we should
+ * continue iterating or not. The signal may call one or more slots that
+ * each will make this determination by themselves, and the result over all
+ * slots (function calls) will be determined by the StateCombiner object.
*
* The arguments passed to the signal are (i) the number of the current
- * iteration; (ii) the value that is used to determine convergence (oftentimes
- * the residual, but in other cases other quantities may be used as long
- * as they converge to zero as the iterate approaches the solution of
- * the linear system); and (iii) a vector that corresponds to the current
- * best guess for the solution at the point where the signal is called.
- * Note that some solvers do not update the approximate solution in every
+ * iteration; (ii) the value that is used to determine convergence
+ * (oftentimes the residual, but in other cases other quantities may be used
+ * as long as they converge to zero as the iterate approaches the solution
+ * of the linear system); and (iii) a vector that corresponds to the current
+ * best guess for the solution at the point where the signal is called. Note
+ * that some solvers do not update the approximate solution in every
* iteration but only after convergence or failure has been determined
* (GMRES is an example); in such cases, the vector passed as the last
- * argument to the signal is simply the best approximate at the time
- * the signal is called, but not the vector that will be returned if
- * the signal's return value indicates that the iteration should be
- * terminated.
+ * argument to the signal is simply the best approximate at the time the
+ * signal is called, but not the vector that will be returned if the
+ * signal's return value indicates that the iteration should be terminated.
*/
boost::signals2::signal<SolverControl::State (const unsigned int iteration,
const double check_value,
/**
* Bicgstab algorithm by van der Vorst.
*
- * For the requirements on matrices and vectors in order to work with
- * this class, see the documentation of the Solver base class.
+ * For the requirements on matrices and vectors in order to work with this
+ * class, see the documentation of the Solver base class.
*
- * Like all other solver classes, this class has a local structure called
- * @p AdditionalData which is used to pass additional parameters to the
- * solver, like damping parameters or the number of temporary vectors. We
- * use this additional structure instead of passing these values directly
- * to the constructor because this makes the use of the @p SolverSelector and
- * other classes much easier and guarantees that these will continue to
- * work even if number or type of the additional parameters for a certain
- * solver changes.
+ * Like all other solver classes, this class has a local structure called @p
+ * AdditionalData which is used to pass additional parameters to the solver,
+ * like damping parameters or the number of temporary vectors. We use this
+ * additional structure instead of passing these values directly to the
+ * constructor because this makes the use of the @p SolverSelector and other
+ * classes much easier and guarantees that these will continue to work even if
+ * number or type of the additional parameters for a certain solver changes.
*
- * The Bicgstab-method has two additional parameters: the first is a
- * boolean, deciding whether to compute the actual residual in each step (@p
- * true) or to use the length of the computed orthogonal residual (@p
- * false). Note that computing the residual causes a third
- * matrix-vector-multiplication, though no additional preconditioning, in
- * each step. The reason for doing this is, that the size of the
- * orthogonalized residual computed during the iteration may be larger by
- * orders of magnitude than the true residual. This is due to numerical
- * instabilities related to badly conditioned matrices. Since this
+ * The Bicgstab-method has two additional parameters: the first is a boolean,
+ * deciding whether to compute the actual residual in each step (@p true) or
+ * to use the length of the computed orthogonal residual (@p false). Note that
+ * computing the residual causes a third matrix-vector-multiplication, though
+ * no additional preconditioning, in each step. The reason for doing this is,
+ * that the size of the orthogonalized residual computed during the iteration
+ * may be larger by orders of magnitude than the true residual. This is due to
+ * numerical instabilities related to badly conditioned matrices. Since this
* instability results in a bad stopping criterion, the default for this
* parameter is @p true. Whenever the user knows that the estimated residual
- * works reasonably as well, the flag should be set to @p false in order
- * to increase the performance of the solver.
+ * works reasonably as well, the flag should be set to @p false in order to
+ * increase the performance of the solver.
*
- * The second parameter is the size of a breakdown criterion. It is
- * difficult to find a general good criterion, so if things do not
- * work for you, try to change this value.
+ * The second parameter is the size of a breakdown criterion. It is difficult
+ * to find a general good criterion, so if things do not work for you, try to
+ * change this value.
*
*
* <h3>Observing the progress of linear solver iterations</h3>
*
- * The solve() function of this class uses the mechanism described
- * in the Solver base class to determine convergence. This mechanism
- * can also be used to observe the progress of the iteration.
+ * The solve() function of this class uses the mechanism described in the
+ * Solver base class to determine convergence. This mechanism can also be used
+ * to observe the progress of the iteration.
*
*/
template <class VECTOR = Vector<double> >
SolverControl::State start(const MATRIX &A);
/**
- * A structure returned by the iterate() function representing
- * what it found is happening during the iteration.
+ * A structure returned by the iterate() function representing what it found
+ * is happening during the iteration.
*/
struct IterationResult
{
};
/**
- * The iteration loop itself. The function returns a structure
- * indicating what happened in this function.
+ * The iteration loop itself. The function returns a structure indicating
+ * what happened in this function.
*/
template<class MATRIX, class PRECONDITIONER>
IterationResult
* solution vector must be passed as template argument, and defaults to
* dealii::Vector<double>.
*
- * Like all other solver classes, this class has a local structure
- * called @p AdditionalData which is used to pass additional
- * parameters to the solver. For this class, there is (among other things)
- * a switch allowing for additional output for the computation of
- * eigenvalues of the matrix.
+ * Like all other solver classes, this class has a local structure called @p
+ * AdditionalData which is used to pass additional parameters to the solver.
+ * For this class, there is (among other things) a switch allowing for
+ * additional output for the computation of eigenvalues of the matrix.
*
- * @note This version of CG is taken from D. Braess's book "Finite
- * Elements". It requires a symmetric preconditioner (i.e., for example, SOR
- * is not a possible choice).
+ * @note This version of CG is taken from D. Braess's book "Finite Elements".
+ * It requires a symmetric preconditioner (i.e., for example, SOR is not a
+ * possible choice).
*
*
* <h3>Eigenvalue computation</h3>
*
* The cg-method performs an orthogonal projection of the original
- * preconditioned linear system to another system of smaller
- * dimension. Furthermore, the projected matrix @p T is
- * tri-diagonal. Since the projection is orthogonal, the eigenvalues
- * of @p T approximate those of the original preconditioned matrix
- * @p PA. In fact, after @p n steps, where @p n is the dimension of
- * the original system, the eigenvalues of both matrices are
- * equal. But, even for small numbers of iteration steps, the
- * condition number of @p T is a good estimate for the one of @p PA.
+ * preconditioned linear system to another system of smaller dimension.
+ * Furthermore, the projected matrix @p T is tri-diagonal. Since the
+ * projection is orthogonal, the eigenvalues of @p T approximate those of the
+ * original preconditioned matrix @p PA. In fact, after @p n steps, where @p n
+ * is the dimension of the original system, the eigenvalues of both matrices
+ * are equal. But, even for small numbers of iteration steps, the condition
+ * number of @p T is a good estimate for the one of @p PA.
*
- * With the coefficients @p alpha and @p beta written to the log
- * file if <tt>AdditionalData::log_coefficients = true</tt>, the matrix
- * @p T_m after @p m steps is the tri-diagonal matrix with diagonal
- * elements <tt>1/alpha_0</tt>, <tt>1/alpha_1 + beta_0/alpha_0</tt>, ...,
+ * With the coefficients @p alpha and @p beta written to the log file if
+ * <tt>AdditionalData::log_coefficients = true</tt>, the matrix @p T_m after
+ * @p m steps is the tri-diagonal matrix with diagonal elements
+ * <tt>1/alpha_0</tt>, <tt>1/alpha_1 + beta_0/alpha_0</tt>, ...,
* <tt>1/alpha_{m-1</tt>+beta_{m-2}/alpha_{m-2}} and off-diagonal elements
* <tt>sqrt(beta_0)/alpha_0</tt>, ..., <tt>sqrt(beta_{m-2</tt>)/alpha_{m-2}}.
* The eigenvalues of this matrix can be computed by postprocessing.
*
- * @see Y. Saad: "Iterative methods for Sparse Linear Systems", section
- * 6.7.3 for details.
+ * @see Y. Saad: "Iterative methods for Sparse Linear Systems", section 6.7.3
+ * for details.
*
*
* <h3>Observing the progress of linear solver iterations</h3>
*
- * The solve() function of this class uses the mechanism described
- * in the Solver base class to determine convergence. This mechanism
- * can also be used to observe the progress of the iteration.
+ * The solve() function of this class uses the mechanism described in the
+ * Solver base class to determine convergence. This mechanism can also be used
+ * to observe the progress of the iteration.
*
*
* @author W. Bangerth, G. Kanschat, R. Becker and F.-T. Suttmeier
typedef types::global_dof_index size_type;
/**
- * Standardized data struct to pipe
- * additional data to the solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
{
/**
- * Write coefficients alpha and beta
- * to the log file for later use in
+ * Write coefficients alpha and beta to the log file for later use in
* eigenvalue estimates.
*/
bool log_coefficients;
/**
- * Compute the condition
- * number of the projected
- * matrix.
+ * Compute the condition number of the projected matrix.
*
* @note Requires LAPACK support.
*/
bool compute_condition_number;
/**
- * Compute the condition
- * number of the projected
- * matrix in each step.
+ * Compute the condition number of the projected matrix in each step.
*
* @note Requires LAPACK support.
*/
bool compute_all_condition_numbers;
/**
- * Compute all eigenvalues of
- * the projected matrix.
+ * Compute all eigenvalues of the projected matrix.
*
* @note Requires LAPACK support.
*/
bool compute_eigenvalues;
/**
- * Constructor. Initialize data
- * fields. Confer the description of
- * those.
+ * Constructor. Initialize data fields. Confer the description of those.
*/
AdditionalData (const bool log_coefficients = false,
const bool compute_condition_number = false,
const AdditionalData &data = AdditionalData());
/**
- * Constructor. Use an object of
- * type GrowingVectorMemory as
- * a default to allocate memory.
+ * Constructor. Use an object of type GrowingVectorMemory as a default to
+ * allocate memory.
*/
SolverCG (SolverControl &cn,
const AdditionalData &data=AdditionalData());
virtual ~SolverCG ();
/**
- * Solve the linear system $Ax=b$
- * for x.
+ * Solve the linear system $Ax=b$ for x.
*/
template <class MATRIX, class PRECONDITIONER>
void
protected:
/**
- * Implementation of the computation of
- * the norm of the residual. This can be
- * replaced by a more problem oriented
- * functional in a derived class.
+ * Implementation of the computation of the norm of the residual. This can
+ * be replaced by a more problem oriented functional in a derived class.
*/
virtual double criterion();
/**
- * Interface for derived class.
- * This function gets the current
- * iteration vector, the residual
- * and the update vector in each
- * step. It can be used for a
- * graphical output of the
- * convergence history.
+ * Interface for derived class. This function gets the current iteration
+ * vector, the residual and the update vector in each step. It can be used
+ * for a graphical output of the convergence history.
*/
virtual void print_vectors(const unsigned int step,
const VECTOR &x,
const VECTOR &d) const;
/**
- * Temporary vectors, allocated through
- * the @p VectorMemory object at the start
- * of the actual solution process and
- * deallocated at the end.
+ * Temporary vectors, allocated through the @p VectorMemory object at the
+ * start of the actual solution process and deallocated at the end.
*/
VECTOR *Vr;
VECTOR *Vp;
VECTOR *Vz;
/**
- * Within the iteration loop, the
- * square of the residual vector is
- * stored in this variable. The
- * function @p criterion uses this
- * variable to compute the convergence
- * value, which in this class is the
- * norm of the residual vector and thus
- * the square root of the @p res2 value.
+ * Within the iteration loop, the square of the residual vector is stored in
+ * this variable. The function @p criterion uses this variable to compute
+ * the convergence value, which in this class is the norm of the residual
+ * vector and thus the square root of the @p res2 value.
*/
double res2;
/**
* Control class to determine convergence of iterative solvers.
*
- * Used by iterative methods to determine whether the iteration should
- * be continued. To this end, the virtual function <tt>check()</tt> is
- * called in each iteration with the current iteration step and the
- * value indicating convergence (usually the residual).
+ * Used by iterative methods to determine whether the iteration should be
+ * continued. To this end, the virtual function <tt>check()</tt> is called in
+ * each iteration with the current iteration step and the value indicating
+ * convergence (usually the residual).
*
* After the iteration has terminated, the functions last_value() and
- * last_step() can be used to obtain information about the final state
- * of the iteration.
+ * last_step() can be used to obtain information about the final state of the
+ * iteration.
*
- * check() can be replaced in derived classes to allow for more
- * sophisticated tests.
+ * check() can be replaced in derived classes to allow for more sophisticated
+ * tests.
*
*
- * <h3>State</h3>
- * The return states of the check function are of type #State,
- * which is an enum local to this class. It indicates the state the
- * solver is in.
+ * <h3>State</h3> The return states of the check function are of type #State,
+ * which is an enum local to this class. It indicates the state the solver is
+ * in.
*
* The possible values of State are
* <ul>
* <li> <tt>iterate = 0</tt>: continue the iteration.
* <li> @p success: the goal is reached, the iterative method can terminate
- * successfully.
- * <li> @p failure: the iterative method should stop because convergence
- * could not be achieved or at least was not achieved within the given
- * maximal number of iterations.
+ * successfully.
+ * <li> @p failure: the iterative method should stop because convergence could
+ * not be achieved or at least was not achieved within the given maximal
+ * number of iterations.
* </ul>
*
* @author Guido Kanschat
/**
- * Class to be thrown upon failing convergence of an iterative solver,
- * when either the number of iterations exceeds the limit or the residual
- * fails to reach the desired limit, e.g. in the case of a break-down.
+ * Class to be thrown upon failing convergence of an iterative solver, when
+ * either the number of iterations exceeds the limit or the residual fails
+ * to reach the desired limit, e.g. in the case of a break-down.
*
* The residual in the last iteration, as well as the iteration number of
* the last step are stored in this object and can be recovered upon
/**
* Constructor. The parameters @p n and @p tol are the maximum number of
- * iteration steps before failure and the tolerance to determine success
- * of the iteration.
+ * iteration steps before failure and the tolerance to determine success of
+ * the iteration.
*
* @p log_history specifies whether the history (i.e. the value to be
* checked and the number of the iteration step) shall be printed to @p
* deallog stream. Default is: do not print. Similarly, @p log_result
- * specifies the whether the final result is logged to @p deallog.
- * Default is yes.
+ * specifies the whether the final result is logged to @p deallog. Default
+ * is yes.
*/
SolverControl (const unsigned int n = 100,
const double tol = 1.e-10,
void parse_parameters (ParameterHandler ¶m);
/**
- * Decide about success or failure of an iteration. This function gets
- * the current iteration step to determine, whether the allowed number of
- * steps has been exceeded and returns @p failure in this case. If @p
- * check_value is below the prescribed tolerance, it returns @p success.
- * In all other cases @p iterate is returned to suggest continuation of
- * the iterative procedure.
+ * Decide about success or failure of an iteration. This function gets the
+ * current iteration step to determine, whether the allowed number of steps
+ * has been exceeded and returns @p failure in this case. If @p check_value
+ * is below the prescribed tolerance, it returns @p success. In all other
+ * cases @p iterate is returned to suggest continuation of the iterative
+ * procedure.
*
* The iteration is also aborted if the residual becomes a denormalized
- * value (@p NaN). Note, however, that this check is only performed if
- * the @p isnan function is provided by the operating system, which is
- * not always true. The @p configure scripts checks for this and sets the
- * flag @p HAVE_ISNAN in the file <tt>Make.global_options</tt> if this
- * function was found.
+ * value (@p NaN). Note, however, that this check is only performed if the
+ * @p isnan function is provided by the operating system, which is not
+ * always true. The @p configure scripts checks for this and sets the flag
+ * @p HAVE_ISNAN in the file <tt>Make.global_options</tt> if this function
+ * was found.
*
- * <tt>check()</tt> additionally preserves @p step and @p check_value.
- * These values are accessible by <tt>last_value()</tt> and
- * <tt>last_step()</tt>.
+ * <tt>check()</tt> additionally preserves @p step and @p check_value. These
+ * values are accessible by <tt>last_value()</tt> and <tt>last_step()</tt>.
*
- * Derived classes may overload this function, e.g. to log the
- * convergence indicators (@p check_value) or to do other computations.
+ * Derived classes may overload this function, e.g. to log the convergence
+ * indicators (@p check_value) or to do other computations.
*/
virtual State check (const unsigned int step,
const double check_value);
double set_tolerance (const double);
/**
- * Enables writing residuals of each step into a vector for later
- * analysis.
+ * Enables writing residuals of each step into a vector for later analysis.
*/
void enable_history_data();
bool log_result () const;
/**
- * This exception is thrown if a function operating on the vector of
- * history data of a SolverControl object id called, but storage of
- * history data was not enabled by enable_history_data().
+ * This exception is thrown if a function operating on the vector of history
+ * data of a SolverControl object id called, but storage of history data was
+ * not enabled by enable_history_data().
*/
DeclException0(ExcHistoryDataRequired);
bool m_log_result;
/**
- * Control over the storage of history data. Set by
- * enable_history_data().
+ * Control over the storage of history data. Set by enable_history_data().
*/
bool history_data_enabled;
/**
- * Vector storing the result after each iteration step for later
- * statistical analysis.
+ * Vector storing the result after each iteration step for later statistical
+ * analysis.
*
* Use of this vector is enabled by enable_history_data().
*/
/**
- * Specialization of @p SolverControl which returns @p success if either
- * the specified tolerance is achieved or if the initial residual (or
- * whatever criterion was chosen by the solver class) is reduced by a
- * given factor. This is useful in cases where you don't want to solve
- * exactly, but rather want to gain two digits or if the maximal
- * number of iterations is achieved. For example: The maximal number
- * of iterations is 20, the reduction factor is 1% und the tolerance
- * is 0.1%. The initial residual is 2.5. The process will break if 20
- * iteration are comleted or the new residual is less then 2.5*1% or
- * if it is less then 0.1%.
+ * Specialization of @p SolverControl which returns @p success if either the
+ * specified tolerance is achieved or if the initial residual (or whatever
+ * criterion was chosen by the solver class) is reduced by a given factor.
+ * This is useful in cases where you don't want to solve exactly, but rather
+ * want to gain two digits or if the maximal number of iterations is achieved.
+ * For example: The maximal number of iterations is 20, the reduction factor
+ * is 1% und the tolerance is 0.1%. The initial residual is 2.5. The process
+ * will break if 20 iteration are comleted or the new residual is less then
+ * 2.5*1% or if it is less then 0.1%.
*
* @author Guido Kanschat
*/
{
public:
/**
- * Constructor. Provide the reduction factor in addition to arguments
- * that have the same meaning as those of the constructor of the
- * SolverControl constructor.
+ * Constructor. Provide the reduction factor in addition to arguments that
+ * have the same meaning as those of the constructor of the SolverControl
+ * constructor.
*/
ReductionControl (const unsigned int maxiter = 100,
const double tolerance = 1.e-10,
void parse_parameters (ParameterHandler ¶m);
/**
- * Decide about success or failure of an iteration. This function calls
- * the one in the base class, but sets the tolerance to <tt>reduction *
- * initial value</tt> upon the first iteration.
+ * Decide about success or failure of an iteration. This function calls the
+ * one in the base class, but sets the tolerance to <tt>reduction * initial
+ * value</tt> upon the first iteration.
*/
virtual State check (const unsigned int step,
const double check_value);
double reduce;
/**
- * Reduced tolerance. Stop iterations if either this value is achieved or
- * if the base class indicates success.
+ * Reduced tolerance. Stop iterations if either this value is achieved or if
+ * the base class indicates success.
*/
double reduced_tol;
};
/**
* Specialization of @p SolverControl which returns @p success if a given
- * number of iteration was performed, irrespective of the actual
- * residual. This is useful in cases where you don't want to solve exactly,
- * but rather want to perform a fixed number of iterations, e.g. in an inner
- * solver. The arguments given to this class are exactly the same as for the
- * SolverControl class and the solver terminates similarly when one of the
- * given tolerance or the maximum iteration count were reached. The only
- * difference to SolverControl is that the solver returns success in the
- * latter case.
+ * number of iteration was performed, irrespective of the actual residual.
+ * This is useful in cases where you don't want to solve exactly, but rather
+ * want to perform a fixed number of iterations, e.g. in an inner solver. The
+ * arguments given to this class are exactly the same as for the SolverControl
+ * class and the solver terminates similarly when one of the given tolerance
+ * or the maximum iteration count were reached. The only difference to
+ * SolverControl is that the solver returns success in the latter case.
*
* @author Martin Kronbichler
*/
}
/**
- * Implementation of the Restarted Preconditioned Direct Generalized
- * Minimal Residual Method. The stopping criterion is the norm of the
- * residual.
+ * Implementation of the Restarted Preconditioned Direct Generalized Minimal
+ * Residual Method. The stopping criterion is the norm of the residual.
*
- * The AdditionalData structure contains the number of temporary
- * vectors used. The size of the Arnoldi basis is this number minus
- * three. Additionally, it allows you to choose between right or left
- * preconditioning. The default is left preconditioning. Finally it
- * includes a flag indicating whether or not the default residual is
- * used as stopping criterion.
+ * The AdditionalData structure contains the number of temporary vectors used.
+ * The size of the Arnoldi basis is this number minus three. Additionally, it
+ * allows you to choose between right or left preconditioning. The default is
+ * left preconditioning. Finally it includes a flag indicating whether or not
+ * the default residual is used as stopping criterion.
*
*
* <h3>Left versus right preconditioning</h3>
*
* @p AdditionalData allows you to choose between left and right
- * preconditioning. As expected, this switches between solving for the
- * systems <i>P<sup>-1</sup>A</i> and <i>AP<sup>-1</sup></i>,
- * respectively.
+ * preconditioning. As expected, this switches between solving for the systems
+ * <i>P<sup>-1</sup>A</i> and <i>AP<sup>-1</sup></i>, respectively.
*
- * A second consequence is the type of residual which is used to
- * measure convergence. With left preconditioning, this is the
- * <b>preconditioned</b> residual, while with right preconditioning,
- * it is the residual of the unpreconditioned system.
+ * A second consequence is the type of residual which is used to measure
+ * convergence. With left preconditioning, this is the <b>preconditioned</b>
+ * residual, while with right preconditioning, it is the residual of the
+ * unpreconditioned system.
*
* Optionally, this behavior can be overridden by using the flag
- * AdditionalData::use_default_residual. A <tt>true</tt> value refers
- * to the behavior described in the previous paragraph, while
- * <tt>false</tt> reverts it. Be aware though that additional
- * residuals have to be computed in this case, impeding the overall
- * performance of the solver.
+ * AdditionalData::use_default_residual. A <tt>true</tt> value refers to the
+ * behavior described in the previous paragraph, while <tt>false</tt> reverts
+ * it. Be aware though that additional residuals have to be computed in this
+ * case, impeding the overall performance of the solver.
*
*
* <h3>The size of the Arnoldi basis</h3>
*
- * The maximal basis size is controlled by
- * AdditionalData::max_n_tmp_vectors, and it is this number minus 2.
- * If the number of iteration steps exceeds this number, all basis
- * vectors are discarded and the iteration starts anew from the
- * approximation obtained so far.
+ * The maximal basis size is controlled by AdditionalData::max_n_tmp_vectors,
+ * and it is this number minus 2. If the number of iteration steps exceeds
+ * this number, all basis vectors are discarded and the iteration starts anew
+ * from the approximation obtained so far.
*
- * Note that the minimizing property of GMRes only pertains to the
- * Krylov space spanned by the Arnoldi basis. Therefore, restarted
- * GMRes is <b>not</b> minimizing anymore. The choice of the basis
- * length is a trade-off between memory consumption and convergence
- * speed, since a longer basis means minimization over a larger
- * space.
+ * Note that the minimizing property of GMRes only pertains to the Krylov
+ * space spanned by the Arnoldi basis. Therefore, restarted GMRes is
+ * <b>not</b> minimizing anymore. The choice of the basis length is a trade-
+ * off between memory consumption and convergence speed, since a longer basis
+ * means minimization over a larger space.
*
- * For the requirements on matrices and vectors in order to work with
- * this class, see the documentation of the Solver base class.
+ * For the requirements on matrices and vectors in order to work with this
+ * class, see the documentation of the Solver base class.
*
*
* <h3>Observing the progress of linear solver iterations</h3>
*
- * The solve() function of this class uses the mechanism described
- * in the Solver base class to determine convergence. This mechanism
- * can also be used to observe the progress of the iteration.
+ * The solve() function of this class uses the mechanism described in the
+ * Solver base class to determine convergence. This mechanism can also be used
+ * to observe the progress of the iteration.
*
*
* @author Wolfgang Bangerth, Guido Kanschat, Ralf Hartmann.
/**
* Constructor. By default, set the number of temporary vectors to 30,
* i.e. do a restart every 28 iterations. Also set preconditioning from
- * left, the residual of the stopping criterion to the default
- * residual, and re-orthogonalization only if necessary.
+ * left, the residual of the stopping criterion to the default residual,
+ * and re-orthogonalization only if necessary.
*/
AdditionalData (const unsigned int max_n_tmp_vectors = 30,
const bool right_preconditioning = false,
bool use_default_residual;
/**
- * Flag to force re-orthogonalization of orthonormal basis in every
- * step. If set to false, the solver automatically checks for loss of
+ * Flag to force re-orthogonalization of orthonormal basis in every step.
+ * If set to false, the solver automatically checks for loss of
* orthogonality every 5 iterations and enables re-orthogonalization only
* if necessary.
*/
/**
* Orthogonalize the vector @p vv against the @p dim (orthogonal) vectors
- * given by the first argument using the modified Gram-Schmidt
- * algorithm. The factors used for orthogonalization are stored in @p h. The
- * boolean @p re_orthogonalize specifies whether the modified Gram-Schmidt
- * algorithm should be applied twice. The algorithm checks loss of
- * orthogonality in the procedure every fifth step and sets the flag to true
- * in that case. All subsequent iterations use re-orthogonalization.
+ * given by the first argument using the modified Gram-Schmidt algorithm.
+ * The factors used for orthogonalization are stored in @p h. The boolean @p
+ * re_orthogonalize specifies whether the modified Gram-Schmidt algorithm
+ * should be applied twice. The algorithm checks loss of orthogonality in
+ * the procedure every fifth step and sets the flag to true in that case.
+ * All subsequent iterations use re-orthogonalization.
*/
static double
modified_gram_schmidt (const internal::SolverGMRES::TmpVectors<VECTOR> &orthogonal_vectors,
* preconditioning method.
*
* This version of the GMRES method allows for the use of a different
- * preconditioner in each iteration step. Therefore, it is also more
- * robust with respect to inaccurate evaluation of the
- * preconditioner. An important application is also the use of a
- * Krylov space method inside the preconditioner.
+ * preconditioner in each iteration step. Therefore, it is also more robust
+ * with respect to inaccurate evaluation of the preconditioner. An important
+ * application is also the use of a Krylov space method inside the
+ * preconditioner.
*
- * FGMRES needs two vectors in each iteration steps yielding a total
- * of <tt>2 * SolverFGMRESAdditionalData::max_basis_size+1</tt>
- * auxiliary vectors.
+ * FGMRES needs two vectors in each iteration steps yielding a total of <tt>2
+ * * SolverFGMRESAdditionalData::max_basis_size+1</tt> auxiliary vectors.
*
- * Caveat: documentation of this class is not up to date. There are
- * also a few parameters of GMRES we would like to introduce here.
+ * Caveat: documentation of this class is not up to date. There are also a few
+ * parameters of GMRES we would like to introduce here.
*
* @author Guido Kanschat, 2003
*/
/**
* Minimal residual method for symmetric matrices.
*
- * For the requirements on matrices and vectors in order to work with
- * this class, see the documentation of the Solver base class.
+ * For the requirements on matrices and vectors in order to work with this
+ * class, see the documentation of the Solver base class.
*
- * Like all other solver classes, this class has a local structure called
- * @p AdditionalData which is used to pass additional parameters to the
- * solver, like damping parameters or the number of temporary vectors. We
- * use this additional structure instead of passing these values directly
- * to the constructor because this makes the use of the @p SolverSelector and
- * other classes much easier and guarantees that these will continue to
- * work even if number or type of the additional parameters for a certain
- * solver changes.
+ * Like all other solver classes, this class has a local structure called @p
+ * AdditionalData which is used to pass additional parameters to the solver,
+ * like damping parameters or the number of temporary vectors. We use this
+ * additional structure instead of passing these values directly to the
+ * constructor because this makes the use of the @p SolverSelector and other
+ * classes much easier and guarantees that these will continue to work even if
+ * number or type of the additional parameters for a certain solver changes.
*
- * However, since the MinRes method does not need additional data, the respective
- * structure is empty and does not offer any functionality. The constructor
- * has a default argument, so you may call it without the additional
- * parameter.
+ * However, since the MinRes method does not need additional data, the
+ * respective structure is empty and does not offer any functionality. The
+ * constructor has a default argument, so you may call it without the
+ * additional parameter.
*
* The preconditioner has to be positive definite and symmetric
*
- * The algorithm is taken from the Master thesis of Astrid Battermann
- * with some changes. The full text can be found at
+ * The algorithm is taken from the Master thesis of Astrid Battermann with
+ * some changes. The full text can be found at
* http://scholar.lib.vt.edu/theses/public/etd-12164379662151/etd-title.html
*
*
* <h3>Observing the progress of linear solver iterations</h3>
*
- * The solve() function of this class uses the mechanism described
- * in the Solver base class to determine convergence. This mechanism
- * can also be used to observe the progress of the iteration.
+ * The solve() function of this class uses the mechanism described in the
+ * Solver base class to determine convergence. This mechanism can also be used
+ * to observe the progress of the iteration.
*
*
* @author Thomas Richter, 2000, Luca Heltai, 2006
{
public:
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver. This solver does not
- * need additional data yet.
+ * Standardized data struct to pipe additional data to the solver. This
+ * solver does not need additional data yet.
*/
struct AdditionalData
{
const AdditionalData &data=AdditionalData());
/**
- * Constructor. Use an object of
- * type GrowingVectorMemory as
- * a default to allocate memory.
+ * Constructor. Use an object of type GrowingVectorMemory as a default to
+ * allocate memory.
*/
SolverMinRes (SolverControl &cn,
const AdditionalData &data=AdditionalData());
virtual ~SolverMinRes ();
/**
- * Solve the linear system $Ax=b$
- * for x.
+ * Solve the linear system $Ax=b$ for x.
*/
template<class MATRIX, class PRECONDITIONER>
void
const VECTOR &b,
const PRECONDITIONER &precondition);
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
protected:
/**
- * Implementation of the computation of
- * the norm of the residual.
+ * Implementation of the computation of the norm of the residual.
*/
virtual double criterion();
/**
- * Interface for derived class.
- * This function gets the current
- * iteration vector, the residual
- * and the update vector in each
- * step. It can be used for a
- * graphical output of the
- * convergence history.
+ * Interface for derived class. This function gets the current iteration
+ * vector, the residual and the update vector in each step. It can be used
+ * for a graphical output of the convergence history.
*/
virtual void print_vectors(const unsigned int step,
const VECTOR &x,
const VECTOR &d) const;
/**
- * Temporary vectors, allocated through
- * the @p VectorMemory object at the start
- * of the actual solution process and
- * deallocated at the end.
+ * Temporary vectors, allocated through the @p VectorMemory object at the
+ * start of the actual solution process and deallocated at the end.
*/
VECTOR *Vu0, *Vu1, *Vu2;
VECTOR *Vm0, *Vm1, *Vm2;
VECTOR *Vv;
/**
- * Within the iteration loop, the
- * square of the residual vector is
- * stored in this variable. The
- * function @p criterion uses this
- * variable to compute the convergence
- * value, which in this class is the
- * norm of the residual vector and thus
- * the square root of the @p res2 value.
+ * Within the iteration loop, the square of the residual vector is stored in
+ * this variable. The function @p criterion uses this variable to compute
+ * the convergence value, which in this class is the norm of the residual
+ * vector and thus the square root of the @p res2 value.
*/
double res2;
};
/**
* Quasi-minimal residual method for symmetric matrices.
*
- * The QMRS method is supposed to solve symmetric indefinite linear
- * systems with symmetric, not necessarily definite preconditioners.
- * This version of QMRS is adapted from
- * Freund/Nachtigal: Software for simplified Lanczos and QMR
- * algorithms, Appl. Num. Math. 19 (1995), pp. 319-341
+ * The QMRS method is supposed to solve symmetric indefinite linear systems
+ * with symmetric, not necessarily definite preconditioners. This version of
+ * QMRS is adapted from Freund/Nachtigal: Software for simplified Lanczos and
+ * QMR algorithms, Appl. Num. Math. 19 (1995), pp. 319-341
*
* This version is for right preconditioning only, since then only the
- * preconditioner is used: left preconditioning seems to require the
- * inverse.
+ * preconditioner is used: left preconditioning seems to require the inverse.
*
- * For the requirements on matrices and vectors in order to work with
- * this class, see the documentation of the Solver base class.
+ * For the requirements on matrices and vectors in order to work with this
+ * class, see the documentation of the Solver base class.
*
- * Like all other solver classes, this class has a local structure called
- * @p AdditionalData which is used to pass additional parameters to the
- * solver, like damping parameters or the number of temporary vectors. We
- * use this additional structure instead of passing these values directly
- * to the constructor because this makes the use of the @p SolverSelector and
- * other classes much easier and guarantees that these will continue to
- * work even if number or type of the additional parameters for a certain
- * solver changes.
+ * Like all other solver classes, this class has a local structure called @p
+ * AdditionalData which is used to pass additional parameters to the solver,
+ * like damping parameters or the number of temporary vectors. We use this
+ * additional structure instead of passing these values directly to the
+ * constructor because this makes the use of the @p SolverSelector and other
+ * classes much easier and guarantees that these will continue to work even if
+ * number or type of the additional parameters for a certain solver changes.
*
- * However, since the QMRS method does not need additional data, the respective
- * structure is empty and does not offer any functionality. The constructor
- * has a default argument, so you may call it without the additional
- * parameter.
+ * However, since the QMRS method does not need additional data, the
+ * respective structure is empty and does not offer any functionality. The
+ * constructor has a default argument, so you may call it without the
+ * additional parameter.
*
*
* <h3>Observing the progress of linear solver iterations</h3>
*
- * The solve() function of this class uses the mechanism described
- * in the Solver base class to determine convergence. This mechanism
- * can also be used to observe the progress of the iteration.
+ * The solve() function of this class uses the mechanism described in the
+ * Solver base class to determine convergence. This mechanism can also be used
+ * to observe the progress of the iteration.
*
*
* @author Guido Kanschat, 1999
{
public:
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver.
+ * Standardized data struct to pipe additional data to the solver.
*
- * There are two possibilities to compute
- * the residual: one is an estimate using
- * the computed value @p tau. The other
- * is exact computation using another matrix
- * vector multiplication.
+ * There are two possibilities to compute the residual: one is an estimate
+ * using the computed value @p tau. The other is exact computation using
+ * another matrix vector multiplication.
*
- * QMRS, is susceptible to
- * breakdowns, so we need a
- * parameter telling us, which
- * numbers are considered
- * zero. The proper breakdown
- * criterion is very unclear, so
- * experiments may be necessary
- * here.
+ * QMRS, is susceptible to breakdowns, so we need a parameter telling us,
+ * which numbers are considered zero. The proper breakdown criterion is very
+ * unclear, so experiments may be necessary here.
*/
struct AdditionalData
{
/**
* Constructor.
*
- * The default is no exact residual
- * computation and breakdown
- * parameter 1e-16.
+ * The default is no exact residual computation and breakdown parameter
+ * 1e-16.
*/
AdditionalData(bool exact_residual = false,
double breakdown=1.e-16) :
const AdditionalData &data=AdditionalData());
/**
- * Constructor. Use an object of
- * type GrowingVectorMemory as
- * a default to allocate memory.
+ * Constructor. Use an object of type GrowingVectorMemory as a default to
+ * allocate memory.
*/
SolverQMRS (SolverControl &cn,
const AdditionalData &data=AdditionalData());
/**
- * Solve the linear system $Ax=b$
- * for x.
+ * Solve the linear system $Ax=b$ for x.
*/
template<class MATRIX, class PRECONDITIONER>
void
const PRECONDITIONER &precondition);
/**
- * Interface for derived class.
- * This function gets the current
- * iteration vector, the residual
- * and the update vector in each
- * step. It can be used for a
- * graphical output of the
- * convergence history.
+ * Interface for derived class. This function gets the current iteration
+ * vector, the residual and the update vector in each step. It can be used
+ * for a graphical output of the convergence history.
*/
virtual void print_vectors(const unsigned int step,
const VECTOR &x,
const VECTOR &d) const;
protected:
/**
- * Implementation of the computation of
- * the norm of the residual.
+ * Implementation of the computation of the norm of the residual.
*/
virtual double criterion();
/**
- * Temporary vectors, allocated through
- * the @p VectorMemory object at the start
- * of the actual solution process and
- * deallocated at the end.
+ * Temporary vectors, allocated through the @p VectorMemory object at the
+ * start of the actual solution process and deallocated at the end.
*/
VECTOR *Vv;
VECTOR *Vp;
const VECTOR *Vb;
/**
- * Within the iteration loop, the
- * square of the residual vector is
- * stored in this variable. The
- * function @p criterion uses this
- * variable to compute the convergence
- * value, which in this class is the
- * norm of the residual vector and thus
- * the square root of the @p res2 value.
+ * Within the iteration loop, the square of the residual vector is stored in
+ * this variable. The function @p criterion uses this variable to compute
+ * the convergence value, which in this class is the norm of the residual
+ * vector and thus the square root of the @p res2 value.
*/
double res2;
private:
/**
- * A structure returned by the iterate() function representing
- * what it found is happening during the iteration.
+ * A structure returned by the iterate() function representing what it found
+ * is happening during the iteration.
*/
struct IterationResult
{
/**
- * The iteration loop itself. The function returns a structure
- * indicating what happened in this function.
+ * The iteration loop itself. The function returns a structure indicating
+ * what happened in this function.
*/
template<class MATRIX, class PRECONDITIONER>
IterationResult
DEAL_II_NAMESPACE_OPEN
/**
- * Implementation of an iterative solver based on relaxation
- * methods. The stopping criterion is the norm of the residual.
+ * Implementation of an iterative solver based on relaxation methods. The
+ * stopping criterion is the norm of the residual.
*
- * For the requirements on matrices and vectors in order to work with
- * this class, see the documentation of the Solver base class.
+ * For the requirements on matrices and vectors in order to work with this
+ * class, see the documentation of the Solver base class.
*
- * Like all other solver classes, this class has a local structure called
- * @p AdditionalData which is used to pass additional parameters to the
- * solver, like damping parameters or the number of temporary vectors. We
- * use this additional structure instead of passing these values directly
- * to the constructor because this makes the use of the @p SolverSelector and
- * other classes much easier and guarantees that these will continue to
- * work even if number or type of the additional parameters for a certain
- * solver changes. AdditionalData of this class currently does not
- * contain any data.
+ * Like all other solver classes, this class has a local structure called @p
+ * AdditionalData which is used to pass additional parameters to the solver,
+ * like damping parameters or the number of temporary vectors. We use this
+ * additional structure instead of passing these values directly to the
+ * constructor because this makes the use of the @p SolverSelector and other
+ * classes much easier and guarantees that these will continue to work even if
+ * number or type of the additional parameters for a certain solver changes.
+ * AdditionalData of this class currently does not contain any data.
*
*
* <h3>Observing the progress of linear solver iterations</h3>
*
- * The solve() function of this class uses the mechanism described
- * in the Solver base class to determine convergence. This mechanism
- * can also be used to observe the progress of the iteration.
+ * The solve() function of this class uses the mechanism described in the
+ * Solver base class to determine convergence. This mechanism can also be used
+ * to observe the progress of the iteration.
*
*
* @ingroup Solvers
{
public:
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver. There is no data in
- * here for relaxation methods.
+ * Standardized data struct to pipe additional data to the solver. There is
+ * no data in here for relaxation methods.
*/
struct AdditionalData {};
virtual ~SolverRelaxation ();
/**
- * Solve the system $Ax = b$
- * using the relaxation method
- * $x_{k+1} = R(x_k,b)$. The
- * amtrix <i>A</i> itself is only
- * used to compute the residual.
+ * Solve the system $Ax = b$ using the relaxation method $x_{k+1} =
+ * R(x_k,b)$. The amtrix <i>A</i> itself is only used to compute the
+ * residual.
*/
template<class MATRIX, class RELAXATION>
void
/*@{*/
/**
- * Implementation of the preconditioned Richardson iteration method. The stopping criterion
- * is the norm of the residual.
+ * Implementation of the preconditioned Richardson iteration method. The
+ * stopping criterion is the norm of the residual.
*
- * For the requirements on matrices and vectors in order to work with
- * this class, see the documentation of the Solver base class.
+ * For the requirements on matrices and vectors in order to work with this
+ * class, see the documentation of the Solver base class.
*
- * Like all other solver classes, this class has a local structure called
- * @p AdditionalData which is used to pass additional parameters to the
- * solver, like damping parameters or the number of temporary vectors. We
- * use this additional structure instead of passing these values directly
- * to the constructor because this makes the use of the @p SolverSelector and
- * other classes much easier and guarantees that these will continue to
- * work even if number or type of the additional parameters for a certain
- * solver changes.
+ * Like all other solver classes, this class has a local structure called @p
+ * AdditionalData which is used to pass additional parameters to the solver,
+ * like damping parameters or the number of temporary vectors. We use this
+ * additional structure instead of passing these values directly to the
+ * constructor because this makes the use of the @p SolverSelector and other
+ * classes much easier and guarantees that these will continue to work even if
+ * number or type of the additional parameters for a certain solver changes.
*
* For the Richardson method, the additional data is the damping parameter,
* which is the only content of the @p AdditionalData structure. By default,
*
* <h3>Observing the progress of linear solver iterations</h3>
*
- * The solve() function of this class uses the mechanism described
- * in the Solver base class to determine convergence. This mechanism
- * can also be used to observe the progress of the iteration.
+ * The solve() function of this class uses the mechanism described in the
+ * Solver base class to determine convergence. This mechanism can also be used
+ * to observe the progress of the iteration.
*
*
* @author Ralf Hartmann
{
public:
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
{
/**
- * Constructor. By default,
- * set the damping parameter
- * to one.
+ * Constructor. By default, set the damping parameter to one.
*/
AdditionalData (const double omega = 1,
const bool use_preconditioned_residual = false);
const AdditionalData &data=AdditionalData());
/**
- * Constructor. Use an object of
- * type GrowingVectorMemory as
- * a default to allocate memory.
+ * Constructor. Use an object of type GrowingVectorMemory as a default to
+ * allocate memory.
*/
SolverRichardson (SolverControl &cn,
const AdditionalData &data=AdditionalData());
virtual ~SolverRichardson ();
/**
- * Solve the linear system $Ax=b$
- * for x.
+ * Solve the linear system $Ax=b$ for x.
*/
template<class MATRIX, class PRECONDITIONER>
void
const PRECONDITIONER &precondition);
/**
- * Set the damping-coefficient.
- * Default is 1., i.e. no damping.
+ * Set the damping-coefficient. Default is 1., i.e. no damping.
*/
void set_omega (const double om=1.);
/**
- * Interface for derived class.
- * This function gets the current
- * iteration vector, the residual
- * and the update vector in each
- * step. It can be used for a
- * graphical output of the
- * convergence history.
+ * Interface for derived class. This function gets the current iteration
+ * vector, the residual and the update vector in each step. It can be used
+ * for a graphical output of the convergence history.
*/
virtual void print_vectors(const unsigned int step,
const VECTOR &x,
protected:
/**
- * Implementation of the computation of
- * the norm of the residual.
+ * Implementation of the computation of the norm of the residual.
*/
virtual typename VECTOR::value_type criterion();
/**
- * Residual. Temporary vector allocated through
- * the VectorMemory object at the start
- * of the actual solution process and
- * deallocated at the end.
+ * Residual. Temporary vector allocated through the VectorMemory object at
+ * the start of the actual solution process and deallocated at the end.
*/
VECTOR *Vr;
/**
- * Preconditioned
- * residual. Temporary vector
- * allocated through the
- * VectorMemory object at the
- * start of the actual solution
- * process and deallocated at the
- * end.
+ * Preconditioned residual. Temporary vector allocated through the
+ * VectorMemory object at the start of the actual solution process and
+ * deallocated at the end.
*/
VECTOR *Vd;
AdditionalData additional_data;
/**
- * Within the iteration loop, the
- * norm of the residual is
- * stored in this variable. The
- * function @p criterion uses this
- * variable to compute the convergence
- * value, which in this class is the
- * norm of the residual vector and thus
- * the square root of the @p res2 value.
+ * Within the iteration loop, the norm of the residual is stored in this
+ * variable. The function @p criterion uses this variable to compute the
+ * convergence value, which in this class is the norm of the residual vector
+ * and thus the square root of the @p res2 value.
*/
typename VECTOR::value_type res;
};
/**
* Selects a solver by changing a parameter.
*
- * By calling the @p solve function of this @p SolverSelector, it selects
- * the @p solve function of that @p Solver that was specified in the constructor
+ * By calling the @p solve function of this @p SolverSelector, it selects the
+ * @p solve function of that @p Solver that was specified in the constructor
* of this class.
*
- * <h3>Usage</h3>
- * The simplest use of this class is the following:
+ * <h3>Usage</h3> The simplest use of this class is the following:
* @code
* // generate a @p SolverControl and
* // a @p VectorMemory
* // preconditioning as last argument
* solver_selector.solve(A,x,b,preconditioning);
* @endcode
- * But the full usefulness of the @p SolverSelector class is not
- * clear until the presentation of the following example that assumes
- * the user using the @p ParameterHandler class and having declared a
- * "solver" entry, e.g. with
+ * But the full usefulness of the @p SolverSelector class is not clear until
+ * the presentation of the following example that assumes the user using the
+ * @p ParameterHandler class and having declared a "solver" entry, e.g. with
* @code
* Parameter_Handler prm;
* prm.declare_entry ("solver", "none",
* ...
* @endcode
* Assuming that in the users parameter file there exists the line
- @verbatim
- set solver = cg
- @endverbatim
+ * @verbatim
+ * set solver = cg
+ * @endverbatim
* then `Line 3' of the above example reads
* @code
* SolverSelector<SparseMatrix<double>, Vector<double> >
public:
/**
- * Constructor, filling in
- * default values
+ * Constructor, filling in default values
*/
SolverSelector ();
/**
- * @deprecated Use the default
- * constructor, set_control() and select().
+ * @deprecated Use the default constructor, set_control() and select().
*
- * Constructor. Use the arguments
- * to initialize actual solver
- * objects. The VectorMemory
- * argument is ignored.
+ * Constructor. Use the arguments to initialize actual solver objects. The
+ * VectorMemory argument is ignored.
*/
SolverSelector (const std::string &solvername,
SolverControl &control,
~SolverSelector();
/**
- * Solver procedure. Calls the @p solve
- * function
- * of the @p solver whose @p SolverName
- * was specified in the constructor.
+ * Solver procedure. Calls the @p solve function of the @p solver whose @p
+ * SolverName was specified in the constructor.
*
*/
template<class Matrix, class Preconditioner>
const Preconditioner &precond) const;
/**
- * Select a new solver. Note that
- * all solver names used in this
- * class are all lower case.
+ * Select a new solver. Note that all solver names used in this class are
+ * all lower case.
*/
void select(const std::string &name);
/**
- * Set a new SolverControl. This needs to
- * be set before solving.
+ * Set a new SolverControl. This needs to be set before solving.
*/
void set_control(SolverControl &ctrl);
/**
- * Set the additional data. For more
- * info see the @p Solver class.
+ * Set the additional data. For more info see the @p Solver class.
*/
void set_data(const typename SolverRichardson<VECTOR>
::AdditionalData &data);
/**
- * Set the additional data. For more
- * info see the @p Solver class.
+ * Set the additional data. For more info see the @p Solver class.
*/
void set_data(const typename SolverCG<VECTOR>
::AdditionalData &data);
/**
- * Set the additional data. For more
- * info see the @p Solver class.
+ * Set the additional data. For more info see the @p Solver class.
*/
void set_data(const typename SolverMinRes<VECTOR>
::AdditionalData &data);
/**
- * Set the additional data. For more
- * info see the @p Solver class.
+ * Set the additional data. For more info see the @p Solver class.
*/
void set_data(const typename SolverBicgstab<VECTOR>
::AdditionalData &data);
/**
- * Set the additional data. For more
- * info see the @p Solver class.
+ * Set the additional data. For more info see the @p Solver class.
*/
void set_data(const typename SolverGMRES<VECTOR>
::AdditionalData &data);
/**
- * Set the additional data. For more
- * info see the @p Solver class.
+ * Set the additional data. For more info see the @p Solver class.
*/
void set_data(const typename SolverFGMRES<VECTOR>
::AdditionalData &data);
/**
- * Get the names of all implemented
- * solvers.
+ * Get the names of all implemented solvers.
*/
static std::string get_solver_names ();
protected:
/**
- * Stores the @p SolverControl that is
- * needed in the constructor of each @p
- * Solver class. This can be changed with
- * @p set_control().
+ * Stores the @p SolverControl that is needed in the constructor of each @p
+ * Solver class. This can be changed with @p set_control().
*/
SmartPointer< SolverControl, SolverSelector< VECTOR > > control;
*/
/**
- * Abstract base class for incomplete decompositions of a sparse matrix
- * into sparse factors. This class can't be used by itself, but
- * only as the base class of derived classes that actually implement
- * particular decompositions such as SparseILU or SparseMIC.
+ * Abstract base class for incomplete decompositions of a sparse matrix into
+ * sparse factors. This class can't be used by itself, but only as the base
+ * class of derived classes that actually implement particular decompositions
+ * such as SparseILU or SparseMIC.
*
- * The decomposition is stored as a sparse matrix which is why this
- * class is derived from the SparseMatrix. Since it is not a matrix in
- * the usual sense (the stored entries are not those of a matrix, but
- * of two different matrix factors), the derivation is
- * <tt>protected</tt> rather than <tt>public</tt>.
+ * The decomposition is stored as a sparse matrix which is why this class is
+ * derived from the SparseMatrix. Since it is not a matrix in the usual sense
+ * (the stored entries are not those of a matrix, but of two different matrix
+ * factors), the derivation is <tt>protected</tt> rather than <tt>public</tt>.
*
*
* <h3>Fill-in</h3>
*
- * Sparse decompositions are frequently used with additional
- * fill-in, i.e., the sparsity structure of the decomposition is denser
- * than that of the matrix to be decomposed. The initialize()
- * function of this class allows this fill-in via the AdditionalData
- * object as long as all entries
- * present in the original matrix are present in the decomposition
- * also, i.e. the sparsity pattern of the decomposition is a superset
- * of the sparsity pattern in the original matrix.
+ * Sparse decompositions are frequently used with additional fill-in, i.e.,
+ * the sparsity structure of the decomposition is denser than that of the
+ * matrix to be decomposed. The initialize() function of this class allows
+ * this fill-in via the AdditionalData object as long as all entries present
+ * in the original matrix are present in the decomposition also, i.e. the
+ * sparsity pattern of the decomposition is a superset of the sparsity pattern
+ * in the original matrix.
*
- * Such fill-in can be accomplished by various ways, one of which is a
- * copy-constructor of the SparsityPattern class which allows the addition
- * of side-diagonals to a given sparsity structure.
+ * Such fill-in can be accomplished by various ways, one of which is a copy-
+ * constructor of the SparsityPattern class which allows the addition of side-
+ * diagonals to a given sparsity structure.
*
*
* <h3>Unified use of preconditioners</h3>
*
- * While objects of this class can not be used directly (this class is
- * only a base class for others implementing actual decompositions),
- * derived classes such as SparseILU and SparseMIC can be used in the
- * usual form as preconditioners. For example, this works:
+ * While objects of this class can not be used directly (this class is only a
+ * base class for others implementing actual decompositions), derived classes
+ * such as SparseILU and SparseMIC can be used in the usual form as
+ * preconditioners. For example, this works:
* @code
* SparseILU<double> ilu;
* ilu.initialize(matrix, SparseILU<double>::AdditionalData(...));
* somesolver.solve (A, x, f, ilu);
* @endcode
*
- * Through the AdditionalData object it is possible to specify
- * additional parameters of the LU decomposition.
+ * Through the AdditionalData object it is possible to specify additional
+ * parameters of the LU decomposition.
*
* 1/ The matrix diagonals can be strengthened by adding
- * <tt>strengthen_diagonal</tt> times the sum of the absolute row entries
- * of each row to the respective diagonal entries. By default no
- * strengthening is performed.
+ * <tt>strengthen_diagonal</tt> times the sum of the absolute row entries of
+ * each row to the respective diagonal entries. By default no strengthening is
+ * performed.
*
- * 2/ By default, each initialize() function call creates its own
- * sparsity. For that, it copies the sparsity of <tt>matrix</tt> and adds a
- * specific number of extra off diagonal entries specified by
+ * 2/ By default, each initialize() function call creates its own sparsity.
+ * For that, it copies the sparsity of <tt>matrix</tt> and adds a specific
+ * number of extra off diagonal entries specified by
* <tt>extra_off_diagonals</tt>.
*
* 3/ By setting <tt>use_previous_sparsity=true</tt> the sparsity is not
- * recreated but the sparsity of the previous initialize() call is
- * reused (recycled). This might be useful when several linear
- * problems on the same sparsity need to solved, as for example
- * several Newton iteration steps on the same triangulation. The
- * default is <tt>false</tt>.
+ * recreated but the sparsity of the previous initialize() call is reused
+ * (recycled). This might be useful when several linear problems on the same
+ * sparsity need to solved, as for example several Newton iteration steps on
+ * the same triangulation. The default is <tt>false</tt>.
*
* 4/ It is possible to give a user defined sparsity to
* <tt>use_this_sparsity</tt>. Then, no sparsity is created but
*
* <h3>State management</h3>
*
- * The state management simply requires the initialize() function to
- * be called before the object is used as preconditioner.
+ * The state management simply requires the initialize() function to be called
+ * before the object is used as preconditioner.
*
- * <b>Obsolete:</b>
- * In order to prevent users from applying decompositions before the
- * decomposition itself has been built, and to introduce some
- * optimization of common "sparse idioms", this class introduces a
- * simple state management. A SparseLUdecomposition instance is
- * considered not decomposed if the decompose method has not yet
- * been invoked since the last time the underlying SparseMatrix
- * had changed. The underlying sparse matrix is considered changed
- * when one of this class reinit methods, constructors or destructors
- * are invoked. The not-decomposed state is indicated by a false
- * value returned by is_decomposed() method. It is illegal to apply
- * this decomposition (vmult() method) in not decomposed state; in
- * this case, the vmult() method throws an <tt>ExcInvalidState</tt>
- * exception. This object turns into decomposed state immediately
- * after its decompose() method is invoked. The decomposed
- * state is indicated by true value returned by is_decomposed()
- * method. It is legal to apply this decomposition (vmult() method) in
- * decomposed state.
+ * <b>Obsolete:</b> In order to prevent users from applying decompositions
+ * before the decomposition itself has been built, and to introduce some
+ * optimization of common "sparse idioms", this class introduces a simple
+ * state management. A SparseLUdecomposition instance is considered not
+ * decomposed if the decompose method has not yet been invoked since the last
+ * time the underlying SparseMatrix had changed. The underlying sparse matrix
+ * is considered changed when one of this class reinit methods, constructors
+ * or destructors are invoked. The not-decomposed state is indicated by a
+ * false value returned by is_decomposed() method. It is illegal to apply
+ * this decomposition (vmult() method) in not decomposed state; in this case,
+ * the vmult() method throws an <tt>ExcInvalidState</tt> exception. This
+ * object turns into decomposed state immediately after its decompose() method
+ * is invoked. The decomposed state is indicated by true value returned by
+ * is_decomposed() method. It is legal to apply this decomposition (vmult()
+ * method) in decomposed state.
*
* <h3>Particular implementations</h3>
*
- * It is enough to override the initialize() and vmult() methods to
- * implement particular LU decompositions, like the true LU, or the
- * Cholesky decomposition. Additionally, if that decomposition needs
- * fine tuned diagonal strengthening on a per row basis, it may override the
- * get_strengthen_diagonal() method. You should invoke the non-abstract
- * base class method to employ the state management. Implementations
- * may choose more restrictive definition of what is legal or illegal
- * state; but they must conform to the is_decomposed() method
- * specification above.
+ * It is enough to override the initialize() and vmult() methods to implement
+ * particular LU decompositions, like the true LU, or the Cholesky
+ * decomposition. Additionally, if that decomposition needs fine tuned
+ * diagonal strengthening on a per row basis, it may override the
+ * get_strengthen_diagonal() method. You should invoke the non-abstract base
+ * class method to employ the state management. Implementations may choose
+ * more restrictive definition of what is legal or illegal state; but they
+ * must conform to the is_decomposed() method specification above.
*
- * If an exception is thrown by method other than vmult(), this
- * object may be left in an inconsistent state.
+ * If an exception is thrown by method other than vmult(), this object may be
+ * left in an inconsistent state.
*
- * @author Stephen "Cheffo" Kolaroff, 2002, based on SparseILU implementation by Wolfgang Bangerth; unified interface: Ralf Hartmann, 2003
+ * @author Stephen "Cheffo" Kolaroff, 2002, based on SparseILU implementation
+ * by Wolfgang Bangerth; unified interface: Ralf Hartmann, 2003
*/
template <typename number>
class SparseLUDecomposition : protected SparseMatrix<number>,
/**
* Constructor. Does nothing.
*
- * Call the initialize()
- * function before using this
- * object as preconditioner
+ * Call the initialize() function before using this object as preconditioner
* (vmult()).
*/
SparseLUDecomposition ();
/**
- * @deprecated This method is deprecated, and
- * left for backward
- * compatibility. It will be removed
- * in later versions.
- * Instead, pass the sparsity pattern that you want used for
- * the decomposition in the AdditionalData structure.
+ * @deprecated This method is deprecated, and left for backward
+ * compatibility. It will be removed in later versions. Instead, pass the
+ * sparsity pattern that you want used for the decomposition in the
+ * AdditionalData structure.
*/
SparseLUDecomposition (const SparsityPattern &sparsity) DEAL_II_DEPRECATED;
typedef types::global_dof_index size_type;
/**
- * Destruction. Mark the
- * destructor pure to ensure that
- * this class isn't used
- * directly, but only its derived
- * classes.
+ * Destruction. Mark the destructor pure to ensure that this class isn't
+ * used directly, but only its derived classes.
*/
virtual ~SparseLUDecomposition () = 0;
/**
- * Deletes all member
- * variables. Leaves the class in
- * the state that it had directly
- * after calling the constructor
+ * Deletes all member variables. Leaves the class in the state that it had
+ * directly after calling the constructor
*/
virtual void clear();
/**
- * Parameters for
- * SparseDecomposition.
+ * Parameters for SparseDecomposition.
*/
class AdditionalData
{
public:
/**
- * Constructor. For the
- * parameters' description,
- * see below.
+ * Constructor. For the parameters' description, see below.
*/
AdditionalData (const double strengthen_diagonal=0,
const unsigned int extra_off_diagonals=0,
const SparsityPattern *use_this_sparsity=0);
/**
- * <tt>strengthen_diag</tt> times
- * the sum of absolute row
- * entries is added to the
- * diagonal entries.
+ * <tt>strengthen_diag</tt> times the sum of absolute row entries is added
+ * to the diagonal entries.
*
- * Per default, this value is
- * zero, i.e. the diagonal is
- * not strengthened.
+ * Per default, this value is zero, i.e. the diagonal is not strengthened.
*/
double strengthen_diagonal;
/**
- * By default, the
- * <tt>initialize(matrix,
- * data)</tt> function creates
- * its own sparsity. This
- * sparsity has the same
- * SparsityPattern as
- * <tt>matrix</tt> with some extra
- * off diagonals the number
- * of which is specified by
- * <tt>extra_off_diagonals</tt>.
+ * By default, the <tt>initialize(matrix, data)</tt> function creates its
+ * own sparsity. This sparsity has the same SparsityPattern as
+ * <tt>matrix</tt> with some extra off diagonals the number of which is
+ * specified by <tt>extra_off_diagonals</tt>.
*
- * The user can give a
- * SparsityPattern to
- * <tt>use_this_sparsity</tt>. Then
- * this sparsity is used and
- * the
- * <tt>extra_off_diagonals</tt>
- * argument is ignored.
+ * The user can give a SparsityPattern to <tt>use_this_sparsity</tt>. Then
+ * this sparsity is used and the <tt>extra_off_diagonals</tt> argument is
+ * ignored.
*/
unsigned int extra_off_diagonals;
/**
- * If this flag is true the
- * initialize() function uses
- * the same sparsity that was
- * used during the previous
- * initialize() call.
+ * If this flag is true the initialize() function uses the same sparsity
+ * that was used during the previous initialize() call.
*
- * This might be useful when
- * several linear problems on
- * the same sparsity need to
- * solved, as for example
- * several Newton iteration
- * steps on the same
- * triangulation.
+ * This might be useful when several linear problems on the same sparsity
+ * need to solved, as for example several Newton iteration steps on the
+ * same triangulation.
*/
bool use_previous_sparsity;
/**
- * When a
- * SparsityPattern is
- * given to this argument,
- * the initialize()
- * function calls
- * <tt>reinit(*use_this_sparsity)</tt>
- * causing this sparsity to
- * be used.
+ * When a SparsityPattern is given to this argument, the initialize()
+ * function calls <tt>reinit(*use_this_sparsity)</tt> causing this
+ * sparsity to be used.
*
- * Note that the sparsity structures
- * of <tt>*use_this_sparsity</tt> and
- * the matrix passed to the
- * initialize function need not be
- * equal. Fill-in is allowed, as well
- * as filtering out some elements in
- * the matrix.
+ * Note that the sparsity structures of <tt>*use_this_sparsity</tt> and
+ * the matrix passed to the initialize function need not be equal. Fill-in
+ * is allowed, as well as filtering out some elements in the matrix.
*/
const SparsityPattern *use_this_sparsity;
};
/**
- * This function needs to be
- * called before an object of
- * this class is used as
- * preconditioner.
+ * This function needs to be called before an object of this class is used
+ * as preconditioner.
*
- * For more detail about possible
- * parameters, see the class
- * documentation and the
- * documentation of the
- * SparseLUDecomposition::AdditionalData
- * class.
+ * For more detail about possible parameters, see the class documentation
+ * and the documentation of the SparseLUDecomposition::AdditionalData class.
*
- * According to the
- * <tt>parameters</tt>, this function
- * creates a new SparsityPattern
- * or keeps the previous sparsity
- * or takes the sparsity given by
- * the user to <tt>data</tt>. Then,
- * this function performs the LU
+ * According to the <tt>parameters</tt>, this function creates a new
+ * SparsityPattern or keeps the previous sparsity or takes the sparsity
+ * given by the user to <tt>data</tt>. Then, this function performs the LU
* decomposition.
*
- * After this function is called
- * the preconditioner is ready to
- * be used (using the
- * <code>vmult</code> function of
- * derived classes).
+ * After this function is called the preconditioner is ready to be used
+ * (using the <code>vmult</code> function of derived classes).
*/
template <typename somenumber>
void initialize (const SparseMatrix<somenumber> &matrix,
const AdditionalData parameters);
/**
- * This method is deprecated,
- * and left for backward
- * compatibility. It will be removed
- * in later versions.
+ * This method is deprecated, and left for backward compatibility. It will
+ * be removed in later versions.
*
* @deprecated
*/
void reinit (const SparsityPattern &sparsity) DEAL_II_DEPRECATED;
/**
- * This method is deprecated,
- * and left for backward
- * compability. It will be removed
- * in later versions.
+ * This method is deprecated, and left for backward compability. It will be
+ * removed in later versions.
*
* @deprecated
*/
const double strengthen_diagonal=0.) DEAL_II_DEPRECATED;
/**
- * This method is deprecated,
- * and left for backward
- * compability. It will be removed
- * in later versions.
+ * This method is deprecated, and left for backward compability. It will be
+ * removed in later versions.
*
* @deprecated
*/
virtual bool is_decomposed () const DEAL_II_DEPRECATED;
/**
- * Return whether the object is
- * empty. It calls the inherited
+ * Return whether the object is empty. It calls the inherited
* SparseMatrix::empty() function.
*/
bool empty () const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
virtual std::size_t memory_consumption () const;
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
//@}
protected:
/**
- * Copies the passed SparseMatrix
- * onto this object. This
- * object's sparsity pattern
- * remains unchanged.
+ * Copies the passed SparseMatrix onto this object. This object's sparsity
+ * pattern remains unchanged.
*/
template<typename somenumber>
void copy_from (const SparseMatrix<somenumber> &matrix);
/**
- * Performs the strengthening
- * loop. For each row calculates
- * the sum of absolute values of
- * its elements, determines the
- * strengthening factor (through
- * get_strengthen_diagonal())
- * sf and multiplies the diagonal
- * entry with <tt>sf+1</tt>.
+ * Performs the strengthening loop. For each row calculates the sum of
+ * absolute values of its elements, determines the strengthening factor
+ * (through get_strengthen_diagonal()) sf and multiplies the diagonal entry
+ * with <tt>sf+1</tt>.
*/
virtual void strengthen_diagonal_impl ();
/**
- * In the decomposition phase,
- * computes a strengthening
- * factor for the diagonal entry
- * in row <tt>row</tt> with sum of
- * absolute values of its
+ * In the decomposition phase, computes a strengthening factor for the
+ * diagonal entry in row <tt>row</tt> with sum of absolute values of its
* elements <tt>rowsum</tt>.<br> Note:
- * The default implementation in
- * SparseLUDecomposition
- * returns
- * <tt>strengthen_diagonal</tt>'s
- * value.
+ * The default implementation in SparseLUDecomposition returns
+ * <tt>strengthen_diagonal</tt>'s value.
*/
virtual number get_strengthen_diagonal(const number rowsum, const size_type row) const;
/**
- * State flag. If not in
- * decomposed state, it is
- * illegal to apply the
- * decomposition. This flag is
- * cleared when the underlaying
- * SparseMatrix
- * SparsityPattern is
- * changed, and set by
- * decompose().
+ * State flag. If not in decomposed state, it is illegal to apply the
+ * decomposition. This flag is cleared when the underlaying SparseMatrix
+ * SparsityPattern is changed, and set by decompose().
*/
bool decomposed;
/**
- * The default strengthening
- * value, returned by
- * get_strengthen_diagonal().
+ * The default strengthening value, returned by get_strengthen_diagonal().
*/
double strengthen_diagonal;
/**
- * For every row in the
- * underlying
- * SparsityPattern, this
- * array contains a pointer
- * to the row's first
- * afterdiagonal entry. Becomes
- * available after invocation of
- * decompose().
+ * For every row in the underlying SparsityPattern, this array contains a
+ * pointer to the row's first afterdiagonal entry. Becomes available after
+ * invocation of decompose().
*/
std::vector<const size_type *> prebuilt_lower_bound;
private:
/**
- * Fills the
- * #prebuilt_lower_bound
- * array.
+ * Fills the #prebuilt_lower_bound array.
*/
void prebuild_lower_bound ();
/**
- * In general this pointer is
- * zero except for the case that
- * no SparsityPattern is
- * given to this class. Then, a
- * SparsityPattern is created
- * and is passed down to the
- * SparseMatrix base class.
+ * In general this pointer is zero except for the case that no
+ * SparsityPattern is given to this class. Then, a SparsityPattern is
+ * created and is passed down to the SparseMatrix base class.
*
- * Nevertheless, the
- * SparseLUDecomposition
- * needs to keep ownership of
- * this sparsity. It keeps this
- * pointer to it enabling it to
- * delete this sparsity at
- * destruction time.
+ * Nevertheless, the SparseLUDecomposition needs to keep ownership of this
+ * sparsity. It keeps this pointer to it enabling it to delete this sparsity
+ * at destruction time.
*/
SparsityPattern *own_sparsity;
};
DEAL_II_NAMESPACE_OPEN
/**
- * This class provides an interface to the sparse direct solver
- * UMFPACK (see <a
- * href="http://www.cise.ufl.edu/research/sparse/umfpack">this
- * link</a>). UMFPACK is a set of routines for solving non-symmetric
- * sparse linear systems, Ax=b, using the Unsymmetric-pattern
- * MultiFrontal method and direct sparse LU factorization. Matrices
- * may have symmetric or unsymmetrix sparsity patterns, and may have
- * unsymmetric entries. The use of this class is explained in the @ref
- * step_22 "step-22" and @ref
- * step_29 "step-29" tutorial programs.
+ * This class provides an interface to the sparse direct solver UMFPACK (see
+ * <a href="http://www.cise.ufl.edu/research/sparse/umfpack">this link</a>).
+ * UMFPACK is a set of routines for solving non-symmetric sparse linear
+ * systems, Ax=b, using the Unsymmetric-pattern MultiFrontal method and direct
+ * sparse LU factorization. Matrices may have symmetric or unsymmetrix
+ * sparsity patterns, and may have unsymmetric entries. The use of this class
+ * is explained in the @ref step_22 "step-22" and @ref step_29 "step-29"
+ * tutorial programs.
*
- * This matrix class implements the usual interface of
- * preconditioners, that is a function initialize(const
- * SparseMatrix<double>&matrix,const AdditionalData) for initalizing
- * and the whole set of vmult() functions common to all
- * matrices. Implemented here are only vmult() and vmult_add(), which
- * perform multiplication with the inverse matrix. Furthermore, this
- * class provides an older interface, consisting of the functions
- * factorize() and solve(). Both interfaces are interchangeable.
+ * This matrix class implements the usual interface of preconditioners, that
+ * is a function initialize(const SparseMatrix<double>&matrix,const
+ * AdditionalData) for initalizing and the whole set of vmult() functions
+ * common to all matrices. Implemented here are only vmult() and vmult_add(),
+ * which perform multiplication with the inverse matrix. Furthermore, this
+ * class provides an older interface, consisting of the functions factorize()
+ * and solve(). Both interfaces are interchangeable.
*
* @note This class only exists if support for <a
* href="http://www.cise.ufl.edu/research/sparse/umfpack">UMFPACK</a> was
/**
- * Constructor. See the documentation of this class for the meaning of
- * the parameters to this function.
+ * Constructor. See the documentation of this class for the meaning of the
+ * parameters to this function.
*/
SparseDirectUMFPACK ();
/**
* Factorize the matrix. This function may be called multiple times for
- * different matrices, after the object of this class has been
- * initialized for a certain sparsity pattern. You may therefore save
- * some computing time if you want to invert several matrices with the
- * same sparsity pattern. However, note that the bulk of the computing
- * time is actually spent in the factorization, so this functionality may
- * not always be of large benefit.
+ * different matrices, after the object of this class has been initialized
+ * for a certain sparsity pattern. You may therefore save some computing
+ * time if you want to invert several matrices with the same sparsity
+ * pattern. However, note that the bulk of the computing time is actually
+ * spent in the factorization, so this functionality may not always be of
+ * large benefit.
*
- * In contrast to the other direct solver classes, the initialisation
- * method does nothing. Therefore initialise is not automatically called
- * by this method, when the initialization step has not been performed
- * yet.
+ * In contrast to the other direct solver classes, the initialisation method
+ * does nothing. Therefore initialise is not automatically called by this
+ * method, when the initialization step has not been performed yet.
*
- * This function copies the contents of the matrix into its own storage;
- * the matrix can therefore be deleted after this operation, even if
- * subsequent solves are required.
+ * This function copies the contents of the matrix into its own storage; the
+ * matrix can therefore be deleted after this operation, even if subsequent
+ * solves are required.
*/
template <class Matrix>
void factorize (const Matrix &matrix);
*/
/**
- * Preconditioner interface function. Usually, given the source vector,
- * this method returns an approximate solution of <i>Ax = b</i>. As this
- * class provides a wrapper to a direct solver, here it is actually the
- * exact solution (exact within the range of numerical accuracy of
- * course).
+ * Preconditioner interface function. Usually, given the source vector, this
+ * method returns an approximate solution of <i>Ax = b</i>. As this class
+ * provides a wrapper to a direct solver, here it is actually the exact
+ * solution (exact within the range of numerical accuracy of course).
*
- * In other words, this function actually multiplies with the exact
- * inverse of the matrix, $A^{-1}$.
+ * In other words, this function actually multiplies with the exact inverse
+ * of the matrix, $A^{-1}$.
*/
void vmult (Vector<double> &dst,
const Vector<double> &src) const;
const BlockVector<double> &src) const;
/**
- * Same as before, but uses the transpose of the matrix, i.e. this
- * function multiplies with $A^{-T}$.
+ * Same as before, but uses the transpose of the matrix, i.e. this function
+ * multiplies with $A^{-T}$.
*/
void Tvmult (Vector<double> &dst,
const Vector<double> &src) const;
const BlockVector<double> &src) const;
/**
- * Same as vmult(), but adding to the previous solution. Not implemented
- * yet but necessary for compiling certain other classes.
+ * Same as vmult(), but adding to the previous solution. Not implemented yet
+ * but necessary for compiling certain other classes.
*/
void vmult_add (Vector<double> &dst,
const Vector<double> &src) const;
/**
- * Same as before, but uses the transpose of the matrix, i.e. this
- * function multiplies with $A^{-T}$.
+ * Same as before, but uses the transpose of the matrix, i.e. this function
+ * multiplies with $A^{-T}$.
*/
void Tvmult_add (Vector<double> &dst,
const Vector<double> &src) const;
*/
/**
- * Solve for a certain right hand side vector. This function may be
- * called multiple times for different right hand side vectors after the
- * matrix has been factorized. This yields a big saving in computing
- * time, since the actual solution is fast, compared to the factorization
- * of the matrix.
+ * Solve for a certain right hand side vector. This function may be called
+ * multiple times for different right hand side vectors after the matrix has
+ * been factorized. This yields a big saving in computing time, since the
+ * actual solution is fast, compared to the factorization of the matrix.
*
* The solution will be returned in place of the right hand side vector.
*
- * If the factorization has not happened before, strange things will
- * happen. Note that we can't actually call the factorize() function from
- * here if it has not yet been called, since we have no access to the
- * actual matrix.
+ * If the factorization has not happened before, strange things will happen.
+ * Note that we can't actually call the factorize() function from here if it
+ * has not yet been called, since we have no access to the actual matrix.
*
- * If @p transpose is set to true this function solves for the transpose
- * of the matrix, i.e. $x=A^{-T}b$.
+ * If @p transpose is set to true this function solves for the transpose of
+ * the matrix, i.e. $x=A^{-T}b$.
*/
void solve (Vector<double> &rhs_and_solution, bool transpose = false) const;
void solve (BlockVector<double> &rhs_and_solution, bool transpose = false) const;
/**
- * Call the two functions factorize() and solve() in that order, i.e. perform
- * the whole solution process for the given right hand side vector.
+ * Call the two functions factorize() and solve() in that order, i.e.
+ * perform the whole solution process for the given right hand side vector.
*
* The solution will be returned in place of the right hand side vector.
*/
*/
/**
- * One of the UMFPack routines threw an error. The error code is included
- * in the output and can be looked up in the UMFPack user manual. The
- * name of the routine is included for reference.
+ * One of the UMFPack routines threw an error. The error code is included in
+ * the output and can be looked up in the UMFPack user manual. The name of
+ * the routine is included for reference.
*/
DeclException2 (ExcUMFPACKError, char *, int,
<< "UMFPACK routine " << arg1
private:
/**
* The UMFPACK routines allocate objects in which they store information
- * about symbolic and numeric values of the decomposition. The actual
- * data type of these objects is opaque, and only passed around as void
- * pointers.
+ * about symbolic and numeric values of the decomposition. The actual data
+ * type of these objects is opaque, and only passed around as void pointers.
*/
void *symbolic_decomposition;
void *numeric_decomposition;
void clear ();
/**
- * Make sure that the arrays Ai and Ap are sorted in each row. UMFPACK
- * wants it this way. We need to have three versions of this function,
- * one for the usual SparseMatrix, one for the SparseMatrixEZ, and one
- * for the BlockSparseMatrix classes
+ * Make sure that the arrays Ai and Ap are sorted in each row. UMFPACK wants
+ * it this way. We need to have three versions of this function, one for the
+ * usual SparseMatrix, one for the SparseMatrixEZ, and one for the
+ * BlockSparseMatrix classes
*/
template <typename number>
void sort_arrays (const SparseMatrixEZ<number> &);
/**
- * This class provides an interface to the parallel sparse direct solver
- * <a href="http://mumps.enseeiht.fr">MUMPS</a>. MUMPS is direct method
- * based on a multifrontal approach, which performs a direct LU
- * factorization. The matrix coming in may have either symmetric or
- * nonsymmetric sparsity pattern.
+ * This class provides an interface to the parallel sparse direct solver <a
+ * href="http://mumps.enseeiht.fr">MUMPS</a>. MUMPS is direct method based on
+ * a multifrontal approach, which performs a direct LU factorization. The
+ * matrix coming in may have either symmetric or nonsymmetric sparsity
+ * pattern.
*
* @note This class is useable if and only if a working installation of <a
* href="http://mumps.enseeiht.fr">MUMPS</a> exists on your system and was
/**
* This function initializes a MUMPS instance and hands over the system's
- * matrix <tt>matrix</tt> and right-hand side <tt>vector</tt> to the
- * solver.
+ * matrix <tt>matrix</tt> and right-hand side <tt>vector</tt> to the solver.
*/
template <class Matrix>
void initialize (const Matrix &matrix,
const Vector<double> &vector);
/**
- * This function initializes a MUMPS instance and computes the
- * factorization of the system's matrix <tt>matrix</tt>.
+ * This function initializes a MUMPS instance and computes the factorization
+ * of the system's matrix <tt>matrix</tt>.
*/
template <class Matrix>
void initialize (const Matrix &matrix);
/**
- * A function in which the linear system is solved and the solution
- * vector is copied into the given <tt>vector</tt>. The right-hand side
- * need to be supplied in initialize(matrix, vector);
+ * A function in which the linear system is solved and the solution vector
+ * is copied into the given <tt>vector</tt>. The right-hand side need to be
+ * supplied in initialize(matrix, vector);
*/
void solve (Vector<double> &vector);
*/
/**
- * This class computes an Incomplete LU (ILU) decomposition of a sparse matrix,
- * using either the same sparsity pattern or a different one.
- * By incomplete we mean that unlike the exact decomposition, the incomplete
- * one is also computed using sparse factors, and entries
- * in the decomposition that do not fit into the given sparsity structure
- * are discarded.
+ * This class computes an Incomplete LU (ILU) decomposition of a sparse
+ * matrix, using either the same sparsity pattern or a different one. By
+ * incomplete we mean that unlike the exact decomposition, the incomplete one
+ * is also computed using sparse factors, and entries in the decomposition
+ * that do not fit into the given sparsity structure are discarded.
*
- * The algorithm used by this class is essentially a copy of the
- * algorithm given in the book Y. Saad: "Iterative methods for sparse
- * linear systems", second edition, in section 10.3.2.
+ * The algorithm used by this class is essentially a copy of the algorithm
+ * given in the book Y. Saad: "Iterative methods for sparse linear systems",
+ * second edition, in section 10.3.2.
*
*
* <h3>Usage and state management</h3>
*
- * Refer to SparseLUDecomposition documentation for suggested
- * usage and state management. This class is used in the @ref
- * step_22 "step-22" tutorial program.
+ * Refer to SparseLUDecomposition documentation for suggested usage and state
+ * management. This class is used in the @ref step_22 "step-22" tutorial
+ * program.
*
* @note Instantiations for this template are provided for <tt>@<float@> and
* @<double@></tt>; others can be generated in application programs (see the
/**
* Constructor. Does nothing.
*
- * Call the @p initialize
- * function before using this
- * object as preconditioner.
+ * Call the @p initialize function before using this object as
+ * preconditioner.
*/
SparseILU ();
/**
- * @deprecated This method is deprecated, and
- * left for backward
- * compatibility. It will be removed
- * in later versions.
- * Instead, pass the sparsity pattern that you want used for
- * the decomposition in the AdditionalData structure.
+ * @deprecated This method is deprecated, and left for backward
+ * compatibility. It will be removed in later versions. Instead, pass the
+ * sparsity pattern that you want used for the decomposition in the
+ * AdditionalData structure.
*/
SparseILU (const SparsityPattern &sparsity) DEAL_II_DEPRECATED;
/**
- * Make
- * SparseLUDecomposition::AdditionalData
- * accessible to this class as
+ * Make SparseLUDecomposition::AdditionalData accessible to this class as
* well.
*/
typedef
AdditionalData;
/**
- * Perform the incomplete LU
- * factorization of the given
- * matrix.
+ * Perform the incomplete LU factorization of the given matrix.
*
- * This function needs to be
- * called before an object of
- * this class is used as
- * preconditioner.
+ * This function needs to be called before an object of this class is used
+ * as preconditioner.
*
- * For more details about
- * possible parameters, see the
- * class documentation of
- * SparseLUDecomposition and the
- * documentation of the
- * @p SparseLUDecomposition::AdditionalData
- * class.
+ * For more details about possible parameters, see the class documentation
+ * of SparseLUDecomposition and the documentation of the @p
+ * SparseLUDecomposition::AdditionalData class.
*
- * According to the
- * @p parameters, this function
- * creates a new SparsityPattern
- * or keeps the previous sparsity
- * or takes the sparsity given by
- * the user to @p data. Then,
- * this function performs the LU
+ * According to the @p parameters, this function creates a new
+ * SparsityPattern or keeps the previous sparsity or takes the sparsity
+ * given by the user to @p data. Then, this function performs the LU
* decomposition.
*
- * After this function is called
- * the preconditioner is ready to
- * be used.
+ * After this function is called the preconditioner is ready to be used.
*/
template <typename somenumber>
void initialize (const SparseMatrix<somenumber> &matrix,
const AdditionalData ¶meters = AdditionalData());
/**
- * @deprecated This method is deprecated, and left for backward
- * compability. It will be removed in later versions.
+ * @deprecated This method is deprecated, and left for backward compability.
+ * It will be removed in later versions.
*/
template <typename somenumber>
void decompose (const SparseMatrix<somenumber> &matrix,
const double strengthen_diagonal=0.) DEAL_II_DEPRECATED;
/**
- * @deprecated This method is deprecated, and
- * left for backward
- * compatibility. It will be
- * removed in later versions.
+ * @deprecated This method is deprecated, and left for backward
+ * compatibility. It will be removed in later versions.
*/
template <typename somenumber>
void apply_decomposition (Vector<somenumber> &dst,
const Vector<somenumber> &src) const DEAL_II_DEPRECATED;
/**
- * Apply the incomplete decomposition,
- * i.e. do one forward-backward step
+ * Apply the incomplete decomposition, i.e. do one forward-backward step
* $dst=(LU)^{-1}src$.
*
- * The initialize() function
- * needs to be called before.
+ * The initialize() function needs to be called before.
*/
template <typename somenumber>
void vmult (Vector<somenumber> &dst,
/**
- * Apply the transpose of the
- * incomplete decomposition,
- * i.e. do one forward-backward step
- * $dst=(LU)^{-T}src$.
+ * Apply the transpose of the incomplete decomposition, i.e. do one forward-
+ * backward step $dst=(LU)^{-T}src$.
*
- * The initialize() function
- * needs to be called before.
+ * The initialize() function needs to be called before.
*/
template <typename somenumber>
void Tvmult (Vector<somenumber> &dst,
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
friend class Iterator;
/**
- * Make the SparseMatrix class a friend so that it, in turn, can
- * declare the Reference class a friend.
+ * Make the SparseMatrix class a friend so that it, in turn, can declare
+ * the Reference class a friend.
*/
template <typename> friend class dealii::SparseMatrix;
};
/**
* STL conforming iterator for constant and non-constant matrices.
*
- * The typical use for these iterators is to iterate over the elements of
- * a sparse matrix
- * or over the elements of individual rows. Note that there is no guarantee
- * that the elements of a row are actually traversed in an order in which
- * columns monotonically increase. See the documentation of the
- * SparsityPattern class for more information.
+ * The typical use for these iterators is to iterate over the elements of a
+ * sparse matrix or over the elements of individual rows. Note that there is
+ * no guarantee that the elements of a row are actually traversed in an
+ * order in which columns monotonically increase. See the documentation of
+ * the SparsityPattern class for more information.
*
* The first template argument denotes the underlying numeric type, the
* second the constness of the matrix.
* matrices.
*
* @note This class operates directly on the internal data structures of the
- * SparsityPattern and SparseMatrix classes. As a consequence, some operations
- * are cheap and some are not. In particular, it is cheap to access the column
- * index and the value of an entry pointed to. On the other hand, it is expensive
- * to access the row index (this requires $O(\log(N))$ operations for a
- * matrix with $N$ row). As a consequence, when you design algorithms that
- * use these iterators, it is common practice to not loop over <i>all</i>
- * elements of a sparse matrix at once, but to have an outer loop over
- * all rows and within this loop iterate over the elements of this row.
- * This way, you only ever need to dereference the iterator to obtain
- * the column indices and values whereas the (expensive) lookup of the row index
- * can be avoided by using the loop index instead.
+ * SparsityPattern and SparseMatrix classes. As a consequence, some
+ * operations are cheap and some are not. In particular, it is cheap to
+ * access the column index and the value of an entry pointed to. On the
+ * other hand, it is expensive to access the row index (this requires
+ * $O(\log(N))$ operations for a matrix with $N$ row). As a consequence,
+ * when you design algorithms that use these iterators, it is common
+ * practice to not loop over <i>all</i> elements of a sparse matrix at once,
+ * but to have an outer loop over all rows and within this loop iterate over
+ * the elements of this row. This way, you only ever need to dereference the
+ * iterator to obtain the column indices and values whereas the (expensive)
+ * lookup of the row index can be avoided by using the loop index instead.
*/
template <typename number, bool Constness>
class Iterator
MatrixType;
/**
- * A typedef for the type you get when you dereference an iterator
- * of the current kind.
+ * A typedef for the type you get when you dereference an iterator of the
+ * current kind.
*/
typedef
const Accessor<number,Constness> &value_type;
bool operator > (const Iterator &) const;
/**
- * Return the distance between the current iterator and the argument.
- * The distance is given by how many times one has to apply operator++
- * to the current iterator to get the argument (for a positive return
- * value), or operator-- (for a negative return value).
+ * Return the distance between the current iterator and the argument. The
+ * distance is given by how many times one has to apply operator++ to the
+ * current iterator to get the argument (for a positive return value), or
+ * operator-- (for a negative return value).
*/
int operator - (const Iterator &p) const;
//TODO: Add multithreading to the other vmult functions.
/**
- * Sparse matrix. This class implements the function to store values
- * in the locations of a sparse matrix denoted by a
- * SparsityPattern. The separation of sparsity pattern and values is
- * done since one can store data elements of different type in these
- * locations without the SparsityPattern having to know this, and more
- * importantly one can associate more than one matrix with the same
- * sparsity pattern.
+ * Sparse matrix. This class implements the function to store values in the
+ * locations of a sparse matrix denoted by a SparsityPattern. The separation
+ * of sparsity pattern and values is done since one can store data elements of
+ * different type in these locations without the SparsityPattern having to
+ * know this, and more importantly one can associate more than one matrix with
+ * the same sparsity pattern.
*
* The elements of a SparseMatrix are stored in the same order in which the
- * SparsityPattern class stores its entries.
- * Within each row, elements are generally stored left-to-right in increasing
- * column index order; the exception to this rule is that if the matrix
- * is square (n_rows() == n_columns()), then the diagonal entry is stored
- * as the first element in each row to make operations like applying a
- * Jacobi or SSOR preconditioner faster. As a consequence, if you traverse
- * the elements of a row of a SparseMatrix with the help of iterators into
- * this object (using SparseMatrix::begin and SparseMatrix::end) you
- * will find that the elements are not sorted by column index within each row
- * whenever the matrix is square.
+ * SparsityPattern class stores its entries. Within each row, elements are
+ * generally stored left-to-right in increasing column index order; the
+ * exception to this rule is that if the matrix is square (n_rows() ==
+ * n_columns()), then the diagonal entry is stored as the first element in
+ * each row to make operations like applying a Jacobi or SSOR preconditioner
+ * faster. As a consequence, if you traverse the elements of a row of a
+ * SparseMatrix with the help of iterators into this object (using
+ * SparseMatrix::begin and SparseMatrix::end) you will find that the elements
+ * are not sorted by column index within each row whenever the matrix is
+ * square.
*
* @note Instantiations for this template are provided for <tt>@<float@> and
* @<double@></tt>; others can be generated in application programs (see the
/**
* Declare a type that has holds real-valued numbers with the same precision
* as the template argument to this class. If the template argument of this
- * class is a real data type, then real_type equals the template
- * argument. If the template argument is a std::complex type then real_type
- * equals the type underlying the complex numbers.
+ * class is a real data type, then real_type equals the template argument.
+ * If the template argument is a std::complex type then real_type equals the
+ * type underlying the complex numbers.
*
* This typedef is used to represent the return type of norms.
*/
void symmetrize ();
/**
- * Copy the given matrix to this one. The operation triggers an assertion if the
- * sparsity patterns of the two involved matrices do not point to the same
- * object, since in this case the copy operation is cheaper. Since this
+ * Copy the given matrix to this one. The operation triggers an assertion
+ * if the sparsity patterns of the two involved matrices do not point to the
+ * same object, since in this case the copy operation is cheaper. Since this
* operation is notheless not for free, we do not make it available through
* <tt>operator =</tt>, since this may lead to unwanted usage, e.g. in copy
* arguments to functions, which should really be arguments by reference.
/**
* Return the value of the entry (<i>i,j</i>). This may be an expensive
- * operation and you should always take care where to call this function.
- * In order to avoid abuse, this function throws an exception if the
- * required element does not exist in the matrix.
+ * operation and you should always take care where to call this function. In
+ * order to avoid abuse, this function throws an exception if the required
+ * element does not exist in the matrix.
*
* In case you want a function that returns zero instead (for entries that
* are not in the sparsity pattern of the matrix), use the el() function.
const size_type index) const DEAL_II_DEPRECATED;
/**
- * This is for hackers. Get access to the <i>i</i>th element of this
- * matrix. The elements are stored in a consecutive way, refer to the
+ * This is for hackers. Get access to the <i>i</i>th element of this matrix.
+ * The elements are stored in a consecutive way, refer to the
* SparsityPattern class for more details.
*
* You should use this interface very carefully and only if you are
* Return the $l_1$-norm of the matrix, that is $|M|_1=\max_{\mathrm{all\
* columns\ }j}\sum_{\mathrm{all\ rows\ } i} |M_{ij}|$, (max. sum of
* columns). This is the natural matrix norm that is compatible to the
- * $l_1$-norm for vectors, i.e. $|Mv|_1\leq |M|_1 |v|_1$.
- * (cf. Haemmerlin-Hoffmann: Numerische Mathematik)
+ * $l_1$-norm for vectors, i.e. $|Mv|_1\leq |M|_1 |v|_1$. (cf. Haemmerlin-
+ * Hoffmann: Numerische Mathematik)
*/
real_type l1_norm () const;
* $|M|_\infty=\max_{\mathrm{all\ rows\ }i}\sum_{\mathrm{all\ columns\ }j}
* |M_{ij}|$, (max. sum of rows). This is the natural matrix norm that is
* compatible to the $l_\infty$-norm of vectors, i.e. $|Mv|_\infty \leq
- * |M|_\infty |v|_\infty$. (cf. Haemmerlin-Hoffmann: Numerische
- * Mathematik)
+ * |M|_\infty |v|_\infty$. (cf. Haemmerlin-Hoffmann: Numerische Mathematik)
*/
real_type linfty_norm () const;
const number omega = 1.) const;
/**
- * Apply SSOR preconditioning to <tt>src</tt> with damping
- * <tt>omega</tt>. The optional argument <tt>pos_right_of_diagonal</tt> is
- * supposed to provide an array where each entry specifies the position just
- * right of the diagonal in the global array of nonzeros.
+ * Apply SSOR preconditioning to <tt>src</tt> with damping <tt>omega</tt>.
+ * The optional argument <tt>pos_right_of_diagonal</tt> is supposed to
+ * provide an array where each entry specifies the position just right of
+ * the diagonal in the global array of nonzeros.
*/
template <typename somenumber>
void precondition_SSOR (Vector<somenumber> &dst,
* STL-like iterator with the first entry of the matrix. This is the version
* for constant matrices.
*
- * Note the discussion in the general documentation of this class about
- * the order in which elements are accessed.
+ * Note the discussion in the general documentation of this class about the
+ * order in which elements are accessed.
*/
const_iterator begin () const;
* STL-like iterator with the first entry of the matrix. This is the version
* for non-constant matrices.
*
- * Note the discussion in the general documentation of this class about
- * the order in which elements are accessed.
+ * Note the discussion in the general documentation of this class about the
+ * order in which elements are accessed.
*/
iterator begin ();
* <tt>end(r)</tt>. Note also that the iterator may not be dereferencable in
* that case.
*
- * Note the discussion in the general documentation of this class about
- * the order in which elements are accessed.
+ * Note the discussion in the general documentation of this class about the
+ * order in which elements are accessed.
*/
iterator begin (const size_type r);
//@{
/**
- * Print the matrix to the given stream, using the format
- * <tt>(row,column) value</tt>, i.e. one nonzero entry of the matrix
- * per line. If <tt>across</tt> is true, print all entries on a
- * single line, using the format row,column:value.
+ * Print the matrix to the given stream, using the format <tt>(row,column)
+ * value</tt>, i.e. one nonzero entry of the matrix per line. If
+ * <tt>across</tt> is true, print all entries on a single line, using the
+ * format row,column:value.
*
- * If the argument <tt>diagonal_first</tt> is true, diagonal
- * elements of quadratic matrices are printed first in their row,
- * corresponding to the internal storage scheme. If it is false, the
- * elements in a row are written in ascending column order.
+ * If the argument <tt>diagonal_first</tt> is true, diagonal elements of
+ * quadratic matrices are printed first in their row, corresponding to the
+ * internal storage scheme. If it is false, the elements in a row are
+ * written in ascending column order.
*/
template <class STREAM>
void print (STREAM &out,
void block_write (std::ostream &out) const;
/**
- * Read data that has previously been written by block_write() from a
- * file. This is done using the inverse operations to the above function, so
- * it is reasonably fast because the bitstream is not interpreted except for
- * a few numbers up front.
+ * Read data that has previously been written by block_write() from a file.
+ * This is done using the inverse operations to the above function, so it is
+ * reasonably fast because the bitstream is not interpreted except for a few
+ * numbers up front.
*
* The object is resized on this operation, and all previous contents are
* lost. Note, however, that no checks are performed whether new data and
*/
void block_read (std::istream &in);
//@}
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
template <typename> friend class BlockMatrixBase;
/**
- * Also give access to internal details to the iterator/accessor
- * classes.
+ * Also give access to internal details to the iterator/accessor classes.
*/
template <typename,bool> friend class SparseMatrixIterators::Iterator;
template <typename,bool> friend class SparseMatrixIterators::Accessor;
namespace SparseMatrix
{
/**
- * Perform a vmult using the SparseMatrix
- * data structures, but only using a
- * subinterval for the row indices.
+ * Perform a vmult using the SparseMatrix data structures, but only using
+ * a subinterval for the row indices.
*
- * In the sequential case, this function
- * is called on all rows, in the parallel
- * case it may be called on a subrange,
- * at the discretion of the task
- * scheduler.
+ * In the sequential case, this function is called on all rows, in the
+ * parallel case it may be called on a subrange, at the discretion of the
+ * task scheduler.
*/
template <typename number,
typename InVector>
namespace SparseMatrix
{
/**
- * Perform a vmult using the SparseMatrix
- * data structures, but only using a
- * subinterval for the row indices.
+ * Perform a vmult using the SparseMatrix data structures, but only using
+ * a subinterval for the row indices.
*
- * In the sequential case, this function
- * is called on all rows, in the parallel
- * case it may be called on a subrange,
- * at the discretion of the task
- * scheduler.
+ * In the sequential case, this function is called on all rows, in the
+ * parallel case it may be called on a subrange, at the discretion of the
+ * task scheduler.
*/
template <typename number,
typename InVector>
namespace SparseMatrix
{
/**
- * Perform a vmult using the SparseMatrix
- * data structures, but only using a
- * subinterval for the row indices.
+ * Perform a vmult using the SparseMatrix data structures, but only using
+ * a subinterval for the row indices.
*
- * In the sequential case, this function
- * is called on all rows, in the parallel
- * case it may be called on a subrange,
- * at the discretion of the task
- * scheduler.
+ * In the sequential case, this function is called on all rows, in the
+ * parallel case it may be called on a subrange, at the discretion of the
+ * task scheduler.
*/
template <typename number,
typename InVector,
/**
* Sparse matrix without sparsity pattern.
*
- * Instead of using a pre-assembled sparsity pattern, this matrix
- * builds the pattern on the fly. Filling the matrix may consume more
- * time as with @p SparseMatrix, since large memory movements may be
- * involved. To help optimizing things, an expected row-length may be
- * provided to the constructor, as well as an increment size
- * for rows.
+ * Instead of using a pre-assembled sparsity pattern, this matrix builds the
+ * pattern on the fly. Filling the matrix may consume more time as with @p
+ * SparseMatrix, since large memory movements may be involved. To help
+ * optimizing things, an expected row-length may be provided to the
+ * constructor, as well as an increment size for rows.
*
- * The storage structure: like with the usual sparse matrix, it is
- * attempted to store only non-zero elements. these are stored in a
- * single data array @p data. They are ordered by row and inside each
- * row by column number. Each row is described by its starting point
- * in the data array and its length. These are stored in the
- * @p row_info array, together with additional useful information.
+ * The storage structure: like with the usual sparse matrix, it is attempted
+ * to store only non-zero elements. these are stored in a single data array @p
+ * data. They are ordered by row and inside each row by column number. Each
+ * row is described by its starting point in the data array and its length.
+ * These are stored in the @p row_info array, together with additional useful
+ * information.
*
- * Due to the structure, gaps may occur between rows. Whenever a new
- * entry must be created, an attempt is made to use the gap in its
- * row. If the gap is full, the row must be extended and all
- * subsequent rows must be shifted backwards. This is a very expensive
- * operation and should be avoided as much as possible.
+ * Due to the structure, gaps may occur between rows. Whenever a new entry
+ * must be created, an attempt is made to use the gap in its row. If the gap
+ * is full, the row must be extended and all subsequent rows must be shifted
+ * backwards. This is a very expensive operation and should be avoided as much
+ * as possible.
*
- * This is, where the optimization parameters, provided to the
- * constructor or to the function @p reinit come
- * in. @p default_row_length is the amount of entries that will be
- * allocated for each row on initialization (the actual length of the
- * rows is still zero). This means, that @p default_row_length
- * entries can be added to this row without shifting other rows. If
- * less entries are added, the additional memory will be wasted.
+ * This is, where the optimization parameters, provided to the constructor or
+ * to the function @p reinit come in. @p default_row_length is the amount of
+ * entries that will be allocated for each row on initialization (the actual
+ * length of the rows is still zero). This means, that @p default_row_length
+ * entries can be added to this row without shifting other rows. If less
+ * entries are added, the additional memory will be wasted.
*
- * If the space for a row is not sufficient, then it is enlarged by
- * @p default_increment entries. This way, the subsequent rows are
- * not shifted by single entries very often.
+ * If the space for a row is not sufficient, then it is enlarged by @p
+ * default_increment entries. This way, the subsequent rows are not shifted by
+ * single entries very often.
*
- * Finally, the @p default_reserve allocates extra space at the end
- * of the data array. This space is used whenever a row must be
- * enlarged. Since @p std::vector doubles the capacity every time it
- * must increase it, this value should allow for all the growth needed.
+ * Finally, the @p default_reserve allocates extra space at the end of the
+ * data array. This space is used whenever a row must be enlarged. Since @p
+ * std::vector doubles the capacity every time it must increase it, this value
+ * should allow for all the growth needed.
*
- * Suggested settings: @p default_row_length should be the length of
- * a typical row, for instance the size of the stencil in regular
- * parts of the grid. Then, @p default_increment may be the expected
- * amount of entries added to the row by having one hanging node. This
- * way, a good compromise between memory consumption and speed should
- * be achieved. @p default_reserve should then be an estimate for the
- * number of hanging nodes times @p default_increment.
+ * Suggested settings: @p default_row_length should be the length of a typical
+ * row, for instance the size of the stencil in regular parts of the grid.
+ * Then, @p default_increment may be the expected amount of entries added to
+ * the row by having one hanging node. This way, a good compromise between
+ * memory consumption and speed should be achieved. @p default_reserve should
+ * then be an estimate for the number of hanging nodes times @p
+ * default_increment.
*
- * Letting @p default_increment zero causes an exception whenever a
- * row overflows.
+ * Letting @p default_increment zero causes an exception whenever a row
+ * overflows.
*
- * If the rows are expected to be filled more or less from first to
- * last, using a @p default_row_length of zero may not be such a bad
- * idea.
+ * If the rows are expected to be filled more or less from first to last,
+ * using a @p default_row_length of zero may not be such a bad idea.
*
- * The name of this matrix is in reverence to a publication of the
- * Internal Revenue Service of the United States of America. I hope
- * some other aliens will appreciate it. By the way, the suffix makes
- * sense by pronouncing it the American way.
+ * The name of this matrix is in reverence to a publication of the Internal
+ * Revenue Service of the United States of America. I hope some other aliens
+ * will appreciate it. By the way, the suffix makes sense by pronouncing it
+ * the American way.
*
* @author Guido Kanschat
* @date 2002, 2010
typedef types::global_dof_index size_type;
/**
- * The class for storing the
- * column number of an entry
- * together with its value.
+ * The class for storing the column number of an entry together with its
+ * value.
*/
struct Entry
{
/**
- * Standard constructor. Sets
- * @p column to
- * @p invalid.
+ * Standard constructor. Sets @p column to @p invalid.
*/
Entry();
/**
- * Constructor. Fills column
- * and value.
+ * Constructor. Fills column and value.
*/
Entry (const size_type column,
const number &value);
};
/**
- * Structure for storing
- * information on a matrix
- * row. One object for each row
- * will be stored in the matrix.
+ * Structure for storing information on a matrix row. One object for each
+ * row will be stored in the matrix.
*/
struct RowInfo
{
RowInfo (size_type start = Entry::invalid);
/**
- * Index of first entry of
- * the row in the data field.
+ * Index of first entry of the row in the data field.
*/
size_type start;
/**
- * Number of entries in this
- * row.
+ * Number of entries in this row.
*/
unsigned short length;
/**
- * Position of the diagonal
- * element relative tor the
- * start index.
+ * Position of the diagonal element relative tor the start index.
*/
unsigned short diagonal;
/**
{
public:
/**
- * Constructor. Since we use
- * accessors only for read
- * access, a const matrix
- * pointer is sufficient.
+ * Constructor. Since we use accessors only for read access, a const
+ * matrix pointer is sufficient.
*/
Accessor (const SparseMatrixEZ<number> *matrix,
const size_type row,
const unsigned short index);
/**
- * Row number of the element
- * represented by this
- * object.
+ * Row number of the element represented by this object.
*/
size_type row() const;
/**
- * Index in row of the element
- * represented by this
- * object.
+ * Index in row of the element represented by this object.
*/
unsigned short index() const;
/**
- * Column number of the
- * element represented by
- * this object.
+ * Column number of the element represented by this object.
*/
size_type column() const;
unsigned short a_index;
/**
- * Make enclosing class a
- * friend.
+ * Make enclosing class a friend.
*/
friend class const_iterator;
};
const unsigned short index);
/**
- * Prefix increment. This
- * always returns a valid
- * entry or <tt>end()</tt>.
+ * Prefix increment. This always returns a valid entry or <tt>end()</tt>.
*/
const_iterator &operator++ ();
/**
- * Postfix increment. This
- * always returns a valid
- * entry or <tt>end()</tt>.
+ * Postfix increment. This always returns a valid entry or <tt>end()</tt>.
*/
const_iterator &operator++ (int);
const Accessor *operator-> () const;
/**
- * Comparison. True, if
- * both iterators point to
- * the same matrix
- * position.
+ * Comparison. True, if both iterators point to the same matrix position.
*/
bool operator == (const const_iterator &) const;
/**
bool operator != (const const_iterator &) const;
/**
- * Comparison
- * operator. Result is true
- * if either the first row
- * number is smaller or if
- * the row numbers are
- * equal and the first
- * index is smaller.
+ * Comparison operator. Result is true if either the first row number is
+ * smaller or if the row numbers are equal and the first index is smaller.
*/
bool operator < (const const_iterator &) const;
private:
/**
- * Store an object of the
- * accessor class.
+ * Store an object of the accessor class.
*/
Accessor accessor;
/**
- * Make the enclosing class a
- * friend. This is only
- * necessary since icc7
- * otherwise wouldn't allow
- * us to make
- * const_iterator::Accessor a
- * friend, stating that it
- * can't access this class --
- * this is of course bogus,
- * since granting friendship
- * doesn't need access to the
- * class being granted
- * friendship...
+ * Make the enclosing class a friend. This is only necessary since icc7
+ * otherwise wouldn't allow us to make const_iterator::Accessor a friend,
+ * stating that it can't access this class -- this is of course bogus,
+ * since granting friendship doesn't need access to the class being
+ * granted friendship...
*/
};
/**
- * Type of matrix entries. In analogy to
- * the STL container classes.
+ * Type of matrix entries. In analogy to the STL container classes.
*/
typedef number value_type;
*/
//@{
/**
- * Constructor. Initializes an
- * empty matrix of dimension zero
- * times zero.
+ * Constructor. Initializes an empty matrix of dimension zero times zero.
*/
SparseMatrixEZ ();
/**
- * Dummy copy constructor. This
- * is here for use in
- * containers. It may only be
- * called for empty objects.
+ * Dummy copy constructor. This is here for use in containers. It may only
+ * be called for empty objects.
*
- * If you really want to copy a whole
- * matrix, you can do so by using the
- * @p copy_from function.
+ * If you really want to copy a whole matrix, you can do so by using the @p
+ * copy_from function.
*/
SparseMatrixEZ (const SparseMatrixEZ &);
/**
- * Constructor. Generates a
- * matrix of the given size,
- * ready to be filled. The
- * optional parameters
- * @p default_row_length and
- * @p default_increment allow
- * for preallocating
- * memory. Providing these
- * properly is essential for an
- * efficient assembling of the
- * matrix.
+ * Constructor. Generates a matrix of the given size, ready to be filled.
+ * The optional parameters @p default_row_length and @p default_increment
+ * allow for preallocating memory. Providing these properly is essential for
+ * an efficient assembling of the matrix.
*/
explicit SparseMatrixEZ (const size_type n_rows,
const size_type n_columns,
const unsigned int default_increment = 1);
/**
- * Destructor. Free all memory, but do not
- * release the memory of the sparsity
- * structure.
+ * Destructor. Free all memory, but do not release the memory of the
+ * sparsity structure.
*/
~SparseMatrixEZ ();
/**
- * Pseudo operator only copying
- * empty objects.
+ * Pseudo operator only copying empty objects.
*/
SparseMatrixEZ<number> &operator = (const SparseMatrixEZ<number> &);
/**
- * This operator assigns a scalar to
- * a matrix. Since this does usually
- * not make much sense (should we set
- * all matrix entries to this value?
- * Only the nonzero entries of the
- * sparsity pattern?), this operation
- * is only allowed if the actual
- * value to be assigned is zero. This
- * operator only exists to allow for
- * the obvious notation
- * <tt>matrix=0</tt>, which sets all
- * elements of the matrix to zero,
- * but keep the sparsity pattern
- * previously used.
+ * This operator assigns a scalar to a matrix. Since this does usually not
+ * make much sense (should we set all matrix entries to this value? Only the
+ * nonzero entries of the sparsity pattern?), this operation is only allowed
+ * if the actual value to be assigned is zero. This operator only exists to
+ * allow for the obvious notation <tt>matrix=0</tt>, which sets all elements
+ * of the matrix to zero, but keep the sparsity pattern previously used.
*/
SparseMatrixEZ<number> &operator = (const double d);
/**
- * Reinitialize the sparse matrix
- * to the dimensions provided.
- * The matrix will have no
- * entries at this point. The
- * optional parameters
- * @p default_row_length,
- * @p default_increment and
- * @p reserve allow
- * for preallocating
- * memory. Providing these
- * properly is essential for an
- * efficient assembling of the
- * matrix.
+ * Reinitialize the sparse matrix to the dimensions provided. The matrix
+ * will have no entries at this point. The optional parameters @p
+ * default_row_length, @p default_increment and @p reserve allow for
+ * preallocating memory. Providing these properly is essential for an
+ * efficient assembling of the matrix.
*/
void reinit (const size_type n_rows,
const size_type n_columns,
size_type reserve = 0);
/**
- * Release all memory and return
- * to a state just like after
- * having called the default
- * constructor. It also forgets
- * its sparsity pattern.
+ * Release all memory and return to a state just like after having called
+ * the default constructor. It also forgets its sparsity pattern.
*/
void clear ();
//@}
*/
//@{
/**
- * Return whether the object is
- * empty. It is empty if
- * both dimensions are zero.
+ * Return whether the object is empty. It is empty if both dimensions are
+ * zero.
*/
bool empty () const;
/**
- * Return the dimension of the
- * image space. To remember: the
- * matrix is of dimension
- * $m \times n$.
+ * Return the dimension of the image space. To remember: the matrix is of
+ * dimension $m \times n$.
*/
size_type m () const;
/**
- * Return the dimension of the
- * range space. To remember: the
- * matrix is of dimension
- * $m \times n$.
+ * Return the dimension of the range space. To remember: the matrix is of
+ * dimension $m \times n$.
*/
size_type n () const;
/**
- * Return the number of entries
- * in a specific row.
+ * Return the number of entries in a specific row.
*/
size_type get_row_length (const size_type row) const;
/**
- * Return the number of nonzero
- * elements of this matrix.
+ * Return the number of nonzero elements of this matrix.
*/
size_type n_nonzero_elements () const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
/**
- * Print statistics. If @p full
- * is @p true, prints a
- * histogram of all existing row
- * lengths and allocated row
- * lengths. Otherwise, just the
- * relation of allocated and used
- * entries is shown.
+ * Print statistics. If @p full is @p true, prints a histogram of all
+ * existing row lengths and allocated row lengths. Otherwise, just the
+ * relation of allocated and used entries is shown.
*/
template <class STREAM>
void print_statistics (STREAM &s, bool full = false);
/**
* Compute numbers of entries.
*
- * In the first three arguments,
- * this function returns the
- * number of entries used,
- * allocated and reserved by this
- * matrix.
+ * In the first three arguments, this function returns the number of entries
+ * used, allocated and reserved by this matrix.
*
- * If the final argument is true,
- * the number of entries in each
- * line is printed as well.
+ * If the final argument is true, the number of entries in each line is
+ * printed as well.
*/
void compute_statistics (size_type &used,
size_type &allocated,
*/
//@{
/**
- * Set the element <tt>(i,j)</tt> to
- * @p value. Allocates the entry,
- * if it does not exist and
- * @p value is non-zero.
- * If <tt>value</tt> is not a
- * finite number an exception
- * is thrown.
- */
+ * Set the element <tt>(i,j)</tt> to @p value. Allocates the entry, if it
+ * does not exist and @p value is non-zero. If <tt>value</tt> is not a
+ * finite number an exception is thrown.
+ */
void set (const size_type i, const size_type j,
const number value);
/**
- * Add @p value to the element
- * <tt>(i,j)</tt>. Allocates the entry
- * if it does not exist. Filters
- * out zeroes automatically.
- * If <tt>value</tt> is not a
- * finite number an exception
- * is thrown.
+ * Add @p value to the element <tt>(i,j)</tt>. Allocates the entry if it
+ * does not exist. Filters out zeroes automatically. If <tt>value</tt> is
+ * not a finite number an exception is thrown.
*/
void add (const size_type i,
const size_type j,
const number value);
/**
- * Add all elements given in a
- * FullMatrix<double> into sparse
- * matrix locations given by
- * <tt>indices</tt>. In other words,
- * this function adds the elements in
- * <tt>full_matrix</tt> to the
- * respective entries in calling
- * matrix, using the local-to-global
- * indexing specified by
- * <tt>indices</tt> for both the rows
- * and the columns of the
- * matrix. This function assumes a
- * quadratic sparse matrix and a
- * quadratic full_matrix, the usual
- * situation in FE calculations.
+ * Add all elements given in a FullMatrix<double> into sparse matrix
+ * locations given by <tt>indices</tt>. In other words, this function adds
+ * the elements in <tt>full_matrix</tt> to the respective entries in calling
+ * matrix, using the local-to-global indexing specified by <tt>indices</tt>
+ * for both the rows and the columns of the matrix. This function assumes a
+ * quadratic sparse matrix and a quadratic full_matrix, the usual situation
+ * in FE calculations.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> can be
- * used to specify whether zero
- * values should be added anyway or
- * these should be filtered away and
- * only non-zero data is added. The
- * default value is <tt>true</tt>,
- * i.e., zero values won't be added
- * into the matrix.
+ * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+ * whether zero values should be added anyway or these should be filtered
+ * away and only non-zero data is added. The default value is <tt>true</tt>,
+ * i.e., zero values won't be added into the matrix.
*/
template <typename number2>
void add (const std::vector<size_type> &indices,
const bool elide_zero_values = true);
/**
- * Same function as before, but now
- * including the possibility to use
- * rectangular full_matrices and
- * different local-to-global indexing
- * on rows and columns, respectively.
+ * Same function as before, but now including the possibility to use
+ * rectangular full_matrices and different local-to-global indexing on rows
+ * and columns, respectively.
*/
template <typename number2>
void add (const std::vector<size_type> &row_indices,
const bool elide_zero_values = true);
/**
- * Set several elements in the
- * specified row of the matrix with
- * column indices as given by
- * <tt>col_indices</tt> to the
- * respective value.
+ * Set several elements in the specified row of the matrix with column
+ * indices as given by <tt>col_indices</tt> to the respective value.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> can be
- * used to specify whether zero
- * values should be added anyway or
- * these should be filtered away and
- * only non-zero data is added. The
- * default value is <tt>true</tt>,
- * i.e., zero values won't be added
- * into the matrix.
+ * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+ * whether zero values should be added anyway or these should be filtered
+ * away and only non-zero data is added. The default value is <tt>true</tt>,
+ * i.e., zero values won't be added into the matrix.
*/
template <typename number2>
void add (const size_type row,
const bool elide_zero_values = true);
/**
- * Add an array of values given by
- * <tt>values</tt> in the given
- * global matrix row at columns
- * specified by col_indices in the
- * sparse matrix.
+ * Add an array of values given by <tt>values</tt> in the given global
+ * matrix row at columns specified by col_indices in the sparse matrix.
*
- * The optional parameter
- * <tt>elide_zero_values</tt> can be
- * used to specify whether zero
- * values should be added anyway or
- * these should be filtered away and
- * only non-zero data is added. The
- * default value is <tt>true</tt>,
- * i.e., zero values won't be added
- * into the matrix.
+ * The optional parameter <tt>elide_zero_values</tt> can be used to specify
+ * whether zero values should be added anyway or these should be filtered
+ * away and only non-zero data is added. The default value is <tt>true</tt>,
+ * i.e., zero values won't be added into the matrix.
*/
template <typename number2>
void add (const size_type row,
const bool col_indices_are_sorted = false);
/**
- * Copy the given matrix to this
- * one. The operation throws an
- * error if the sparsity patterns
- * of the two involved matrices
- * do not point to the same
- * object, since in this case the
- * copy operation is
- * cheaper. Since this operation
- * is notheless not for free, we
- * do not make it available
- * through <tt>operator =</tt>, since
- * this may lead to unwanted
- * usage, e.g. in copy arguments
- * to functions, which should
- * really be arguments by
- * reference.
+ * Copy the given matrix to this one. The operation throws an error if the
+ * sparsity patterns of the two involved matrices do not point to the same
+ * object, since in this case the copy operation is cheaper. Since this
+ * operation is notheless not for free, we do not make it available through
+ * <tt>operator =</tt>, since this may lead to unwanted usage, e.g. in copy
+ * arguments to functions, which should really be arguments by reference.
*
- * The source matrix may be a matrix
- * of arbitrary type, as long as its
- * data type is convertible to the
- * data type of this matrix.
+ * The source matrix may be a matrix of arbitrary type, as long as its data
+ * type is convertible to the data type of this matrix.
*
- * The function returns a reference to
- * @p this.
+ * The function returns a reference to @p this.
*/
template <class MATRIX>
SparseMatrixEZ<number> &
copy_from (const MATRIX &source);
/**
- * Add @p matrix scaled by
- * @p factor to this matrix.
+ * Add @p matrix scaled by @p factor to this matrix.
*
- * The source matrix may be a
- * matrix of arbitrary type, as
- * long as its data type is
- * convertible to the data type
- * of this matrix and it has the
+ * The source matrix may be a matrix of arbitrary type, as long as its data
+ * type is convertible to the data type of this matrix and it has the
* standard @p const_iterator.
*/
template <class MATRIX>
*/
//@{
/**
- * Return the value of the entry
- * (i,j). This may be an
- * expensive operation and you
- * should always take care where
- * to call this function. In
- * order to avoid abuse, this
- * function throws an exception
- * if the required element does
- * not exist in the matrix.
+ * Return the value of the entry (i,j). This may be an expensive operation
+ * and you should always take care where to call this function. In order to
+ * avoid abuse, this function throws an exception if the required element
+ * does not exist in the matrix.
*
- * In case you want a function
- * that returns zero instead (for
- * entries that are not in the
- * sparsity pattern of the
- * matrix), use the @p el
- * function.
+ * In case you want a function that returns zero instead (for entries that
+ * are not in the sparsity pattern of the matrix), use the @p el function.
*/
number operator () (const size_type i,
const size_type j) const;
/**
- * Return the value of the entry
- * (i,j). Returns zero for all
- * non-existing entries.
+ * Return the value of the entry (i,j). Returns zero for all non-existing
+ * entries.
*/
number el (const size_type i,
const size_type j) const;
*/
//@{
/**
- * Matrix-vector multiplication:
- * let $dst = M*src$ with $M$
- * being this matrix.
+ * Matrix-vector multiplication: let $dst = M*src$ with $M$ being this
+ * matrix.
*/
template <typename somenumber>
void vmult (Vector<somenumber> &dst,
const Vector<somenumber> &src) const;
/**
- * Matrix-vector multiplication:
- * let $dst = M^T*src$ with $M$
- * being this matrix. This
- * function does the same as
- * @p vmult but takes the
- * transposed matrix.
+ * Matrix-vector multiplication: let $dst = M^T*src$ with $M$ being this
+ * matrix. This function does the same as @p vmult but takes the transposed
+ * matrix.
*/
template <typename somenumber>
void Tvmult (Vector<somenumber> &dst,
const Vector<somenumber> &src) const;
/**
- * Adding Matrix-vector
- * multiplication. Add $M*src$ on
- * $dst$ with $M$ being this
- * matrix.
+ * Adding Matrix-vector multiplication. Add $M*src$ on $dst$ with $M$ being
+ * this matrix.
*/
template <typename somenumber>
void vmult_add (Vector<somenumber> &dst,
const Vector<somenumber> &src) const;
/**
- * Adding Matrix-vector
- * multiplication. Add $M^T*src$
- * to $dst$ with $M$ being this
- * matrix. This function does the
- * same as @p vmult_add but takes
+ * Adding Matrix-vector multiplication. Add $M^T*src$ to $dst$ with $M$
+ * being this matrix. This function does the same as @p vmult_add but takes
* the transposed matrix.
*/
template <typename somenumber>
*/
//@{
/**
- * Apply the Jacobi
- * preconditioner, which
- * multiplies every element of
- * the @p src vector by the
- * inverse of the respective
- * diagonal element and
- * multiplies the result with the
- * damping factor @p omega.
+ * Apply the Jacobi preconditioner, which multiplies every element of the @p
+ * src vector by the inverse of the respective diagonal element and
+ * multiplies the result with the damping factor @p omega.
*/
template <typename somenumber>
void precondition_Jacobi (Vector<somenumber> &dst,
const number omega = 1.) const;
/**
- * Apply SSOR preconditioning to
- * @p src.
+ * Apply SSOR preconditioning to @p src.
*/
template <typename somenumber>
void precondition_SSOR (Vector<somenumber> &dst,
const std::vector<std::size_t> &pos_right_of_diagonal = std::vector<std::size_t>()) const;
/**
- * Apply SOR preconditioning matrix to @p src.
- * The result of this method is
+ * Apply SOR preconditioning matrix to @p src. The result of this method is
* $dst = (om D - L)^{-1} src$.
*/
template <typename somenumber>
const number om = 1.) const;
/**
- * Apply transpose SOR preconditioning matrix to @p src.
- * The result of this method is
- * $dst = (om D - U)^{-1} src$.
+ * Apply transpose SOR preconditioning matrix to @p src. The result of this
+ * method is $dst = (om D - U)^{-1} src$.
*/
template <typename somenumber>
void precondition_TSOR (Vector<somenumber> &dst,
const number om = 1.) const;
/**
- * Add the matrix @p A
- * conjugated by @p B, that is,
- * $B A B^T$ to this object. If
- * the parameter @p transpose is
- * true, compute $B^T A B$.
+ * Add the matrix @p A conjugated by @p B, that is, $B A B^T$ to this
+ * object. If the parameter @p transpose is true, compute $B^T A B$.
*
- * This function requires that
- * @p B has a @p const_iterator
- * traversing all matrix entries
- * and that @p A has a function
- * <tt>el(i,j)</tt> for access to a
- * specific entry.
+ * This function requires that @p B has a @p const_iterator traversing all
+ * matrix entries and that @p A has a function <tt>el(i,j)</tt> for access
+ * to a specific entry.
*/
template <class MATRIXA, class MATRIXB>
void conjugate_add (const MATRIXA &A,
*/
//@{
/**
- * STL-like iterator with the
- * first existing entry.
+ * STL-like iterator with the first existing entry.
*/
const_iterator begin () const;
const_iterator end () const;
/**
- * STL-like iterator with the
- * first entry of row @p r. If
- * this row is empty, the result
- * is <tt>end(r)</tt>, which does NOT
- * point into row @p r..
+ * STL-like iterator with the first entry of row @p r. If this row is empty,
+ * the result is <tt>end(r)</tt>, which does NOT point into row @p r..
*/
const_iterator begin (const size_type r) const;
/**
- * Final iterator of row
- * @p r. The result may be
- * different from <tt>end()</tt>!
+ * Final iterator of row @p r. The result may be different from
+ * <tt>end()</tt>!
*/
const_iterator end (const size_type r) const;
//@}
*/
//@{
/**
- * Print the matrix to the given
- * stream, using the format
- * <tt>(line,col) value</tt>, i.e. one
- * nonzero entry of the matrix
- * per line.
+ * Print the matrix to the given stream, using the format <tt>(line,col)
+ * value</tt>, i.e. one nonzero entry of the matrix per line.
*/
void print (std::ostream &out) const;
/**
- * Print the matrix in the usual
- * format, i.e. as a matrix and
- * not as a list of nonzero
- * elements. For better
- * readability, elements not in
- * the matrix are displayed as
- * empty space, while matrix
- * elements which are explicitly
- * set to zero are displayed as
- * such.
+ * Print the matrix in the usual format, i.e. as a matrix and not as a list
+ * of nonzero elements. For better readability, elements not in the matrix
+ * are displayed as empty space, while matrix elements which are explicitly
+ * set to zero are displayed as such.
*
- * The parameters allow for a
- * flexible setting of the output
- * format: @p precision and
- * @p scientific are used to
- * determine the number format,
- * where @p scientific = @p false
- * means fixed point notation. A
- * zero entry for @p width makes
- * the function compute a width,
- * but it may be changed to a
- * positive value, if output is
- * crude.
+ * The parameters allow for a flexible setting of the output format: @p
+ * precision and @p scientific are used to determine the number format,
+ * where @p scientific = @p false means fixed point notation. A zero entry
+ * for @p width makes the function compute a width, but it may be changed to
+ * a positive value, if output is crude.
*
- * Additionally, a character for
- * an empty value may be
- * specified.
+ * Additionally, a character for an empty value may be specified.
*
- * Finally, the whole matrix can
- * be multiplied with a common
- * denominator to produce more
- * readable output, even
- * integers.
+ * Finally, the whole matrix can be multiplied with a common denominator to
+ * produce more readable output, even integers.
*
- * This function
- * may produce @em large amounts of
- * output if applied to a large matrix!
+ * This function may produce @em large amounts of output if applied to a
+ * large matrix!
*/
void print_formatted (std::ostream &out,
const unsigned int precision = 3,
const double denominator = 1.) const;
/**
- * Write the data of this object
- * in binary mode to a file.
+ * Write the data of this object in binary mode to a file.
*
- * Note that this binary format
- * is platform dependent.
+ * Note that this binary format is platform dependent.
*/
void block_write (std::ostream &out) const;
/**
- * Read data that has previously
- * been written by
- * @p block_write.
+ * Read data that has previously been written by @p block_write.
*
- * The object is resized on this
- * operation, and all previous
- * contents are lost.
+ * The object is resized on this operation, and all previous contents are
+ * lost.
*
- * A primitive form of error
- * checking is performed which
- * will recognize the bluntest
- * attempts to interpret some
- * data as a vector stored
- * bitwise to a file, but not
- * more.
+ * A primitive form of error checking is performed which will recognize the
+ * bluntest attempts to interpret some data as a vector stored bitwise to a
+ * file, but not more.
*/
void block_read (std::istream &in);
//@}
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception for missing diagonal entry.
//@}
private:
/**
- * Find an entry and return a
- * const pointer. Return a
- * zero-pointer if the entry does
- * not exist.
+ * Find an entry and return a const pointer. Return a zero-pointer if the
+ * entry does not exist.
*/
const Entry *locate (const size_type row,
const size_type col) const;
/**
- * Find an entry and return a
- * writable pointer. Return a
- * zero-pointer if the entry does
- * not exist.
+ * Find an entry and return a writable pointer. Return a zero-pointer if the
+ * entry does not exist.
*/
Entry *locate (const size_type row,
const size_type col);
const size_type col);
/**
- * Version of @p vmult which only
- * performs its actions on the
- * region defined by
- * <tt>[begin_row,end_row)</tt>. This
- * function is called by @p vmult
- * in the case of enabled
- * multithreading.
+ * Version of @p vmult which only performs its actions on the region defined
+ * by <tt>[begin_row,end_row)</tt>. This function is called by @p vmult in
+ * the case of enabled multithreading.
*/
template <typename somenumber>
void threaded_vmult (Vector<somenumber> &dst,
const size_type end_row) const;
/**
- * Version of
- * @p matrix_norm_square which
- * only performs its actions on
- * the region defined by
- * <tt>[begin_row,end_row)</tt>. This
- * function is called by
- * @p matrix_norm_square in the
- * case of enabled
- * multithreading.
+ * Version of @p matrix_norm_square which only performs its actions on the
+ * region defined by <tt>[begin_row,end_row)</tt>. This function is called
+ * by @p matrix_norm_square in the case of enabled multithreading.
*/
template <typename somenumber>
void threaded_matrix_norm_square (const Vector<somenumber> &v,
somenumber *partial_sum) const;
/**
- * Version of
- * @p matrix_scalar_product which
- * only performs its actions on
- * the region defined by
- * <tt>[begin_row,end_row)</tt>. This
- * function is called by
- * @p matrix_scalar_product in the
- * case of enabled
- * multithreading.
+ * Version of @p matrix_scalar_product which only performs its actions on
+ * the region defined by <tt>[begin_row,end_row)</tt>. This function is
+ * called by @p matrix_scalar_product in the case of enabled multithreading.
*/
template <typename somenumber>
void threaded_matrix_scalar_product (const Vector<somenumber> &u,
somenumber *partial_sum) const;
/**
- * Number of columns. This is
- * used to check vector
- * dimensions only.
+ * Number of columns. This is used to check vector dimensions only.
*/
size_type n_columns;
*/
/**
- * Modified incomplete Cholesky (MIC(0)) preconditioner. This class
- * conforms to the state and usage specification in
- * SparseLUDecomposition.
+ * Modified incomplete Cholesky (MIC(0)) preconditioner. This class conforms
+ * to the state and usage specification in SparseLUDecomposition.
*
*
* <h3>The decomposition</h3>
*
* Let a sparse matrix $A$ be in the form $A = - L - U + D$, where $-L$ and
* $-U$ are strictly lower and upper triangular matrices. The MIC(0)
- * decomposition of the matrix $A$ is defined by $B = (X-L)X^(-1)(X-U)$,
- * where $X$ is a diagonal matrix, defined by the condition $\text{rowsum}(A) =
+ * decomposition of the matrix $A$ is defined by $B = (X-L)X^(-1)(X-U)$, where
+ * $X$ is a diagonal matrix, defined by the condition $\text{rowsum}(A) =
* \text{rowsum}(B)$.
*
- * @author Stephen "Cheffo" Kolaroff, 2002, unified interface: Ralf
- * Hartmann 2003.
+ * @author Stephen "Cheffo" Kolaroff, 2002, unified interface: Ralf Hartmann
+ * 2003.
*/
template <typename number>
class SparseMIC : public SparseLUDecomposition<number>
typedef types::global_dof_index size_type;
/**
- * Constructor. Does nothing, so
- * you have to call @p decompose
- * sometimes afterwards.
+ * Constructor. Does nothing, so you have to call @p decompose sometimes
+ * afterwards.
*/
SparseMIC ();
/**
* @deprecated This method is deprecated, and left for backward
- * compatibility. It will be removed in later versions. Instead,
- * pass the sparsity pattern that you want used for the
- * decomposition in the AdditionalData structure.
+ * compatibility. It will be removed in later versions. Instead, pass the
+ * sparsity pattern that you want used for the decomposition in the
+ * AdditionalData structure.
*/
SparseMIC (const SparsityPattern &sparsity) DEAL_II_DEPRECATED;
virtual ~SparseMIC();
/**
- * Deletes all member
- * variables. Leaves the class in
- * the state that it had directly
- * after calling the constructor
+ * Deletes all member variables. Leaves the class in the state that it had
+ * directly after calling the constructor
*/
virtual void clear();
/**
- * Make the @p AdditionalData
- * type in the base class
- * accessible to this class as
- * well.
+ * Make the @p AdditionalData type in the base class accessible to this
+ * class as well.
*/
typedef
typename SparseLUDecomposition<number>::AdditionalData
AdditionalData;
/**
- * @deprecated This method is deprecated, and
- * left for backward
- * compatibility. It will be
- * removed in later versions.
+ * @deprecated This method is deprecated, and left for backward
+ * compatibility. It will be removed in later versions.
*/
void reinit (const SparsityPattern &sparsity) DEAL_II_DEPRECATED;
/**
- * Perform the incomplete LU
- * factorization of the given
- * matrix.
+ * Perform the incomplete LU factorization of the given matrix.
*
- * This function needs to be
- * called before an object of
- * this class is used as
- * preconditioner.
+ * This function needs to be called before an object of this class is used
+ * as preconditioner.
*
- * For more details about
- * possible parameters, see the
- * class documentation of
- * SparseLUDecomposition and the
- * documentation of the
- * @p SparseLUDecomposition::AdditionalData
- * class.
+ * For more details about possible parameters, see the class documentation
+ * of SparseLUDecomposition and the documentation of the @p
+ * SparseLUDecomposition::AdditionalData class.
*
- * According to the
- * @p parameters, this function
- * creates a new SparsityPattern
- * or keeps the previous sparsity
- * or takes the sparsity given by
- * the user to @p data. Then,
- * this function performs the MIC
+ * According to the @p parameters, this function creates a new
+ * SparsityPattern or keeps the previous sparsity or takes the sparsity
+ * given by the user to @p data. Then, this function performs the MIC
* decomposition.
*
- * After this function is called
- * the preconditioner is ready to
- * be used.
+ * After this function is called the preconditioner is ready to be used.
*/
template <typename somenumber>
void initialize (const SparseMatrix<somenumber> &matrix,
const AdditionalData ¶meters = AdditionalData());
/**
- * @deprecated This method is deprecated, and left for backward
- * compability. It will be removed in later versions. Use
- * initialize() instead.
+ * @deprecated This method is deprecated, and left for backward compability.
+ * It will be removed in later versions. Use initialize() instead.
*/
template <typename somenumber>
void decompose (const SparseMatrix<somenumber> &matrix,
const double strengthen_diagonal=0.) DEAL_II_DEPRECATED;
/**
- * Apply the incomplete decomposition,
- * i.e. do one forward-backward step
+ * Apply the incomplete decomposition, i.e. do one forward-backward step
* $dst=(LU)^{-1}src$.
*
- * Call @p initialize before
- * calling this function.
+ * Call @p initialize before calling this function.
*/
template <typename somenumber>
void vmult (Vector<somenumber> &dst,
const Vector<somenumber> &src) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
//@}
private:
/**
- * Values of the computed
- * diagonal.
+ * Values of the computed diagonal.
*/
std::vector<number> diag;
/**
- * Inverses of the the diagonal:
- * precomputed for faster vmult.
+ * Inverses of the the diagonal: precomputed for faster vmult.
*/
std::vector<number> inv_diag;
/**
- * Values of the computed "inner
- * sums", i.e. per-row sums of
- * the elements laying on the
- * right side of the diagonal.
+ * Values of the computed "inner sums", i.e. per-row sums of the elements
+ * laying on the right side of the diagonal.
*/
std::vector<number> inner_sums;
/**
- * Compute the row-th "inner
- * sum".
+ * Compute the row-th "inner sum".
*/
number get_rowsum (const size_type row) const;
};
*/
/**
- * Point-wise Vanka preconditioning.
- * This class does Vanka preconditioning on a point-wise base.
- * Vanka preconditioners are used for saddle point problems like Stoke's
- * problem or problems arising in optimization where Lagrange multiplier
- * occur and let Netwon's matrix have a zero block. With these matrices the
- * application of Jacobi or Gauss-Seidel methods is impossible, because
- * some diagonal elements are zero in the rows of the Lagrange multiplier.
- * The approach of Vanka is to solve a small (usually indefinite) system
- * of equations for each Langrange multiplie variable (we will also call
- * the pressure in Stokes' equation a Langrange multiplier since it
- * can be interpreted as such).
+ * Point-wise Vanka preconditioning. This class does Vanka preconditioning on
+ * a point-wise base. Vanka preconditioners are used for saddle point problems
+ * like Stoke's problem or problems arising in optimization where Lagrange
+ * multiplier occur and let Netwon's matrix have a zero block. With these
+ * matrices the application of Jacobi or Gauss-Seidel methods is impossible,
+ * because some diagonal elements are zero in the rows of the Lagrange
+ * multiplier. The approach of Vanka is to solve a small (usually indefinite)
+ * system of equations for each Langrange multiplie variable (we will also
+ * call the pressure in Stokes' equation a Langrange multiplier since it can
+ * be interpreted as such).
*
- * Objects of this class are constructed by passing a vector of indices
- * of the degrees of freedom of the Lagrange multiplier. In the actual
- * preconditioning method, these rows are traversed in the order in which
- * the appear in the matrix. Since this is a Gau�-Seidel like procedure,
+ * Objects of this class are constructed by passing a vector of indices of the
+ * degrees of freedom of the Lagrange multiplier. In the actual
+ * preconditioning method, these rows are traversed in the order in which the
+ * appear in the matrix. Since this is a Gau�-Seidel like procedure,
* remember to have a good ordering in advance (for transport dominated
- * problems, Cuthill-McKee algorithms are a good means for this, if points
- * on the inflow boundary are chosen as starting points for the renumbering).
+ * problems, Cuthill-McKee algorithms are a good means for this, if points on
+ * the inflow boundary are chosen as starting points for the renumbering).
*
* For each selected degree of freedom, a local system of equations is built
* by the degree of freedom itself and all other values coupling immediately,
* i.e. the set of degrees of freedom considered for the local system of
* equations for degree of freedom @p i is @p i itself and all @p j such that
* the element <tt>(i,j)</tt> is a nonzero entry in the sparse matrix under
- * consideration. The elements <tt>(j,i)</tt> are not considered. We now pick all
- * matrix entries from rows and columns out of the set of degrees of freedom
- * just described out of the global matrix and put it into a local matrix,
- * which is subsequently inverted. This system may be of different size for
- * each degree of freedom, depending for example on the local neighborhood of
- * the respective node on a computational grid.
+ * consideration. The elements <tt>(j,i)</tt> are not considered. We now pick
+ * all matrix entries from rows and columns out of the set of degrees of
+ * freedom just described out of the global matrix and put it into a local
+ * matrix, which is subsequently inverted. This system may be of different
+ * size for each degree of freedom, depending for example on the local
+ * neighborhood of the respective node on a computational grid.
*
- * The right hand side is built up in the same way, i.e. by copying
- * all entries that coupled with the one under present consideration,
- * but it is augmented by all degrees of freedom coupling with the
- * degrees from the set described above (i.e. the DoFs coupling second
- * order to the present one). The reason for this is, that the local
- * problems to be solved shall have Dirichlet boundary conditions on
- * the second order coupling DoFs, so we have to take them into
- * account but eliminate them before actually solving; this
- * elimination is done by the modification of the right hand side, and
- * in the end these degrees of freedom do not occur in the matrix and
- * solution vector any more at all.
+ * The right hand side is built up in the same way, i.e. by copying all
+ * entries that coupled with the one under present consideration, but it is
+ * augmented by all degrees of freedom coupling with the degrees from the set
+ * described above (i.e. the DoFs coupling second order to the present one).
+ * The reason for this is, that the local problems to be solved shall have
+ * Dirichlet boundary conditions on the second order coupling DoFs, so we have
+ * to take them into account but eliminate them before actually solving; this
+ * elimination is done by the modification of the right hand side, and in the
+ * end these degrees of freedom do not occur in the matrix and solution vector
+ * any more at all.
*
- * This local system is solved and the values are updated into the
- * destination vector.
+ * This local system is solved and the values are updated into the destination
+ * vector.
*
* Remark: the Vanka method is a non-symmetric preconditioning method.
*
*
- * <h3>Example of Use</h3>
- * This little example is taken from a program doing parameter optimization.
- * The Lagrange multiplier is the third component of the finite element
- * used. The system is solved by the GMRES method.
+ * <h3>Example of Use</h3> This little example is taken from a program doing
+ * parameter optimization. The Lagrange multiplier is the third component of
+ * the finite element used. The system is solved by the GMRES method.
* @code
* // tag the Lagrange multiplier variable
* vector<bool> signature(3);
* @endcode
*
*
- * <h4>Implementor's remark</h4>
- * At present, the local matrices are built up such that the degree of freedom
- * associated with the local Lagrange multiplier is the first one. Thus, usually
- * the upper left entry in the local matrix is zero. It is not clear to me (W.B.)
- * whether this might pose some problems in the inversion of the local matrices.
- * Maybe someone would like to check this.
+ * <h4>Implementor's remark</h4> At present, the local matrices are built up
+ * such that the degree of freedom associated with the local Lagrange
+ * multiplier is the first one. Thus, usually the upper left entry in the
+ * local matrix is zero. It is not clear to me (W.B.) whether this might pose
+ * some problems in the inversion of the local matrices. Maybe someone would
+ * like to check this.
*
* @note Instantiations for this template are provided for <tt>@<float@> and
* @<double@></tt>; others can be generated in application programs (see the
typedef types::global_dof_index size_type;
/**
- * Constructor. Gets the matrix
- * for preconditioning and a bit
- * vector with entries @p true for
- * all rows to be updated. A
- * reference to this vector will
- * be stored, so it must persist
- * longer than the Vanka
- * object. The same is true for
- * the matrix.
+ * Constructor. Gets the matrix for preconditioning and a bit vector with
+ * entries @p true for all rows to be updated. A reference to this vector
+ * will be stored, so it must persist longer than the Vanka object. The same
+ * is true for the matrix.
*
- * The matrix @p M which is passed
- * here may or may not be the
- * same matrix for which this
- * object shall act as
- * preconditioner. In particular,
- * it is conceivable that the
- * preconditioner is build up for
- * one matrix once, but is used
- * for subsequent steps in a
- * nonlinear process as well,
- * where the matrix changes in
- * each step slightly.
+ * The matrix @p M which is passed here may or may not be the same matrix
+ * for which this object shall act as preconditioner. In particular, it is
+ * conceivable that the preconditioner is build up for one matrix once, but
+ * is used for subsequent steps in a nonlinear process as well, where the
+ * matrix changes in each step slightly.
*
- * If @p conserve_mem is @p false,
- * then the inverses of the local
- * systems are computed now; if
- * the flag is @p true, then they
- * are computed every time the
- * preconditioner is
- * applied. This saves some
- * memory, but makes
- * preconditioning very
- * slow. Note also, that if the
- * flag is @p false, then the
- * contents of the matrix @p M at
- * the time of calling this
- * constructor are used, while if
- * the flag is @p true, then the
- * values in @p M at the time of
- * preconditioning are used. This
- * may lead to different results,
+ * If @p conserve_mem is @p false, then the inverses of the local systems
+ * are computed now; if the flag is @p true, then they are computed every
+ * time the preconditioner is applied. This saves some memory, but makes
+ * preconditioning very slow. Note also, that if the flag is @p false, then
+ * the contents of the matrix @p M at the time of calling this constructor
+ * are used, while if the flag is @p true, then the values in @p M at the
+ * time of preconditioning are used. This may lead to different results,
* obviously, of @p M changes.
*
- * The parameter @p n_threads
- * determines how many threads
- * shall be used in parallel when
- * building the inverses of the
- * diagonal blocks. This
- * parameter is ignored if not in
- * multithreaded mode.
+ * The parameter @p n_threads determines how many threads shall be used in
+ * parallel when building the inverses of the diagonal blocks. This
+ * parameter is ignored if not in multithreaded mode.
*/
SparseVanka(const SparseMatrix<number> &M,
const std::vector<bool> &selected,
const unsigned int n_threads = multithread_info.n_threads());
/**
- * Destructor.
- * Delete all allocated matrices.
+ * Destructor. Delete all allocated matrices.
*/
~SparseVanka();
/**
- * Do the preconditioning.
- * This function takes the residual
- * in @p src and returns the resulting
- * update vector in @p dst.
+ * Do the preconditioning. This function takes the residual in @p src and
+ * returns the resulting update vector in @p dst.
*/
template<typename number2>
void vmult (Vector<number2> &dst,
protected:
/**
- * Apply the inverses
- * corresponding to those degrees
- * of freedom that have a @p true
- * value in @p dof_mask, to the
- * @p src vector and move the
- * result into @p dst. Actually,
- * only values for allowed
- * indices are written to @p dst,
- * so the application of this
- * function only does what is
- * announced in the general
- * documentation if the given
- * mask sets all values to zero
+ * Apply the inverses corresponding to those degrees of freedom that have a
+ * @p true value in @p dof_mask, to the @p src vector and move the result
+ * into @p dst. Actually, only values for allowed indices are written to @p
+ * dst, so the application of this function only does what is announced in
+ * the general documentation if the given mask sets all values to zero
*
- * The reason for providing the
- * mask anyway is that in derived
- * classes we may want to apply
- * the preconditioner to parts of
- * the matrix only, in order to
- * parallelize the
- * application. Then, it is
- * important to only write to
- * some slices of @p dst, in order
- * to eliminate the dependencies
- * of threads of each other.
+ * The reason for providing the mask anyway is that in derived classes we
+ * may want to apply the preconditioner to parts of the matrix only, in
+ * order to parallelize the application. Then, it is important to only write
+ * to some slices of @p dst, in order to eliminate the dependencies of
+ * threads of each other.
*
- * If a null pointer is passed
- * instead of a pointer to the
- * @p dof_mask (as is the default
- * value), then it is assumed
- * that we shall work on all
- * degrees of freedom. This is
- * then equivalent to calling the
- * function with a
- * <tt>vector<bool>(n_dofs,true)</tt>.
+ * If a null pointer is passed instead of a pointer to the @p dof_mask (as
+ * is the default value), then it is assumed that we shall work on all
+ * degrees of freedom. This is then equivalent to calling the function with
+ * a <tt>vector<bool>(n_dofs,true)</tt>.
*
- * The @p vmult of this class
- * of course calls this function
- * with a null pointer
+ * The @p vmult of this class of course calls this function with a null
+ * pointer
*/
template<typename number2>
void apply_preconditioner (Vector<number2> &dst,
const std::vector<bool> *const dof_mask = 0) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
const bool conserve_mem;
/**
- * Indices of those degrees of
- * freedom that we shall work on.
+ * Indices of those degrees of freedom that we shall work on.
*/
const std::vector<bool> &selected;
/**
- * Number of threads to be used
- * when building the
- * inverses. Only relevant in
+ * Number of threads to be used when building the inverses. Only relevant in
* multithreaded mode.
*/
const unsigned int n_threads;
/**
- * Array of inverse matrices,
- * one for each degree of freedom.
- * Only those elements will be used
- * that are tagged in @p selected.
+ * Array of inverse matrices, one for each degree of freedom. Only those
+ * elements will be used that are tagged in @p selected.
*/
mutable std::vector<SmartPointer<FullMatrix<float>,SparseVanka<number> > > inverses;
/**
- * Compute the inverses of all
- * selected diagonal elements.
+ * Compute the inverses of all selected diagonal elements.
*/
void compute_inverses ();
/**
- * Compute the inverses at
- * positions in the range
- * <tt>[begin,end)</tt>. In
- * non-multithreaded mode,
- * <tt>compute_inverses()</tt> calls
- * this function with the whole
- * range, but in multithreaded
- * mode, several copies of this
+ * Compute the inverses at positions in the range <tt>[begin,end)</tt>. In
+ * non-multithreaded mode, <tt>compute_inverses()</tt> calls this function
+ * with the whole range, but in multithreaded mode, several copies of this
* function are spawned.
*/
void compute_inverses (const size_type begin,
const size_type end);
/**
- * Compute the inverse of the
- * block located at position
- * @p row. Since the vector is
- * used quite often, it is
- * generated only once in the
- * caller of this function and
- * passed to this function which
- * first clears it. Reusing the
- * vector makes the process
- * significantly faster than in
- * the case where this function
- * re-creates it each time.
+ * Compute the inverse of the block located at position @p row. Since the
+ * vector is used quite often, it is generated only once in the caller of
+ * this function and passed to this function which first clears it. Reusing
+ * the vector makes the process significantly faster than in the case where
+ * this function re-creates it each time.
*/
void compute_inverse (const size_type row,
std::vector<size_type> &local_indices);
/**
- * Make the derived class a
- * friend. This seems silly, but
- * is actually necessary, since
- * derived classes can only
- * access non-public members
- * through their @p this
- * pointer, but not access these
- * members as member functions of
- * other objects of the type of
- * this base class (i.e. like
- * <tt>x.f()</tt>, where @p x is an
- * object of the base class, and
- * @p f one of it's non-public
- * member functions).
+ * Make the derived class a friend. This seems silly, but is actually
+ * necessary, since derived classes can only access non-public members
+ * through their @p this pointer, but not access these members as member
+ * functions of other objects of the type of this base class (i.e. like
+ * <tt>x.f()</tt>, where @p x is an object of the base class, and @p f one
+ * of it's non-public member functions).
*
- * Now, in the case of the
- * @p SparseBlockVanka class, we
- * would like to take the address
- * of a function of the base
- * class in order to call it
- * through the multithreading
- * framework, so the derived
- * class has to be a friend.
+ * Now, in the case of the @p SparseBlockVanka class, we would like to take
+ * the address of a function of the base class in order to call it through
+ * the multithreading framework, so the derived class has to be a friend.
*/
template <typename T> friend class SparseBlockVanka;
};
/**
- * Block version of the sparse Vanka preconditioner. This class
- * divides the matrix into blocks and works on the diagonal blocks
- * only, which of course reduces the efficiency as preconditioner, but
- * is perfectly parallelizable. The constructor takes a parameter into
- * how many blocks the matrix shall be subdivided and then lets the
- * underlying class do the work. Division of the matrix is done in
- * several ways which are described in detail below.
+ * Block version of the sparse Vanka preconditioner. This class divides the
+ * matrix into blocks and works on the diagonal blocks only, which of course
+ * reduces the efficiency as preconditioner, but is perfectly parallelizable.
+ * The constructor takes a parameter into how many blocks the matrix shall be
+ * subdivided and then lets the underlying class do the work. Division of the
+ * matrix is done in several ways which are described in detail below.
*
- * This class is probably useless if you don't have a multiprocessor
- * system, since then the amount of work per preconditioning step is
- * the same as for the @p SparseVanka class, but preconditioning
- * properties are worse. On the other hand, if you have a
- * multiprocessor system, the worse preconditioning quality (leading
- * to more iterations of the linear solver) usually is well balanced
- * by the increased speed of application due to the parallelization,
- * leading to an overall decrease in elapsed wall-time for solving
- * your linear system. It should be noted that the quality as
- * preconditioner reduces with growing number of blocks, so there may
- * be an optimal value (in terms of wall-time per linear solve) for
- * the number of blocks.
+ * This class is probably useless if you don't have a multiprocessor system,
+ * since then the amount of work per preconditioning step is the same as for
+ * the @p SparseVanka class, but preconditioning properties are worse. On the
+ * other hand, if you have a multiprocessor system, the worse preconditioning
+ * quality (leading to more iterations of the linear solver) usually is well
+ * balanced by the increased speed of application due to the parallelization,
+ * leading to an overall decrease in elapsed wall-time for solving your linear
+ * system. It should be noted that the quality as preconditioner reduces with
+ * growing number of blocks, so there may be an optimal value (in terms of
+ * wall-time per linear solve) for the number of blocks.
*
- * To facilitate writing portable code, if the number of blocks into
- * which the matrix is to be subdivided, is set to one, then this
- * class acts just like the @p SparseVanka class. You may therefore
- * want to set the number of blocks equal to the number of processors
- * you have.
+ * To facilitate writing portable code, if the number of blocks into which the
+ * matrix is to be subdivided, is set to one, then this class acts just like
+ * the @p SparseVanka class. You may therefore want to set the number of
+ * blocks equal to the number of processors you have.
*
* Note that the parallelization is done if <tt>deal.II</tt> was configured
- * for multithread use and that the number of threads which is spawned
- * equals the number of blocks. This is reasonable since you will not
- * want to set the number of blocks unnecessarily large, since, as
- * mentioned, this reduces the preconditioning properties.
+ * for multithread use and that the number of threads which is spawned equals
+ * the number of blocks. This is reasonable since you will not want to set the
+ * number of blocks unnecessarily large, since, as mentioned, this reduces the
+ * preconditioning properties.
*
*
* <h3>Splitting the matrix into blocks</h3>
*
- * Splitting the matrix into blocks is always done in a way such that
- * the blocks are not necessarily of equal size, but such that the
- * number of selected degrees of freedom for which a local system is
- * to be solved is equal between blocks. The reason for this strategy
- * to subdivision is load-balancing for multithreading. There are
- * several possibilities to actually split the matrix into blocks,
- * which are selected by the flag @p blocking_strategy that is passed
- * to the constructor. By a block, we will in the sequel denote a list
- * of indices of degrees of freedom; the algorithm will work on each
- * block separately, i.e. the solutions of the local systems
- * corresponding to a degree of freedom of one block will only be used
- * to update the degrees of freedom belonging to the same block, but
- * never to update degrees of freedoms of other blocks. A block can be
- * a consecutive list of indices, as in the first alternative below,
- * or a nonconsecutive list of indices. Of course, we assume that the
- * intersection of each two blocks is empty and that the union of all
- * blocks equals the interval <tt>[0,N)</tt>, where @p N is the number of
- * degrees of freedom of the system of equations.
+ * Splitting the matrix into blocks is always done in a way such that the
+ * blocks are not necessarily of equal size, but such that the number of
+ * selected degrees of freedom for which a local system is to be solved is
+ * equal between blocks. The reason for this strategy to subdivision is load-
+ * balancing for multithreading. There are several possibilities to actually
+ * split the matrix into blocks, which are selected by the flag @p
+ * blocking_strategy that is passed to the constructor. By a block, we will in
+ * the sequel denote a list of indices of degrees of freedom; the algorithm
+ * will work on each block separately, i.e. the solutions of the local systems
+ * corresponding to a degree of freedom of one block will only be used to
+ * update the degrees of freedom belonging to the same block, but never to
+ * update degrees of freedoms of other blocks. A block can be a consecutive
+ * list of indices, as in the first alternative below, or a nonconsecutive
+ * list of indices. Of course, we assume that the intersection of each two
+ * blocks is empty and that the union of all blocks equals the interval
+ * <tt>[0,N)</tt>, where @p N is the number of degrees of freedom of the
+ * system of equations.
*
* <ul>
- * <li> @p index_intervals:
- * Here, we chose the blocks to be intervals <tt>[a_i,a_{i+1</tt>)},
- * i.e. consecutive degrees of freedom are usually also within the
- * same block. This is a reasonable strategy, if the degrees of
- * freedom have, for example, be re-numbered using the
- * Cuthill-McKee algorithm, in which spatially neighboring degrees
- * of freedom have neighboring indices. In that case, coupling in
- * the matrix is usually restricted to the vicinity of the diagonal
- * as well, and we can simply cut the matrix into blocks.
+ * <li> @p index_intervals: Here, we chose the blocks to be intervals
+ * <tt>[a_i,a_{i+1</tt>)}, i.e. consecutive degrees of freedom are usually
+ * also within the same block. This is a reasonable strategy, if the degrees
+ * of freedom have, for example, be re-numbered using the Cuthill-McKee
+ * algorithm, in which spatially neighboring degrees of freedom have
+ * neighboring indices. In that case, coupling in the matrix is usually
+ * restricted to the vicinity of the diagonal as well, and we can simply cut
+ * the matrix into blocks.
*
- * The bounds of the intervals, i.e. the @p a_i above, are chosen
- * such that the number of degrees of freedom on which we shall
- * work (i.e. usually the degrees of freedom corresponding to
- * Lagrange multipliers) is about the same in each block; this does
- * not mean, however, that the sizes of the blocks are equal, since
- * the blocks also comprise the other degrees of freedom for which
- * no local system is solved. In the extreme case, consider that
- * all Lagrange multipliers are sorted to the end of the range of
- * DoF indices, then the first block would be very large, since it
- * comprises all other DoFs and some Lagrange multipliers, while
- * all other blocks are rather small and comprise only Langrange
- * multipliers. This strategy therefore does not only depend on the
- * order in which the Lagrange DoFs are sorted, but also on the
- * order in which the other DoFs are sorted. It is therefore
- * necessary to note that this almost renders the capability as
- * preconditioner useless if the degrees of freedom are numbered by
- * component, i.e. all Lagrange multipliers en bloc.
+ * The bounds of the intervals, i.e. the @p a_i above, are chosen such that
+ * the number of degrees of freedom on which we shall work (i.e. usually the
+ * degrees of freedom corresponding to Lagrange multipliers) is about the same
+ * in each block; this does not mean, however, that the sizes of the blocks
+ * are equal, since the blocks also comprise the other degrees of freedom for
+ * which no local system is solved. In the extreme case, consider that all
+ * Lagrange multipliers are sorted to the end of the range of DoF indices,
+ * then the first block would be very large, since it comprises all other DoFs
+ * and some Lagrange multipliers, while all other blocks are rather small and
+ * comprise only Langrange multipliers. This strategy therefore does not only
+ * depend on the order in which the Lagrange DoFs are sorted, but also on the
+ * order in which the other DoFs are sorted. It is therefore necessary to note
+ * that this almost renders the capability as preconditioner useless if the
+ * degrees of freedom are numbered by component, i.e. all Lagrange multipliers
+ * en bloc.
*
- * <li> @p adaptive: This strategy is a bit more clever in cases where
- * the Langrange DoFs are clustered, as in the example above. It
- * works as follows: it first groups the Lagrange DoFs into blocks,
- * using the same strategy as above. However, instead of grouping
- * the other DoFs into the blocks of Lagrange DoFs with nearest DoF
- * index, it decides for each non-Lagrange DoF to put it into the
- * block of Lagrange DoFs which write to this non-Lagrange DoF most
- * often. This makes it possible to even sort the Lagrange DoFs to
- * the end and still associate spatially neighboring non-Lagrange
- * DoFs to the same blocks where the respective Lagrange DoFs are,
- * since they couple to each other while spatially distant DoFs
- * don't couple.
+ * <li> @p adaptive: This strategy is a bit more clever in cases where the
+ * Langrange DoFs are clustered, as in the example above. It works as follows:
+ * it first groups the Lagrange DoFs into blocks, using the same strategy as
+ * above. However, instead of grouping the other DoFs into the blocks of
+ * Lagrange DoFs with nearest DoF index, it decides for each non-Lagrange DoF
+ * to put it into the block of Lagrange DoFs which write to this non-Lagrange
+ * DoF most often. This makes it possible to even sort the Lagrange DoFs to
+ * the end and still associate spatially neighboring non-Lagrange DoFs to the
+ * same blocks where the respective Lagrange DoFs are, since they couple to
+ * each other while spatially distant DoFs don't couple.
*
- * The additional computational effort to sorting the non-Lagrange
- * DoFs is not very large compared with the inversion of the local
- * systems and applying the preconditioner, so this strategy might
- * be reasonable if you want to sort your degrees of freedom by
- * component. If the degrees of freedom are not sorted by
- * component, the results of the both strategies outlined above
- * does not differ much. However, unlike the first strategy, the
- * performance of the second strategy does not deteriorate if the
- * DoFs are renumbered by component.
+ * The additional computational effort to sorting the non-Lagrange DoFs is not
+ * very large compared with the inversion of the local systems and applying
+ * the preconditioner, so this strategy might be reasonable if you want to
+ * sort your degrees of freedom by component. If the degrees of freedom are
+ * not sorted by component, the results of the both strategies outlined above
+ * does not differ much. However, unlike the first strategy, the performance
+ * of the second strategy does not deteriorate if the DoFs are renumbered by
+ * component.
* </ul>
*
*
* <h3>Typical results</h3>
*
- * As a prototypical test case, we use a nonlinear problem from
- * optimization, which leads to a series of saddle point problems,
- * each of which is solved using GMRES with Vanka as
- * preconditioner. The equation had approx. 850 degrees of
- * freedom. With the non-blocked version @p SparseVanka (or
- * @p SparseBlockVanka with <tt>n_blocks==1</tt>), the following numbers of
- * iterations is needed to solver the linear system in each nonlinear
- * step:
+ * As a prototypical test case, we use a nonlinear problem from optimization,
+ * which leads to a series of saddle point problems, each of which is solved
+ * using GMRES with Vanka as preconditioner. The equation had approx. 850
+ * degrees of freedom. With the non-blocked version @p SparseVanka (or @p
+ * SparseBlockVanka with <tt>n_blocks==1</tt>), the following numbers of
+ * iterations is needed to solver the linear system in each nonlinear step:
* @verbatim
* 101 68 64 53 35 21
* @endverbatim
* @verbatim
* 124 88 83 66 44 28
* @endverbatim
- * As can be seen, more iterations are needed. However, in terms of
- * computing time, the first version needs 72 seconds wall time (and
- * 79 seconds CPU time, which is more than wall time since some other
- * parts of the program were parallelized as well), while the second
- * version needed 53 second wall time (and 110 seconds CPU time) on a
- * four processor machine. The total time is in both cases dominated
- * by the linear solvers. In this case, it is therefore worth while
- * using the blocked version of the preconditioner if wall time is
- * more important than CPU time.
+ * As can be seen, more iterations are needed. However, in terms of computing
+ * time, the first version needs 72 seconds wall time (and 79 seconds CPU
+ * time, which is more than wall time since some other parts of the program
+ * were parallelized as well), while the second version needed 53 second wall
+ * time (and 110 seconds CPU time) on a four processor machine. The total time
+ * is in both cases dominated by the linear solvers. In this case, it is
+ * therefore worth while using the blocked version of the preconditioner if
+ * wall time is more important than CPU time.
*
- * The results with the block version above were obtained with the
- * first blocking strategy and the degrees of freedom were not
- * numbered by component. Using the second strategy does not much
- * change the numbers of iterations (at most by one in each step) and
- * they also do not change when the degrees of freedom are sorted
- * by component, while the first strategy significantly deteriorated.
+ * The results with the block version above were obtained with the first
+ * blocking strategy and the degrees of freedom were not numbered by
+ * component. Using the second strategy does not much change the numbers of
+ * iterations (at most by one in each step) and they also do not change when
+ * the degrees of freedom are sorted by component, while the first strategy
+ * significantly deteriorated.
*
* @author Wolfgang Bangerth, 2000
*/
typedef types::global_dof_index size_type;
/**
- * Enumeration of the different
- * methods by which the DoFs are
- * distributed to the blocks on
- * which we are to work.
+ * Enumeration of the different methods by which the DoFs are distributed to
+ * the blocks on which we are to work.
*/
enum BlockingStrategy
{
};
/**
- * Constructor. Pass all
- * arguments except for
- * @p n_blocks to the base class.
+ * Constructor. Pass all arguments except for @p n_blocks to the base class.
*/
SparseBlockVanka (const SparseMatrix<number> &M,
const std::vector<bool> &selected,
const Vector<number2> &src) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
const unsigned int n_blocks;
/**
- * In this field, we precompute
- * for each block which degrees
- * of freedom belong to it. Thus,
- * if <tt>dof_masks[i][j]==true</tt>,
- * then DoF @p j belongs to block
- * @p i. Of course, no other
- * <tt>dof_masks[l][j]</tt> may be
- * @p true for <tt>l!=i</tt>. This
- * computation is done in the
- * constructor, to avoid
- * recomputing each time the
- * preconditioner is called.
+ * In this field, we precompute for each block which degrees of freedom
+ * belong to it. Thus, if <tt>dof_masks[i][j]==true</tt>, then DoF @p j
+ * belongs to block @p i. Of course, no other <tt>dof_masks[l][j]</tt> may
+ * be @p true for <tt>l!=i</tt>. This computation is done in the
+ * constructor, to avoid recomputing each time the preconditioner is called.
*/
std::vector<std::vector<bool> > dof_masks;
/**
- * Compute the contents of the
- * field @p dof_masks. This
- * function is called from the
- * constructor.
+ * Compute the contents of the field @p dof_masks. This function is called
+ * from the constructor.
*/
void compute_dof_masks (const SparseMatrix<number> &M,
const std::vector<bool> &selected,
typedef types::global_dof_index size_type;
/**
- * Accessor class for iterators into sparsity patterns. This class is
- * also the base class for both const and non-const accessor classes
- * into sparse matrices.
+ * Accessor class for iterators into sparsity patterns. This class is also
+ * the base class for both const and non-const accessor classes into sparse
+ * matrices.
*
* Note that this class only allows read access to elements, providing their
* row and column number (or alternatively the index within the complete
size_type row () const;
/**
- * Index within the current row of the element represented by this object. This function
- * can only be called for entries for which is_valid_entry() is true.
+ * Index within the current row of the element represented by this object.
+ * This function can only be called for entries for which is_valid_entry()
+ * is true.
*/
size_type index () const;
* entries are valid. However, before compression, the sparsity pattern
* allocated some memory to be used while still adding new nonzero
* entries; if you create iterators in this phase of the sparsity
- * pattern's lifetime, you will iterate over elements that are not
- * valid. If this is so, then this function will return false.
+ * pattern's lifetime, you will iterate over elements that are not valid.
+ * If this is so, then this function will return false.
*/
bool is_valid_entry () const;
/**
* STL conforming iterator walking over the elements of a sparsity pattern.
*
- * The typical use for these iterators is to iterate over the elements of
- * a sparsity pattern (or, since they also serve as the basis for iterating
- * over the elements of an associated matrix, over the elements of a sparse matrix)
- * or over the elements of individual rows. Note that there is no guarantee
- * that the elements of a row are actually traversed in an order in which
- * columns monotonically increase. See the documentation of the
+ * The typical use for these iterators is to iterate over the elements of a
+ * sparsity pattern (or, since they also serve as the basis for iterating
+ * over the elements of an associated matrix, over the elements of a sparse
+ * matrix) or over the elements of individual rows. Note that there is no
+ * guarantee that the elements of a row are actually traversed in an order
+ * in which columns monotonically increase. See the documentation of the
* SparsityPattern class for more information.
*
* @note This class operates directly on the internal data structures of the
* matrix with $N$ row). As a consequence, when you design algorithms that
* use these iterators, it is common practice to not loop over <i>all</i>
* elements of a sparsity pattern at once, but to have an outer loop over
- * all rows and within this loop iterate over the elements of this row.
- * This way, you only ever need to dereference the iterator to obtain
- * the column indices whereas the (expensive) lookup of the row index
- * can be avoided by using the loop index instead.
+ * all rows and within this loop iterate over the elements of this row. This
+ * way, you only ever need to dereference the iterator to obtain the column
+ * indices whereas the (expensive) lookup of the row index can be avoided by
+ * using the loop index instead.
*/
class Iterator
{
bool operator < (const Iterator &) const;
/**
- * Return the distance between the current iterator and the argument.
- * The distance is given by how many times one has to apply operator++
- * to the current iterator to get the argument (for a positive return
- * value), or operator-- (for a negative return value).
+ * Return the distance between the current iterator and the argument. The
+ * distance is given by how many times one has to apply operator++ to the
+ * current iterator to get the argument (for a positive return value), or
+ * operator-- (for a negative return value).
*/
int operator - (const Iterator &p) const;
/**
- * Structure representing the sparsity pattern of a sparse matrix.
- * This class is an example of the "static" type of @ref Sparsity.
- * It uses the compressed row storage (CSR) format to store data.
+ * Structure representing the sparsity pattern of a sparse matrix. This class
+ * is an example of the "static" type of @ref Sparsity. It uses the compressed
+ * row storage (CSR) format to store data.
*
* The elements of a SparsityPattern, corresponding to the places where
* SparseMatrix objects can store nonzero entries, are stored row-by-row.
* Within each row, elements are generally stored left-to-right in increasing
- * column index order; the exception to this rule is that if the matrix
- * is square (n_rows() == n_columns()), then the diagonal entry is stored
- * as the first element in each row to make operations like applying a
- * Jacobi or SSOR preconditioner faster. As a consequence, if you traverse
- * the elements of a row of a SparsityPattern with the help of iterators into
- * this object (using SparsityPattern::begin and SparsityPattern::end) you
- * will find that the elements are not sorted by column index within each row
- * whenever the matrix is square (the first item will be the diagonal, followed
- * by the other entries sorted by column index).
+ * column index order; the exception to this rule is that if the matrix is
+ * square (n_rows() == n_columns()), then the diagonal entry is stored as the
+ * first element in each row to make operations like applying a Jacobi or SSOR
+ * preconditioner faster. As a consequence, if you traverse the elements of a
+ * row of a SparsityPattern with the help of iterators into this object (using
+ * SparsityPattern::begin and SparsityPattern::end) you will find that the
+ * elements are not sorted by column index within each row whenever the matrix
+ * is square (the first item will be the diagonal, followed by the other
+ * entries sorted by column index).
*
- * @note While this class forms the basis upon which SparseMatrix
- * objects base their storage format, and thus plays a central role in
- * setting up linear systems, it is rarely set up directly due to the
- * way it stores its information. Rather, one typically goes through
- * an intermediate format first, see for example the step-2 tutorial
- * program as well as the documentation module @ref Sparsity.
+ * @note While this class forms the basis upon which SparseMatrix objects base
+ * their storage format, and thus plays a central role in setting up linear
+ * systems, it is rarely set up directly due to the way it stores its
+ * information. Rather, one typically goes through an intermediate format
+ * first, see for example the step-2 tutorial program as well as the
+ * documentation module @ref Sparsity.
*
* @author Wolfgang Bangerth, Guido Kanschat and others
*/
static const size_type invalid_entry = numbers::invalid_size_type;
/**
- * @name Construction and setup
- * Constructors, destructor; functions initializing, copying and filling an object.
+ * @name Construction and setup Constructors, destructor; functions
+ * initializing, copying and filling an object.
*/
// @{
/**
/**
* Initialize a rectangular matrix.
*
- * @arg m number of rows
- * @arg n number of columns
- * @arg max_per_row maximum number of nonzero entries per row
+ * @arg m number of rows @arg n number of columns @arg max_per_row maximum
+ * number of nonzero entries per row
*/
SparsityPattern (const size_type m,
const size_type n,
/**
* Initialize a rectangular matrix.
*
- * @arg m number of rows
- * @arg n number of columns
- * @arg row_lengths possible number of nonzero entries for each row. This
- * vector must have one entry for each row.
+ * @arg m number of rows @arg n number of columns @arg row_lengths possible
+ * number of nonzero entries for each row. This vector must have one entry
+ * for each row.
*/
SparsityPattern (const size_type m,
const size_type n,
/**
* Initialize a quadratic matrix.
*
- * @arg m number of rows and columns
- * @arg row_lengths possible number of nonzero entries for each row. This
- * vector must have one entry for each row.
+ * @arg m number of rows and columns @arg row_lengths possible number of
+ * nonzero entries for each row. This vector must have one entry for each
+ * row.
*/
SparsityPattern (const size_type m,
const std::vector<unsigned int> &row_lengths);
*
* This constructs objects intended for the application of the ILU(n)-method
* or other incomplete decompositions. Therefore, additional to the
- * original entry structure, space for <tt>extra_off_diagonals</tt>
- * side-diagonals is provided on both sides of the main diagonal.
+ * original entry structure, space for <tt>extra_off_diagonals</tt> side-
+ * diagonals is provided on both sides of the main diagonal.
*
* <tt>max_per_row</tt> is the maximum number of nonzero elements per row
* which this structure is to hold. It is assumed that this number is
* will usually want to give the same number as you gave for
* <tt>original</tt> plus the number of side diagonals times two. You may
* however give a larger value if you wish to add further nonzero entries
- * for the decomposition based on other criteria than their being on
- * side-diagonals.
+ * for the decomposition based on other criteria than their being on side-
+ * diagonals.
*
* This function requires that <tt>original</tt> refers to a quadratic
* matrix structure. It must be compressed. The matrix structure is not
/**
* Copy data from an object of type CompressedSparsityPattern,
* CompressedSetSparsityPattern or CompressedSimpleSparsityPattern. Although
- * not a compressed sparsity pattern, this function is also instantiated
- * if the argument is of type SparsityPattern (i.e., the current class).
+ * not a compressed sparsity pattern, this function is also instantiated if
+ * the argument is of type SparsityPattern (i.e., the current class).
* Previous content of this object is lost, and the sparsity pattern is in
* compressed mode afterwards.
*/
* iterator can be used to walk over all nonzero entries of the sparsity
* pattern.
*
- * Note the discussion in the general documentation of this class about
- * the order in which elements are accessed.
+ * Note the discussion in the general documentation of this class about the
+ * order in which elements are accessed.
*/
iterator begin () const;
*/
// @{
/**
- * Test for equality of two SparsityPatterns.
+ * Test for equality of two SparsityPatterns.
*/
bool operator == (const SparsityPattern &) const;
* complexity of this function is <i>log(m)</i> if the sparsity pattern is
* compressed.
*
- * @note This function is not cheap since it has to search through all
- * of the elements of the given row <tt>i</tt> to find whether index
- * <tt>j</tt> exists. Thus, it is more expensive than necessary in cases
- * where you want to loop over all of the nonzero elements of this
- * sparsity pattern (or of a sparse matrix associated with it) or of a
- * single row. In such cases, it is more efficient to use iterators over
- * the elements of the sparsity pattern or of the sparse matrix.
+ * @note This function is not cheap since it has to search through all of
+ * the elements of the given row <tt>i</tt> to find whether index <tt>j</tt>
+ * exists. Thus, it is more expensive than necessary in cases where you want
+ * to loop over all of the nonzero elements of this sparsity pattern (or of
+ * a sparse matrix associated with it) or of a single row. In such cases, it
+ * is more efficient to use iterators over the elements of the sparsity
+ * pattern or of the sparse matrix.
*/
size_type operator() (const size_type i,
const size_type j) const;
* i.e. <tt>column_number(row,0)==row</tt>.
*
* If the sparsity pattern is already compressed, then (except for the
- * diagonal element), the entries are sorted by columns,
- * i.e. <tt>column_number(row,i)</tt> <tt><</tt>
- * <tt>column_number(row,i+1)</tt>.
+ * diagonal element), the entries are sorted by columns, i.e.
+ * <tt>column_number(row,i)</tt> <tt><</tt> <tt>column_number(row,i+1)</tt>.
*/
size_type column_number (const size_type row,
const unsigned int index) const;
void block_write (std::ostream &out) const;
/**
- * Read data that has previously been written by block_write() from a
- * file. This is done using the inverse operations to the above function, so
- * it is reasonably fast because the bitstream is not interpreted except for
- * a few numbers up front.
+ * Read data that has previously been written by block_write() from a file.
+ * This is done using the inverse operations to the above function, so it is
+ * reasonably fast because the bitstream is not interpreted except for a few
+ * numbers up front.
*
* The object is resized on this operation, and all previous contents are
* lost.
/**
* Initialize a rectangular matrix.
*
- * @arg m number of rows
- * @arg n number of columns
- * @arg max_per_row maximum number of nonzero entries per row
- * @arg optimize_diagonal This parameter is ignored.
+ * @arg m number of rows @arg n number of columns @arg max_per_row maximum
+ * number of nonzero entries per row @arg optimize_diagonal This parameter
+ * is ignored.
*
- * @deprecated Use the constructor without the last argument since
- * it is ignored.
+ * @deprecated Use the constructor without the last argument since it is
+ * ignored.
*/
SparsityPattern (const size_type m,
const size_type n,
/**
* Initialize a rectangular matrix.
*
- * @arg m number of rows
- * @arg n number of columns
- * @arg row_lengths possible number of nonzero entries for each row. This
- * vector must have one entry for each row.
- * @arg optimize_diagonal This argument is ignored.
+ * @arg m number of rows @arg n number of columns @arg row_lengths possible
+ * number of nonzero entries for each row. This vector must have one entry
+ * for each row. @arg optimize_diagonal This argument is ignored.
*
- * @deprecated Use the constructor without the last argument since
- * it is ignored.
+ * @deprecated Use the constructor without the last argument since it is
+ * ignored.
*/
SparsityPattern (const size_type m,
const size_type n,
/**
* Initialize a quadratic matrix.
*
- * @arg m number of rows and columns
- * @arg row_lengths possible number of nonzero entries for each row. This
- * vector must have one entry for each row.
- * @arg optimize_diagonal This argument is ignored.
+ * @arg m number of rows and columns @arg row_lengths possible number of
+ * nonzero entries for each row. This vector must have one entry for each
+ * row. @arg optimize_diagonal This argument is ignored.
*
- * @deprecated Use the constructor without the last argument since
- * it is ignored.
+ * @deprecated Use the constructor without the last argument since it is
+ * ignored.
*/
SparsityPattern (const size_type m,
const std::vector<unsigned int> &row_lengths,
* optimized access in relaxation methods of SparseMatrix.
*
* @deprecated The last argument of this function is ignored. Use the
- * version of this function without the last argument.
+ * version of this function without the last argument.
*/
void reinit (const size_type m,
const size_type n,
* Same as above, but with a VectorSlice argument instead.
*
* @deprecated The last argument of this function is ignored. Use the
- * version of this function without the last argument.
+ * version of this function without the last argument.
*/
void reinit (const size_type m,
const size_type n,
* function.
*
* @deprecated The last argument of this function is ignored. Use the
- * version of this function without the last argument.
+ * version of this function without the last argument.
*/
void reinit (const size_type m,
const size_type n,
* iterators that point to such pairs.
*
* @deprecated The last argument of this function is ignored. Use the
- * version of this function without the last argument.
+ * version of this function without the last argument.
*/
template <typename ForwardIterator>
void copy_from (const size_type n_rows,
/**
* Copy data from an object of type CompressedSparsityPattern,
- * CompressedSetSparsityPattern or CompressedSimpleSparsityPattern.
- * Previous content of this object is lost, and the sparsity pattern is in
- * compressed mode afterwards.
+ * CompressedSetSparsityPattern or CompressedSimpleSparsityPattern. Previous
+ * content of this object is lost, and the sparsity pattern is in compressed
+ * mode afterwards.
*
* @deprecated The last argument of this function is ignored. Use the
- * version of this function without the last argument.
+ * version of this function without the last argument.
*/
template <typename CompressedSparsityType>
void copy_from (const CompressedSparsityType &csp,
* compressed mode afterwards.
*
* @deprecated The last argument of this function is ignored. Use the
- * version of this function without the last argument.
+ * version of this function without the last argument.
*/
template <typename number>
void copy_from (const FullMatrix<number> &matrix,
* <tt>end(r)</tt>. Note also that the iterator may not be dereferencable in
* that case.
*
- * @deprecated Use the iterators provided by the begin() and end()
- * functions instead.
+ * @deprecated Use the iterators provided by the begin() and end() functions
+ * instead.
*/
row_iterator row_begin (const size_type r) const DEAL_II_DEPRECATED;
* particular the case if it is the end iterator for the last row of a
* matrix.
*
- * @deprecated Use the iterators provided by the begin() and end()
- * functions instead.
+ * @deprecated Use the iterators provided by the begin() and end() functions
+ * instead.
*/
row_iterator row_end (const size_type r) const DEAL_II_DEPRECATED;
* Determine whether the matrix uses the special convention for quadratic
* matrices that the diagonal entries are stored first in each row.
*
- * @deprecated The function always returns true if the matrix is
- * square and false if it is not.
+ * @deprecated The function always returns true if the matrix is square and
+ * false if it is not.
*/
bool optimize_diagonal () const DEAL_II_DEPRECATED;
// @}
BOOST_SERIALIZATION_SPLIT_MEMBER()
- /** @addtogroup Exceptions
- * @name Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions @name Exceptions
+ * @{
+ */
/**
* You tried to add an element to a row, but there was no space left.
*/
friend class ChunkSparsityPattern;
/**
- * Also give access to internal details to the iterator/accessor
- * classes.
+ * Also give access to internal details to the iterator/accessor classes.
*/
friend class SparsityPatternIterators::Iterator;
friend class SparsityPatternIterators::Accessor;
* patterns, such as renumbering rows and columns (or degrees of freedom if
* you want) according to the connectivity, or partitioning degrees of
* freedom.
-*/
+ */
namespace SparsityTools
{
/**
* These algorithms have one major drawback: they require a good starting
* node, i.e. node that will have number zero in the output array. A
* starting node forming the initial level of nodes can thus be given by the
- * user, e.g. by exploiting knowledge of the actual topology of the
- * domain. It is also possible to give several starting indices, which may
- * be used to simulate a simple upstream numbering (by giving the inflow
- * nodes as starting values) or to make preconditioning faster (by letting
- * the Dirichlet boundary indices be starting points).
+ * user, e.g. by exploiting knowledge of the actual topology of the domain.
+ * It is also possible to give several starting indices, which may be used
+ * to simulate a simple upstream numbering (by giving the inflow nodes as
+ * starting values) or to make preconditioning faster (by letting the
+ * Dirichlet boundary indices be starting points).
*
* If no starting index is given, one is chosen automatically, namely one
* with the smallest coordination number (the coordination number is the
/**
* similar to the function above, but includes support for
- * BlockCompressedSimpleSparsityPattern.
- * @p owned_set_per_cpu is typically DoFHandler::locally_owned_dofs_per_processor
- * and @p myrange are locally_relevant_dofs.
+ * BlockCompressedSimpleSparsityPattern. @p owned_set_per_cpu is typically
+ * DoFHandler::locally_owned_dofs_per_processor and @p myrange are
+ * locally_relevant_dofs.
*/
template <class CSP_t>
void distribute_sparsity_pattern(CSP_t &csp,
}
/**
- *@}
+ * @}
*/
DEAL_II_NAMESPACE_CLOSE
*/
/**
- * This class is a wrapper to the @p Vector class which allows to swap
- * out the data to a file and reload it later on. It handles the
- * management of the name of the file where the data is to be stored
- * temporarily and removes the file is necessary at the end of the
- * lifetime of the vector.
+ * This class is a wrapper to the @p Vector class which allows to swap out the
+ * data to a file and reload it later on. It handles the management of the
+ * name of the file where the data is to be stored temporarily and removes the
+ * file is necessary at the end of the lifetime of the vector.
*
- * There are functions to swap the data to a file, and to reload
- * it. There is also a function @p alert that can be used to signal to
- * an object of this class that the data will be needed shortly, so
- * the object can initiate that the data be loaded already. While in
- * non-multithreading mode, this function has no effect since @p reload
- * has to be called afterwards anyway. On the other hand, in
- * multithreading mode, the data is preloaded in the background using
- * a thread on its own, and may already be available at the time when
- * @p reload is called. If it is not available, @p reload waits until
- * the detached thread has loaded the data.
+ * There are functions to swap the data to a file, and to reload it. There is
+ * also a function @p alert that can be used to signal to an object of this
+ * class that the data will be needed shortly, so the object can initiate that
+ * the data be loaded already. While in non-multithreading mode, this function
+ * has no effect since @p reload has to be called afterwards anyway. On the
+ * other hand, in multithreading mode, the data is preloaded in the background
+ * using a thread on its own, and may already be available at the time when @p
+ * reload is called. If it is not available, @p reload waits until the
+ * detached thread has loaded the data.
*
* @note Instantiations for this template are provided for <tt>@<float@> and
* @<double@></tt>; others can be generated in application programs (see the
{
public:
/**
- * Constructor. Does nothing
- * apart from calling the
- * constructor of the underlying
- * class.
+ * Constructor. Does nothing apart from calling the constructor of the
+ * underlying class.
*/
SwappableVector ();
/**
- * Copy constructor. Copies the
- * data if @p v contains some, but
- * does not do so if @p v is empty
- * or has its data swapped
- * out. In the latter case, warn
- * about that. In particular do
- * not take over ownership of any
- * files that @p v might own.
+ * Copy constructor. Copies the data if @p v contains some, but does not do
+ * so if @p v is empty or has its data swapped out. In the latter case, warn
+ * about that. In particular do not take over ownership of any files that @p
+ * v might own.
*/
SwappableVector (const SwappableVector &v);
/**
- * Destructor. If this class
- * still owns a file to which
- * temporary data was stored,
- * then it is deleted.
+ * Destructor. If this class still owns a file to which temporary data was
+ * stored, then it is deleted.
*/
virtual ~SwappableVector ();
/**
- * Copy operator. Do mostly the
- * same as the copy constructor
- * does; if necessary, delete
- * temporary files owned by this
- * object at first.
+ * Copy operator. Do mostly the same as the copy constructor does; if
+ * necessary, delete temporary files owned by this object at first.
*/
SwappableVector &operator = (const SwappableVector &);
/**
- * Swap out the data of this
- * vector to the file of which
- * the name is given. It is
- * assumed that the file can be
- * overwritten if it exists, and
- * ownership of this file is
- * assumed by this object. The
- * file is deleted either upon
- * calling @p kill_file, or on
- * destruction of this object.
+ * Swap out the data of this vector to the file of which the name is given.
+ * It is assumed that the file can be overwritten if it exists, and
+ * ownership of this file is assumed by this object. The file is deleted
+ * either upon calling @p kill_file, or on destruction of this object.
*
- * The content of the vector is
- * cleared and it size is reset
- * to zero.
+ * The content of the vector is cleared and it size is reset to zero.
*
- * If this object owns another
- * file, for example when
- * @p swap_out but no @p kill_file
- * has previously been called,
- * then that is deleted first.
+ * If this object owns another file, for example when @p swap_out but no @p
+ * kill_file has previously been called, then that is deleted first.
*/
void swap_out (const std::string &filename);
/**
- * Reload the data of this vector
- * from the file to which it has
- * been stored previously using
- * @p swap_out. Since the file is
- * not deleted after reloading,
- * you can call @p reload multiple
- * times, in between you may do
- * everything with the vector,
- * including changing its size.
+ * Reload the data of this vector from the file to which it has been stored
+ * previously using @p swap_out. Since the file is not deleted after
+ * reloading, you can call @p reload multiple times, in between you may do
+ * everything with the vector, including changing its size.
*
- * This function resets the size
- * of the vector to the number of
- * elements there were upon
- * calling @p swap_out before.
+ * This function resets the size of the vector to the number of elements
+ * there were upon calling @p swap_out before.
*/
void reload ();
/**
- * Calling this function can be
- * used to alert this vector that
- * it will need to reload its
- * data soon. It has no effect if
- * the data of the vector is
- * already present, and it has no
- * effect in single-thread mode
- * as well, but in multithread
- * mode, it spawns another thread
- * that reads the data in
- * parallel to the usual
- * execution of the program, such
- * that when @p reload is called,
- * the data may eventually be
- * available already. It might
- * therefore be wirthwhile to
- * call this function some time
- * in advance, if you know that
- * the data will be needed, and
- * loading takes some time, for
- * instance if the file to which
- * the data was written is not in
- * a local tmp directory.
+ * Calling this function can be used to alert this vector that it will need
+ * to reload its data soon. It has no effect if the data of the vector is
+ * already present, and it has no effect in single-thread mode as well, but
+ * in multithread mode, it spawns another thread that reads the data in
+ * parallel to the usual execution of the program, such that when @p reload
+ * is called, the data may eventually be available already. It might
+ * therefore be wirthwhile to call this function some time in advance, if
+ * you know that the data will be needed, and loading takes some time, for
+ * instance if the file to which the data was written is not in a local tmp
+ * directory.
*
- * Calling this function multiple
- * times before calling @p reload
- * is allowed and has no effect
- * for subsequent calls. Calling
- * this function while the data
- * is still or already in memory
- * is allowed and has no effect.
+ * Calling this function multiple times before calling @p reload is allowed
+ * and has no effect for subsequent calls. Calling this function while the
+ * data is still or already in memory is allowed and has no effect.
*/
void alert ();
/**
- * Remove the file to which the
- * data has been stored the last
- * time. After this, the object
- * does not own any file any
- * more, so of course you can't
+ * Remove the file to which the data has been stored the last time. After
+ * this, the object does not own any file any more, so of course you can't
* call @p reload no more.
*
- * If this object does not own a
- * file, for example since
- * @p swap_out was not called, or
- * because @p kill_file has been
- * called previously, then this
+ * If this object does not own a file, for example since @p swap_out was not
+ * called, or because @p kill_file has been called previously, then this
* function does nothing.
*/
void kill_file ();
/**
- * Return the name of the file to
- * which the data was stored the
- * last time you called
- * @p swap_out. If @p swap_out was
- * not called, or if in between
- * @p kill_file was called, then
- * the filename is an empty
- * string.
+ * Return the name of the file to which the data was stored the last time
+ * you called @p swap_out. If @p swap_out was not called, or if in between
+ * @p kill_file was called, then the filename is an empty string.
*/
const std::string &get_filename () const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception.
*/
//@}
private:
/**
- * Name of the file to which data
- * was swapped out. If no data is
- * presently swapped out
- * (i.e. before calling
- * @p swap_out and after
- * @p kill_file), the string is
- * empty, indicating no ownership
- * of files.
+ * Name of the file to which data was swapped out. If no data is presently
+ * swapped out (i.e. before calling @p swap_out and after @p kill_file), the
+ * string is empty, indicating no ownership of files.
*/
std::string filename;
/**
- * If in multithread mode, then
- * the @p alert function has
- * functionality, but needs to
- * coordinate with the @p reload
- * function. This is done through
- * the following lock.
+ * If in multithread mode, then the @p alert function has functionality, but
+ * needs to coordinate with the @p reload function. This is done through the
+ * following lock.
*
- * If not in MT mode, then the
- * class used here is empty, and
- * we can as well get away
- * with it.
+ * If not in MT mode, then the class used here is empty, and we can as well
+ * get away with it.
*/
Threads::Mutex lock;
/**
- * Flag by which the @p alert
- * function signifies that the
- * data has been preloaded
- * already. This flag is always
- * @p false in non-MT mode.
+ * Flag by which the @p alert function signifies that the data has been
+ * preloaded already. This flag is always @p false in non-MT mode.
*/
bool data_is_preloaded;
/**
- * Internal function that
- * actually reloads the
- * vector. Called from @p reload
+ * Internal function that actually reloads the vector. Called from @p reload
* and @p alert.
*
- * The parameter specifies
- * whether the function shall set
- * @p data_is_preloaded or
- * not. The calling functions
- * can't sometimes do this
- * themselves, since they call
- * this function detached, so
- * this function has to signal
- * success itself if this is
- * required.
+ * The parameter specifies whether the function shall set @p
+ * data_is_preloaded or not. The calling functions can't sometimes do this
+ * themselves, since they call this function detached, so this function has
+ * to signal success itself if this is required.
*/
void reload_vector (const bool set_flag);
};
/**
- * The transpose of a given matrix. This auxiliary class swaps the
- * effect ov vmult() and Tvmult() as well as vmult_add() and
- * Tvmult_add().
+ * The transpose of a given matrix. This auxiliary class swaps the effect ov
+ * vmult() and Tvmult() as well as vmult_add() and Tvmult_add().
*
* The implementation is analogous to the class PointerMatrix.
*
- * @note The transposed matrix is never actually assembled. Instead,
- * only the matrix vector multiplication is performed in a transposed
- * way.
+ * @note The transposed matrix is never actually assembled. Instead, only the
+ * matrix vector multiplication is performed in a transposed way.
*
* @ingroup Matrix2
* @author Guido Kanschat, 2006
{
public:
/**
- * Constructor. The pointer in the
- * argument is stored in this
- * class. As usual, the lifetime of
- * <tt>*M</tt> must be longer than the
- * one of the PointerMatrix.
+ * Constructor. The pointer in the argument is stored in this class. As
+ * usual, the lifetime of <tt>*M</tt> must be longer than the one of the
+ * PointerMatrix.
*
- * If <tt>M</tt> is zero, no
- * matrix is stored.
+ * If <tt>M</tt> is zero, no matrix is stored.
*/
TransposeMatrix (const MATRIX *M=0);
/**
- * Constructor. The name argument
- * is used to identify the
- * SmartPointer for this object.
+ * Constructor. The name argument is used to identify the SmartPointer for
+ * this object.
*/
TransposeMatrix(const char *name);
/**
- * Constructor. <tt>M</tt> points
- * to a matrix which must live
- * longer than the
- * TransposeMatrix. The name
- * argument is used to identify
- * the SmartPointer for this
- * object.
+ * Constructor. <tt>M</tt> points to a matrix which must live longer than
+ * the TransposeMatrix. The name argument is used to identify the
+ * SmartPointer for this object.
*/
TransposeMatrix(const MATRIX *M,
const char *name);
virtual void clear();
/**
- * Return whether the object is
- * empty.
+ * Return whether the object is empty.
*/
bool empty () const;
/**
- * Assign a new matrix
- * pointer. Deletes the old pointer
- * and releases its matrix.
- * @see SmartPointer
+ * Assign a new matrix pointer. Deletes the old pointer and releases its
+ * matrix. @see SmartPointer
*/
const TransposeMatrix &operator= (const MATRIX *M);
const VECTOR &src) const;
/**
- * Matrix-vector product, adding to
- * <tt>dst</tt>.
+ * Matrix-vector product, adding to <tt>dst</tt>.
*/
virtual void vmult_add (VECTOR &dst,
const VECTOR &src) const;
/**
- * Tranposed matrix-vector product,
- * adding to <tt>dst</tt>.
+ * Tranposed matrix-vector product, adding to <tt>dst</tt>.
*/
virtual void Tvmult_add (VECTOR &dst,
const VECTOR &src) const;
/**
- * A quadratic tridiagonal matrix. That is, a matrix where all entries
- * are zero, except the diagonal and the entries left and right of it.
+ * A quadratic tridiagonal matrix. That is, a matrix where all entries are
+ * zero, except the diagonal and the entries left and right of it.
*
- * The matrix has an additional symmetric mode, in which case only the
- * upper triangle of the matrix is stored and mirrored to the lower
- * one for matrix vector operations.
+ * The matrix has an additional symmetric mode, in which case only the upper
+ * triangle of the matrix is stored and mirrored to the lower one for matrix
+ * vector operations.
*
* @ingroup Matrix1
* @author Guido Kanschat, 2005, 2006
-*/
+ */
template<typename number>
class TridiagonalMatrix
{
* @name Constructors and initalization.
*/
/**
- * Constructor generating an
- * empty matrix of dimension
- * <tt>n</tt>.
+ * Constructor generating an empty matrix of dimension <tt>n</tt>.
*/
TridiagonalMatrix(size_type n = 0,
bool symmetric = false);
/**
- * Reinitialize the matrix to a
- * new size and reset all entries
- * to zero. The symmetry
- * properties may be set as well.
+ * Reinitialize the matrix to a new size and reset all entries to zero. The
+ * symmetry properties may be set as well.
*/
void reinit(size_type n,
bool symmetric = false);
//@{
/**
- * Number of rows of this matrix.
- * To remember: this matrix is an
- * <i>m x m</i>-matrix.
+ * Number of rows of this matrix. To remember: this matrix is an <i>m x
+ * m</i>-matrix.
*/
size_type m () const;
/**
- * Number of columns of this matrix.
- * To remember: this matrix is an
- * <i>n x n</i>-matrix.
+ * Number of columns of this matrix. To remember: this matrix is an <i>n x
+ * n</i>-matrix.
*/
size_type n () const;
/**
- * Return whether the matrix
- * contains only elements with
- * value zero. This function is
- * mainly for internal
- * consistency checks and should
- * seldom be used when not in
- * debug mode since it uses quite
- * some time.
+ * Return whether the matrix contains only elements with value zero. This
+ * function is mainly for internal consistency checks and should seldom be
+ * used when not in debug mode since it uses quite some time.
*/
bool all_zero () const;
///@name Element access
//@{
/**
- * Read-only access to a
- * value. This is restricted to
- * the case where <i>|i-j| <=
- * 1</i>.
+ * Read-only access to a value. This is restricted to the case where
+ * <i>|i-j| <= 1</i>.
*/
number operator()(size_type i, size_type j) const;
/**
- * Read-write access to a
- * value. This is restricted to
- * the case where <i>|i-j| <=
- * 1</i>.
+ * Read-write access to a value. This is restricted to the case where
+ * <i>|i-j| <= 1</i>.
*
- * @note In case of symmetric
- * storage technique, the entries
- * <i>(i,j)</i> and <i>(j,i)</i>
- * are identified and <b>both</b>
- * exist. This must be taken into
- * account if adding up is used
- * for matrix assembling in order
- * not to obtain doubled entries.
+ * @note In case of symmetric storage technique, the entries <i>(i,j)</i>
+ * and <i>(j,i)</i> are identified and <b>both</b> exist. This must be taken
+ * into account if adding up is used for matrix assembling in order not to
+ * obtain doubled entries.
*/
number &operator()(size_type i, size_type j);
//@{
/**
- * Matrix-vector-multiplication. Multiplies
- * <tt>v</tt> from the right and
- * stores the result in
- * <tt>w</tt>.
+ * Matrix-vector-multiplication. Multiplies <tt>v</tt> from the right and
+ * stores the result in <tt>w</tt>.
*
- * If the optional parameter
- * <tt>adding</tt> is <tt>true</tt>, the
- * result is added to <tt>w</tt>.
+ * If the optional parameter <tt>adding</tt> is <tt>true</tt>, the result is
+ * added to <tt>w</tt>.
*
- * Source and destination must
- * not be the same vector.
+ * Source and destination must not be the same vector.
*/
void vmult (Vector<number> &w,
const Vector<number> &v,
const bool adding=false) const;
/**
- * Adding
- * Matrix-vector-multiplication. Same
- * as vmult() with parameter
- * <tt>adding=true</tt>, but
- * widely used in
- * <tt>deal.II</tt> classes.
+ * Adding Matrix-vector-multiplication. Same as vmult() with parameter
+ * <tt>adding=true</tt>, but widely used in <tt>deal.II</tt> classes.
*
- * Source and destination must
- * not be the same vector.
+ * Source and destination must not be the same vector.
*/
void vmult_add (Vector<number> &w,
const Vector<number> &v) const;
/**
- * Transpose
- * matrix-vector-multiplication.
- * Multiplies
- * <tt>v<sup>T</sup></tt> from
- * the left and stores the result
- * in <tt>w</tt>.
+ * Transpose matrix-vector-multiplication. Multiplies <tt>v<sup>T</sup></tt>
+ * from the left and stores the result in <tt>w</tt>.
*
- * If the optional parameter
- * <tt>adding</tt> is <tt>true</tt>, the
- * result is added to <tt>w</tt>.
+ * If the optional parameter <tt>adding</tt> is <tt>true</tt>, the result is
+ * added to <tt>w</tt>.
*
- * Source and destination must
- * not be the same vector.
+ * Source and destination must not be the same vector.
*/
void Tvmult (Vector<number> &w,
const Vector<number> &v,
const bool adding=false) const;
/**
- * Adding transpose
- * matrix-vector-multiplication. Same
- * as Tvmult() with parameter
- * <tt>adding=true</tt>, but
- * widely used in
- * <tt>deal.II</tt> classes.
+ * Adding transpose matrix-vector-multiplication. Same as Tvmult() with
+ * parameter <tt>adding=true</tt>, but widely used in <tt>deal.II</tt>
+ * classes.
*
- * Source and destination must
- * not be the same vector.
+ * Source and destination must not be the same vector.
*/
void Tvmult_add (Vector<number> &w,
const Vector<number> &v) const;
/**
- * Build the matrix scalar product
- * <tt>u^T M v</tt>. This function is mostly
- * useful when building the cellwise
- * scalar product of two functions in
- * the finite element context.
+ * Build the matrix scalar product <tt>u^T M v</tt>. This function is mostly
+ * useful when building the cellwise scalar product of two functions in the
+ * finite element context.
*/
number matrix_scalar_product (const Vector<number> &u,
const Vector<number> &v) const;
/**
- * Return the square of the norm
- * of the vector <tt>v</tt> with
- * respect to the norm induced by
- * this matrix,
- * i.e. <i>(v,Mv)</i>. This is
- * useful, e.g. in the finite
- * element context, where the
- * <i>L<sup>2</sup></i> norm of a
- * function equals the matrix
- * norm with respect to the mass
- * matrix of the vector
- * representing the nodal values
- * of the finite element
- * function.
+ * Return the square of the norm of the vector <tt>v</tt> with respect to
+ * the norm induced by this matrix, i.e. <i>(v,Mv)</i>. This is useful, e.g.
+ * in the finite element context, where the <i>L<sup>2</sup></i> norm of a
+ * function equals the matrix norm with respect to the mass matrix of the
+ * vector representing the nodal values of the finite element function.
*
- * Obviously, the matrix needs to
- * be quadratic for this operation.
+ * Obviously, the matrix needs to be quadratic for this operation.
*/
number matrix_norm_square (const Vector<number> &v) const;
//@{
/**
- * Return the $l_1$-norm of the matrix, i.e.
- * $|M|_1=max_{all columns j}\sum_{all
- * rows i} |M_ij|$,
- * (max. sum of columns). This is the
- * natural matrix norm that is compatible
- * to the $l_1$-norm for vectors, i.e.
- * $|Mv|_1\leq |M|_1 |v|_1$.
- * (cf. Rannacher Numerik0)
+ * Return the $l_1$-norm of the matrix, i.e. $|M|_1=max_{all columns
+ * j}\sum_{all rows i} |M_ij|$, (max. sum of columns). This is the natural
+ * matrix norm that is compatible to the $l_1$-norm for vectors, i.e.
+ * $|Mv|_1\leq |M|_1 |v|_1$. (cf. Rannacher Numerik0)
*/
number l1_norm () const;
/**
- * Return the $l_\infty$-norm of the
- * matrix, i.e.
- * $|M|_\infty=\max_{all rows i}\sum_{all
- * columns j} |M_{ij}|$,
- * (max. sum of rows).
- * This is the
- * natural matrix norm that is compatible
- * to the $l_\infty$-norm of vectors, i.e.
+ * Return the $l_\infty$-norm of the matrix, i.e. $|M|_\infty=\max_{all rows
+ * i}\sum_{all columns j} |M_{ij}|$, (max. sum of rows). This is the natural
+ * matrix norm that is compatible to the $l_\infty$-norm of vectors, i.e.
* $|Mv|_\infty \leq |M|_\infty |v|_\infty$.
*/
number linfty_norm () const;
/**
- * The Frobenius norm of the matrix.
- * Return value is the root of the square
+ * The Frobenius norm of the matrix. Return value is the root of the square
* sum of all matrix entries.
*/
number frobenius_norm () const;
/**
- * Compute the relative norm of
- * the skew-symmetric part. The
- * return value is the Frobenius
- * norm of the skew-symmetric
- * part of the matrix divided by
+ * Compute the relative norm of the skew-symmetric part. The return value is
+ * the Frobenius norm of the skew-symmetric part of the matrix divided by
* that of the matrix.
*
- * Main purpose of this function
- * is to check, if a matrix is
- * symmetric within a certain
- * accuracy, or not.
+ * Main purpose of this function is to check, if a matrix is symmetric
+ * within a certain accuracy, or not.
*/
number relative_symmetry_norm2 () const;
//@}
///@name LAPACK operations
//@{
/**
- * Compute the eigenvalues of the
- * symmetric tridiagonal matrix.
+ * Compute the eigenvalues of the symmetric tridiagonal matrix.
*
- * @note This function requires
- * configuration of deal.II with
- * LAPACK support. Additionally,
- * the matrix must use symmetric
- * storage technique.
+ * @note This function requires configuration of deal.II with LAPACK
+ * support. Additionally, the matrix must use symmetric storage technique.
*/
void compute_eigenvalues();
/**
- * After calling
- * compute_eigenvalues(), you can
- * access each eigenvalue here.
+ * After calling compute_eigenvalues(), you can access each eigenvalue here.
*/
number eigenvalue(const size_type i) const;
//@}
///@name Miscellanea
//@{
/**
- * Output of the matrix in
- * user-defined format.
+ * Output of the matrix in user-defined format.
*/
template <class OUT>
void print (OUT &s,
const unsigned int precision=2) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
//@}
*/
std::vector<number> diagonal;
/**
- * The entries left of the
- * diagonal. The entry with index
- * zero is always zero, since the
- * first row has no entry left of
- * the diagonal. Therefore, the
- * length of this vector is the
- * same as that of #diagonal.
+ * The entries left of the diagonal. The entry with index zero is always
+ * zero, since the first row has no entry left of the diagonal. Therefore,
+ * the length of this vector is the same as that of #diagonal.
*
- * The length of this vector is
- * zero for symmetric storage. In
- * this case, the second element
- * of #left is identified with
- * the first element of #right.
+ * The length of this vector is zero for symmetric storage. In this case,
+ * the second element of #left is identified with the first element of
+ * #right.
*/
std::vector<number> left;
/**
- * The entries right of the
- * diagonal. The last entry is
- * always zero, since the last
- * row has no entry right of the
- * diagonal. Therefore, the
- * length of this vector is the
- * same as that of #diagonal.
+ * The entries right of the diagonal. The last entry is always zero, since
+ * the last row has no entry right of the diagonal. Therefore, the length of
+ * this vector is the same as that of #diagonal.
*/
std::vector<number> right;
/**
- * If this flag is true, only the
- * entries to the right of the
- * diagonal are stored and the
- * matrix is assumed symmetric.
+ * If this flag is true, only the entries to the right of the diagonal are
+ * stored and the matrix is assumed symmetric.
*/
bool is_symmetric;
/**
- * The state of the
- * matrix. Normally, the state is
- * LAPACKSupport::matrix,
- * indicating that the object can
- * be used for regular matrix
- * operations.
+ * The state of the matrix. Normally, the state is LAPACKSupport::matrix,
+ * indicating that the object can be used for regular matrix operations.
*
- * See explanation of this data
- * type for details.
+ * See explanation of this data type for details.
*/
LAPACKSupport::State state;
};
*/
/**
- * Blocked sparse matrix based on the TrilinosWrappers::SparseMatrix class. This
- * class implements the functions that are specific to the Trilinos SparseMatrix
- * base objects for a blocked sparse matrix, and leaves the actual work
- * relaying most of the calls to the individual blocks to the functions
- * implemented in the base class. See there also for a description of when
- * this class is useful.
+ * Blocked sparse matrix based on the TrilinosWrappers::SparseMatrix class.
+ * This class implements the functions that are specific to the Trilinos
+ * SparseMatrix base objects for a blocked sparse matrix, and leaves the
+ * actual work relaying most of the calls to the individual blocks to the
+ * functions implemented in the base class. See there also for a description
+ * of when this class is useful.
*
- * In contrast to the deal.II-type SparseMatrix class, the Trilinos matrices do
- * not have external objects for the sparsity patterns. Thus, one does not
- * determine the size of the individual blocks of a block matrix of this type
- * by attaching a block sparsity pattern, but by calling reinit() to set the
- * number of blocks and then by setting the size of each block separately. In
- * order to fix the data structures of the block matrix, it is then necessary
- * to let it know that we have changed the sizes of the underlying
- * matrices. For this, one has to call the collect_sizes() function, for much
- * the same reason as is documented with the BlockSparsityPattern class.
+ * In contrast to the deal.II-type SparseMatrix class, the Trilinos matrices
+ * do not have external objects for the sparsity patterns. Thus, one does
+ * not determine the size of the individual blocks of a block matrix of this
+ * type by attaching a block sparsity pattern, but by calling reinit() to
+ * set the number of blocks and then by setting the size of each block
+ * separately. In order to fix the data structures of the block matrix, it
+ * is then necessary to let it know that we have changed the sizes of the
+ * underlying matrices. For this, one has to call the collect_sizes()
+ * function, for much the same reason as is documented with the
+ * BlockSparsityPattern class.
*
- * @ingroup Matrix1
- * @see @ref GlossBlockLA "Block (linear algebra)"
+ * @ingroup Matrix1 @see @ref GlossBlockLA "Block (linear algebra)"
* @author Martin Kronbichler, Wolfgang Bangerth, 2008
*/
class BlockSparseMatrix : public BlockMatrixBase<SparseMatrix>
{
public:
/**
- * Typedef the base class for simpler
- * access to its own typedefs.
+ * Typedef the base class for simpler access to its own typedefs.
*/
typedef BlockMatrixBase<SparseMatrix> BaseClass;
/**
- * Typedef the type of the underlying
- * matrix.
+ * Typedef the type of the underlying matrix.
*/
typedef BaseClass::BlockType BlockType;
/**
- * Import the typedefs from the base
- * class.
+ * Import the typedefs from the base class.
*/
typedef BaseClass::value_type value_type;
typedef BaseClass::pointer pointer;
typedef BaseClass::const_iterator const_iterator;
/**
- * Constructor; initializes the
- * matrix to be empty, without
- * any structure, i.e. the
- * matrix is not usable at
- * all. This constructor is
- * therefore only useful for
- * matrices which are members of
- * a class. All other matrices
- * should be created at a point
- * in the data flow where all
- * necessary information is
- * available.
+ * Constructor; initializes the matrix to be empty, without any structure,
+ * i.e. the matrix is not usable at all. This constructor is therefore
+ * only useful for matrices which are members of a class. All other
+ * matrices should be created at a point in the data flow where all
+ * necessary information is available.
*
- * You have to initialize the
- * matrix before usage with
- * reinit(BlockSparsityPattern). The
- * number of blocks per row and
- * column are then determined by
- * that function.
+ * You have to initialize the matrix before usage with
+ * reinit(BlockSparsityPattern). The number of blocks per row and column
+ * are then determined by that function.
*/
BlockSparseMatrix ();
~BlockSparseMatrix ();
/**
- * Pseudo copy operator only copying
- * empty objects. The sizes of the block
+ * Pseudo copy operator only copying empty objects. The sizes of the block
* matrices need to be the same.
*/
BlockSparseMatrix &
operator = (const BlockSparseMatrix &);
/**
- * This operator assigns a scalar to a
- * matrix. Since this does usually not
- * make much sense (should we set all
- * matrix entries to this value? Only
- * the nonzero entries of the sparsity
- * pattern?), this operation is only
- * allowed if the actual value to be
- * assigned is zero. This operator only
- * exists to allow for the obvious
- * notation <tt>matrix=0</tt>, which
- * sets all elements of the matrix to
- * zero, but keep the sparsity pattern
+ * This operator assigns a scalar to a matrix. Since this does usually not
+ * make much sense (should we set all matrix entries to this value? Only
+ * the nonzero entries of the sparsity pattern?), this operation is only
+ * allowed if the actual value to be assigned is zero. This operator only
+ * exists to allow for the obvious notation <tt>matrix=0</tt>, which sets
+ * all elements of the matrix to zero, but keep the sparsity pattern
* previously used.
*/
BlockSparseMatrix &
operator = (const double d);
/**
- * Resize the matrix, by setting
- * the number of block rows and
- * columns. This deletes all
- * blocks and replaces them by
- * unitialized ones, i.e. ones
- * for which also the sizes are
- * not yet set. You have to do
- * that by calling the @p reinit
- * functions of the blocks
- * themselves. Do not forget to
- * call collect_sizes() after
- * that on this object.
+ * Resize the matrix, by setting the number of block rows and columns.
+ * This deletes all blocks and replaces them by unitialized ones, i.e.
+ * ones for which also the sizes are not yet set. You have to do that by
+ * calling the @p reinit functions of the blocks themselves. Do not forget
+ * to call collect_sizes() after that on this object.
*
- * The reason that you have to
- * set sizes of the blocks
- * yourself is that the sizes may
- * be varying, the maximum number
- * of elements per row may be
- * varying, etc. It is simpler
- * not to reproduce the interface
- * of the @p SparsityPattern
- * class here but rather let the
- * user call whatever function
- * she desires.
+ * The reason that you have to set sizes of the blocks yourself is that
+ * the sizes may be varying, the maximum number of elements per row may be
+ * varying, etc. It is simpler not to reproduce the interface of the @p
+ * SparsityPattern class here but rather let the user call whatever
+ * function she desires.
*/
void reinit (const size_type n_block_rows,
const size_type n_block_columns);
/**
- * Resize the matrix, by using an
- * array of Epetra maps to determine
- * the %parallel distribution of the
- * individual matrices. This function
- * assumes that a quadratic block
- * matrix is generated.
+ * Resize the matrix, by using an array of Epetra maps to determine the
+ * %parallel distribution of the individual matrices. This function
+ * assumes that a quadratic block matrix is generated.
*/
template <typename BlockSparsityType>
void reinit (const std::vector<Epetra_Map> &input_maps,
const bool exchange_data = false);
/**
- * Resize the matrix, by using an
- * array of index sets to determine
- * the %parallel distribution of the
- * individual matrices. This function
- * assumes that a quadratic block
- * matrix is generated.
+ * Resize the matrix, by using an array of index sets to determine the
+ * %parallel distribution of the individual matrices. This function
+ * assumes that a quadratic block matrix is generated.
*/
template <typename BlockSparsityType>
void reinit (const std::vector<IndexSet> &input_maps,
const bool exchange_data = false);
/**
- * Resize the matrix and initialize it
- * by the given sparsity pattern. Since
- * no distribution map is given, the
- * result is a block matrix for which
- * all elements are stored locally.
+ * Resize the matrix and initialize it by the given sparsity pattern.
+ * Since no distribution map is given, the result is a block matrix for
+ * which all elements are stored locally.
*/
template <typename BlockSparsityType>
void reinit (const BlockSparsityType &block_sparsity_pattern);
/**
- * This function initializes the
- * Trilinos matrix using the deal.II
- * sparse matrix and the entries stored
- * therein. It uses a threshold
- * to copy only elements whose
- * modulus is larger than the
- * threshold (so zeros in the
- * deal.II matrix can be filtered
- * away).
+ * This function initializes the Trilinos matrix using the deal.II sparse
+ * matrix and the entries stored therein. It uses a threshold to copy only
+ * elements whose modulus is larger than the threshold (so zeros in the
+ * deal.II matrix can be filtered away).
*/
void reinit (const std::vector<Epetra_Map> &input_maps,
const ::dealii::BlockSparseMatrix<double> &deal_ii_sparse_matrix,
const double drop_tolerance=1e-13);
/**
- * This function initializes
- * the Trilinos matrix using
- * the deal.II sparse matrix
- * and the entries stored
- * therein. It uses a threshold
- * to copy only elements whose
- * modulus is larger than the
- * threshold (so zeros in the
- * deal.II matrix can be
- * filtered away). Since no
- * Epetra_Map is given, all the
- * elements will be locally
- * stored.
+ * This function initializes the Trilinos matrix using the deal.II sparse
+ * matrix and the entries stored therein. It uses a threshold to copy only
+ * elements whose modulus is larger than the threshold (so zeros in the
+ * deal.II matrix can be filtered away). Since no Epetra_Map is given, all
+ * the elements will be locally stored.
*/
void reinit (const ::dealii::BlockSparseMatrix<double> &deal_ii_sparse_matrix,
const double drop_tolerance=1e-13);
/**
- * Returns the state of the
- * matrix, i.e., whether
- * compress() needs to be called
- * after an operation requiring
- * data exchange. Does only
- * return non-true values when
- * used in <tt>debug</tt> mode,
- * since it is quite expensive to
- * keep track of all operations
- * that lead to the need for
+ * Returns the state of the matrix, i.e., whether compress() needs to be
+ * called after an operation requiring data exchange. Does only return
+ * non-true values when used in <tt>debug</tt> mode, since it is quite
+ * expensive to keep track of all operations that lead to the need for
* compress().
*/
bool is_compressed () const;
/**
- * This function collects the
- * sizes of the sub-objects and
- * stores them in internal
- * arrays, in order to be able to
- * relay global indices into the
- * matrix to indices into the
- * subobjects. You *must* call
- * this function each time after
- * you have changed the size of
- * the sub-objects. Note that
- * this is a collective
- * operation, i.e., it needs to
- * be called on all MPI
- * processes. This command
- * internally calls the method
- * <tt>compress()</tt>, so you
- * don't need to call that
- * function in case you use
- * <tt>collect_sizes()</tt>.
+ * This function collects the sizes of the sub-objects and stores them in
+ * internal arrays, in order to be able to relay global indices into the
+ * matrix to indices into the subobjects. You *must* call this function
+ * each time after you have changed the size of the sub-objects. Note that
+ * this is a collective operation, i.e., it needs to be called on all MPI
+ * processes. This command internally calls the method
+ * <tt>compress()</tt>, so you don't need to call that function in case
+ * you use <tt>collect_sizes()</tt>.
*/
void collect_sizes ();
/**
- * Return the number of nonzero
- * elements of this
- * matrix.
+ * Return the number of nonzero elements of this matrix.
*/
size_type n_nonzero_elements () const;
const VectorType2 &src) const;
/**
- * Compute the residual of an
- * equation <i>Mx=b</i>, where
- * the residual is defined to
- * be <i>r=b-Mx</i>. Write the
- * residual into @p dst. The
- * <i>l<sub>2</sub></i> norm of
- * the residual vector is
- * returned.
+ * Compute the residual of an equation <i>Mx=b</i>, where the residual is
+ * defined to be <i>r=b-Mx</i>. Write the residual into @p dst. The
+ * <i>l<sub>2</sub></i> norm of the residual vector is returned.
*
- * Source <i>x</i> and
- * destination <i>dst</i> must
- * not be the same vector.
+ * Source <i>x</i> and destination <i>dst</i> must not be the same vector.
*
- * Note that both vectors have
- * to be distributed vectors
- * generated using the same Map
- * as was used for the matrix
- * in case you work on a
- * distributed memory
- * architecture, using the
- * interface in the
- * TrilinosWrappers::MPI::BlockVector
- * class.
+ * Note that both vectors have to be distributed vectors generated using
+ * the same Map as was used for the matrix in case you work on a
+ * distributed memory architecture, using the interface in the
+ * TrilinosWrappers::MPI::BlockVector class.
*/
TrilinosScalar residual (MPI::BlockVector &dst,
const MPI::BlockVector &x,
const MPI::BlockVector &b) const;
/**
- * Compute the residual of an
- * equation <i>Mx=b</i>, where
- * the residual is defined to
- * be <i>r=b-Mx</i>. Write the
- * residual into @p dst. The
- * <i>l<sub>2</sub></i> norm of
- * the residual vector is
- * returned.
+ * Compute the residual of an equation <i>Mx=b</i>, where the residual is
+ * defined to be <i>r=b-Mx</i>. Write the residual into @p dst. The
+ * <i>l<sub>2</sub></i> norm of the residual vector is returned.
*
- * Source <i>x</i> and
- * destination <i>dst</i> must
- * not be the same vector.
+ * Source <i>x</i> and destination <i>dst</i> must not be the same vector.
*
- * Note that both vectors have
- * to be distributed vectors
- * generated using the same Map
- * as was used for the matrix
- * in case you work on a
- * distributed memory
- * architecture, using the
- * interface in the
- * TrilinosWrappers::BlockVector
- * class. Since the block
- * matrix is in general
- * distributed among processes,
- * this function only works
- * when running the program on
- * one processor.
+ * Note that both vectors have to be distributed vectors generated using
+ * the same Map as was used for the matrix in case you work on a
+ * distributed memory architecture, using the interface in the
+ * TrilinosWrappers::BlockVector class. Since the block matrix is in
+ * general distributed among processes, this function only works when
+ * running the program on one processor.
*/
TrilinosScalar residual (BlockVector &dst,
const BlockVector &x,
const BlockVector &b) const;
/**
- * Compute the residual of an
- * equation <i>Mx=b</i>, where
- * the residual is defined to
- * be <i>r=b-Mx</i>. Write the
- * residual into @p dst. The
- * <i>l<sub>2</sub></i> norm of
- * the residual vector is
- * returned. Just like the
- * previous function, but only
- * applicable if the matrix
- * only has one block row.
+ * Compute the residual of an equation <i>Mx=b</i>, where the residual is
+ * defined to be <i>r=b-Mx</i>. Write the residual into @p dst. The
+ * <i>l<sub>2</sub></i> norm of the residual vector is returned. Just like
+ * the previous function, but only applicable if the matrix only has one
+ * block row.
*/
TrilinosScalar residual (MPI::BlockVector &dst,
const MPI::Vector &x,
const MPI::BlockVector &b) const;
/**
- * Compute the residual of an
- * equation <i>Mx=b</i>, where
- * the residual is defined to
- * be <i>r=b-Mx</i>. Write the
- * residual into @p dst. The
- * <i>l<sub>2</sub></i> norm of
- * the residual vector is
- * returned. Just like the
- * previous function, but only
- * applicable if the matrix
- * only has one block row.
+ * Compute the residual of an equation <i>Mx=b</i>, where the residual is
+ * defined to be <i>r=b-Mx</i>. Write the residual into @p dst. The
+ * <i>l<sub>2</sub></i> norm of the residual vector is returned. Just like
+ * the previous function, but only applicable if the matrix only has one
+ * block row.
*/
TrilinosScalar residual (BlockVector &dst,
const Vector &x,
const BlockVector &b) const;
/**
- * Compute the residual of an
- * equation <i>Mx=b</i>, where
- * the residual is defined to
- * be <i>r=b-Mx</i>. Write the
- * residual into @p dst. The
- * <i>l<sub>2</sub></i> norm of
- * the residual vector is
- * returned. Just like the
- * previous function, but only
- * applicable if the matrix
- * only has one block column.
+ * Compute the residual of an equation <i>Mx=b</i>, where the residual is
+ * defined to be <i>r=b-Mx</i>. Write the residual into @p dst. The
+ * <i>l<sub>2</sub></i> norm of the residual vector is returned. Just like
+ * the previous function, but only applicable if the matrix only has one
+ * block column.
*/
TrilinosScalar residual (MPI::Vector &dst,
const MPI::BlockVector &x,
const MPI::Vector &b) const;
/**
- * Compute the residual of an
- * equation <i>Mx=b</i>, where
- * the residual is defined to
- * be <i>r=b-Mx</i>. Write the
- * residual into @p dst. The
- * <i>l<sub>2</sub></i> norm of
- * the residual vector is
- * returned. Just like the
- * previous function, but only
- * applicable if the matrix
- * only has one block column.
+ * Compute the residual of an equation <i>Mx=b</i>, where the residual is
+ * defined to be <i>r=b-Mx</i>. Write the residual into @p dst. The
+ * <i>l<sub>2</sub></i> norm of the residual vector is returned. Just like
+ * the previous function, but only applicable if the matrix only has one
+ * block column.
*/
TrilinosScalar residual (Vector &dst,
const BlockVector &x,
const Vector &b) const;
/**
- * Compute the residual of an
- * equation <i>Mx=b</i>, where
- * the residual is defined to
- * be <i>r=b-Mx</i>. Write the
- * residual into @p dst. The
- * <i>l<sub>2</sub></i> norm of
- * the residual vector is
- * returned. Just like the
- * previous function, but only
- * applicable if the matrix
- * only has one block.
+ * Compute the residual of an equation <i>Mx=b</i>, where the residual is
+ * defined to be <i>r=b-Mx</i>. Write the residual into @p dst. The
+ * <i>l<sub>2</sub></i> norm of the residual vector is returned. Just like
+ * the previous function, but only applicable if the matrix only has one
+ * block.
*/
TrilinosScalar residual (VectorBase &dst,
const VectorBase &x,
const VectorBase &b) const;
/**
- * Make the clear() function in the
- * base class visible, though it is
+ * Make the clear() function in the base class visible, though it is
* protected.
*/
using BlockMatrixBase<SparseMatrix>::clear;
- /** @addtogroup Exceptions
+ /**
+ * @addtogroup Exceptions
* @{
*/
/**
- * An implementation of block vectors based on the vector class
- * implemented in TrilinosWrappers. While the base class provides for
- * most of the interface, this class handles the actual allocation of
- * vectors and provides functions that are specific to the underlying
- * vector type.
+ * An implementation of block vectors based on the vector class implemented
+ * in TrilinosWrappers. While the base class provides for most of the
+ * interface, this class handles the actual allocation of vectors and
+ * provides functions that are specific to the underlying vector type.
*
* In contrast to the class MPI::BlockVector, this class is based on a
- * localized version of the vectors, which means that the whole vector
- * is stored on each processor. Note that matrix vector products with
- * this block vector class do only work in case the program is run on
- * only one processor, since the Trilinos matrices are inherently
- * parallel.
+ * localized version of the vectors, which means that the whole vector is
+ * stored on each processor. Note that matrix vector products with this
+ * block vector class do only work in case the program is run on only one
+ * processor, since the Trilinos matrices are inherently parallel.
*
* @ingroup Vectors
- * @ingroup TrilinosWrappers
- * @see @ref GlossBlockLA "Block (linear algebra)"
+ * @ingroup TrilinosWrappers @see @ref GlossBlockLA "Block (linear algebra)"
* @author Martin Kronbichler, 2008
*/
class BlockVector : public BlockVectorBase<Vector>
~BlockVector ();
/**
- * use compress(VectorOperation) instead
- *
- * @deprecated
- *
- * See @ref GlossCompress "Compressing distributed objects" for more
- * information.
- */
+ * use compress(VectorOperation) instead
+ *
+ * @deprecated
+ *
+ * See @ref GlossCompress "Compressing distributed objects" for more
+ * information.
+ */
void compress (const Epetra_CombineMode last_action) DEAL_II_DEPRECATED;
/**
* index sets given in the input argument, according to the global size of
* the individual components described in the index set, and using a given
* MPI communicator. The MPI communicator is useful when data exchange
- * with a distributed vector based on the same initialization is
- * intended. In that case, the same communicator is used for data
- * exchange.
+ * with a distributed vector based on the same initialization is intended.
+ * In that case, the same communicator is used for data exchange.
*
- * If <tt>fast==false</tt>, the vector
- * is filled with zeros.
+ * If <tt>fast==false</tt>, the vector is filled with zeros.
*/
void reinit (const std::vector<IndexSet> &partitioning,
const MPI_Comm &communicator = MPI_COMM_WORLD,
* elements in the first argument, and with the respective sizes. Since no
* distribution map is given, all vectors are local vectors.
*
- * If <tt>fast==false</tt>, the vector
- * is filled with zeros.
+ * If <tt>fast==false</tt>, the vector is filled with zeros.
*/
void reinit (const std::vector<size_type> &N,
const bool fast=false);
/**
- * Reinitialize the vector in the same way as the given to a
- * distributed block vector. The elements will be copied in this
- * process.
+ * Reinitialize the vector in the same way as the given to a distributed
+ * block vector. The elements will be copied in this process.
*/
void reinit (const MPI::BlockVector &V);
*
* Note that you must call this (or the other reinit() functions)
* function, rather than calling the reinit() functions of an individual
- * block, to allow the block vector to update its caches of vector
- * sizes. If you call reinit() on one of the blocks, then subsequent
- * actions on this object may yield unpredictable results since they may
- * be routed to the wrong block.
+ * block, to allow the block vector to update its caches of vector sizes.
+ * If you call reinit() on one of the blocks, then subsequent actions on
+ * this object may yield unpredictable results since they may be routed to
+ * the wrong block.
*/
void reinit (const BlockVector &V,
const bool fast = false);
/**
- * Global function which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two vectors.
+ * Global function which overloads the default implementation of the C++
+ * standard library which uses a temporary object. The function simply
+ * exchanges the data of the two vectors.
*
* @relates TrilinosWrappers::BlockVector
* @author Martin Kronbichler, 2008
{
/**
* An implementation of block vectors based on the vector class
- * implemented in TrilinosWrappers. While the base class provides for
- * most of the interface, this class handles the actual allocation of
- * vectors and provides functions that are specific to the underlying
- * vector type.
+ * implemented in TrilinosWrappers. While the base class provides for most
+ * of the interface, this class handles the actual allocation of vectors
+ * and provides functions that are specific to the underlying vector type.
*
- * The model of distribution of data is such that each of the blocks
- * is distributed across all MPI processes named in the MPI
- * communicator. I.e. we don't just distribute the whole vector, but
- * each component. In the constructors and reinit() functions, one
- * therefore not only has to specify the sizes of the individual
- * blocks, but also the number of elements of each of these blocks to
- * be stored on the local process.
+ * The model of distribution of data is such that each of the blocks is
+ * distributed across all MPI processes named in the MPI communicator.
+ * I.e. we don't just distribute the whole vector, but each component. In
+ * the constructors and reinit() functions, one therefore not only has to
+ * specify the sizes of the individual blocks, but also the number of
+ * elements of each of these blocks to be stored on the local process.
*
* @ingroup Vectors
- * @ingroup TrilinosWrappers
- * @see @ref GlossBlockLA "Block (linear algebra)"
+ * @ingroup TrilinosWrappers @see @ref GlossBlockLA "Block (linear
+ * algebra)"
* @author Martin Kronbichler, Wolfgang Bangerth, 2008, 2009
*/
class BlockVector : public BlockVectorBase<Vector>
/**
* Another copy function. This one takes a deal.II block vector and
* copies it into a TrilinosWrappers block vector. Note that the number
- * of blocks has to be the same in the vector as in the input
- * vector. Use the reinit() command for resizing the BlockVector or for
- * changing the internal structure of the block components.
+ * of blocks has to be the same in the vector as in the input vector.
+ * Use the reinit() command for resizing the BlockVector or for changing
+ * the internal structure of the block components.
*
* Since Trilinos only works on doubles, this function is limited to
* accept only one possible number type in the deal.II vector.
* Reinit functionality. This function destroys the old vector content
* and generates a new one based on the input partitioning. In addition
* to just specifying one index set as in all the other methods above,
- * this method allows to supply an additional set of ghost
- * entries. There are two different versions of a vector that can be
- * created. If the flag @p vector_writable is set to @p false, the
- * vector only allows read access to the joint set of @p
- * parallel_partitioning and @p ghost_entries. The effect of the reinit
- * method is then equivalent to calling the other reinit method with an
- * index set containing both the locally owned entries and the ghost
- * entries.
+ * this method allows to supply an additional set of ghost entries.
+ * There are two different versions of a vector that can be created. If
+ * the flag @p vector_writable is set to @p false, the vector only
+ * allows read access to the joint set of @p parallel_partitioning and
+ * @p ghost_entries. The effect of the reinit method is then equivalent
+ * to calling the other reinit method with an index set containing both
+ * the locally owned entries and the ghost entries.
*
* If the flag @p vector_writable is set to true, this creates an
* alternative storage scheme for ghost elements that allows multiple
* then queried from the input vector. Note that you should not write to
* the resulting vector any more, since the some data can be stored
* several times on different processors, leading to unpredictable
- * results. In particular, such a vector cannot be used for
- * matrix-vector products as for example done during the solution of
- * linear systems.
+ * results. In particular, such a vector cannot be used for matrix-
+ * vector products as for example done during the solution of linear
+ * systems.
*/
void import_nonlocal_data_for_fe (const TrilinosWrappers::BlockSparseMatrix &m,
const BlockVector &v);
/**
- * Global function which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two vectors.
+ * Global function which overloads the default implementation of the C++
+ * standard library which uses a temporary object. The function simply
+ * exchanges the data of the two vectors.
*
* @relates TrilinosWrappers::MPI::BlockVector
* @author Martin Kronbichler, Wolfgang Bangerth, 2008
class SolverBase;
/**
- * The base class for all preconditioners based on Trilinos sparse
- * matrices.
+ * The base class for all preconditioners based on Trilinos sparse matrices.
*
* @ingroup TrilinosWrappers
* @ingroup Preconditioners
/**
- * A wrapper class for a (pointwise) Jacobi preconditioner for
- * Trilinos matrices. This preconditioner works both in serial and in
- * parallel, depending on the matrix it is based on.
+ * A wrapper class for a (pointwise) Jacobi preconditioner for Trilinos
+ * matrices. This preconditioner works both in serial and in parallel,
+ * depending on the matrix it is based on.
*
- * The AdditionalData data structure allows to set preconditioner
- * options. For the Jacobi preconditioner, these options are the
- * damping parameter <tt>omega</tt> and a <tt>min_diagonal</tt>
- * argument that can be used to make the preconditioner work even if
- * the matrix contains some zero elements on the diagonal. The default
- * settings are 1 for the damping parameter and zero for the diagonal
- * augmentation.
+ * The AdditionalData data structure allows to set preconditioner options.
+ * For the Jacobi preconditioner, these options are the damping parameter
+ * <tt>omega</tt> and a <tt>min_diagonal</tt> argument that can be used to
+ * make the preconditioner work even if the matrix contains some zero
+ * elements on the diagonal. The default settings are 1 for the damping
+ * parameter and zero for the diagonal augmentation.
*
* @ingroup TrilinosWrappers
* @ingroup Preconditioners
double omega;
/**
- * This specifies the minimum value the diagonal elements should
- * have. This might be necessary when the Jacobi preconditioner is used
- * on matrices with zero diagonal elements. In that case, a
- * straight-forward application would not be possible since we would
- * divide by zero.
+ * This specifies the minimum value the diagonal elements should have.
+ * This might be necessary when the Jacobi preconditioner is used on
+ * matrices with zero diagonal elements. In that case, a straight-
+ * forward application would not be possible since we would divide by
+ * zero.
*/
double min_diagonal;
* matrices. This preconditioner works both in serial and in parallel,
* depending on the matrix it is based on.
*
- * The AdditionalData data structure allows to set preconditioner
- * options. For the SSOR preconditioner, these options are the
- * damping/relaxation parameter <tt>omega</tt>, a
- * <tt>min_diagonal</tt> argument that can be used to make the
- * preconditioner work even if the matrix contains some zero elements
- * on the diagonal, and a parameter <tt>overlap</tt> that determines
- * if and how much overlap there should be between the matrix
- * partitions on the various MPI processes. The default settings are 1
- * for the relaxation parameter, 0 for the diagonal augmentation and 0
- * for the overlap.
+ * The AdditionalData data structure allows to set preconditioner options.
+ * For the SSOR preconditioner, these options are the damping/relaxation
+ * parameter <tt>omega</tt>, a <tt>min_diagonal</tt> argument that can be
+ * used to make the preconditioner work even if the matrix contains some
+ * zero elements on the diagonal, and a parameter <tt>overlap</tt> that
+ * determines if and how much overlap there should be between the matrix
+ * partitions on the various MPI processes. The default settings are 1 for
+ * the relaxation parameter, 0 for the diagonal augmentation and 0 for the
+ * overlap.
*
- * Note that a parallel application of the SSOR preconditioner is
- * actually a block-Jacobi preconditioner with block size equal to the
- * local matrix size. Spoken more technically, this parallel operation
- * is an <a
+ * Note that a parallel application of the SSOR preconditioner is actually a
+ * block-Jacobi preconditioner with block size equal to the local matrix
+ * size. Spoken more technically, this parallel operation is an <a
* href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
* Schwarz method</a> with an SSOR <em>approximate solve</em> as inner
* solver, based on the outer parallel partitioning.
* setting the parameter <tt>min_diagonal</tt> to a small nonzero value
* the SOR will work on a matrix that is not too far away from the one we
* want to treat. Finally, <tt>overlap</tt> governs the overlap of the
- * partitions when the preconditioner runs in parallel, forming a
- * so-called additive Schwarz preconditioner.
+ * partitions when the preconditioner runs in parallel, forming a so-
+ * called additive Schwarz preconditioner.
*/
struct AdditionalData
{
double omega;
/**
- * This specifies the minimum value the diagonal elements should
- * have. This might be necessary when the SSOR preconditioner is used on
- * matrices with zero diagonal elements. In that case, a
- * straight-forward application would not be possible since we divide by
- * the diagonal element.
+ * This specifies the minimum value the diagonal elements should have.
+ * This might be necessary when the SSOR preconditioner is used on
+ * matrices with zero diagonal elements. In that case, a straight-
+ * forward application would not be possible since we divide by the
+ * diagonal element.
*/
double min_diagonal;
* matrices. This preconditioner works both in serial and in parallel,
* depending on the matrix it is based on.
*
- * The AdditionalData data structure allows to set preconditioner
- * options. For the SOR preconditioner, these options are the
- * damping/relaxation parameter <tt>omega</tt>, a
- * <tt>min_diagonal</tt> argument that can be used to make the
- * preconditioner work even if the matrix contains some zero elements
- * on the diagonal, and a parameter <tt>overlap</tt> that determines
- * if and how much overlap there should be between the matrix
- * partitions on the various MPI processes. The default settings are 1
- * for the relaxation parameter, 0 for the diagonal augmentation and 0
- * for the overlap.
+ * The AdditionalData data structure allows to set preconditioner options.
+ * For the SOR preconditioner, these options are the damping/relaxation
+ * parameter <tt>omega</tt>, a <tt>min_diagonal</tt> argument that can be
+ * used to make the preconditioner work even if the matrix contains some
+ * zero elements on the diagonal, and a parameter <tt>overlap</tt> that
+ * determines if and how much overlap there should be between the matrix
+ * partitions on the various MPI processes. The default settings are 1 for
+ * the relaxation parameter, 0 for the diagonal augmentation and 0 for the
+ * overlap.
*
- * Note that a parallel application of the SOR preconditioner is
- * actually a block-Jacobi preconditioner with block size equal to the
- * local matrix size. Spoken more technically, this parallel operation
- * is an <a
+ * Note that a parallel application of the SOR preconditioner is actually a
+ * block-Jacobi preconditioner with block size equal to the local matrix
+ * size. Spoken more technically, this parallel operation is an <a
* href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
* Schwarz method</a> with an SOR <em>approximate solve</em> as inner
* solver, based on the outer parallel partitioning.
* setting the parameter <tt>min_diagonal</tt> to a small nonzero value
* the SOR will work on a matrix that is not too far away from the one we
* want to treat. Finally, <tt>overlap</tt> governs the overlap of the
- * partitions when the preconditioner runs in parallel, forming a
- * so-called additive Schwarz preconditioner.
+ * partitions when the preconditioner runs in parallel, forming a so-
+ * called additive Schwarz preconditioner.
*/
struct AdditionalData
{
double omega;
/**
- * This specifies the minimum value the diagonal elements should
- * have. This might be necessary when the SOR preconditioner is used on
- * matrices with zero diagonal elements. In that case, a
- * straight-forward application would not be possible since we divide by
- * the diagonal element.
+ * This specifies the minimum value the diagonal elements should have.
+ * This might be necessary when the SOR preconditioner is used on
+ * matrices with zero diagonal elements. In that case, a straight-
+ * forward application would not be possible since we divide by the
+ * diagonal element.
*/
double min_diagonal;
/**
- * A wrapper class for a block Jacobi preconditioner for Trilinos
- * matrices. As opposed to PreconditionSOR where each row is treated
- * separately, this scheme collects block of a given size and inverts a full
- * matrix for all these rows simultaneously. Trilinos allows to select
- * several strategies for selecting which rows form a block, including
- * "linear" (i.e., divide the local range of the matrix in slices of the
- * block size), "greedy" or "metis". Note that the term <em>block
- * Jacobi</em> does not relate to possible blocks in the MPI setting, but
- * small blocks of dense matrices extracted from the sparse matrix local to
- * each processor.
+ * A wrapper class for a block Jacobi preconditioner for Trilinos matrices.
+ * As opposed to PreconditionSOR where each row is treated separately, this
+ * scheme collects block of a given size and inverts a full matrix for all
+ * these rows simultaneously. Trilinos allows to select several strategies
+ * for selecting which rows form a block, including "linear" (i.e., divide
+ * the local range of the matrix in slices of the block size), "greedy" or
+ * "metis". Note that the term <em>block Jacobi</em> does not relate to
+ * possible blocks in the MPI setting, but small blocks of dense matrices
+ * extracted from the sparse matrix local to each processor.
*
- * The AdditionalData data structure allows to set preconditioner
- * options.
+ * The AdditionalData data structure allows to set preconditioner options.
*
* @ingroup TrilinosWrappers
* @ingroup Preconditioners
/**
* Strategy for creation of blocks passed on to Ifpack block relaxation
- * (variable 'partitioner: type') with this string as the given
- * value. Available types in Ifpack include "linear" (i.e., divide the
- * local range of the matrix in slices of the block size), "greedy"
- * "metis". For a full list, see the documentation of Ifpack.
+ * (variable 'partitioner: type') with this string as the given value.
+ * Available types in Ifpack include "linear" (i.e., divide the local
+ * range of the matrix in slices of the block size), "greedy" "metis".
+ * For a full list, see the documentation of Ifpack.
*/
std::string block_creation_type;
double omega;
/**
- * This specifies the minimum value the diagonal elements should
- * have. This might be necessary when the block Jacobi preconditioner is
- * used on matrices with zero diagonal elements. In that case, a
- * straight-forward application would not be possible since we divide by
- * the diagonal element.
+ * This specifies the minimum value the diagonal elements should have.
+ * This might be necessary when the block Jacobi preconditioner is used
+ * on matrices with zero diagonal elements. In that case, a straight-
+ * forward application would not be possible since we divide by the
+ * diagonal element.
*/
double min_diagonal;
/**
* A wrapper class for a block SSOR preconditioner for Trilinos matrices. As
- * opposed to PreconditionSSOR where each row is treated separately
- * (point-wise), this scheme collects block of a given size and inverts a
- * full matrix for all these rows simultaneously. Trilinos allows to select
+ * opposed to PreconditionSSOR where each row is treated separately (point-
+ * wise), this scheme collects block of a given size and inverts a full
+ * matrix for all these rows simultaneously. Trilinos allows to select
* several strategies for selecting which rows form a block, including
* "linear" (i.e., divide the local range of the matrix in slices of the
* block size), "greedy" or "metis".
*
- * The AdditionalData data structure allows to set preconditioner
- * options.
+ * The AdditionalData data structure allows to set preconditioner options.
*
* Note that a parallel application of this preconditioner is actually a
* block-Jacobi preconditioner with (outer) block size equal to the local
/**
* Strategy for creation of blocks passed on to Ifpack block relaxation
- * (variable 'partitioner: type') with this string as the given
- * value. Available types in Ifpack include "linear" (i.e., divide the
- * local range of the matrix in slices of the block size), "greedy"
- * "metis". For a full list, see the documentation of Ifpack.
+ * (variable 'partitioner: type') with this string as the given value.
+ * Available types in Ifpack include "linear" (i.e., divide the local
+ * range of the matrix in slices of the block size), "greedy" "metis".
+ * For a full list, see the documentation of Ifpack.
*/
std::string block_creation_type;
double omega;
/**
- * This specifies the minimum value the diagonal elements should
- * have. This might be necessary when the SSOR preconditioner is used on
- * matrices with zero diagonal elements. In that case, a
- * straight-forward application would not be possible since we divide by
- * the diagonal element.
+ * This specifies the minimum value the diagonal elements should have.
+ * This might be necessary when the SSOR preconditioner is used on
+ * matrices with zero diagonal elements. In that case, a straight-
+ * forward application would not be possible since we divide by the
+ * diagonal element.
*/
double min_diagonal;
* the local range of the matrix in slices of the block size), "greedy" or
* "metis".
*
- * The AdditionalData data structure allows to set preconditioner
- * options.
+ * The AdditionalData data structure allows to set preconditioner options.
*
* Note that a parallel application of this preconditioner is actually a
* block-Jacobi preconditioner with (outer) block size equal to the local
/**
* Strategy for creation of blocks passed on to Ifpack block relaxation
- * (variable 'partitioner: type') with this string as the given
- * value. Available types in Ifpack include "linear" (i.e., divide the
- * local range of the matrix in slices of the block size), "greedy"
- * "metis". For a full list, see the documentation of Ifpack.
+ * (variable 'partitioner: type') with this string as the given value.
+ * Available types in Ifpack include "linear" (i.e., divide the local
+ * range of the matrix in slices of the block size), "greedy" "metis".
+ * For a full list, see the documentation of Ifpack.
*/
std::string block_creation_type;
double omega;
/**
- * This specifies the minimum value the diagonal elements should
- * have. This might be necessary when the SOR preconditioner is used on
- * matrices with zero diagonal elements. In that case, a
- * straight-forward application would not be possible since we divide by
- * the diagonal element.
+ * This specifies the minimum value the diagonal elements should have.
+ * This might be necessary when the SOR preconditioner is used on
+ * matrices with zero diagonal elements. In that case, a straight-
+ * forward application would not be possible since we divide by the
+ * diagonal element.
*/
double min_diagonal;
/**
* A wrapper class for an incomplete Cholesky factorization (IC)
- * preconditioner for @em symmetric Trilinos matrices. This
- * preconditioner works both in serial and in parallel, depending on
- * the matrix it is based on. In general, an incomplete factorization
- * does not take all fill-in elements that would appear in a full
- * factorization (that is the basis for a direct solve). Trilinos
- * allows to set the amount of fill-in elements, governed by the
- * additional data argument <tt>ic_fill</tt>, so one can gradually
- * choose between a factorization on the sparse matrix structure only
- * (<tt>ic_fill=0</tt>) to a full factorization (<tt>ic_fill</tt> in
- * the range of 10 to 50, depending on the spatial dimension of the
- * PDE problem and the degree of the finite element basis functions;
- * generally, more required fill-in elements require this parameter to
- * be set to a higher integer value).
+ * preconditioner for @em symmetric Trilinos matrices. This preconditioner
+ * works both in serial and in parallel, depending on the matrix it is based
+ * on. In general, an incomplete factorization does not take all fill-in
+ * elements that would appear in a full factorization (that is the basis for
+ * a direct solve). Trilinos allows to set the amount of fill-in elements,
+ * governed by the additional data argument <tt>ic_fill</tt>, so one can
+ * gradually choose between a factorization on the sparse matrix structure
+ * only (<tt>ic_fill=0</tt>) to a full factorization (<tt>ic_fill</tt> in
+ * the range of 10 to 50, depending on the spatial dimension of the PDE
+ * problem and the degree of the finite element basis functions; generally,
+ * more required fill-in elements require this parameter to be set to a
+ * higher integer value).
*
- * The AdditionalData data structure allows to set preconditioner
- * options. Besides the fill-in argument, these options are some
- * options for perturbations (see the documentation of the
- * AdditionalData structure for details), and a parameter
- * <tt>overlap</tt> that determines if and how much overlap there
- * should be between the matrix partitions on the various MPI
- * processes. The default settings are 0 for the additional fill-in, 0
- * for the absolute augmentation tolerance, 1 for the relative
- * augmentation tolerance, 0 for the overlap.
+ * The AdditionalData data structure allows to set preconditioner options.
+ * Besides the fill-in argument, these options are some options for
+ * perturbations (see the documentation of the AdditionalData structure for
+ * details), and a parameter <tt>overlap</tt> that determines if and how
+ * much overlap there should be between the matrix partitions on the various
+ * MPI processes. The default settings are 0 for the additional fill-in, 0
+ * for the absolute augmentation tolerance, 1 for the relative augmentation
+ * tolerance, 0 for the overlap.
*
- * Note that a parallel application of the IC preconditioner is
- * actually a block-Jacobi preconditioner with block size equal to the
- * local matrix size. Spoken more technically, this parallel operation
- * is an <a
+ * Note that a parallel application of the IC preconditioner is actually a
+ * block-Jacobi preconditioner with block size equal to the local matrix
+ * size. Spoken more technically, this parallel operation is an <a
* href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
- * Schwarz method</a> with an IC <em>approximate solve</em> as inner
- * solver, based on the (outer) parallel partitioning.
+ * Schwarz method</a> with an IC <em>approximate solve</em> as inner solver,
+ * based on the (outer) parallel partitioning.
*
* @ingroup TrilinosWrappers
* @ingroup Preconditioners
/**
- * A wrapper class for an incomplete LU factorization (ILU)
- * preconditioner for Trilinos matrices. This preconditioner works
- * both in serial and in parallel, depending on the matrix it is based
- * on. In general, an incomplete factorization does not take all
- * fill-in elements that would appear in a full factorization (that is
- * the basis for a direct solve). Trilinos allows to set the amount of
- * fill-in elements, governed by the additional data argument
- * <tt>ilu_fill</tt>, so one can gradually choose between a
- * factorization on the sparse matrix structure only
- * (<tt>ilu_fill=0</tt>) to a full factorization (<tt>ilu_fill</tt> in
- * the range of 10 to 50, depending on the spatial dimension of the
- * PDE problem and the degree of the finite element basis functions;
- * generally, more required fill-in elements require this parameter to
- * be set to a higher integer value).
+ * A wrapper class for an incomplete LU factorization (ILU) preconditioner
+ * for Trilinos matrices. This preconditioner works both in serial and in
+ * parallel, depending on the matrix it is based on. In general, an
+ * incomplete factorization does not take all fill-in elements that would
+ * appear in a full factorization (that is the basis for a direct solve).
+ * Trilinos allows to set the amount of fill-in elements, governed by the
+ * additional data argument <tt>ilu_fill</tt>, so one can gradually choose
+ * between a factorization on the sparse matrix structure only
+ * (<tt>ilu_fill=0</tt>) to a full factorization (<tt>ilu_fill</tt> in the
+ * range of 10 to 50, depending on the spatial dimension of the PDE problem
+ * and the degree of the finite element basis functions; generally, more
+ * required fill-in elements require this parameter to be set to a higher
+ * integer value).
*
- * The AdditionalData data structure allows to set preconditioner
- * options. Besides the fill-in argument, these options are some
- * options for perturbations (see the documentation of the
- * AdditionalData structure for details), and a parameter
- * <tt>overlap</tt> that determines if and how much overlap there
- * should be between the matrix partitions on the various MPI
- * processes. The default settings are 0 for the additional fill-in, 0
- * for the absolute augmentation tolerance, 1 for the relative
- * augmentation tolerance, 0 for the overlap.
+ * The AdditionalData data structure allows to set preconditioner options.
+ * Besides the fill-in argument, these options are some options for
+ * perturbations (see the documentation of the AdditionalData structure for
+ * details), and a parameter <tt>overlap</tt> that determines if and how
+ * much overlap there should be between the matrix partitions on the various
+ * MPI processes. The default settings are 0 for the additional fill-in, 0
+ * for the absolute augmentation tolerance, 1 for the relative augmentation
+ * tolerance, 0 for the overlap.
*
- * Note that a parallel application of the ILU preconditioner is
- * actually a block-Jacobi preconditioner with block size equal to the
- * local matrix size. Spoken more technically, this parallel operation
- * is an <a
+ * Note that a parallel application of the ILU preconditioner is actually a
+ * block-Jacobi preconditioner with block size equal to the local matrix
+ * size. Spoken more technically, this parallel operation is an <a
* href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
* Schwarz method</a> with an ILU <em>approximate solve</em> as inner
* solver, based on the (outer) parallel partitioning.
* lets the user specify which elements should be dropped (i.e., should not
* be part of the incomplete decomposition). Trilinos calculates first the
* complete factorization for one row, and then skips those elements that
- * are lower than the threshold. This is the main difference to the
- * non-thresholded ILU preconditioner, where the parameter
- * <tt>ilut_fill</tt> governs the incomplete factorization structure. This
- * parameter is available here as well, but provides only some extra
- * information here.
+ * are lower than the threshold. This is the main difference to the non-
+ * thresholded ILU preconditioner, where the parameter <tt>ilut_fill</tt>
+ * governs the incomplete factorization structure. This parameter is
+ * available here as well, but provides only some extra information here.
*
- * The AdditionalData data structure allows to set preconditioner
- * options. Besides the fill-in arguments, these options are some options
- * for perturbations (see the documentation of the AdditionalData structure
- * for details), and a parameter <tt>overlap</tt> that determines if and how
+ * The AdditionalData data structure allows to set preconditioner options.
+ * Besides the fill-in arguments, these options are some options for
+ * perturbations (see the documentation of the AdditionalData structure for
+ * details), and a parameter <tt>overlap</tt> that determines if and how
* much overlap there should be between the matrix partitions on the various
* MPI processes. The default settings are 0 for the additional fill-in, 0
* for the absolute augmentation tolerance, 1 for the relative augmentation
* tolerance, 0 for the overlap.
*
- * Note that a parallel application of the ILU-T preconditioner is
- * actually a block-Jacobi preconditioner with block size equal to the
- * local matrix size. Spoken more technically, this parallel operation
- * is an <a
+ * Note that a parallel application of the ILU-T preconditioner is actually
+ * a block-Jacobi preconditioner with block size equal to the local matrix
+ * size. Spoken more technically, this parallel operation is an <a
* href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
* Schwarz method</a> with an ILU <em>approximate solve</em> as inner
* solver, based on the (outer) parallel partitioning.
public:
/**
* Standardized data struct to pipe additional parameters to the
- * preconditioner. The Trilinos ILU-T decomposition allows for some
- * fill-in, so it actually is a threshold incomplete LU factorization. The
+ * preconditioner. The Trilinos ILU-T decomposition allows for some fill-
+ * in, so it actually is a threshold incomplete LU factorization. The
* amount of fill-in, and hence, the amount of memory used by this
* preconditioner, is controlled by the parameters <tt>ilut_drop</tt> and
* <tt>ilut_fill</tt>, which specifies a threshold about which values
/**
- * A wrapper class for a sparse direct LU decomposition on parallel
- * blocks for Trilinos matrices. When run in serial, this corresponds
- * to a direct solve on the matrix.
+ * A wrapper class for a sparse direct LU decomposition on parallel blocks
+ * for Trilinos matrices. When run in serial, this corresponds to a direct
+ * solve on the matrix.
*
- * The AdditionalData data structure allows to set preconditioner
- * options.
+ * The AdditionalData data structure allows to set preconditioner options.
*
- * Note that a parallel application of the block direct solve
- * preconditioner is actually a block-Jacobi preconditioner with block
- * size equal to the local matrix size. Spoken more technically, this
- * parallel operation is an <a
- * href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
- * Schwarz method</a> with an <em>exact solve</em> as inner solver,
- * based on the (outer) parallel partitioning.
+ * Note that a parallel application of the block direct solve preconditioner
+ * is actually a block-Jacobi preconditioner with block size equal to the
+ * local matrix size. Spoken more technically, this parallel operation is an
+ * <a href="http://en.wikipedia.org/wiki/Additive_Schwarz_method">additive
+ * Schwarz method</a> with an <em>exact solve</em> as inner solver, based on
+ * the (outer) parallel partitioning.
*
* @ingroup TrilinosWrappers
* @ingroup Preconditioners
/**
* A wrapper class for a Chebyshev preconditioner for Trilinos matrices.
*
- * The AdditionalData data structure allows to set preconditioner
- * options.
+ * The AdditionalData data structure allows to set preconditioner options.
*
* @ingroup TrilinosWrappers
* @ingroup Preconditioners
* processors.
*
* For proper functionality of this class we recommend using Trilinos v9.0
- * and higher. Older versions may have problems with generating the
- * coarse-matrix structure when using matrices with many nonzero entries per
- * row (i.e., matrices stemming from higher order finite element
+ * and higher. Older versions may have problems with generating the coarse-
+ * matrix structure when using matrices with many nonzero entries per row
+ * (i.e., matrices stemming from higher order finite element
* discretizations).
*
* @ingroup TrilinosWrappers
/**
* A data structure that is used to control details of how the algebraic
- * multigrid is set up. The flags detailed in here are then passed to
- * the Trilinos ML implementation. A structure of the current type are
- * passed to the constructor of PreconditionAMG.
+ * multigrid is set up. The flags detailed in here are then passed to the
+ * Trilinos ML implementation. A structure of the current type are passed
+ * to the constructor of PreconditionAMG.
*/
struct AdditionalData
{
/**
* Determines whether the AMG preconditioner should be optimized for
* elliptic problems (ML option smoothed aggregation SA, using a
- * Chebyshev smoother) or for non-elliptic problems (ML option
- * non-symmetric smoothed aggregation NSSA, smoother is SSOR with
+ * Chebyshev smoother) or for non-elliptic problems (ML option non-
+ * symmetric smoothed aggregation NSSA, smoother is SSOR with
* underrelaxation).
*/
bool elliptic;
bool output_details;
/**
- * Determines which smoother to use for the AMG cycle. Possibilities
- * for smoother_type are the following:
+ * Determines which smoother to use for the AMG cycle. Possibilities for
+ * smoother_type are the following:
* <ul>
- * <li> "Aztec" </li>
- * <li> "IFPACK" </li>
- * <li> "Jacobi" </li>
- * <li> "ML symmetric Gauss-Seidel" </li>
- * <li> "symmetric Gauss-Seidel" </li>
- * <li> "ML Gauss-Seidel" </li>
- * <li> "Gauss-Seidel" </li>
- * <li> "block Gauss-Seidel" </li>
- * <li> "symmetric block Gauss-Seidel" </li>
- * <li> "Chebyshev" </li>
- * <li> "MLS" </li>
- * <li> "Hiptmair" </li>
- * <li> "Amesos-KLU" </li>
- * <li> "Amesos-Superlu" </li>
- * <li> "Amesos-UMFPACK" </li>
- * <li> "Amesos-Superludist" </li>
- * <li> "Amesos-MUMPS" </li>
- * <li> "user-defined" </li>
- * <li> "SuperLU" </li>
- * <li> "IFPACK-Chebyshev" </li>
- * <li> "self" </li>
- * <li> "do-nothing" </li>
- * <li> "IC" </li>
- * <li> "ICT" </li>
- * <li> "ILU" </li>
- * <li> "ILUT" </li>
- * <li> "Block Chebyshev" </li>
- * <li> "IFPACK-Block Chebyshev" </li>
+ * <li> "Aztec" </li>
+ * <li> "IFPACK" </li>
+ * <li> "Jacobi" </li>
+ * <li> "ML symmetric Gauss-Seidel" </li>
+ * <li> "symmetric Gauss-Seidel" </li>
+ * <li> "ML Gauss-Seidel" </li>
+ * <li> "Gauss-Seidel" </li>
+ * <li> "block Gauss-Seidel" </li>
+ * <li> "symmetric block Gauss-Seidel" </li>
+ * <li> "Chebyshev" </li>
+ * <li> "MLS" </li>
+ * <li> "Hiptmair" </li>
+ * <li> "Amesos-KLU" </li>
+ * <li> "Amesos-Superlu" </li>
+ * <li> "Amesos-UMFPACK" </li>
+ * <li> "Amesos-Superludist" </li>
+ * <li> "Amesos-MUMPS" </li>
+ * <li> "user-defined" </li>
+ * <li> "SuperLU" </li>
+ * <li> "IFPACK-Chebyshev" </li>
+ * <li> "self" </li>
+ * <li> "do-nothing" </li>
+ * <li> "IC" </li>
+ * <li> "ICT" </li>
+ * <li> "ILU" </li>
+ * <li> "ILUT" </li>
+ * <li> "Block Chebyshev" </li>
+ * <li> "IFPACK-Block Chebyshev" </li>
* </ul>
*/
const char *smoother_type;
const VectorBase &src) const;
/**
- * Apply the preconditioner on deal.II data structures
- * instead of the ones provided in the Trilinos wrapper class,
- * i.e., dst = src.
+ * Apply the preconditioner on deal.II data structures instead of the ones
+ * provided in the Trilinos wrapper class, i.e., dst = src.
*/
void vmult (dealii::Vector<double> &dst,
const dealii::Vector<double> &src) const;
/**
- * Apply the transpose preconditioner on deal.II data structures
- * instead of the ones provided in the Trilinos wrapper class,
- * i.e. dst = src.
+ * Apply the transpose preconditioner on deal.II data structures instead
+ * of the ones provided in the Trilinos wrapper class, i.e. dst = src.
*/
void Tvmult (dealii::Vector<double> &dst,
const dealii::Vector<double> &src) const;
/**
- * Apply the preconditioner on deal.II parallel data structures
- * instead of the ones provided in the Trilinos wrapper class,
- * i.e., dst = src.
+ * Apply the preconditioner on deal.II parallel data structures instead of
+ * the ones provided in the Trilinos wrapper class, i.e., dst = src.
*/
void vmult (parallel::distributed::Vector<double> &dst,
const dealii::parallel::distributed::Vector<double> &src) const;
/**
* Apply the transpose preconditioner on deal.II parallel data structures
- * instead of the ones provided in the Trilinos wrapper class,
- * i.e., dst = src.
+ * instead of the ones provided in the Trilinos wrapper class, i.e., dst =
+ * src.
*/
void Tvmult (parallel::distributed::Vector<double> &dst,
const dealii::parallel::distributed::Vector<double> &src) const;
/**
- * Base class for solver classes using the Trilinos solvers. Since
- * solvers in Trilinos are selected based on flags passed to a generic
- * solver object, basically all the actual solver calls happen in this
- * class, and derived classes simply set the right flags to select one
- * solver or another, or to set certain parameters for individual
- * solvers. For a general discussion on the Trilinos solver package
- * AztecOO, we refer to the <a href =
- * "http://trilinos.sandia.gov/packages/aztecoo/AztecOOUserGuide.pdf">AztecOO
- * user guide</a>.
+ * Base class for solver classes using the Trilinos solvers. Since solvers
+ * in Trilinos are selected based on flags passed to a generic solver
+ * object, basically all the actual solver calls happen in this class, and
+ * derived classes simply set the right flags to select one solver or
+ * another, or to set certain parameters for individual solvers. For a
+ * general discussion on the Trilinos solver package AztecOO, we refer to
+ * the <a href = "http://trilinos.sandia.gov/packages/aztecoo/AztecOOUserGui
+ * de.pdf">AztecOO user guide</a>.
*
* This solver class can also be used as a standalone class, where the
- * respective Krylov method is set via the flag
- * <tt>solver_name</tt>. This can be done at runtime (e.g., when
- * parsing the solver from a ParameterList) and is similar to the
- * deal.II class SolverSelector.
+ * respective Krylov method is set via the flag <tt>solver_name</tt>. This
+ * can be done at runtime (e.g., when parsing the solver from a
+ * ParameterList) and is similar to the deal.II class SolverSelector.
*
* @ingroup TrilinosWrappers
* @author Martin Kronbichler, 2008, 2009
enum SolverName {cg, cgs, gmres, bicgstab, tfqmr} solver_name;
/**
- * Standardized data struct to
- * pipe additional data to the
- * solver.
+ * Standardized data struct to pipe additional data to the solver.
*/
struct AdditionalData
const PreconditionBase &preconditioner);
/**
- * Solve the linear system <tt>Ax=b</tt> where <tt>A</tt> is an
- * operator. This function can be used for matrix free
- * computation. Depending on the information provided by derived classes
- * and the object passed as a preconditioner, one of the linear solvers
- * and preconditioners of Trilinos is chosen.
+ * Solve the linear system <tt>Ax=b</tt> where <tt>A</tt> is an operator.
+ * This function can be used for matrix free computation. Depending on the
+ * information provided by derived classes and the object passed as a
+ * preconditioner, one of the linear solvers and preconditioners of
+ * Trilinos is chosen.
*/
void
solve (Epetra_Operator &A,
/**
* Solve the linear system <tt>Ax=b</tt>. Depending on the information
* provided by derived classes and the object passed as a preconditioner,
- * one of the linear solvers and preconditioners of Trilinos is
- * chosen. This class works with matrices according to the
- * TrilinosWrappers format, but can take deal.II vectors as
- * argument. Since deal.II are serial vectors (not distributed), this
- * function does only what you expect in case the matrix is locally
- * owned. Otherwise, an exception will be thrown.
+ * one of the linear solvers and preconditioners of Trilinos is chosen.
+ * This class works with matrices according to the TrilinosWrappers
+ * format, but can take deal.II vectors as argument. Since deal.II are
+ * serial vectors (not distributed), this function does only what you
+ * expect in case the matrix is locally owned. Otherwise, an exception
+ * will be thrown.
*/
void
solve (const SparseMatrix &A,
const PreconditionBase &preconditioner);
/**
- * Solve the linear system <tt>Ax=b</tt> where <tt>A</tt> is an
- * operator. This function can be used for matrix free
- * computations. Depending on the information provided by derived classes
- * and the object passed as a preconditioner, one of the linear solvers
- * and preconditioners of Trilinos is chosen. This class works with
- * matrices according to the TrilinosWrappers format, but can take deal.II
- * vectors as argument. Since deal.II are serial vectors (not
- * distributed), this function does only what you expect in case the
- * matrix is locally owned. Otherwise, an exception will be thrown.
+ * Solve the linear system <tt>Ax=b</tt> where <tt>A</tt> is an operator.
+ * This function can be used for matrix free computations. Depending on
+ * the information provided by derived classes and the object passed as a
+ * preconditioner, one of the linear solvers and preconditioners of
+ * Trilinos is chosen. This class works with matrices according to the
+ * TrilinosWrappers format, but can take deal.II vectors as argument.
+ * Since deal.II are serial vectors (not distributed), this function does
+ * only what you expect in case the matrix is locally owned. Otherwise, an
+ * exception will be thrown.
*/
void
solve (Epetra_Operator &A,
const PreconditionBase &preconditioner);
/**
- * Solve the linear system <tt>Ax=b</tt> where <tt>A</tt> is an
- * operator. This function can be used for matrix free
- * computation. Depending on the information provided by derived classes
- * and the object passed as a preconditioner, one of the linear solvers
- * and preconditioners of Trilinos is chosen.
+ * Solve the linear system <tt>Ax=b</tt> where <tt>A</tt> is an operator.
+ * This function can be used for matrix free computation. Depending on the
+ * information provided by derived classes and the object passed as a
+ * preconditioner, one of the linear solvers and preconditioners of
+ * Trilinos is chosen.
*/
void
solve (Epetra_Operator &A,
/**
- * An implementation of the solver interface using the Trilinos CG
- * solver.
+ * An implementation of the solver interface using the Trilinos CG solver.
*
* @ingroup TrilinosWrappers
* @author Martin Kronbichler, 2008
/**
- * An implementation of the solver interface using the Trilinos CGS
- * solver.
+ * An implementation of the solver interface using the Trilinos CGS solver.
*
* @ingroup TrilinosWrappers
* @author Martin Kronbichler, 2008
/**
- * An implementation of Trilinos direct solvers (using the Amesos
- * package). The data field AdditionalData::solver_type can be used to
- * specify the type of solver. It allows the use of built-in solvers
- * Amesos_Klu as well as third-party solvers Amesos_Superludist or
- * Amesos_Mumps.
+ * An implementation of Trilinos direct solvers (using the Amesos package).
+ * The data field AdditionalData::solver_type can be used to specify the
+ * type of solver. It allows the use of built-in solvers Amesos_Klu as well
+ * as third-party solvers Amesos_Superludist or Amesos_Mumps.
*
- * For instructions on how to install Trilinos for use with
- * direct solvers other than KLU, see the link to the Trilinos
- * installation instructions linked to from the deal.II ReadMe file.
+ * For instructions on how to install Trilinos for use with direct solvers
+ * other than KLU, see the link to the Trilinos installation instructions
+ * linked to from the deal.II ReadMe file.
*
* @ingroup TrilinosWrappers
* @author Martin Kronbichler, 2009, Uwe Köcher, 2014
* Set the solver type (for third party solver support of Trilinos
* Amesos package). Possibilities are:
* <ul>
- * <li> "Amesos_Lapack" </li>
- * <li> "Amesos_Scalapack" </li>
- * <li> "Amesos_Klu" </li>
- * <li> "Amesos_Umfpack" </li>
- * <li> "Amesos_Pardiso" </li>
- * <li> "Amesos_Taucs" </li>
- * <li> "Amesos_Superlu" </li>
- * <li> "Amesos_Superludist" </li>
- * <li> "Amesos_Dscpack" </li>
- * <li> "Amesos_Mumps" </li>
+ * <li> "Amesos_Lapack" </li>
+ * <li> "Amesos_Scalapack" </li>
+ * <li> "Amesos_Klu" </li>
+ * <li> "Amesos_Umfpack" </li>
+ * <li> "Amesos_Pardiso" </li>
+ * <li> "Amesos_Taucs" </li>
+ * <li> "Amesos_Superlu" </li>
+ * <li> "Amesos_Superludist" </li>
+ * <li> "Amesos_Dscpack" </li>
+ * <li> "Amesos_Mumps" </li>
* </ul>
* Note that the availability of these solvers in deal.II depends on
* which solvers were set when configuring Trilinos.
const dealii::parallel::distributed::Vector<double> &b);
/**
- * Access to object that controls
- * convergence.
+ * Access to object that controls convergence.
*/
SolverControl &control() const;
/**
* General template for sparse matrix accessors. The first template
- * argument denotes the underlying numeric type, the second the
- * constness of the matrix.
+ * argument denotes the underlying numeric type, the second the constness
+ * of the matrix.
*
- * The general template is not implemented, only the specializations
- * for the two possible values of the second template
- * argument. Therefore, the interface listed here only serves as a
- * template provided since doxygen does not link the specializations.
+ * The general template is not implemented, only the specializations for
+ * the two possible values of the second template argument. Therefore, the
+ * interface listed here only serves as a template provided since doxygen
+ * does not link the specializations.
*/
template <bool Constess>
class Accessor : public AccessorBase
{
/**
- * Value of this matrix entry.
- */
+ * Value of this matrix entry.
+ */
TrilinosScalar value() const;
/**
};
/**
- * STL conforming iterator. This class acts as an iterator walking
- * over the elements of Trilinos matrices. The implementation of this
- * class is similar to the one for PETSc matrices.
+ * STL conforming iterator. This class acts as an iterator walking over
+ * the elements of Trilinos matrices. The implementation of this class is
+ * similar to the one for PETSc matrices.
*
* Note that Trilinos stores the elements within each row in ascending
* order. This is opposed to the deal.II sparse matrix style where the
/**
- * This class implements a wrapper to use the Trilinos distributed
- * sparse matrix class Epetra_FECrsMatrix. This is precisely the kind of
- * matrix we deal with all the time - we most likely get it from some
- * assembly process, where also entries not locally owned might need to
- * be written and hence need to be forwarded to the owner process. This
- * class is designed to be used in a distributed memory architecture
- * with an MPI compiler on the bottom, but works equally well also for
- * serial processes. The only requirement for this class to work is that
- * Trilinos has been installed with the same compiler as is used for
- * generating deal.II.
+ * This class implements a wrapper to use the Trilinos distributed sparse
+ * matrix class Epetra_FECrsMatrix. This is precisely the kind of matrix we
+ * deal with all the time - we most likely get it from some assembly
+ * process, where also entries not locally owned might need to be written
+ * and hence need to be forwarded to the owner process. This class is
+ * designed to be used in a distributed memory architecture with an MPI
+ * compiler on the bottom, but works equally well also for serial processes.
+ * The only requirement for this class to work is that Trilinos has been
+ * installed with the same compiler as is used for generating deal.II.
*
- * The interface of this class is modeled after the existing
- * SparseMatrix class in deal.II. It has almost the same member
- * functions, and is often exchangable. However, since Trilinos only
- * supports a single scalar type (double), it is not templated, and only
- * works with doubles.
+ * The interface of this class is modeled after the existing SparseMatrix
+ * class in deal.II. It has almost the same member functions, and is often
+ * exchangable. However, since Trilinos only supports a single scalar type
+ * (double), it is not templated, and only works with doubles.
*
- * Note that Trilinos only guarantees that operations do what you expect
- * if the functions @p GlobalAssemble has been called after matrix
- * assembly. Therefore, you need to call SparseMatrix::compress()
- * before you actually use the matrix. This also calls @p FillComplete
- * that compresses the storage format for sparse matrices by discarding
- * unused elements. Trilinos allows to continue with assembling the
- * matrix after calls to these functions, though.
+ * Note that Trilinos only guarantees that operations do what you expect if
+ * the functions @p GlobalAssemble has been called after matrix assembly.
+ * Therefore, you need to call SparseMatrix::compress() before you actually
+ * use the matrix. This also calls @p FillComplete that compresses the
+ * storage format for sparse matrices by discarding unused elements.
+ * Trilinos allows to continue with assembling the matrix after calls to
+ * these functions, though.
*
* <h3>Thread safety of Trilinos matrices</h3>
*
* rows of the matrix from several threads simultaneously under the
* following three conditions:
* <ul>
- * <li> The matrix uses only one MPI process.
- * <li> The matrix has been initialized with the reinit() method
- * with a CompressedSimpleSparsityPattern (that includes the set of locally
- * relevant rows, i.e., the rows that an assembly routine will possibly
- * write into).
- * <li> The matrix has been initialized from a
- * TrilinosWrappers::SparsityPattern object that in turn has been
- * initialized with the reinit function specifying three index sets, one
- * for the rows, one for the columns and for the larger set of @p
- * writeable_rows, and the operation is an addition. At some point in the
- * future, Trilinos support might be complete enough such that initializing
- * from a
- * TrilinosWrappers::SparsityPattern that has been filled by a function
- * similar to DoFTools::make_sparsity_pattern always results in a matrix
- * that allows several processes to write into the same matrix row. However,
- * Trilinos until version at least 11.12 does not correctly support this
- * feature.
+ * <li> The matrix uses only one MPI process.
+ * <li> The matrix has been initialized with the reinit() method with a
+ * CompressedSimpleSparsityPattern (that includes the set of locally
+ * relevant rows, i.e., the rows that an assembly routine will possibly
+ * write into).
+ * <li> The matrix has been initialized from a
+ * TrilinosWrappers::SparsityPattern object that in turn has been
+ * initialized with the reinit function specifying three index sets, one for
+ * the rows, one for the columns and for the larger set of @p
+ * writeable_rows, and the operation is an addition. At some point in the
+ * future, Trilinos support might be complete enough such that initializing
+ * from a TrilinosWrappers::SparsityPattern that has been filled by a
+ * function similar to DoFTools::make_sparsity_pattern always results in a
+ * matrix that allows several processes to write into the same matrix row.
+ * However, Trilinos until version at least 11.12 does not correctly support
+ * this feature.
* </ul>
*
* Note that all other reinit methods and constructors of
* meant for use in serial programs, where there is no need to specify how
* the matrix is going to be distributed among different processors. This
* function works in %parallel, too, but it is recommended to manually
- * specify the %parallel partioning of the matrix using an
- * Epetra_Map. When run in %parallel, it is currently necessary that each
- * processor holds the sparsity_pattern structure because each processor
- * sets its rows.
+ * specify the %parallel partioning of the matrix using an Epetra_Map.
+ * When run in %parallel, it is currently necessary that each processor
+ * holds the sparsity_pattern structure because each processor sets its
+ * rows.
*
* This is a collective operation that needs to be called on all
* processors in order to avoid a dead lock.
* processors in order to avoid a deadlock.
*
* @note If a different sparsity pattern is given in the last argument
- * (i.e., one that differs from the one used in the sparse matrix given
- * in the first argument), then the resulting Trilinos matrix will have
- * the sparsity pattern so given. This of course also means that all
- * entries in the given matrix that are not part of this separate
- * sparsity pattern will in fact be dropped.
+ * (i.e., one that differs from the one used in the sparse matrix given in
+ * the first argument), then the resulting Trilinos matrix will have the
+ * sparsity pattern so given. This of course also means that all entries
+ * in the given matrix that are not part of this separate sparsity pattern
+ * will in fact be dropped.
*/
template <typename number>
void reinit (const ::dealii::SparseMatrix<number> &dealii_sparse_matrix,
*/
//@{
/**
- * Constructor using an Epetra_Map to describe the %parallel
- * partitioning. The parameter @p n_max_entries_per_row sets the number of
- * nonzero entries in each row that will be allocated. Note that this
- * number does not need to be exact, and it is even allowed that the
- * actual matrix structure has more nonzero entries than specified in the
- * constructor. However it is still advantageous to provide good estimates
- * here since this will considerably increase the performance of the
- * matrix setup. However, there is no effect in the performance of
- * matrix-vector products, since Trilinos reorganizes the matrix memory
- * prior to use (in the compress() step).
+ * Constructor using an Epetra_Map to describe the %parallel partitioning.
+ * The parameter @p n_max_entries_per_row sets the number of nonzero
+ * entries in each row that will be allocated. Note that this number does
+ * not need to be exact, and it is even allowed that the actual matrix
+ * structure has more nonzero entries than specified in the constructor.
+ * However it is still advantageous to provide good estimates here since
+ * this will considerably increase the performance of the matrix setup.
+ * However, there is no effect in the performance of matrix-vector
+ * products, since Trilinos reorganizes the matrix memory prior to use (in
+ * the compress() step).
*/
SparseMatrix (const Epetra_Map ¶llel_partitioning,
const size_type n_max_entries_per_row = 0);
/**
- * Same as before, but now set a value of nonzeros for each matrix
- * row. Since we know the number of elements in the matrix exactly in this
+ * Same as before, but now set a value of nonzeros for each matrix row.
+ * Since we know the number of elements in the matrix exactly in this
* case, we can already allocate the right amount of memory, which makes
* the creation process including the insertion of nonzero elements by the
* respective SparseMatrix::reinit call considerably faster.
* programs following the style of the tutorial programs, this function
* (and the respective call for a rectangular matrix) are the natural way
* to initialize the matrix size, its distribution among the MPI processes
- * (if run in %parallel) as well as the locatoin of non-zero
- * elements. Trilinos stores the sparsity pattern internally, so it won't
- * be needed any more after this call, in contrast to the deal.II own
- * object. The optional argument @p exchange_data can be used for
- * reinitialization with a sparsity pattern that is not fully
- * constructed. This feature is only implemented for input sparsity
- * patterns of type CompressedSimpleSparsityPattern. If the flag is not
- * set, each processor just sets the elements in the sparsity pattern that
- * belong to its rows.
+ * (if run in %parallel) as well as the locatoin of non-zero elements.
+ * Trilinos stores the sparsity pattern internally, so it won't be needed
+ * any more after this call, in contrast to the deal.II own object. The
+ * optional argument @p exchange_data can be used for reinitialization
+ * with a sparsity pattern that is not fully constructed. This feature is
+ * only implemented for input sparsity patterns of type
+ * CompressedSimpleSparsityPattern. If the flag is not set, each processor
+ * just sets the elements in the sparsity pattern that belong to its rows.
*
* If the sparsity pattern given to this function is of type
* CompressedSimpleSparsity pattern, then a matrix will be created that
* actual matrix structure has more nonzero entries than specified in the
* constructor. However it is still advantageous to provide good estimates
* here since this will considerably increase the performance of the
- * matrix setup. However, there is no effect in the performance of
- * matrix-vector products, since Trilinos reorganizes the matrix memory
- * prior to use (in the compress() step).
+ * matrix setup. However, there is no effect in the performance of matrix-
+ * vector products, since Trilinos reorganizes the matrix memory prior to
+ * use (in the compress() step).
*/
SparseMatrix (const IndexSet ¶llel_partitioning,
const MPI_Comm &communicator = MPI_COMM_WORLD,
* in matrix-vector products.
* <li> If the matrix structure has already been fixed (either by
* initialization with a sparsity pattern or by calling compress() during
- * the setup phase), this command does the %parallel exchange of
- * data. This is necessary when we perform assembly on more than one (MPI)
+ * the setup phase), this command does the %parallel exchange of data.
+ * This is necessary when we perform assembly on more than one (MPI)
* process, because then some non-local row data will accumulate on nodes
* that belong to the current's processor element, but are actually held
* by another. This command is usually called after all elements have been
* </ul>
*
* In both cases, this function compresses the data structures and allows
- * the resulting matrix to be used in all other operations like
- * matrix-vector products. This is a collective operation, i.e., it needs
- * to be run on all processors when used in %parallel.
+ * the resulting matrix to be used in all other operations like matrix-
+ * vector products. This is a collective operation, i.e., it needs to be
+ * run on all processors when used in %parallel.
*
- * See @ref GlossCompress "Compressing distributed objects"
- * for more information.
+ * See @ref GlossCompress "Compressing distributed objects" for more
+ * information.
*/
void compress (::dealii::VectorOperation::values operation);
*
* Just as the respective call in deal.II SparseMatrix<Number> class (but
* in contrast to the situation for PETSc based matrices), this function
- * throws an exception if an entry does not exist in the sparsity
- * pattern. Moreover, if <tt>value</tt> is not a finite number an
- * exception is thrown.
+ * throws an exception if an entry does not exist in the sparsity pattern.
+ * Moreover, if <tt>value</tt> is not a finite number an exception is
+ * thrown.
*/
void add (const size_type i,
const size_type j,
SparseMatrix &operator /= (const TrilinosScalar factor);
/**
- * Copy the given (Trilinos) matrix
- * (sparsity pattern and entries).
+ * Copy the given (Trilinos) matrix (sparsity pattern and entries).
*/
void copy_from (const SparseMatrix &source);
/**
* Return the value of the entry (<i>i,j</i>). This may be an expensive
- * operation and you should always take care where to call this
- * function. As in the deal.II sparse matrix class, we throw an exception
- * if the respective entry doesn't exist in the sparsity pattern of this
- * class, which is requested from Trilinos. Moreover, an exception will be
- * thrown when the requested element is not saved on the calling process.
+ * operation and you should always take care where to call this function.
+ * As in the deal.II sparse matrix class, we throw an exception if the
+ * respective entry doesn't exist in the sparsity pattern of this class,
+ * which is requested from Trilinos. Moreover, an exception will be thrown
+ * when the requested element is not saved on the calling process.
*/
TrilinosScalar operator () (const size_type i,
const size_type j) const;
*
* In case of a localized Vector (i.e., TrilinosWrappers::Vector or
* Vector<double>), this function will only work when running on one
- * processor, since the matrix object is inherently
- * distributed. Otherwise, and exception will be thrown.
+ * processor, since the matrix object is inherently distributed.
+ * Otherwise, and exception will be thrown.
*
*/
template<typename VectorType>
*
* In case of a localized Vector (i.e., TrilinosWrappers::Vector or
* Vector<double>), this function will only work when running on one
- * processor, since the matrix object is inherently
- * distributed. Otherwise, and exception will be thrown.
+ * processor, since the matrix object is inherently distributed.
+ * Otherwise, and exception will be thrown.
*/
template <typename VectorType>
void Tvmult_add (VectorType &dst,
const VectorBase &b) const;
/**
- * Perform the matrix-matrix multiplication <tt>C = A * B</tt>, or, if an
- * optional vector argument is given, <tt>C = A * diag(V) * B</tt>, where
- * <tt>diag(V)</tt> defines a diagonal matrix with the vector entries.
- *
- * This function assumes that the calling matrix <tt>A</tt> and <tt>B</tt>
- * have compatible sizes. The size of <tt>C</tt> will be set within this
- * function.
- *
- * The content as well as the sparsity pattern of the matrix C will be
- * changed by this function, so make sure that the sparsity pattern is not
- * used somewhere else in your program. This is an expensive operation, so
- * think twice before you use this function.
- */
+ * Perform the matrix-matrix multiplication <tt>C = A * B</tt>, or, if an
+ * optional vector argument is given, <tt>C = A * diag(V) * B</tt>, where
+ * <tt>diag(V)</tt> defines a diagonal matrix with the vector entries.
+ *
+ * This function assumes that the calling matrix <tt>A</tt> and <tt>B</tt>
+ * have compatible sizes. The size of <tt>C</tt> will be set within this
+ * function.
+ *
+ * The content as well as the sparsity pattern of the matrix C will be
+ * changed by this function, so make sure that the sparsity pattern is not
+ * used somewhere else in your program. This is an expensive operation, so
+ * think twice before you use this function.
+ */
void mmult (SparseMatrix &C,
const SparseMatrix &B,
const VectorBase &V = VectorBase()) const;
/**
- * Perform the matrix-matrix multiplication with the transpose of
- * <tt>this</tt>, i.e., <tt>C = A<sup>T</sup> * B</tt>, or, if an optional
- * vector argument is given, <tt>C = A<sup>T</sup> * diag(V) * B</tt>,
- * where <tt>diag(V)</tt> defines a diagonal matrix with the vector
- * entries.
- *
- * This function assumes that the calling matrix <tt>A</tt> and <tt>B</tt>
- * have compatible sizes. The size of <tt>C</tt> will be set within this
- * function.
- *
- * The content as well as the sparsity pattern of the matrix C will be
- * changed by this function, so make sure that the sparsity pattern is not
- * used somewhere else in your program. This is an expensive operation, so
- * think twice before you use this function.
- */
+ * Perform the matrix-matrix multiplication with the transpose of
+ * <tt>this</tt>, i.e., <tt>C = A<sup>T</sup> * B</tt>, or, if an optional
+ * vector argument is given, <tt>C = A<sup>T</sup> * diag(V) * B</tt>,
+ * where <tt>diag(V)</tt> defines a diagonal matrix with the vector
+ * entries.
+ *
+ * This function assumes that the calling matrix <tt>A</tt> and <tt>B</tt>
+ * have compatible sizes. The size of <tt>C</tt> will be set within this
+ * function.
+ *
+ * The content as well as the sparsity pattern of the matrix C will be
+ * changed by this function, so make sure that the sparsity pattern is not
+ * used somewhere else in your program. This is an expensive operation, so
+ * think twice before you use this function.
+ */
void Tmmult (SparseMatrix &C,
const SparseMatrix &B,
const VectorBase &V = VectorBase()) const;
const bool write_extended_trilinos_info = false) const;
//@}
- /** @addtogroup Exceptions
+ /**
+ * @addtogroup Exceptions
*
*/
//@{
protected:
/**
- * For some matrix storage formats, in particular for the PETSc distributed
- * blockmatrices, set and add operations on individual elements can not be
- * freely mixed. Rather, one has to synchronize operations when one wants
- * to switch from setting elements to adding to elements. BlockMatrixBase
- * automatically synchronizes the access by calling this helper function
- * for each block. This function ensures that the matrix is in a state
- * that allows adding elements; if it previously already was in this state,
- * the function does nothing.
- */
+ * For some matrix storage formats, in particular for the PETSc
+ * distributed blockmatrices, set and add operations on individual
+ * elements can not be freely mixed. Rather, one has to synchronize
+ * operations when one wants to switch from setting elements to adding to
+ * elements. BlockMatrixBase automatically synchronizes the access by
+ * calling this helper function for each block. This function ensures
+ * that the matrix is in a state that allows adding elements; if it
+ * previously already was in this state, the function does nothing.
+ */
void prepare_add();
/**
- * Same as prepare_add() but prepare the matrix for setting elements if the
- * representation of elements in this class requires such an operation.
- */
+ * Same as prepare_add() but prepare the matrix for setting elements if
+ * the representation of elements in this class requires such an
+ * operation.
+ */
void prepare_set();
std_cxx11::shared_ptr<Epetra_FECrsMatrix> matrix;
/**
- * A sparse matrix object in Trilinos to be used for collecting the
- * non-local elements if the matrix was constructed from a Trilinos
- * sparsity pattern with the respective option.
+ * A sparse matrix object in Trilinos to be used for collecting the non-
+ * local elements if the matrix was constructed from a Trilinos sparsity
+ * pattern with the respective option.
*/
std_cxx11::shared_ptr<Epetra_CrsMatrix> nonlocal_matrix;
bool compressed;
/**
- * To allow calling protected prepare_add() and prepare_set().
+ * To allow calling protected prepare_add() and prepare_set().
*/
friend class BlockMatrixBase<SparseMatrix>;
};
class Iterator;
/**
- * Accessor class for iterators into sparsity patterns. This class is
- * also the base class for both const and non-const accessor classes
- * into sparse matrices.
+ * Accessor class for iterators into sparsity patterns. This class is also
+ * the base class for both const and non-const accessor classes into
+ * sparse matrices.
*
* Note that this class only allows read access to elements, providing
- * their row and column number. It does not allow modifying the
- * sparsity pattern itself.
+ * their row and column number. It does not allow modifying the sparsity
+ * pattern itself.
*
* @ingroup TrilinosWrappers
* @author Wolfgang Bangerth, Martin Kronbichler, Guido Kanschat
};
/**
- * Iterator class for sparsity patterns of type TrilinosWrappers::SparsityPattern.
- * Access to individual elements of the sparsity pattern is handled by the
- * Accessor class in this namespace.
+ * Iterator class for sparsity patterns of type
+ * TrilinosWrappers::SparsityPattern. Access to individual elements of the
+ * sparsity pattern is handled by the Accessor class in this namespace.
*/
class Iterator
{
/**
* This class implements a wrapper class to use the Trilinos distributed
* sparsity pattern class Epetra_FECrsGraph. This class is designed to be
- * used for construction of %parallel Trilinos matrices. The functionality of
- * this class is modeled after the existing sparsity pattern classes, with
- * the difference that this class can work fully in %parallel according to a
- * partitioning of the sparsity pattern rows.
+ * used for construction of %parallel Trilinos matrices. The functionality
+ * of this class is modeled after the existing sparsity pattern classes,
+ * with the difference that this class can work fully in %parallel according
+ * to a partitioning of the sparsity pattern rows.
*
* This class has many similarities to the compressed sparsity pattern
* classes of deal.II (i.e., the classes CompressedSparsityPattern,
typedef dealii::types::global_dof_index size_type;
/**
- * Declare a typedef for the
- * iterator class.
+ * Declare a typedef for the iterator class.
*/
typedef SparsityPatternIterators::Iterator const_iterator;
/**
* Constructor for a square sparsity pattern using an Epetra_map for the
* description of the %parallel partitioning. Moreover, the number of
- * nonzero entries in the rows of the sparsity pattern can be
- * specified. Note that this number does not need to be exact, and it is
- * allowed that the actual sparsity structure has more nonzero entries
- * than specified in the constructor (the usual case when the function
+ * nonzero entries in the rows of the sparsity pattern can be specified.
+ * Note that this number does not need to be exact, and it is allowed that
+ * the actual sparsity structure has more nonzero entries than specified
+ * in the constructor (the usual case when the function
* DoFTools::make_sparsity_pattern() is called). However it is still
* advantageous to provide good estimates here since a good value will
* avoid repeated allocation of memory, which considerably increases the
const size_type n_entries_per_row = 0);
/**
- * Same as before, but now use the exact number of nonzeros in each m
- * row. Since we know the number of elements in the sparsity pattern
- * exactly in this case, we can already allocate the right amount of
- * memory, which makes the creation process by the respective
- * SparsityPattern::reinit call considerably faster. However, this is a
- * rather unusual situation, since knowing the number of entries in each
- * row is usually connected to knowing the indices of nonzero entries,
- * which the sparsity pattern is designed to describe.
+ * Same as before, but now use the exact number of nonzeros in each m row.
+ * Since we know the number of elements in the sparsity pattern exactly in
+ * this case, we can already allocate the right amount of memory, which
+ * makes the creation process by the respective SparsityPattern::reinit
+ * call considerably faster. However, this is a rather unusual situation,
+ * since knowing the number of entries in each row is usually connected to
+ * knowing the indices of nonzero entries, which the sparsity pattern is
+ * designed to describe.
*/
SparsityPattern (const Epetra_Map ¶llel_partitioning,
const std::vector<size_type> &n_entries_per_row);
/**
* Reinitialization function for generating a square sparsity pattern
* using an Epetra_Map for the description of the %parallel partitioning
- * and the number of nonzero entries in the rows of the sparsity
- * pattern. Note that this number does not need to be exact, and it is
- * even allowed that the actual sparsity structure has more nonzero
- * entries than specified in the constructor. However it is still
- * advantageous to provide good estimates here since this will
- * considerably increase the performance when creating the sparsity
- * pattern.
+ * and the number of nonzero entries in the rows of the sparsity pattern.
+ * Note that this number does not need to be exact, and it is even allowed
+ * that the actual sparsity structure has more nonzero entries than
+ * specified in the constructor. However it is still advantageous to
+ * provide good estimates here since this will considerably increase the
+ * performance when creating the sparsity pattern.
*
* This function does not create any entries by itself, but provides the
* correct data structures that can be used by the respective add()
const size_type n_entries_per_row = 0);
/**
- * Same as before, but now use the exact number of nonzeros in each m
- * row. Since we know the number of elements in the sparsity pattern
- * exactly in this case, we can already allocate the right amount of
- * memory, which makes process of adding entries to the sparsity pattern
- * considerably faster. However, this is a rather unusual situation, since
- * knowing the number of entries in each row is usually connected to
- * knowing the indices of nonzero entries, which the sparsity pattern is
- * designed to describe.
+ * Same as before, but now use the exact number of nonzeros in each m row.
+ * Since we know the number of elements in the sparsity pattern exactly in
+ * this case, we can already allocate the right amount of memory, which
+ * makes process of adding entries to the sparsity pattern considerably
+ * faster. However, this is a rather unusual situation, since knowing the
+ * number of entries in each row is usually connected to knowing the
+ * indices of nonzero entries, which the sparsity pattern is designed to
+ * describe.
*/
void
reinit (const Epetra_Map ¶llel_partitioning,
/**
* Constructor for a square sparsity pattern using an IndexSet and an MPI
- * communicator for the description of the %parallel
- * partitioning. Moreover, the number of nonzero entries in the rows of
- * the sparsity pattern can be specified. Note that this number does not
- * need to be exact, and it is even allowed that the actual sparsity
- * structure has more nonzero entries than specified in the
- * constructor. However it is still advantageous to provide good estimates
- * here since a good value will avoid repeated allocation of memory, which
- * considerably increases the performance when creating the sparsity
- * pattern.
+ * communicator for the description of the %parallel partitioning.
+ * Moreover, the number of nonzero entries in the rows of the sparsity
+ * pattern can be specified. Note that this number does not need to be
+ * exact, and it is even allowed that the actual sparsity structure has
+ * more nonzero entries than specified in the constructor. However it is
+ * still advantageous to provide good estimates here since a good value
+ * will avoid repeated allocation of memory, which considerably increases
+ * the performance when creating the sparsity pattern.
*/
SparsityPattern (const IndexSet ¶llel_partitioning,
const MPI_Comm &communicator = MPI_COMM_WORLD,
const size_type n_entries_per_row = 0);
/**
- * Same as before, but now use the exact number of nonzeros in each m
- * row. Since we know the number of elements in the sparsity pattern
- * exactly in this case, we can already allocate the right amount of
- * memory, which makes the creation process by the respective
- * SparsityPattern::reinit call considerably faster. However, this is a
- * rather unusual situation, since knowing the number of entries in each
- * row is usually connected to knowing the indices of nonzero entries,
- * which the sparsity pattern is designed to describe.
+ * Same as before, but now use the exact number of nonzeros in each m row.
+ * Since we know the number of elements in the sparsity pattern exactly in
+ * this case, we can already allocate the right amount of memory, which
+ * makes the creation process by the respective SparsityPattern::reinit
+ * call considerably faster. However, this is a rather unusual situation,
+ * since knowing the number of entries in each row is usually connected to
+ * knowing the indices of nonzero entries, which the sparsity pattern is
+ * designed to describe.
*/
SparsityPattern (const IndexSet ¶llel_partitioning,
const MPI_Comm &communicator,
const std::vector<size_type> &n_entries_per_row);
/**
- * This constructor constructs general sparsity patterns, possible
- * non-square ones. Constructing a sparsity pattern this way allows the
- * user to explicitly specify the rows into which we are going to add
- * elements. This set is required to be a superset of the first index set
- * @p row_parallel_partitioning that includes also rows that are owned by
+ * This constructor constructs general sparsity patterns, possible non-
+ * square ones. Constructing a sparsity pattern this way allows the user
+ * to explicitly specify the rows into which we are going to add elements.
+ * This set is required to be a superset of the first index set @p
+ * row_parallel_partitioning that includes also rows that are owned by
* another processor (ghost rows). Note that elements can only be added to
* rows specified by @p writable_rows.
*
const size_type n_entries_per_row = 0);
/**
- * Same as before, but now use the exact number of nonzeros in each m
- * row. Since we know the number of elements in the sparsity pattern
- * exactly in this case, we can already allocate the right amount of
- * memory, which makes process of adding entries to the sparsity pattern
- * considerably faster. However, this is a rather unusual situation, since
- * knowing the number of entries in each row is usually connected to
- * knowing the indices of nonzero entries, which the sparsity pattern is
- * designed to describe.
+ * Same as before, but now use the exact number of nonzeros in each m row.
+ * Since we know the number of elements in the sparsity pattern exactly in
+ * this case, we can already allocate the right amount of memory, which
+ * makes process of adding entries to the sparsity pattern considerably
+ * faster. However, this is a rather unusual situation, since knowing the
+ * number of entries in each row is usually connected to knowing the
+ * indices of nonzero entries, which the sparsity pattern is designed to
+ * describe.
*/
void
reinit (const IndexSet ¶llel_partitioning,
const size_type n_entries_per_row = 0);
/**
- * This reinit function is used to specify general matrices, possibly
- * non-square ones. In addition to the arguments of the other reinit
- * method above, it allows the user to explicitly specify the rows into
- * which we are going to add elements. This set is a superset of the first
- * index set @p row_parallel_partitioning that includes also rows that are
- * owned by another processor (ghost rows).
+ * This reinit function is used to specify general matrices, possibly non-
+ * square ones. In addition to the arguments of the other reinit method
+ * above, it allows the user to explicitly specify the rows into which we
+ * are going to add elements. This set is a superset of the first index
+ * set @p row_parallel_partitioning that includes also rows that are owned
+ * by another processor (ghost rows).
*
* This method is beneficial when the rows to which a processor is going
* to write can be determined before actually inserting elements into the
* what we call the locally relevant dofs (see
* DoFTools::extract_locally_relevant_dofs). Trilinos matrices allow to
* add elements to arbitrary rows (as done by all the other reinit
- * functions) and this is what all the other reinit methods do,
- * too. However, this flexbility come at a cost, the most prominent being
- * that adding elements into the same matrix from multiple threads in
- * shared memory is not safe whenever MPI is used. For these settings, the
+ * functions) and this is what all the other reinit methods do, too.
+ * However, this flexbility come at a cost, the most prominent being that
+ * adding elements into the same matrix from multiple threads in shared
+ * memory is not safe whenever MPI is used. For these settings, the
* current method is the one to choose: It will store the off-processor
* data as an additional sparsity pattern (that is then passed to the
* Trilinos matrix via the reinit mehtod) which can be organized in such a
/**
* Return a const reference to the underlying Trilinos Epetra_Map that
* sets the partitioning of the range space of this sparsity pattern,
- * i.e., the partitioning of the vectors that are result from
- * matrix-vector products.
+ * i.e., the partitioning of the vectors that are result from matrix-
+ * vector products.
*/
const Epetra_Map &range_partitioner () const;
void print_gnuplot (std::ostream &out) const;
//@}
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* Exception
*/
/**
* A sparsity pattern object for the non-local part of the sparsity
- * pattern that is going to be sent to the owning processor. Only used when the particular constructor or reinit method with writable_rows argument is set
+ * pattern that is going to be sent to the owning processor. Only used
+ * when the particular constructor or reinit method with writable_rows
+ * argument is set
*/
std_cxx11::shared_ptr<Epetra_CrsGraph> nonlocal_graph;
/**
* @addtogroup TrilinosWrappers
- *@{
+ * @{
*/
namespace TrilinosWrappers
{
}
/**
- * Namespace for Trilinos vector classes that work in parallel over
- * MPI. This namespace is restricted to vectors only, whereas matrices
- * are always MPI based when run on more than one processor.
+ * Namespace for Trilinos vector classes that work in parallel over MPI.
+ * This namespace is restricted to vectors only, whereas matrices are always
+ * MPI based when run on more than one processor.
*
* @ingroup TrilinosWrappers
* @author Martin Kronbichler, Wolfgang Bangerth, 2008
class BlockVector;
/**
- * This class implements a wrapper to use the Trilinos distributed
- * vector class Epetra_FEVector. This class is derived from the
+ * This class implements a wrapper to use the Trilinos distributed vector
+ * class Epetra_FEVector. This class is derived from the
* TrilinosWrappers::VectorBase class and provides all functionality
* included there.
*
* Note that Trilinos only guarantees that operations do what you expect
- * if the function @p GlobalAssemble has been called after vector
- * assembly in order to distribute the data. This is necessary since
- * some processes might have accumulated data of elements that are not
- * owned by themselves, but must be sent to the owning process. In order
- * to avoid using the wrong data, you need to call Vector::compress()
- * before you actually use the vectors.
+ * if the function @p GlobalAssemble has been called after vector assembly
+ * in order to distribute the data. This is necessary since some processes
+ * might have accumulated data of elements that are not owned by
+ * themselves, but must be sent to the owning process. In order to avoid
+ * using the wrong data, you need to call Vector::compress() before you
+ * actually use the vectors.
*
* <h3>Parallel communication model</h3>
*
* The parallel functionality of Trilinos is built on top of the Message
* Passing Interface (MPI). MPI's communication model is built on
- * collective communications: if one process wants something from
- * another, that other process has to be willing to accept this
- * communication. A process cannot query data from another process by
- * calling a remote function, without that other process expecting such
- * a transaction. The consequence is that most of the operations in the
- * base class of this class have to be called collectively. For example,
- * if you want to compute the l2 norm of a parallel vector, @em all
- * processes across which this vector is shared have to call the @p
- * l2_norm function. If you don't do this, but instead only call the @p
- * l2_norm function on one process, then the following happens: This one
- * process will call one of the collective MPI functions and wait for
- * all the other processes to join in on this. Since the other processes
- * don't call this function, you will either get a time-out on the first
- * process, or, worse, by the time the next a callto a Trilinos function
- * generates an MPI message on the other processes, you will get a
- * cryptic message that only a subset of processes attempted a
- * communication. These bugs can be very hard to figure out, unless you
- * are well-acquainted with the communication model of MPI, and know
- * which functions may generate MPI messages.
+ * collective communications: if one process wants something from another,
+ * that other process has to be willing to accept this communication. A
+ * process cannot query data from another process by calling a remote
+ * function, without that other process expecting such a transaction. The
+ * consequence is that most of the operations in the base class of this
+ * class have to be called collectively. For example, if you want to
+ * compute the l2 norm of a parallel vector, @em all processes across
+ * which this vector is shared have to call the @p l2_norm function. If
+ * you don't do this, but instead only call the @p l2_norm function on one
+ * process, then the following happens: This one process will call one of
+ * the collective MPI functions and wait for all the other processes to
+ * join in on this. Since the other processes don't call this function,
+ * you will either get a time-out on the first process, or, worse, by the
+ * time the next a callto a Trilinos function generates an MPI message on
+ * the other processes, you will get a cryptic message that only a subset
+ * of processes attempted a communication. These bugs can be very hard to
+ * figure out, unless you are well-acquainted with the communication model
+ * of MPI, and know which functions may generate MPI messages.
*
- * One particular case, where an MPI message may be generated
- * unexpectedly is discussed below.
+ * One particular case, where an MPI message may be generated unexpectedly
+ * is discussed below.
*
*
* <h3>Accessing individual elements of a vector</h3>
*
- * Trilinos does of course allow read access to individual
- * elements of a vector, but in the distributed case only to
- * elements that are stored locally. We implement this through
- * calls like <tt>d=vec(i)</tt>. However, if you access an element
- * outside the locally stored range, an exception is generated.
+ * Trilinos does of course allow read access to individual elements of a
+ * vector, but in the distributed case only to elements that are stored
+ * locally. We implement this through calls like <tt>d=vec(i)</tt>.
+ * However, if you access an element outside the locally stored range, an
+ * exception is generated.
*
* In contrast to read access, Trilinos (and the respective deal.II
* wrapper classes) allow to write (or add) to individual elements of
* vectors, even if they are stored on a different process. You can do
* this by writing into or adding to elements using the syntax
- * <tt>vec(i)=d</tt> or <tt>vec(i)+=d</tt>,
- * or similar operations. There is one catch, however, that may lead to
- * very confusing error messages: Trilinos requires application programs
- * to call the compress() function when they switch from performing a set of
- * operations that add to elements, to performing a set of operations
- * that write to elements. The reasoning is that all processes
- * might accumulate addition operations to elements, even if multiple
- * processes write to the same elements. By the time we call compress()
- * the next time, all these additions are executed. However, if one
- * process adds to an element, and another overwrites to it, the order
- * of execution would yield non-deterministic behavior if we don't make
- * sure that a synchronization with compress() happens in between.
+ * <tt>vec(i)=d</tt> or <tt>vec(i)+=d</tt>, or similar operations. There
+ * is one catch, however, that may lead to very confusing error messages:
+ * Trilinos requires application programs to call the compress() function
+ * when they switch from performing a set of operations that add to
+ * elements, to performing a set of operations that write to elements. The
+ * reasoning is that all processes might accumulate addition operations to
+ * elements, even if multiple processes write to the same elements. By the
+ * time we call compress() the next time, all these additions are
+ * executed. However, if one process adds to an element, and another
+ * overwrites to it, the order of execution would yield non-deterministic
+ * behavior if we don't make sure that a synchronization with compress()
+ * happens in between.
*
* In order to make sure these calls to compress() happen at the
- * appropriate time, the deal.II wrappers keep a state variable that
- * store which is the presently allowed operation: additions or
- * writes. If it encounters an operation of the opposite kind, it calls
- * compress() and flips the state. This can sometimes lead to very
- * confusing behavior, in code that may for example look like this:
+ * appropriate time, the deal.II wrappers keep a state variable that store
+ * which is the presently allowed operation: additions or writes. If it
+ * encounters an operation of the opposite kind, it calls compress() and
+ * flips the state. This can sometimes lead to very confusing behavior, in
+ * code that may for example look like this:
*
* @code
* TrilinosWrappers::Vector vector;
*
* This code can run into trouble: by the time we see the first addition
* operation, we need to flush the overwrite buffers for the vector, and
- * the deal.II library will do so by calling compress(). However, it
- * will only do so for all processes that actually do an addition -- if
- * the condition is never true for one of the processes, then this one
- * will not get to the actual compress() call, whereas all the other
- * ones do. This gets us into trouble, since all the other processes
- * hang in the call to flush the write buffers, while the one other
- * process advances to the call to compute the l2 norm. At this time,
- * you will get an error that some operation was attempted by only a
- * subset of processes. This behavior may seem surprising, unless you
- * know that write/addition operations on single elements may trigger
- * this behavior.
+ * the deal.II library will do so by calling compress(). However, it will
+ * only do so for all processes that actually do an addition -- if the
+ * condition is never true for one of the processes, then this one will
+ * not get to the actual compress() call, whereas all the other ones do.
+ * This gets us into trouble, since all the other processes hang in the
+ * call to flush the write buffers, while the one other process advances
+ * to the call to compute the l2 norm. At this time, you will get an error
+ * that some operation was attempted by only a subset of processes. This
+ * behavior may seem surprising, unless you know that write/addition
+ * operations on single elements may trigger this behavior.
*
* The problem described here may be avoided by placing additional calls
* to compress(), or making sure that all processes do the same type of
* Parallel vectors come in two kinds: without and with ghost elements.
* Vectors without ghost elements uniquely partition the vector elements
* between processors: each vector entry has exactly one processor that
- * owns it. For such vectors, you can read those elements that
- * the processor you are currently on owns, and you can write into
- * any element whether you own it or not: if you don't own it, the
- * value written or added to a vector element will be shipped to the
- * processor that owns this vector element the next time you call
- * compress(), as described above.
+ * owns it. For such vectors, you can read those elements that the
+ * processor you are currently on owns, and you can write into any element
+ * whether you own it or not: if you don't own it, the value written or
+ * added to a vector element will be shipped to the processor that owns
+ * this vector element the next time you call compress(), as described
+ * above.
*
- * What we call a 'ghosted' vector (see
- * @ref GlossGhostedVector "vectors with ghost elements")
- * is simply a view of the
- * parallel vector where the element distributions overlap. The 'ghosted'
- * Trilinos vector in itself has no idea of which entries are ghosted and
- * which are locally owned. In fact, a ghosted vector
- * may not even store all of the elements a non-ghosted vector would
- * store on the current processor. Consequently, for Trilinos vectors,
- * there is no notion of an 'owner' of vector elements in the way we
- * have it in the the non-ghost case view.
+ * What we call a 'ghosted' vector (see @ref GlossGhostedVector "vectors
+ * with ghost elements") is simply a view of the parallel vector where the
+ * element distributions overlap. The 'ghosted' Trilinos vector in itself
+ * has no idea of which entries are ghosted and which are locally owned.
+ * In fact, a ghosted vector may not even store all of the elements a non-
+ * ghosted vector would store on the current processor. Consequently, for
+ * Trilinos vectors, there is no notion of an 'owner' of vector elements
+ * in the way we have it in the the non-ghost case view.
*
* This explains why we do not allow writing into ghosted vectors on the
* Trilinos side: Who would be responsible for taking care of the
* duplicated entries, given that there is not such information as locally
- * owned indices? In other words, since a processor doesn't know which other
- * processors own an element, who would it send a value to if one were to write
- * to it? The only possibility would be to send this information to <i>all</i>
- * other processors, but that is clearly not practical. Thus, we only allow
- * reading from ghosted vectors, which however we do very often.
+ * owned indices? In other words, since a processor doesn't know which
+ * other processors own an element, who would it send a value to if one
+ * were to write to it? The only possibility would be to send this
+ * information to <i>all</i> other processors, but that is clearly not
+ * practical. Thus, we only allow reading from ghosted vectors, which
+ * however we do very often.
*
* So how do you fill a ghosted vector if you can't write to it? This only
- * happens through the assignment with a non-ghosted vector. It can go both ways
- * (non-ghosted is assigned to a ghosted vector, and a ghosted vector is assigned
- * to a non-ghosted one; the latter one typically only requires taking out
- * the locally owned part as most often ghosted vectors store a superset of
- * elements of non-ghosted ones). In general, you send data around with that
- * operation and it all depends on the different views of the two vectors.
- * Trilinos also allows you to get subvectors out of a big vector that way.
+ * happens through the assignment with a non-ghosted vector. It can go
+ * both ways (non-ghosted is assigned to a ghosted vector, and a ghosted
+ * vector is assigned to a non-ghosted one; the latter one typically only
+ * requires taking out the locally owned part as most often ghosted
+ * vectors store a superset of elements of non-ghosted ones). In general,
+ * you send data around with that operation and it all depends on the
+ * different views of the two vectors. Trilinos also allows you to get
+ * subvectors out of a big vector that way.
*
*
* <h3>Thread safety of Trilinos vectors</h3>
* Copy operator from a given localized vector (present on all
* processes) in TrilinosWrappers format to the current distributed
* vector. This function assumes that the calling vector (left hand
- * object) already is of the same size as the right hand side
- * vector. Otherwise, an exception will be thrown.
+ * object) already is of the same size as the right hand side vector.
+ * Otherwise, an exception will be thrown.
*/
Vector &
operator = (const ::dealii::TrilinosWrappers::Vector &V);
* then queried from the input vector. Note that you should not write to
* the resulting vector any more, since the some data can be stored
* several times on different processors, leading to unpredictable
- * results. In particular, such a vector cannot be used for
- * matrix-vector products as for example done during the solution of
- * linear systems.
+ * results. In particular, such a vector cannot be used for matrix-
+ * vector products as for example done during the solution of linear
+ * systems.
*/
void import_nonlocal_data_for_fe
(const dealii::TrilinosWrappers::SparseMatrix &matrix,
* all we need to generate a parallel vector.
*
* Depending on whether the @p parallel_partitioning argument uniquely
- * subdivides elements among processors or not, the resulting vector
- * may or may not have ghost elements. See the general documentation of
- * this class for more information.
+ * subdivides elements among processors or not, the resulting vector may
+ * or may not have ghost elements. See the general documentation of this
+ * class for more information.
*
* @see @ref GlossGhostedVector "vectors with ghost elements"
*/
* sets the partitioning details.
*
* Depending on whether the @p parallel_partitioning argument uniquely
- * subdivides elements among processors or not, the resulting vector
- * may or may not have ghost elements. See the general documentation of
- * this class for more information.
+ * subdivides elements among processors or not, the resulting vector may
+ * or may not have ghost elements. See the general documentation of this
+ * class for more information.
*
* @see @ref GlossGhostedVector "vectors with ghost elements"
*/
* %parallel partitioning.
*
* Depending on whether the @p parallel_partitioning argument uniquely
- * subdivides elements among processors or not, the resulting vector
- * may or may not have ghost elements. See the general documentation of
- * this class for more information.
+ * subdivides elements among processors or not, the resulting vector may
+ * or may not have ghost elements. See the general documentation of this
+ * class for more information.
*
* @see @ref GlossGhostedVector "vectors with ghost elements"
*/
* and generates a new one based on the input map.
*
* Depending on whether the @p parallel_partitioning argument uniquely
- * subdivides elements among processors or not, the resulting vector
- * may or may not have ghost elements. See the general documentation of
- * this class for more information.
+ * subdivides elements among processors or not, the resulting vector may
+ * or may not have ghost elements. See the general documentation of this
+ * class for more information.
*
* @see @ref GlossGhostedVector "vectors with ghost elements"
*/
* the given vector, and copies all elements.
*
* Depending on whether the @p parallel_partitioning argument uniquely
- * subdivides elements among processors or not, the resulting vector
- * may or may not have ghost elements. See the general documentation of
- * this class for more information.
+ * subdivides elements among processors or not, the resulting vector may
+ * or may not have ghost elements. See the general documentation of this
+ * class for more information.
*
* @see @ref GlossGhostedVector "vectors with ghost elements"
*/
* need to generate a %parallel vector.
*
* Depending on whether the @p parallel_partitioning argument uniquely
- * subdivides elements among processors or not, the resulting vector
- * may or may not have ghost elements. See the general documentation of
- * this class for more information.
+ * subdivides elements among processors or not, the resulting vector may
+ * or may not have ghost elements. See the general documentation of this
+ * class for more information.
*
* @see @ref GlossGhostedVector "vectors with ghost elements"
*/
/**
* Creates a ghosted parallel vector.
*
- * Depending on whether the @p ghost argument uniquely
- * subdivides elements among processors or not, the resulting vector
- * may or may not have ghost elements. See the general documentation of
- * this class for more information.
+ * Depending on whether the @p ghost argument uniquely subdivides
+ * elements among processors or not, the resulting vector may or may not
+ * have ghost elements. See the general documentation of this class for
+ * more information.
*
* @see @ref GlossGhostedVector "vectors with ghost elements"
*/
* MPI communicator that set the partitioning details.
*
* Depending on whether the @p parallel_partitioning argument uniquely
- * subdivides elements among processors or not, the resulting vector
- * may or may not have ghost elements. See the general documentation of
- * this class for more information.
+ * subdivides elements among processors or not, the resulting vector may
+ * or may not have ghost elements. See the general documentation of this
+ * class for more information.
*
* @see @ref GlossGhostedVector "vectors with ghost elements"
*/
* the given vector, and copies all the elements.
*
* Depending on whether the @p parallel_partitioning argument uniquely
- * subdivides elements among processors or not, the resulting vector
- * may or may not have ghost elements. See the general documentation of
- * this class for more information.
+ * subdivides elements among processors or not, the resulting vector may
+ * or may not have ghost elements. See the general documentation of this
+ * class for more information.
*
* @see @ref GlossGhostedVector "vectors with ghost elements"
*/
*
*
* Depending on whether the @p parallel_partitioning argument uniquely
- * subdivides elements among processors or not, the resulting vector
- * may or may not have ghost elements. See the general documentation of
- * this class for more information.
+ * subdivides elements among processors or not, the resulting vector may
+ * or may not have ghost elements. See the general documentation of this
+ * class for more information.
*
* @see @ref GlossGhostedVector "vectors with ghost elements"
*/
* Reinit functionality. This function destroys the old vector content
* and generates a new one based on the input partitioning. In addition
* to just specifying one index set as in all the other methods above,
- * this method allows to supply an additional set of ghost
- * entries. There are two different versions of a vector that can be
- * created. If the flag @p vector_writable is set to @p false, the
- * vector only allows read access to the joint set of @p
- * parallel_partitioning and @p ghost_entries. The effect of the reinit
- * method is then equivalent to calling the other reinit method with an
- * index set containing both the locally owned entries and the ghost
- * entries.
+ * this method allows to supply an additional set of ghost entries.
+ * There are two different versions of a vector that can be created. If
+ * the flag @p vector_writable is set to @p false, the vector only
+ * allows read access to the joint set of @p parallel_partitioning and
+ * @p ghost_entries. The effect of the reinit method is then equivalent
+ * to calling the other reinit method with an index set containing both
+ * the locally owned entries and the ghost entries.
*
* If the flag @p vector_writable is set to true, this creates an
* alternative storage scheme for ghost elements that allows multiple
* one thread is allowed to write into the ghost entries at a time).
*
* Depending on whether the @p ghost_entries argument uniquely
- * subdivides elements among processors or not, the resulting vector
- * may or may not have ghost elements. See the general documentation of
- * this class for more information.
+ * subdivides elements among processors or not, the resulting vector may
+ * or may not have ghost elements. See the general documentation of this
+ * class for more information.
*
* @see @ref GlossGhostedVector "vectors with ghost elements"
*/
/**
- * Global function @p swap which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two vectors.
+ * Global function @p swap which overloads the default implementation of
+ * the C++ standard library which uses a temporary object. The function
+ * simply exchanges the data of the two vectors.
*
* @relates TrilinosWrappers::MPI::Vector
* @author Martin Kronbichler, Wolfgang Bangerth, 2008
/**
* This class is a specialization of a Trilinos vector to a localized
- * version. The purpose of this class is to provide a copy interface
- * from the possibly parallel Vector class to a local vector on each
- * processor, in order to be able to access all elements in the vector
- * or to apply certain deal.II functions.
+ * version. The purpose of this class is to provide a copy interface from
+ * the possibly parallel Vector class to a local vector on each processor,
+ * in order to be able to access all elements in the vector or to apply
+ * certain deal.II functions.
*
* @ingroup TrilinosWrappers
* @ingroup Vectors
explicit Vector (const size_type n);
/**
- * This constructor takes as input the number of elements in the
- * vector. If the map is not localized, i.e., if there are some elements
- * that are not present on all processes, only the global size of the map
- * will be taken and a localized map will be generated internally.
- * In other words, which element of the @p partitioning argument
- * are set is in fact ignored, the only thing that matters is the size of
- * the index space described by this argument.
+ * This constructor takes as input the number of elements in the vector.
+ * If the map is not localized, i.e., if there are some elements that are
+ * not present on all processes, only the global size of the map will be
+ * taken and a localized map will be generated internally. In other words,
+ * which element of the @p partitioning argument are set is in fact
+ * ignored, the only thing that matters is the size of the index space
+ * described by this argument.
*/
explicit Vector (const Epetra_Map &partitioning);
/**
- * This constructor takes as input the number of elements in the
- * vector. If the index set is not localized, i.e., if there are some
- * elements that are not present on all processes, only the global size of
- * the index set will be taken and a localized version will be generated
- * internally. In other words, which element of the @p partitioning argument
- * are set is in fact ignored, the only thing that matters is the size of
- * the index space described by this argument.
+ * This constructor takes as input the number of elements in the vector.
+ * If the index set is not localized, i.e., if there are some elements
+ * that are not present on all processes, only the global size of the
+ * index set will be taken and a localized version will be generated
+ * internally. In other words, which element of the @p partitioning
+ * argument are set is in fact ignored, the only thing that matters is the
+ * size of the index space described by this argument.
*/
explicit Vector (const IndexSet &partitioning,
const MPI_Comm &communicator = MPI_COMM_WORLD);
* <tt>fast</tt> determines whether the vector should be filled with zero
* or left untouched.
*
- * Which element of the @p input_map argument
- * are set is in fact ignored, the only thing that matters is the size of
- * the index space described by this argument.
+ * Which element of the @p input_map argument are set is in fact ignored,
+ * the only thing that matters is the size of the index space described by
+ * this argument.
*/
void reinit (const Epetra_Map &input_map,
const bool fast = false);
* <tt>fast</tt> determines whether the vector should be filled with zero
* (false) or left untouched (true).
*
- * Which element of the @p input_map argument
- * are set is in fact ignored, the only thing that matters is the size of
- * the index space described by this argument.
+ * Which element of the @p input_map argument are set is in fact ignored,
+ * the only thing that matters is the size of the index space described by
+ * this argument.
*/
void reinit (const IndexSet &input_map,
const MPI_Comm &communicator = MPI_COMM_WORLD,
Vector &operator = (const TrilinosScalar s);
/**
- * Sets the left hand argument to the (parallel) Trilinos
- * Vector. Equivalent to the @p reinit function.
+ * Sets the left hand argument to the (parallel) Trilinos Vector.
+ * Equivalent to the @p reinit function.
*/
Vector &
operator = (const MPI::Vector &V);
/**
- * Global function @p swap which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two vectors.
+ * Global function @p swap which overloads the default implementation of the
+ * C++ standard library which uses a temporary object. The function simply
+ * exchanges the data of the two vectors.
*
* @relates TrilinosWrappers::Vector
* @author Martin Kronbichler, Wolfgang Bangerth, 2008
/**
* @addtogroup TrilinosWrappers
- *@{
+ * @{
*/
namespace TrilinosWrappers
{
*/
/**
- * A namespace for internal implementation details of the
- * TrilinosWrapper members.
+ * A namespace for internal implementation details of the TrilinosWrapper
+ * members.
*
* @ingroup TrilinosWrappers
*/
/**
- * Base class for the two types of Trilinos vectors, the distributed
- * memory vector MPI::Vector and a localized vector Vector. The latter
- * is designed for use in either serial implementations or as a
- * localized copy on each processor. The implementation of this class
- * is based on the Trilinos vector class Epetra_FEVector, the (parallel)
- * partitioning of which is governed by an Epetra_Map. This means that
- * the vector type is generic and can be done in this base class, while
- * the definition of the partition map (and hence, the constructor and
- * reinit function) will have to be done in the derived classes. The
- * Epetra_FEVector is precisely the kind of vector we deal with all the
- * time - we probably get it from some assembly process, where also
- * entries not locally owned might need to written and hence need to be
- * forwarded to the owner. The only requirement for this class to work
- * is that Trilinos is installed with the same compiler as is used for
- * compilation of deal.II.
+ * Base class for the two types of Trilinos vectors, the distributed memory
+ * vector MPI::Vector and a localized vector Vector. The latter is designed
+ * for use in either serial implementations or as a localized copy on each
+ * processor. The implementation of this class is based on the Trilinos
+ * vector class Epetra_FEVector, the (parallel) partitioning of which is
+ * governed by an Epetra_Map. This means that the vector type is generic and
+ * can be done in this base class, while the definition of the partition map
+ * (and hence, the constructor and reinit function) will have to be done in
+ * the derived classes. The Epetra_FEVector is precisely the kind of vector
+ * we deal with all the time - we probably get it from some assembly
+ * process, where also entries not locally owned might need to written and
+ * hence need to be forwarded to the owner. The only requirement for this
+ * class to work is that Trilinos is installed with the same compiler as is
+ * used for compilation of deal.II.
*
- * The interface of this class is modeled after the existing Vector
- * class in deal.II. It has almost the same member functions, and is
- * often exchangable. However, since Trilinos only supports a single
- * scalar type (double), it is not templated, and only works with that
- * type.
+ * The interface of this class is modeled after the existing Vector class in
+ * deal.II. It has almost the same member functions, and is often
+ * exchangable. However, since Trilinos only supports a single scalar type
+ * (double), it is not templated, and only works with that type.
*
- * Note that Trilinos only guarantees that operations do what you expect
- * if the function @p GlobalAssemble has been called after vector
- * assembly in order to distribute the data. Therefore, you need to call
+ * Note that Trilinos only guarantees that operations do what you expect if
+ * the function @p GlobalAssemble has been called after vector assembly in
+ * order to distribute the data. Therefore, you need to call
* Vector::compress() before you actually use the vectors.
*
* @ingroup TrilinosWrappers
const bool fast = false);
/**
- * Compress the underlying representation of the Trilinos object,
- * i.e. flush the buffers of the vector object if it has any. This
- * function is necessary after writing into a vector element-by-element
- * and before anything else can be done on it.
+ * Compress the underlying representation of the Trilinos object, i.e.
+ * flush the buffers of the vector object if it has any. This function is
+ * necessary after writing into a vector element-by-element and before
+ * anything else can be done on it.
*
* The (defaulted) argument can be used to specify the compress mode
* (<code>Add</code> or <code>Insert</code>) in case the vector has not
* argument is ignored if the vector has been added or written to since
* the last time compress() was called.
*
- * See @ref GlossCompress "Compressing distributed objects"
- * for more information.
+ * See @ref GlossCompress "Compressing distributed objects" for more
+ * information.
*/
void compress (::dealii::VectorOperation::values operation);
/**
- * @deprecated: Use the compress(VectorOperation::values) function
- * above instead.
+ * @deprecated: Use the compress(VectorOperation::values) function above
+ * instead.
*/
void compress() DEAL_II_DEPRECATED;
/**
- * @deprecated Use compress(dealii::VectorOperation::values) instead.
- */
+ * @deprecated Use compress(dealii::VectorOperation::values) instead.
+ */
void compress (const Epetra_CombineMode last_action) DEAL_II_DEPRECATED;
/**
* <code>i</code> is the first element of the vector stored on this
* processor, corresponding to the half open interval $[i,i+n)$
*
- * @note The description above is true most of the time, but
- * not always. In particular, Trilinos vectors need not store
- * contiguous ranges of elements such as $[i,i+n)$. Rather, it
- * can store vectors where the elements are distributed in
- * an arbitrary way across all processors and each processor
- * simply stores a particular subset, not necessarily contiguous.
- * In this case, this function clearly makes no sense since it
- * could, at best, return a range that includes all elements
- * that are stored locally. Thus, the function only succeeds
- * if the locally stored range is indeed contiguous. It will
- * trigger an assertion if the local portion of the vector
- * is not contiguous.
+ * @note The description above is true most of the time, but not always.
+ * In particular, Trilinos vectors need not store contiguous ranges of
+ * elements such as $[i,i+n)$. Rather, it can store vectors where the
+ * elements are distributed in an arbitrary way across all processors and
+ * each processor simply stores a particular subset, not necessarily
+ * contiguous. In this case, this function clearly makes no sense since it
+ * could, at best, return a range that includes all elements that are
+ * stored locally. Thus, the function only succeeds if the locally stored
+ * range is indeed contiguous. It will trigger an assertion if the local
+ * portion of the vector is not contiguous.
*/
std::pair<size_type, size_type> local_range () const;
* Return whether @p index is in the local range or not, see also
* local_range().
*
- * @note The same limitation for the applicability of this
- * function applies as listed in the documentation of local_range().
+ * @note The same limitation for the applicability of this function
+ * applies as listed in the documentation of local_range().
*/
bool in_local_range (const size_type index) const;
/**
- * Return an index set that describes which elements of this vector
- * are owned by the current processor. Note that this index set does
- * not include elements this vector may store locally as ghost
- * elements but that are in fact owned by another processor.
- * As a consequence, the index sets returned on different
- * processors if this is a distributed vector will form disjoint
- * sets that add up to the complete index set.
- * Obviously, if a vector is created on only one processor, then
- * the result would satisfy
+ * Return an index set that describes which elements of this vector are
+ * owned by the current processor. Note that this index set does not
+ * include elements this vector may store locally as ghost elements but
+ * that are in fact owned by another processor. As a consequence, the
+ * index sets returned on different processors if this is a distributed
+ * vector will form disjoint sets that add up to the complete index set.
+ * Obviously, if a vector is created on only one processor, then the
+ * result would satisfy
* @code
* vec.locally_owned_elements() == complete_index_set (vec.size())
* @endcode
const VectorBase &W);
/**
- * Return whether the vector contains only elements with value
- * zero. This is a collective operation. This function is expensive, because
+ * Return whether the vector contains only elements with value zero. This
+ * is a collective operation. This function is expensive, because
* potentially all elements have to be checked.
*/
bool all_zero () const;
* Provide access to a given element, both read and write.
*
* When using a vector distributed with MPI, this operation only makes
- * sense for elements that are actually present on the calling
- * processor. Otherwise, an exception is thrown. This is different from
- * the <code>el()</code> function below that always succeeds (but returns
- * zero on non-local elements).
+ * sense for elements that are actually present on the calling processor.
+ * Otherwise, an exception is thrown. This is different from the
+ * <code>el()</code> function below that always succeeds (but returns zero
+ * on non-local elements).
*/
reference
operator () (const size_type index);
* Provide read-only access to an element.
*
* When using a vector distributed with MPI, this operation only makes
- * sense for elements that are actually present on the calling
- * processor. Otherwise, an exception is thrown. This is different from
- * the <code>el()</code> function below that always succeeds (but returns
- * zero on non-local elements).
+ * sense for elements that are actually present on the calling processor.
+ * Otherwise, an exception is thrown. This is different from the
+ * <code>el()</code> function below that always succeeds (but returns zero
+ * on non-local elements).
*/
TrilinosScalar
operator () (const size_type index) const;
/**
* A collective get operation: instead of getting individual elements of a
- * vector, this function allows to get a whole set of elements at
- * once. The indices of the elements to be read are stated in the first
+ * vector, this function allows to get a whole set of elements at once.
+ * The indices of the elements to be read are stated in the first
* argument, the corresponding values are returned in the second.
*/
void extract_subvector_to (const std::vector<size_type> &indices,
* Return the value of the vector entry <i>i</i>. Note that this function
* does only work properly when we request a data stored on the local
* processor. In case the elements sits on another process, this function
- * returns 0 which might or might not be appropriate in a given
- * situation. If you rely on consistent results, use the access functions
- * () or [] that throw an assertion in case a non-local element is used.
+ * returns 0 which might or might not be appropriate in a given situation.
+ * If you rely on consistent results, use the access functions () or []
+ * that throw an assertion in case a non-local element is used.
*/
TrilinosScalar el (const size_type index) const;
iterator begin ();
/**
- * Return constant iterator to the start of the locally owned elements
- * of the vector.
+ * Return constant iterator to the start of the locally owned elements of
+ * the vector.
*/
const_iterator begin () const;
/**
- * Return an iterator pointing to the element past the end of the array
- * of locally owned entries.
+ * Return an iterator pointing to the element past the end of the array of
+ * locally owned entries.
*/
iterator end ();
/**
* A collective set operation: instead of setting individual elements of a
- * vector, this function allows to set a whole set of elements at
- * once. The indices of the elements to be set are stated in the first
- * argument, the corresponding values in the second.
+ * vector, this function allows to set a whole set of elements at once.
+ * The indices of the elements to be set are stated in the first argument,
+ * the corresponding values in the second.
*/
void set (const std::vector<size_type> &indices,
const std::vector<TrilinosScalar> &values);
* then it is possible to add data from a vector that uses a different
* map, i.e., a vector whose elements are split across processors
* differently. This may include vectors with ghost elements, for example.
- * In general, however, adding vectors with a different element-to-processor
- * map requires communicating data among processors and, consequently,
- * is a slower operation than when using vectors using the same map.
+ * In general, however, adding vectors with a different element-to-
+ * processor map requires communicating data among processors and,
+ * consequently, is a slower operation than when using vectors using the
+ * same map.
*/
void add (const VectorBase &V,
const bool allow_different_maps = false);
const Epetra_Map &vector_partitioner () const;
/**
- * Output of vector in user-defined format in analogy to the
- * dealii::Vector class.
+ * Output of vector in user-defined format in analogy to the
+ * dealii::Vector class.
*/
void print (const char *format = 0) const;
bool has_ghosts;
/**
- * Pointer to the actual Epetra vector object. This may represent a
- * vector that is in fact distributed among multiple processors. The
- * object requires an existing Epetra_Map for
- * storing data when setting it up.
+ * Pointer to the actual Epetra vector object. This may represent a vector
+ * that is in fact distributed among multiple processors. The object
+ * requires an existing Epetra_Map for storing data when setting it up.
*/
std_cxx11::shared_ptr<Epetra_FEVector> vector;
// ------------------- inline and template functions --------------
/**
- * Global function swap which overloads the default implementation of
- * the C standard library which uses a temporary object. The function
- * simply exchanges the data of the two vectors.
+ * Global function swap which overloads the default implementation of the C
+ * standard library which uses a temporary object. The function simply
+ * exchanges the data of the two vectors.
*
* @relates TrilinosWrappers::VectorBase
* @author Martin Kronbichler, Wolfgang Bangerth, 2008
/**
- * Numerical vector of data. For this class there are different types
- * of functions available. The first type of function initializes the
- * vector, changes its size, or computes the norm
- * of the vector in order to measure its length in a suitable norm. The
- * second type helps us to manipulate the components of the vector. The
- * third type defines the algebraic operations for vectors, while the
- * last type defines a few input and output functions.
- * As opposed to the array of the C++ standard library called
- * @p vector (with a lowercase "v"), this class implements an element
- * of a vector space suitable for numerical computations.
+ * Numerical vector of data. For this class there are different types of
+ * functions available. The first type of function initializes the vector,
+ * changes its size, or computes the norm of the vector in order to measure
+ * its length in a suitable norm. The second type helps us to manipulate the
+ * components of the vector. The third type defines the algebraic operations
+ * for vectors, while the last type defines a few input and output functions.
+ * As opposed to the array of the C++ standard library called @p vector (with
+ * a lowercase "v"), this class implements an element of a vector space
+ * suitable for numerical computations.
*
- * @note Instantiations for this template are provided for
- * <tt>@<float@>, @<double@>, @<long double@>,
- * @<std::complex@<float@>@>, @<std::complex@<double@>@>,
- * @<std::complex@<long double@>@></tt>; others can be generated in
- * application programs (see the section on @ref Instantiations in the
- * manual).
+ * @note Instantiations for this template are provided for <tt>@<float@>,
+ * @<double@>, @<long double@>, @<std::complex@<float@>@>,
+ * @<std::complex@<double@>@>, @<std::complex@<long double@>@></tt>; others
+ * can be generated in application programs (see the section on @ref
+ * Instantiations in the manual).
*
* @author Guido Kanschat, Franz-Theo Suttmeier, Wolfgang Bangerth
*/
/**
* Declare a type that has holds real-valued numbers with the same precision
* as the template argument to this class. If the template argument of this
- * class is a real data type, then real_type equals the template
- * argument. If the template argument is a std::complex type then real_type
- * equals the type underlying the complex numbers.
+ * class is a real data type, then real_type equals the template argument.
+ * If the template argument is a std::complex type then real_type equals the
+ * type underlying the complex numbers.
*
* This typedef is used to represent the return type of norms.
*/
typedef typename numbers::NumberTraits<Number>::real_type real_type;
/**
- * A variable that indicates whether this vector
- * supports distributed data storage. If true, then
- * this vector also needs an appropriate compress()
- * function that allows communicating recent set or
- * add operations to individual elements to be communicated
- * to other processors.
+ * A variable that indicates whether this vector supports distributed data
+ * storage. If true, then this vector also needs an appropriate compress()
+ * function that allows communicating recent set or add operations to
+ * individual elements to be communicated to other processors.
*
- * For the current class, the variable equals
- * false, since it does not support parallel data storage.
+ * For the current class, the variable equals false, since it does not
+ * support parallel data storage.
*/
static const bool supports_distributed_data = false;
*/
//@{
/**
- * Constructor. Create a vector of dimension zero.
+ * Constructor. Create a vector of dimension zero.
*/
Vector ();
#ifdef DEAL_II_WITH_TRILINOS
/**
- * Another copy constructor: copy the values from a Trilinos wrapper
- * vector. This copy constructor is only available if Trilinos was detected
- * during configuration time.
+ * Another copy constructor: copy the values from a Trilinos wrapper vector.
+ * This copy constructor is only available if Trilinos was detected during
+ * configuration time.
*
* Note that due to the communication model used in MPI, this operation can
* only succeed if all processes do it at the same time. This means that it
*
* Since the semantics of assigning a scalar to a vector are not immediately
* clear, this operator should really only be used if you want to set the
- * entire vector to zero. This allows the intuitive notation
- * <tt>v=0</tt>. Assigning other values is deprecated and may be disallowed
- * in the future.
+ * entire vector to zero. This allows the intuitive notation <tt>v=0</tt>.
+ * Assigning other values is deprecated and may be disallowed in the future.
*
* @dealiiOperationIsMultithreaded
*/
* For complex vectors, the scalar product is implemented as
* $\left<v,w\right>=\sum_i v_i \bar{w_i}$.
*
- * @dealiiOperationIsMultithreaded The algorithm uses pairwise
- * summation with the same order of summation in every run, which gives
- * fully repeatable results from one run to another.
+ * @dealiiOperationIsMultithreaded The algorithm uses pairwise summation
+ * with the same order of summation in every run, which gives fully
+ * repeatable results from one run to another.
*/
template <typename Number2>
Number operator * (const Vector<Number2> &V) const;
/**
* Return square of the $l_2$-norm.
*
- * @dealiiOperationIsMultithreaded The algorithm uses pairwise
- * summation with the same order of summation in every run, which gives
- * fully repeatable results from one run to another.
+ * @dealiiOperationIsMultithreaded The algorithm uses pairwise summation
+ * with the same order of summation in every run, which gives fully
+ * repeatable results from one run to another.
*/
real_type norm_sqr () const;
/**
* Mean value of the elements of this vector.
*
- * @dealiiOperationIsMultithreaded The algorithm uses pairwise
- * summation with the same order of summation in every run, which gives
- * fully repeatable results from one run to another.
+ * @dealiiOperationIsMultithreaded The algorithm uses pairwise summation
+ * with the same order of summation in every run, which gives fully
+ * repeatable results from one run to another.
*/
Number mean_value () const;
/**
* $l_1$-norm of the vector. The sum of the absolute values.
*
- * @dealiiOperationIsMultithreaded The algorithm uses pairwise
- * summation with the same order of summation in every run, which gives
- * fully repeatable results from one run to another.
+ * @dealiiOperationIsMultithreaded The algorithm uses pairwise summation
+ * with the same order of summation in every run, which gives fully
+ * repeatable results from one run to another.
*/
real_type l1_norm () const;
* $l_2$-norm of the vector. The square root of the sum of the squares of
* the elements.
*
- * @dealiiOperationIsMultithreaded The algorithm uses pairwise
- * summation with the same order of summation in every run, which gives
- * fully repeatable results from one run to another.
+ * @dealiiOperationIsMultithreaded The algorithm uses pairwise summation
+ * with the same order of summation in every run, which gives fully
+ * repeatable results from one run to another.
*/
real_type l2_norm () const;
* $l_p$-norm of the vector. The pth root of the sum of the pth powers of
* the absolute values of the elements.
*
- * @dealiiOperationIsMultithreaded The algorithm uses pairwise
- * summation with the same order of summation in every run, which gives
- * fully repeatable results from one run to another.
+ * @dealiiOperationIsMultithreaded The algorithm uses pairwise summation
+ * with the same order of summation in every run, which gives fully
+ * repeatable results from one run to another.
*/
real_type lp_norm (const real_type p) const;
real_type linfty_norm () const;
/**
- * Performs a combined operation of a vector addition and a subsequent
- * inner product, returning the value of the inner product. In other words,
- * the result of this function is the same as if the user called
+ * Performs a combined operation of a vector addition and a subsequent inner
+ * product, returning the value of the inner product. In other words, the
+ * result of this function is the same as if the user called
* @code
* this->add(a, V);
* return_value = *this * W;
* most vector operations are memory transfer limited, this reduces the time
* by 25\% (or 50\% if @p W equals @p this).
*
- * @dealiiOperationIsMultithreaded The algorithm uses pairwise
- * summation with the same order of summation in every run, which gives
- * fully repeatable results from one run to another.
+ * @dealiiOperationIsMultithreaded The algorithm uses pairwise summation
+ * with the same order of summation in every run, which gives fully
+ * repeatable results from one run to another.
*/
Number add_and_dot (const Number a,
const Vector<Number> &V,
*/
//@{
/**
- * Output of vector in user-defined format. For complex-valued vectors, the
- * format should include specifiers for both the real and imaginary parts.
+ * Output of vector in user-defined format. For complex-valued vectors, the
+ * format should include specifiers for both the real and imaginary parts.
*/
void print (const char *format = 0) const;
bool in_local_range (const size_type global_index) const;
/**
- * Return an index set that describes which elements of this vector
- * are owned by the current processor. Note that this index set does
- * not include elements this vector may store locally as ghost
- * elements but that are in fact owned by another processor.
- * As a consequence, the index sets returned on different
- * processors if this is a distributed vector will form disjoint
- * sets that add up to the complete index set.
- * Obviously, if a vector is created on only one processor, then
- * the result would satisfy
+ * Return an index set that describes which elements of this vector are
+ * owned by the current processor. Note that this index set does not include
+ * elements this vector may store locally as ghost elements but that are in
+ * fact owned by another processor. As a consequence, the index sets
+ * returned on different processors if this is a distributed vector will
+ * form disjoint sets that add up to the complete index set. Obviously, if a
+ * vector is created on only one processor, then the result would satisfy
* @code
* vec.locally_owned_elements() == complete_index_set (vec.size())
* @endcode
*
- * Since the current data type does not support parallel data storage
- * across different processors, the returned index set is the
- * complete index set.
+ * Since the current data type does not support parallel data storage across
+ * different processors, the returned index set is the complete index set.
*/
IndexSet locally_owned_elements () const;
/**
- * Global function @p swap which overloads the default implementation
- * of the C++ standard library which uses a temporary object. The
- * function simply exchanges the data of the two vectors.
+ * Global function @p swap which overloads the default implementation of the
+ * C++ standard library which uses a temporary object. The function simply
+ * exchanges the data of the two vectors.
*
* @relates Vector
* @author Wolfgang Bangerth, 2000
/*@{*/
/**
- * Memory management base class for vectors. This is an abstract base
- * class used, among other places, by all iterative methods to
- * allocate space for auxiliary vectors.
+ * Memory management base class for vectors. This is an abstract base class
+ * used, among other places, by all iterative methods to allocate space for
+ * auxiliary vectors.
*
- * The purpose of this class is as follows: in iterative solvers and
- * other places, one needs to allocate temporary storage for vectors,
- * for example for auxiliary vectors. One could allocate and release
- * them anew every time, but this may be expensive in some situations
- * if it has to happen very frequently. A common case for this is when
- * an iterative method is used to invert a matrix in each iteration an
- * outer solver, such as when inverting a matrix block for a Schur
- * complement solver.
+ * The purpose of this class is as follows: in iterative solvers and other
+ * places, one needs to allocate temporary storage for vectors, for example
+ * for auxiliary vectors. One could allocate and release them anew every time,
+ * but this may be expensive in some situations if it has to happen very
+ * frequently. A common case for this is when an iterative method is used to
+ * invert a matrix in each iteration an outer solver, such as when inverting a
+ * matrix block for a Schur complement solver.
*
- * In such situations, allocating and deallocating vectors anew in
- * each call to the inner solver is expensive and leads to memory
- * fragmentation. The present class allows to avoid this by offering
- * an interface that other classes can use to allocate and deallocate
- * vectors. Different derived classes then implement different
- * strategies to provide temporary storage vectors to using
- * classes.
+ * In such situations, allocating and deallocating vectors anew in each call
+ * to the inner solver is expensive and leads to memory fragmentation. The
+ * present class allows to avoid this by offering an interface that other
+ * classes can use to allocate and deallocate vectors. Different derived
+ * classes then implement different strategies to provide temporary storage
+ * vectors to using classes.
*
* For example, the PrimitiveVectorMemory class simply allocates and
* deallocated vectors each time it is asked for a vector. It is an
- * appropriate implementation to use for iterative solvers that are
- * called only once, or very infrequently.
+ * appropriate implementation to use for iterative solvers that are called
+ * only once, or very infrequently.
*
- * On the other hand, the GrowingVectorMemory class never returns
- * memory space to the operating system memory management subsystem
- * during its lifetime; it only marks them as unused and allows them
- * to be reused next time a vector is requested.
+ * On the other hand, the GrowingVectorMemory class never returns memory space
+ * to the operating system memory management subsystem during its lifetime; it
+ * only marks them as unused and allows them to be reused next time a vector
+ * is requested.
*
- * Yet other classes, when implemented, could provide even other
- * strategies for memory management.
+ * Yet other classes, when implemented, could provide even other strategies
+ * for memory management.
*
* @author Guido Kanschat, 1998-2003
-*/
+ */
template<class VECTOR = dealii::Vector<double> >
class VectorMemory : public Subscriptor
{
public:
/**
- * Virtual destructor is needed
- * as there are virtual functions
- * in this class.
+ * Virtual destructor is needed as there are virtual functions in this
+ * class.
*/
virtual ~VectorMemory () {}
/**
- * Return a pointer to a new
- * vector. The number of elements
- * or their subdivision into
- * blocks (if applicable) is
- * unspecified and users of this
- * function should reset vectors
- * to their proper size. The same
- * holds for the contents of
- * vectors: they are unspecified.
+ * Return a pointer to a new vector. The number of elements or their
+ * subdivision into blocks (if applicable) is unspecified and users of this
+ * function should reset vectors to their proper size. The same holds for
+ * the contents of vectors: they are unspecified.
*/
virtual VECTOR *alloc () = 0;
/**
- * Return a vector and indicate
- * that it is not going to be
- * used any further by the
- * instance that called alloc()
- * to get a pointer to it.
+ * Return a vector and indicate that it is not going to be used any further
+ * by the instance that called alloc() to get a pointer to it.
*/
virtual void free (const VECTOR *const) = 0;
- /** @addtogroup Exceptions
- * @{ */
+ /**
+ * @addtogroup Exceptions
+ * @{
+ */
/**
* No more available vectors.
*/
DeclException0(ExcNoMoreVectors);
/**
- * Vector was not allocated from
- * this memory pool.
+ * Vector was not allocated from this memory pool.
*/
DeclException0(ExcNotAllocatedHere);
//@}
/**
- * Pointer to vectors allocated from VectorMemory objects. This
- * pointer is safe in the sense that it automatically calls free()
- * when it is destroyed, thus relieving the user from using vector
- * management functions at all.
+ * Pointer to vectors allocated from VectorMemory objects. This pointer is
+ * safe in the sense that it automatically calls free() when it is
+ * destroyed, thus relieving the user from using vector management functions
+ * at all.
*
* @author Guido Kanschat, 2009
*/
{
public:
/**
- * Constructor, automatically
- * allocating a vector from
- * @p mem.
+ * Constructor, automatically allocating a vector from @p mem.
*/
Pointer(VectorMemory<VECTOR> &mem);
/**
- * Destructor, automatically
- * releasing the vector from
- * the memory #pool.
+ * Destructor, automatically releasing the vector from the memory #pool.
*/
~Pointer();
/**
- * Simple memory management. See the documentation of the base class
- * for a description of its purpose.
+ * Simple memory management. See the documentation of the base class for a
+ * description of its purpose.
*
- * This class allocates and deletes
- * vectors as needed from the global heap, i.e. performs no
- * specially adapted actions for memory management.
+ * This class allocates and deletes vectors as needed from the global heap,
+ * i.e. performs no specially adapted actions for memory management.
*/
template<class VECTOR = dealii::Vector<double> >
class PrimitiveVectorMemory : public VectorMemory<VECTOR>
PrimitiveVectorMemory () {}
/**
- * Return a pointer to a new
- * vector. The number of elements
- * or their subdivision into
- * blocks (if applicable) is
- * unspecified and users of this
- * function should reset vectors
- * to their proper size. The same
- * holds for the contents of
- * vectors: they are unspecified.
+ * Return a pointer to a new vector. The number of elements or their
+ * subdivision into blocks (if applicable) is unspecified and users of this
+ * function should reset vectors to their proper size. The same holds for
+ * the contents of vectors: they are unspecified.
*
- * For the present class, calling
- * this function will allocate a
- * new vector on the heap and
- * returning a pointer to it.
+ * For the present class, calling this function will allocate a new vector
+ * on the heap and returning a pointer to it.
*/
virtual VECTOR *alloc ()
{
}
/**
- * Return a vector and indicate
- * that it is not going to be
- * used any further by the
- * instance that called alloc()
- * to get a pointer to it.
+ * Return a vector and indicate that it is not going to be used any further
+ * by the instance that called alloc() to get a pointer to it.
*
*
- * For the present class, this
- * means that the vector is
- * returned to the global heap.
+ * For the present class, this means that the vector is returned to the
+ * global heap.
*/
virtual void free (const VECTOR *const v)
{
/**
- * A pool based memory management class. See the documentation of the
- * base class for a description of its purpose.
+ * A pool based memory management class. See the documentation of the base
+ * class for a description of its purpose.
*
- * Each time a vector is requested from this class, it checks if it
- * has one available and returns its address, or allocates a new one
- * on the heap. If a vector is returned, through the free() member
- * function, it doesn't return it to the operating system memory
- * subsystem, but keeps it around unused for later use if alloc() is
- * called again, or until the object is destroyed. The class therefore
- * avoid the overhead of repeatedly allocating memory on the heap if
- * temporary vectors are required and released frequently; on the
- * other hand, it doesn't release once-allocated memory at the
- * earliest possible time and may therefore lead to an increased
- * overall memory consumption.
+ * Each time a vector is requested from this class, it checks if it has one
+ * available and returns its address, or allocates a new one on the heap. If a
+ * vector is returned, through the free() member function, it doesn't return
+ * it to the operating system memory subsystem, but keeps it around unused for
+ * later use if alloc() is called again, or until the object is destroyed. The
+ * class therefore avoid the overhead of repeatedly allocating memory on the
+ * heap if temporary vectors are required and released frequently; on the
+ * other hand, it doesn't release once-allocated memory at the earliest
+ * possible time and may therefore lead to an increased overall memory
+ * consumption.
*
- * All GrowingVectorMemory objects of the same vector type use the
- * same memory Pool. Therefore, functions can create such a
- * VectorMemory object whenever needed without performance penalty. A
- * drawback of this policy might be that vectors once allocated are
- * only released at the end of the program run. Nevertheless, the
- * since they are reused, this should be of no concern. Additionally,
- * the destructor of the Pool warns about memory leaks.
+ * All GrowingVectorMemory objects of the same vector type use the same memory
+ * Pool. Therefore, functions can create such a VectorMemory object whenever
+ * needed without performance penalty. A drawback of this policy might be that
+ * vectors once allocated are only released at the end of the program run.
+ * Nevertheless, the since they are reused, this should be of no concern.
+ * Additionally, the destructor of the Pool warns about memory leaks.
*
* @author Guido Kanschat, 1999, 2007
*/
typedef types::global_dof_index size_type;
/**
- * Constructor. The argument
- * allows to preallocate a
- * certain number of vectors. The
- * default is not to do this.
+ * Constructor. The argument allows to preallocate a certain number of
+ * vectors. The default is not to do this.
*/
GrowingVectorMemory (const size_type initial_size = 0,
const bool log_statistics = false);
/**
- * Destructor.
- * Release all vectors.
- * This destructor also offers
- * some statistic on the number
- * of allocated vectors.
+ * Destructor. Release all vectors. This destructor also offers some
+ * statistic on the number of allocated vectors.
*
- * The log file will also contain
- * a warning message, if there
- * are allocated vectors left.
+ * The log file will also contain a warning message, if there are allocated
+ * vectors left.
*/
virtual ~GrowingVectorMemory();
/**
- * Return a pointer to a new
- * vector. The number of elements
- * or their subdivision into
- * blocks (if applicable) is
- * unspecified and users of this
- * function should reset vectors
- * to their proper size. The same
- * holds for the contents of
- * vectors: they are unspecified.
+ * Return a pointer to a new vector. The number of elements or their
+ * subdivision into blocks (if applicable) is unspecified and users of this
+ * function should reset vectors to their proper size. The same holds for
+ * the contents of vectors: they are unspecified.
*/
virtual VECTOR *alloc ();
/**
- * Return a vector and indicate
- * that it is not going to be
- * used any further by the
- * instance that called alloc()
- * to get a pointer to it.
+ * Return a vector and indicate that it is not going to be used any further
+ * by the instance that called alloc() to get a pointer to it.
*
- * For the present class, this
- * means retaining the vector for
- * later reuse by the alloc()
- * method.
+ * For the present class, this means retaining the vector for later reuse by
+ * the alloc() method.
*/
virtual void free (const VECTOR *const);
/**
- * Release all vectors that are
- * not currently in use.
+ * Release all vectors that are not currently in use.
*/
static void release_unused_memory ();
/**
- * Memory consumed by this class
- * and all currently allocated
- * vectors.
+ * Memory consumed by this class and all currently allocated vectors.
*/
virtual std::size_t memory_consumption() const;
private:
/**
- * Type to enter into the
- * array. First component will be
- * a flag telling whether the
- * vector is used, second the
- * vector itself.
+ * Type to enter into the array. First component will be a flag telling
+ * whether the vector is used, second the vector itself.
*/
typedef std::pair<bool, VECTOR *> entry_type;
/**
- * The class providing the actual
- * storage for the memory pool.
+ * The class providing the actual storage for the memory pool.
*
- * This is where the actual
- * storage for GrowingVectorMemory
- * is provided. Only one of these
- * pools is used for each vector
- * type, thus allocating all
+ * This is where the actual storage for GrowingVectorMemory is provided.
+ * Only one of these pools is used for each vector type, thus allocating all
* vectors from the same storage.
*
* @author Guido Kanschat, 2007
struct Pool
{
/**
- * Standard constructor
- * creating an empty pool
+ * Standard constructor creating an empty pool
*/
Pool();
/**
- * Destructor. Frees memory
- * and warns about memory
- * leaks
+ * Destructor. Frees memory and warns about memory leaks
*/
~Pool();
/**
- * Create data vector; does
- * nothing after first
- * initialization
+ * Create data vector; does nothing after first initialization
*/
void initialize(const size_type size);
/**
- * Pointer to the storage
- * object
+ * Pointer to the storage object
*/
std::vector<entry_type> *data;
};
static Pool pool;
/**
- * Overall number of
- * allocations. Only used for
- * bookkeeping and to generate
- * output at the end of an
- * object's lifetime.
+ * Overall number of allocations. Only used for bookkeeping and to generate
+ * output at the end of an object's lifetime.
*/
size_type total_alloc;
/**
- * Number of vectors currently
- * allocated in this object; used
- * for detecting memory leaks.
+ * Number of vectors currently allocated in this object; used for detecting
+ * memory leaks.
*/
size_type current_alloc;
/**
- * A flag controlling the logging
- * of statistics by the
- * destructor.
+ * A flag controlling the logging of statistics by the destructor.
*/
bool log_statistics;
/**
- * Mutex to synchronise access to
- * internal data of this object
- * from multiple threads.
+ * Mutex to synchronise access to internal data of this object from multiple
+ * threads.
*/
static Threads::Mutex mutex;
};
*/
/**
- * View of a numerical vector of data. This class provides an
- * interface compatible with the Vector<double> class (from which it
- * is inherited), that allows fast access to locations of memory
- * already allocated with arrays of type Number.
+ * View of a numerical vector of data. This class provides an interface
+ * compatible with the Vector<double> class (from which it is inherited), that
+ * allows fast access to locations of memory already allocated with arrays of
+ * type Number.
*
- * This is in the same style of the vector view in the Trilinos
- * library.
+ * This is in the same style of the vector view in the Trilinos library.
*
- * You should consider using the VectorView object ONLY when ALL of
- * the following requirements are met:
+ * You should consider using the VectorView object ONLY when ALL of the
+ * following requirements are met:
*
* 1. Your application requires a Vector<Number> object.
*
* 2. All you have at your disposal is a Number* pointer.
*
- * 3. You are ABSOLUTELY SURE that the above pointer points to a
- * valid area of memory of the correct size.
+ * 3. You are ABSOLUTELY SURE that the above pointer points to a valid area of
+ * memory of the correct size.
*
- * 4. You really believe that making a copy of that memory would be
- * too expensive.
+ * 4. You really believe that making a copy of that memory would be too
+ * expensive.
*
* 5. You really know what you are doing.
*
- * Notice that NO CHECKS are performed on the actual memory, and if
- * you try to access illegal areas of memory, your computer will
- * suffer from it. Once again, use this class ONLY if you know exactly
- * what you are doing.
+ * Notice that NO CHECKS are performed on the actual memory, and if you try to
+ * access illegal areas of memory, your computer will suffer from it. Once
+ * again, use this class ONLY if you know exactly what you are doing.
*
- * Two constructors are provided. One for read-write access, and one
- * for read only access, and you are allowed to use this class on
- * objects of type const Number*. However you should be aware of the
- * fact that the constness of the array pointed to is ignored, which
- * means that you should only use the const constructor when the
- * actual object you are constructing is itself a constant object.
- * As a corollary, you will be allowed to call even functions of
- * the base class that change data of the array; this being a violation
- * of the C++ type model, you should make sure that this only happens
- * if it is really valid and, in general, if
- * you know what you are doing.
+ * Two constructors are provided. One for read-write access, and one for read
+ * only access, and you are allowed to use this class on objects of type const
+ * Number*. However you should be aware of the fact that the constness of the
+ * array pointed to is ignored, which means that you should only use the const
+ * constructor when the actual object you are constructing is itself a
+ * constant object. As a corollary, you will be allowed to call even functions
+ * of the base class that change data of the array; this being a violation of
+ * the C++ type model, you should make sure that this only happens if it is
+ * really valid and, in general, if you know what you are doing.
*
- * Since this class does not own the memory that you are accessing,
- * you have to make sure that the lifetime of the section of memory you
- * are viewing is longer than this object. No attempt is made to
- * ensure that this is the case.
+ * Since this class does not own the memory that you are accessing, you have
+ * to make sure that the lifetime of the section of memory you are viewing is
+ * longer than this object. No attempt is made to ensure that this is the
+ * case.
*
* An example usage of this class is the following:
*
- @code
- // Create an array of length 5;
- double * array = new double[5];
- // Now create a view of the above array that is compatible with the
- // Vector<double> class
- VectorView<double> view(5, array);
-
- view(1) = 4;
-
- // The following line should output 4.
- cout << array[1] << endl;
-
- // If debug mode is on, then the following triggers an execption:
- view(6) = 4;
-
- // But notice that no checks are performed, so this is legal but WILL
- // NOT work
- VectorView<double> wrong_view(10, array);
-
- // Now no assert will be thrown if you type wrong_view(6), but most
- // likely a seg fault will occur.
- view(6) = 4;
-
- // Notice that this construction is legal. It will create a copy of
- // the array.
- const Vector<double> const_copy(view);
-
- // Now this is the correct way to instantiate a constant view of the
- // above vector:
- const VectorView<double> correct_const_copy_view(5, const_copy.begin());
-
- // While this will compile, BUT WILL NOT COMPLAIN if you try to write
- // on it!
- VectorView<double> wrong_const_copy_view(5, const_copy.begin());
-
- // Now writing to elements of wrong_const_copy_view is allowed, and
- // will change the same memory as the const_copy object.
- wrong_const_copy_view(1) = 5;
-
- if(copy_view(1) == wrong_const_copy_view(1)) cout << "Tautology";
-
- @endcode
+ * @code
+ * // Create an array of length 5;
+ * double * array = new double[5];
+ * // Now create a view of the above array that is compatible with the
+ * // Vector<double> class
+ * VectorView<double> view(5, array);
+ *
+ * view(1) = 4;
+ *
+ * // The following line should output 4.
+ * cout << array[1] << endl;
+ *
+ * // If debug mode is on, then the following triggers an execption:
+ * view(6) = 4;
*
+ * // But notice that no checks are performed, so this is legal but WILL
+ * // NOT work
+ * VectorView<double> wrong_view(10, array);
*
- * @note Instantiations for this template are provided for
- * <tt>@<float@>, @<double@>, @<long double@>,
- * @<std::complex@<float@>@>, @<std::complex@<double@>@>,
- * @<std::complex@<long double@>@></tt>; others can be generated in
- * application programs (see the section on @ref Instantiations in the
- * manual).
+ * // Now no assert will be thrown if you type wrong_view(6), but most
+ * // likely a seg fault will occur.
+ * view(6) = 4;
+ *
+ * // Notice that this construction is legal. It will create a copy of
+ * // the array.
+ * const Vector<double> const_copy(view);
+ *
+ * // Now this is the correct way to instantiate a constant view of the
+ * // above vector:
+ * const VectorView<double> correct_const_copy_view(5, const_copy.begin());
+ *
+ * // While this will compile, BUT WILL NOT COMPLAIN if you try to write
+ * // on it!
+ * VectorView<double> wrong_const_copy_view(5, const_copy.begin());
+ *
+ * // Now writing to elements of wrong_const_copy_view is allowed, and
+ * // will change the same memory as the const_copy object.
+ * wrong_const_copy_view(1) = 5;
+ *
+ * if(copy_view(1) == wrong_const_copy_view(1)) cout << "Tautology";
+ *
+ * @endcode
+ *
+ *
+ * @note Instantiations for this template are provided for <tt>@<float@>,
+ * @<double@>, @<long double@>, @<std::complex@<float@>@>,
+ * @<std::complex@<double@>@>, @<std::complex@<long double@>@></tt>; others
+ * can be generated in application programs (see the section on @ref
+ * Instantiations in the manual).
*
* @author Luca Heltai, 2009
*/
typedef types::global_dof_index size_type;
/**
- * Read write constructor. Takes the size
- * of the vector, just like the standard
- * one, but the data is picked starting
- * from the location of the pointer @p
- * ptr.
+ * Read write constructor. Takes the size of the vector, just like the
+ * standard one, but the data is picked starting from the location of the
+ * pointer @p ptr.
*/
VectorView(const size_type new_size, Number *ptr);
/**
- * The constant constructor is the same
- * as above, however you will not be able
- * to access the data for write access.
+ * The constant constructor is the same as above, however you will not be
+ * able to access the data for write access.
*
- * You should only use this class by
- * constructing it as a const
+ * You should only use this class by constructing it as a const
* VectorView<double>(size, ptr) object.
*
- * Undefined behavior will occur if you
- * construct it as a non const object or
- * attempt to write on it.
+ * Undefined behavior will occur if you construct it as a non const object
+ * or attempt to write on it.
*/
VectorView(const size_type new_size, const Number *ptr);
/**
- * This desctructor will only reset the
- * internal sizes and the internal
- * pointers, but it will NOT clear the
- * memory. */
+ * This desctructor will only reset the internal sizes and the internal
+ * pointers, but it will NOT clear the memory.
+ */
~VectorView();
/**
- * The reinit function of this object has
- * a behavior which is different from the
- * one of the base class. VectorView does
- * not handle memory, and you should not
- * attempt to resize the memory that is
- * pointed to by this object using the
- * reinit function. You can, however,
- * resize the view that you have of the
- * original object. Notice that it is
- * your own responsibility to ensure that
- * the memory you are pointing to is big
- * enough.
+ * The reinit function of this object has a behavior which is different from
+ * the one of the base class. VectorView does not handle memory, and you
+ * should not attempt to resize the memory that is pointed to by this object
+ * using the reinit function. You can, however, resize the view that you
+ * have of the original object. Notice that it is your own responsibility to
+ * ensure that the memory you are pointing to is big enough.
*
- * Similarly to what happens in the base
- * class, if fast is false, then the
- * entire content of the vector is set to
- * 0, otherwise the content of the memory
- * is left unchanged.
+ * Similarly to what happens in the base class, if fast is false, then the
+ * entire content of the vector is set to 0, otherwise the content of the
+ * memory is left unchanged.
*
- * Notice that the following snippet of
- * code may not produce what you expect:
+ * Notice that the following snippet of code may not produce what you
+ * expect:
*
* @code
* // Create a vector of length 1.
* view_of_long_vector.reinit(100, true);
* @endcode
*
- * In the above case, the
- * Vector<double>::reinit method is
- * called, and a NEW area of memory is
- * reserved, possibly not starting at the
- * same place as before. Hoever, the
- * VectorView<double> object keeps
- * pointing to the same old area. After
- * the two reinits, any call to
- * view_of_long_vector(i), with i>0 might
- * cause an attempt to access invalid
- * areas of memory, or might function
- * properly, depending on whether or not
- * the system was able to allocate some
- * memory consecutively after the
- * original allocation.
+ * In the above case, the Vector<double>::reinit method is called, and a NEW
+ * area of memory is reserved, possibly not starting at the same place as
+ * before. Hoever, the VectorView<double> object keeps pointing to the same
+ * old area. After the two reinits, any call to view_of_long_vector(i), with
+ * i>0 might cause an attempt to access invalid areas of memory, or might
+ * function properly, depending on whether or not the system was able to
+ * allocate some memory consecutively after the original allocation.
*
- * In any case, you should not rely on
- * this behavior, and you should only
- * call this reinit function if you
- * really know what you are doing.
+ * In any case, you should not rely on this behavior, and you should only
+ * call this reinit function if you really know what you are doing.
*/
virtual void reinit (const size_type N,
const bool fast=false);
- /** This reinit function is
- equivalent to constructing a
- new object with the given
- size, starting from the
- pointer ptr. */
+ /**
+ * This reinit function is equivalent to constructing a new object with the
+ * given size, starting from the pointer ptr.
+ */
void reinit(const size_type N, Number *ptr);
- /** This reinit function is
- equivalent to constructing a
- new object with the given
- size, starting from the
- pointer ptr. The same
- considerations made for the
- constructor apply here. */
+ /**
+ * This reinit function is equivalent to constructing a new object with the
+ * given size, starting from the pointer ptr. The same considerations made
+ * for the constructor apply here.
+ */
void reinit(const size_type N, const Number *ptr);
/**
- * This function is here to prevent
- * memory corruption. It should never be
- * called, and will throw an exception if
- * you try to do so. */
+ * This function is here to prevent memory corruption. It should never be
+ * called, and will throw an exception if you try to do so.
+ */
virtual void swap (Vector<Number> &v);
};
/**
* This helper function determines a block size if the user decided not
* to force a block size through MatrixFree::AdditionalData. This is
- * computed based on the number of hardware threads on the system
- * and the number of macro cells that we should work on.
+ * computed based on the number of hardware threads on the system and
+ * the number of macro cells that we should work on.
*/
void guess_block_size (const SizeInfo &size_info,
TaskInfo &task_info);
*
* The strategy is based on a two-level approach. The outer level is
* subdivided into partitions similar to the type of neighbors in
- * Cuthill-McKee, and the inner level is again subdivided into
- * Cuthill-McKee-like partitions (partitions whose level differs by more
- * than 2 can be worked on independently). One task is represented by a
- * chunk of cells. The cell chunks are formed after subdivision into the
- * two levels of partitions.
+ * Cuthill-McKee, and the inner level is again subdivided into Cuthill-
+ * McKee-like partitions (partitions whose level differs by more than 2
+ * can be worked on independently). One task is represented by a chunk
+ * of cells. The cell chunks are formed after subdivision into the two
+ * levels of partitions.
*/
void
make_thread_graph_partition_partition (SizeInfo &size_info,
* <tt>n_locally_owned_dofs</tt> to
* <tt>n_locally_owned_dofs+n_ghost_dofs</tt>. The translation between
* this MPI-local index space and the global numbering of degrees of
- * freedom is stored in the @p vector_partitioner data structure.
-
- * This array also includes the indirect contributions from constraints,
+ * freedom is stored in the @p vector_partitioner data structure. This
+ * array also includes the indirect contributions from constraints,
* which are described by the @p constraint_indicator field. Because of
- * variable lengths of rows, this would be a vector of a
- * vector. However, we use one contiguous memory region and store the
- * rowstart in the variable @p row_starts.
+ * variable lengths of rows, this would be a vector of a vector.
+ * However, we use one contiguous memory region and store the rowstart
+ * in the variable @p row_starts.
*/
std::vector<unsigned int> dof_indices;
* @param dim Dimension in which this class is to be used
*
* @param n_components Number of vector components when solving a system of
- * PDEs. If the same operation is applied to several
- * components of a PDE (e.g. a vector Laplace equation), they
- * can be applied simultaneously with one call (and often
- * more efficiently)
+ * PDEs. If the same operation is applied to several components of a PDE (e.g.
+ * a vector Laplace equation), they can be applied simultaneously with one
+ * call (and often more efficiently)
*
* @param Number Number format, usually @p double or @p float
*
unsigned int get_cell_data_number() const;
/**
- * Returns the type of the cell the @p reinit function has been called
- * for. Valid values are @p cartesian for Cartesian cells (which allows for
+ * Returns the type of the cell the @p reinit function has been called for.
+ * Valid values are @p cartesian for Cartesian cells (which allows for
* considerable data compression), @p affine for cells with affine mappings,
* and @p general for general cells without any compressed storage applied.
*/
*
* If some constraints on the vector are inhomogeneous, use the function
* read_dof_values_plain instead and provide the vector with useful data
- * also in constrained positions by calling
- * ConstraintMatrix::distribute. When accessing vector entries during the
- * solution of linear systems, the temporary solution should always have
- * homogeneous constraints and this method is the correct one.
+ * also in constrained positions by calling ConstraintMatrix::distribute.
+ * When accessing vector entries during the solution of linear systems, the
+ * temporary solution should always have homogeneous constraints and this
+ * method is the correct one.
*
* If this class was constructed without a MatrixFree object and the
* information is acquired on the fly through a
/**
* Write a contribution that is tested by the gradient to the field
- * containing the values on quadrature points with component @p
- * q_point. Access to the same field as through @p get_gradient. If applied
- * before the function @p integrate(...,true) is called, this specifies what
- * is tested by all basis function gradients on the current cell and
- * integrated over.
+ * containing the values on quadrature points with component @p q_point.
+ * Access to the same field as through @p get_gradient. If applied before
+ * the function @p integrate(...,true) is called, this specifies what is
+ * tested by all basis function gradients on the current cell and integrated
+ * over.
*
* Note that the derived class FEEvaluationAccess overloads this operation
* with specializations for the scalar case (n_components == 1) and for the
const VectorizedArray<Number> *begin_dof_values () const;
/**
- * Returns a read and write pointer to the first field of the dof
- * values. This is the data field the read_dof_values() functions write
- * into. First come the the dof values for the first component, then all
- * values for the second component, and so on. This is related to the
- * internal data structures used in this class. In general, it is safer to
- * use the get_dof_value() function instead.
+ * Returns a read and write pointer to the first field of the dof values.
+ * This is the data field the read_dof_values() functions write into. First
+ * come the the dof values for the first component, then all values for the
+ * second component, and so on. This is related to the internal data
+ * structures used in this class. In general, it is safer to use the
+ * get_dof_value() function instead.
*/
VectorizedArray<Number> *begin_dof_values ();
/**
* Returns a read-only pointer to the first field of function hessians on
* quadrature points. First comes the xx-component of the hessian for the
- * first component on all quadrature points, then the yy-component,
- * zz-component in (3D), then the xy-component, and so on. Next comes the
- * xx-component of the second component, and so on. This is related to the
+ * first component on all quadrature points, then the yy-component, zz-
+ * component in (3D), then the xy-component, and so on. Next comes the xx-
+ * component of the second component, and so on. This is related to the
* internal data structures used in this class. The raw data after a call to
* @p evaluate only contains unit cell operations, so possible
* transformations, quadrature weights etc. must be applied manually. In
/**
* Returns a read and write pointer to the first field of function hessians
* on quadrature points. First comes the xx-component of the hessian for the
- * first component on all quadrature points, then the yy-component,
- * zz-component in (3D), then the xy-component, and so on. Next comes the
- * xx-component of the second component, and so on. This is related to the
+ * first component on all quadrature points, then the yy-component, zz-
+ * component in (3D), then the xy-component, and so on. Next comes the xx-
+ * component of the second component, and so on. This is related to the
* internal data structures used in this class. The raw data after a call to
* @p evaluate only contains unit cell operations, so possible
* transformations, quadrature weights etc. must be applied manually. In
/**
* Constructor that comes with reduced functionality and works similar as
* FEValues. The arguments are similar to the ones passed to the constructor
- * of FEValues, with the notable difference that FEEvaluation expects a
- * one-dimensional quadrature formula, Quadrature<1>, instead of a @p dim
+ * of FEValues, with the notable difference that FEEvaluation expects a one-
+ * dimensional quadrature formula, Quadrature<1>, instead of a @p dim
* dimensional one. The finite element can be both scalar or vector valued,
* but this method always only selects a scalar base element at a time (with
* @p n_components copies as specified by the class template argument). For
* degrees of freedom of the current class known. If the iterator includes
* DoFHandler information (i.e., it is a DoFHandler::cell_iterator or
* similar), the initialization allows to also read from or write to vectors
- * in the standard way for DoFHandler::active_cell_iterator types for
- * one cell at a time. However, this approach is much slower than the path
- * with MatrixFree with MPI since index translation has to be done. As only
- * one cell at a time is used, this method does not vectorize over several
+ * in the standard way for DoFHandler::active_cell_iterator types for one
+ * cell at a time. However, this approach is much slower than the path with
+ * MatrixFree with MPI since index translation has to be done. As only one
+ * cell at a time is used, this method does not vectorize over several
* elements (which is most efficient for vector operations), but only
* possibly within the element if the evaluate/integrate routines are
* combined inside user code (e.g. for computing cell matrices).
/**
* This field stores the values of the finite element function on quadrature
- * points after applying unit cell transformations or before
- * integrating. The methods get_value() and submit_value() access this
- * field.
+ * points after applying unit cell transformations or before integrating.
+ * The methods get_value() and submit_value() access this field.
*/
VectorizedArray<Number> *values_quad[n_components];
const MatrixFree<dim,Number> *matrix_info;
/**
- * Stores a pointer to the underlying DoF indices and constraint
- * description for the component specified at construction. Also contained
- * in matrix_info, but it simplifies code if we store a reference to it.
+ * Stores a pointer to the underlying DoF indices and constraint description
+ * for the component specified at construction. Also contained in
+ * matrix_info, but it simplifies code if we store a reference to it.
*/
const internal::MatrixFreeFunctions::DoFInfo *dof_info;
/**
- * Stores a pointer to the underlying transformation data from unit to
- * real cells for the given quadrature formula specified at construction.
- * Also contained in matrix_info, but it simplifies code if we store a
- * reference to it.
+ * Stores a pointer to the underlying transformation data from unit to real
+ * cells for the given quadrature formula specified at construction. Also
+ * contained in matrix_info, but it simplifies code if we store a reference
+ * to it.
*/
const internal::MatrixFreeFunctions::MappingInfo<dim,Number> *mapping_info;
/**
* A pointer to the upper diagonal part of the Jacobian gradient on the
- * present cell. Only set to a useful value if on a general cell with
- * non-constant Jacobian.
+ * present cell. Only set to a useful value if on a general cell with non-
+ * constant Jacobian.
*/
const Tensor<1,(dim>1?dim*(dim-1)/2:1),Tensor<1,dim,VectorizedArray<Number> > > * jacobian_grad_upper;
/**
* Debug information to track whether gradients on quadrature points have
- * been submitted for integration before the integration is actually
- * stared. Used to control exceptions when uninitialized data is used.
+ * been submitted for integration before the integration is actually stared.
+ * Used to control exceptions when uninitialized data is used.
*/
bool gradients_quad_submitted;
/**
- * This class provides access to the data fields of the FEEvaluation
- * classes. Generic access is achieved through the base class, and
- * specializations for scalar and vector-valued elements are defined
- * separately.
+ * This class provides access to the data fields of the FEEvaluation classes.
+ * Generic access is achieved through the base class, and specializations for
+ * scalar and vector-valued elements are defined separately.
*
* @author Katharina Kormann and Martin Kronbichler, 2010, 2011
*/
/**
- * This class provides access to the data fields of the FEEvaluation
- * classes. Partial specialization for scalar fields that defines access with
- * simple data fields, i.e., scalars for the values and Tensor<1,dim> for the
+ * This class provides access to the data fields of the FEEvaluation classes.
+ * Partial specialization for scalar fields that defines access with simple
+ * data fields, i.e., scalars for the values and Tensor<1,dim> for the
* gradients.
*
* @author Katharina Kormann and Martin Kronbichler, 2010, 2011
/**
* Write a contribution that is tested by the gradient to the field
- * containing the values on quadrature points with component @p
- * q_point. Access to the same field as through @p get_gradient. If applied
- * before the function @p integrate(...,true) is called, this specifies what
- * is tested by all basis function gradients on the current cell and
- * integrated over.
+ * containing the values on quadrature points with component @p q_point.
+ * Access to the same field as through @p get_gradient. If applied before
+ * the function @p integrate(...,true) is called, this specifies what is
+ * tested by all basis function gradients on the current cell and integrated
+ * over.
*/
void submit_gradient(const gradient_type grad_in,
const unsigned int q_point);
/**
- * This class provides access to the data fields of the FEEvaluation
- * classes. Partial specialization for fields with as many components as the
- * underlying space dimension, i.e., values are of type Tensor<1,dim> and
- * gradients of type Tensor<2,dim>. Provides some additional functions for
- * access, like the symmetric gradient and divergence.
+ * This class provides access to the data fields of the FEEvaluation classes.
+ * Partial specialization for fields with as many components as the underlying
+ * space dimension, i.e., values are of type Tensor<1,dim> and gradients of
+ * type Tensor<2,dim>. Provides some additional functions for access, like the
+ * symmetric gradient and divergence.
*
* @author Katharina Kormann and Martin Kronbichler, 2010, 2011
*/
/**
* Write a contribution that is tested by the gradient to the field
- * containing the values on quadrature points with component @p
- * q_point. Access to the same field as through @p get_gradient. If applied
- * before the function @p integrate(...,true) is called, this specifies what
- * is tested by all basis function gradients on the current cell and
- * integrated over.
+ * containing the values on quadrature points with component @p q_point.
+ * Access to the same field as through @p get_gradient. If applied before
+ * the function @p integrate(...,true) is called, this specifies what is
+ * tested by all basis function gradients on the current cell and integrated
+ * over.
*/
void submit_gradient(const gradient_type grad_in,
const unsigned int q_point);
/**
* Write a contribution that is tested by the gradient to the field
- * containing the values on quadrature points with component @p
- * q_point. This function is an alternative to the other submit_gradient
- * function when using a system of fixed number of equations which happens
- * to coincide with the dimension for some dimensions, but not all. To allow
+ * containing the values on quadrature points with component @p q_point.
+ * This function is an alternative to the other submit_gradient function
+ * when using a system of fixed number of equations which happens to
+ * coincide with the dimension for some dimensions, but not all. To allow
* for dimension-independent programming, this function can be used instead.
*/
void submit_gradient(const Tensor<1,dim,Tensor<1,dim,VectorizedArray<Number> > > grad_in,
/**
* Write a constribution that is tested by the divergence to the field
- * containing the values on quadrature points with component @p
- * q_point. Access to the same field as through @p get_gradient. If applied
- * before the function @p integrate(...,true) is called, this specifies what
- * is tested by all basis function gradients on the current cell and
- * integrated over.
+ * containing the values on quadrature points with component @p q_point.
+ * Access to the same field as through @p get_gradient. If applied before
+ * the function @p integrate(...,true) is called, this specifies what is
+ * tested by all basis function gradients on the current cell and integrated
+ * over.
*/
void submit_divergence (const VectorizedArray<Number> div_in,
const unsigned int q_point);
/**
* Write a contribution that is tested by the gradient to the field
- * containing the values on quadrature points with component @p
- * q_point. Access to the same field as through @p get_gradient. If applied
- * before the function @p integrate(...,true) is called, this specifies the
+ * containing the values on quadrature points with component @p q_point.
+ * Access to the same field as through @p get_gradient. If applied before
+ * the function @p integrate(...,true) is called, this specifies the
* gradient which is tested by all basis function gradients on the current
* cell and integrated over.
*/
/**
- * This class provides access to the data fields of the FEEvaluation
- * classes. Partial specialization for scalar fields in 1d that defines access with
+ * This class provides access to the data fields of the FEEvaluation classes.
+ * Partial specialization for scalar fields in 1d that defines access with
* simple data fields, i.e., scalars for the values and Tensor<1,1> for the
* gradients.
*
- * @author Katharina Kormann and Martin Kronbichler, 2010, 2011, Shiva Rudraraju, 2014
+ * @author Katharina Kormann and Martin Kronbichler, 2010, 2011, Shiva
+ * Rudraraju, 2014
*/
template <typename Number>
class FEEvaluationAccess<1,1,Number> : public FEEvaluationBase<1,1,Number>
/**
* Write a contribution that is tested by the gradient to the field
- * containing the values on quadrature points with component @p
- * q_point. Access to the same field as through @p get_gradient. If applied
- * before the function @p integrate(...,true) is called, this specifies what
- * is tested by all basis function gradients on the current cell and
- * integrated over.
+ * containing the values on quadrature points with component @p q_point.
+ * Access to the same field as through @p get_gradient. If applied before
+ * the function @p integrate(...,true) is called, this specifies what is
+ * tested by all basis function gradients on the current cell and integrated
+ * over.
*/
void submit_gradient(const gradient_type grad_in,
const unsigned int q_point);
* for applying a vector operation for several cells at once. This setting is
* explained in the step-37 and step-48 tutorial programs. For vector-valued
* problems, the deal.II test suite includes a few additional examples as
- * well, e.g. the Stokes operator found at
- * https://github.com/dealii/dealii/blob/master/tests/matrix_free/matrix_vector_stokes_noflux.cc
+ * well, e.g. the Stokes operator found at https://github.com/dealii/dealii/bl
+ * ob/master/tests/matrix_free/matrix_vector_stokes_noflux.cc
*
* For most operator evaluation tasks, this path provides the most efficient
* solution by combining pre-computed data for the mapping (Jacobian
* MatrixFree class may not be desired. In such a case, the cost to initialize
* the necessary geometry data on the fly is comparably low and thus avoiding
* a global object MatrixFree can be useful. When used in this way, reinit
- * methods reminiscent from FEValues with a cell iterator are to be
- * used. However, note that this model results in working on a single cell at
- * a time, with geometry data duplicated in all components of the vectorized
+ * methods reminiscent from FEValues with a cell iterator are to be used.
+ * However, note that this model results in working on a single cell at a
+ * time, with geometry data duplicated in all components of the vectorized
* array. Thus, vectorization is only useful when it can apply the same
* operation on different data, e.g. when performing matrix assembly.
*
* @param dim Dimension in which this class is to be used
*
* @param fe_degree Degree of the tensor product finite element with
- * fe_degree+1 degrees of freedom per coordinate direction
+ * fe_degree+1 degrees of freedom per coordinate direction
*
* @param n_q_points_1d Number of points in the quadrature formula in 1D,
- * defaults to fe_degree+1
+ * defaults to fe_degree+1
*
* @param n_components Number of vector components when solving a system of
- * PDEs. If the same operation is applied to several
- * components of a PDE (e.g. a vector Laplace equation), they
- * can be applied simultaneously with one call (and often
- * more efficiently). Defaults to 1.
+ * PDEs. If the same operation is applied to several components of a PDE (e.g.
+ * a vector Laplace equation), they can be applied simultaneously with one
+ * call (and often more efficiently). Defaults to 1.
*
- * @param Number Number format, usually @p double or @p float.
- * Defaults to @p double
+ * @param Number Number format, usually @p double or @p float. Defaults to @p
+ * double
*
* @author Katharina Kormann and Martin Kronbichler, 2010, 2011
*/
/**
* Constructor that comes with reduced functionality and works similar as
* FEValues. The arguments are similar to the ones passed to the constructor
- * of FEValues, with the notable difference that FEEvaluation expects a
- * one-dimensional quadrature formula, Quadrature<1>, instead of a @p dim
+ * of FEValues, with the notable difference that FEEvaluation expects a one-
+ * dimensional quadrature formula, Quadrature<1>, instead of a @p dim
* dimensional one. The finite element can be both scalar or vector valued,
* but this method always only selects a scalar base element at a time (with
- * @p n_components copies as specified by the class template). For
- * vector-valued elements, the optional argument @p first_selected_component
- * allows to specify the index of the base element to be used for
- * evaluation. Note that the internal data structures always assume that the
- * base element is primitive, non-primitive are not supported currently.
+ * @p n_components copies as specified by the class template). For vector-
+ * valued elements, the optional argument @p first_selected_component allows
+ * to specify the index of the base element to be used for evaluation. Note
+ * that the internal data structures always assume that the base element is
+ * primitive, non-primitive are not supported currently.
*
* As known from FEValues, a call to the reinit method with a
* Triangulation<dim>::cell_iterator is necessary to make the geometry and
template <typename Number> struct ConstraintValues;
/**
- * A struct that collects all information
- * related to parallelization with threads:
- * The work is subdivided into tasks that can
- * be done independently.
+ * A struct that collects all information related to parallelization with
+ * threads: The work is subdivided into tasks that can be done
+ * independently.
*/
struct TaskInfo
{
TaskInfo ();
/**
- * Clears all the data fields and resets them
- * to zero.
+ * Clears all the data fields and resets them to zero.
*/
void clear ();
/**
- * Returns the memory consumption of
- * the class.
+ * Returns the memory consumption of the class.
*/
std::size_t memory_consumption () const;
/**
- * A struct that collects all information
- * related to the size of the problem and MPI
- * parallelization.
+ * A struct that collects all information related to the size of the
+ * problem and MPI parallelization.
*/
struct SizeInfo
{
SizeInfo ();
/**
- * Clears all data fields and resets the sizes
- * to zero.
+ * Clears all data fields and resets the sizes to zero.
*/
void clear();
/**
- * Prints minimum, average, and
- * maximal memory consumption over the
- * MPI processes.
+ * Prints minimum, average, and maximal memory consumption over the MPI
+ * processes.
*/
template <typename STREAM>
void print_memory_statistics (STREAM &out,
std::size_t data_length) const;
/**
- * Determines the position of cells
- * with ghosts for distributed-memory
+ * Determines the position of cells with ghosts for distributed-memory
* calculations.
*/
void make_layout (const unsigned int n_active_cells_in,
unsigned int vectorization_length;
/**
- * index sets to describe the layout of cells:
- * locally owned cells and locally active
- * cells
+ * index sets to describe the layout of cells: locally owned cells and
+ * locally active cells
*/
IndexSet locally_owned_cells;
IndexSet ghost_cells;
/**
- * A class that is used to compare floating point arrays (e.g. std::vectors,
- * Tensor<1,dim>, etc.). The idea of this class is to consider two arrays as
- * equal if they are the same within a given tolerance. We use this
- * comparator class within an std::map<> of the given arrays. Note that this
- * comparison operator does not satisfy all the mathematical properties one
- * usually wants to have (consider e.g. the numbers a=0, b=0.1, c=0.2 with
- * tolerance 0.15; the operator gives a<c, but neither of a<b? or b<c? is
- * satisfied). This is not a problem in the use cases for this class, but be
- * careful when using it in other contexts.
+ * A class that is used to compare floating point arrays (e.g.
+ * std::vectors, Tensor<1,dim>, etc.). The idea of this class is to
+ * consider two arrays as equal if they are the same within a given
+ * tolerance. We use this comparator class within an std::map<> of the
+ * given arrays. Note that this comparison operator does not satisfy all
+ * the mathematical properties one usually wants to have (consider e.g.
+ * the numbers a=0, b=0.1, c=0.2 with tolerance 0.15; the operator gives
+ * a<c, but neither of a<b? or b<c? is satisfied). This is not a problem
+ * in the use cases for this class, but be careful when using it in other
+ * contexts.
*/
template<typename Number>
struct FPArrayComparator
public:
/**
* Constructor, similar to FEValues. Since this class only evaluates the
- * geometry, no finite element has to be specified and the simplest element,
- * FE_Nothing, is used internally for the underlying FEValues object.
+ * geometry, no finite element has to be specified and the simplest
+ * element, FE_Nothing, is used internally for the underlying FEValues
+ * object.
*/
MappingDataOnTheFly (const Mapping<dim> &mapping,
const Quadrature<1> &quadrature,
/**
* Return a reference to the underlying FEValues object that evaluates
- * certain quantities (only mapping-related ones like Jacobians or mapped
- * quadrature points are accessible, as no finite element data is actually
- * used).
+ * certain quantities (only mapping-related ones like Jacobians or
+ * mapped quadrature points are accessible, as no finite element data is
+ * actually used).
*/
const FEValues<dim> &get_fe_values () const;
/**
- * Return a vector of inverse transpose Jacobians. For compatibility with
- * FEEvaluation, it returns tensors of vectorized arrays, even though all
- * components are equal.
+ * Return a vector of inverse transpose Jacobians. For compatibility
+ * with FEEvaluation, it returns tensors of vectorized arrays, even
+ * though all components are equal.
*/
const AlignedVector<Tensor<2,dim,VectorizedArray<Number> > > &
get_inverse_jacobians() const;
get_JxW_values() const;
/**
- * Return a vector of quadrature points in real space on the given
- * cell. For compatibility with FEEvaluation, it returns tensors of
- * vectorized arrays, even though all components are equal.
+ * Return a vector of quadrature points in real space on the given cell.
+ * For compatibility with FEEvaluation, it returns tensors of vectorized
+ * arrays, even though all components are equal.
*/
const AlignedVector<Point<dim,VectorizedArray<Number> > > &
get_quadrature_points() const;
/**
- * Return a vector of quadrature points in real space on the given
- * cell. For compatibility with FEEvaluation, it returns tensors of
- * vectorized arrays, even though all components are equal.
+ * Return a vector of quadrature points in real space on the given cell.
+ * For compatibility with FEEvaluation, it returns tensors of vectorized
+ * arrays, even though all components are equal.
*/
const AlignedVector<Tensor<1,dim,VectorizedArray<Number> > > &
get_normal_vectors() const;
static const std::size_t n_cell_type_bits = 2;
/**
- * Determines how many types of different cells can be detected at
- * most. Corresponds to the number of bits we reserved for it.
+ * Determines how many types of different cells can be detected at most.
+ * Corresponds to the number of bits we reserved for it.
*/
static const unsigned int n_cell_types = 1U<<n_cell_type_bits;
/**
- * An abbreviation for the length of vector lines of the current data type.
+ * An abbreviation for the length of vector lines of the current data
+ * type.
*/
static const unsigned int n_vector_elements = VectorizedArray<Number>::n_array_elements;
/**
* Stores the diagonal part of the gradient of the inverse Jacobian
* transformation. The first index runs over the derivatives
- * $\partial^2/\partial x_i^2$, the second over the space
- * coordinate. Needed for computing the Laplacian of FE functions on
- * the real cell. Uses a separate storage from the off-diagonal part
+ * $\partial^2/\partial x_i^2$, the second over the space coordinate.
+ * Needed for computing the Laplacian of FE functions on the real
+ * cell. Uses a separate storage from the off-diagonal part
* $\partial^2/\partial x_i \partial x_j, i\neq j$ because that is
* only needed for computing a full Hessian.
*/
* The stored data can be subdivided into three main components:
*
* - DoFInfo: It stores how local degrees of freedom relate to global degrees
- * of freedom. It includes a description of constraints that are evaluated
- * as going through all local degrees of freedom on a cell.
+ * of freedom. It includes a description of constraints that are evaluated as
+ * going through all local degrees of freedom on a cell.
*
* - MappingInfo: It stores the transformations from real to unit cells that
- * are necessary in order to build derivatives of finite element functions
- * and find location of quadrature weights in physical space.
+ * are necessary in order to build derivatives of finite element functions and
+ * find location of quadrature weights in physical space.
*
* - ShapeInfo: It contains the shape functions of the finite element,
- * evaluated on the unit cell.
+ * evaluated on the unit cell.
*
- * Besides the initialization routines, this class implements only a
- * single operation, namely a loop over all cells (cell_loop()). This
- * loop is scheduled in such a way that cells that share degrees of
- * freedom are not worked on simultaneously, which implies that it is
- * possible to write to vectors (or matrices) in parallel without
- * having to explicitly synchronize access to these vectors and
- * matrices. This class does not implement any shape values, all it
- * does is to cache the respective data. To implement finite element
- * operations, use the class FEEvaluation (or some of the related
- * classes).
+ * Besides the initialization routines, this class implements only a single
+ * operation, namely a loop over all cells (cell_loop()). This loop is
+ * scheduled in such a way that cells that share degrees of freedom are not
+ * worked on simultaneously, which implies that it is possible to write to
+ * vectors (or matrices) in parallel without having to explicitly synchronize
+ * access to these vectors and matrices. This class does not implement any
+ * shape values, all it does is to cache the respective data. To implement
+ * finite element operations, use the class FEEvaluation (or some of the
+ * related classes).
*
* This class traverses the cells in a different order than the usual
* Triangulation class in deal.II, in order to be flexible with respect to
MPI_Comm mpi_communicator;
/**
- * Sets the scheme for task parallelism. There are four options
- * available. If set to @p none, the operator application is done in
- * serial without shared memory parallelism. If this class is used
- * together with MPI and MPI is also used for parallelism within the
- * nodes, this flag should be set to @p none. The default value is @p
- * partition_partition, i.e. we actually use multithreading with the first
- * option described below.
+ * Sets the scheme for task parallelism. There are four options available.
+ * If set to @p none, the operator application is done in serial without
+ * shared memory parallelism. If this class is used together with MPI and
+ * MPI is also used for parallelism within the nodes, this flag should be
+ * set to @p none. The default value is @p partition_partition, i.e. we
+ * actually use multithreading with the first option described below.
*
* The first option @p partition_partition is to partition the cells on
* two levels in onion-skin-like partitions and forming chunks of
/**
* Sets the number of so-called macro cells that should form one
* partition. If zero size is given, the class tries to find a good size
- * for the blocks based on
- * multithread_info.n_threads() and the number of cells
- * present. Otherwise, the given number is used. If the given number is
- * larger than one third of the number of total cells, this means no
+ * for the blocks based on multithread_info.n_threads() and the number of
+ * cells present. Otherwise, the given number is used. If the given number
+ * is larger than one third of the number of total cells, this means no
* parallelism. Note that in the case vectorization is used, a macro cell
* consists of more than one physical cell.
*/
MatrixFree ();
/**
- * Destructor.
- */
+ * Destructor.
+ */
~MatrixFree();
/**
- * Extracts the information needed to perform loops over cells. The
- * DoFHandler and ConstraintMatrix describe the layout of degrees of freedom,
- * the DoFHandler and the mapping describe the transformations from unit to
- * real cell, and the finite element underlying the DoFHandler together with
- * the quadrature formula describe the local operations. Note that the finite
- * element underlying the DoFHandler must either be scalar or contain several
- * copies of the same element. Mixing several different elements into one
- * FESystem is not allowed. In that case, use the initialization function
- * with several DoFHandler arguments.
- *
- * The @p IndexSet @p locally_owned_dofs is used to specify the parallel
- * partitioning with MPI. Usually, this needs not be specified, and the other
- * initialization function without and @p IndexSet description can be used,
- * which gets the partitioning information builtin into the DoFHandler.
- */
+ * Extracts the information needed to perform loops over cells. The
+ * DoFHandler and ConstraintMatrix describe the layout of degrees of
+ * freedom, the DoFHandler and the mapping describe the transformations from
+ * unit to real cell, and the finite element underlying the DoFHandler
+ * together with the quadrature formula describe the local operations. Note
+ * that the finite element underlying the DoFHandler must either be scalar
+ * or contain several copies of the same element. Mixing several different
+ * elements into one FESystem is not allowed. In that case, use the
+ * initialization function with several DoFHandler arguments.
+ *
+ * The @p IndexSet @p locally_owned_dofs is used to specify the parallel
+ * partitioning with MPI. Usually, this needs not be specified, and the
+ * other initialization function without and @p IndexSet description can be
+ * used, which gets the partitioning information builtin into the
+ * DoFHandler.
+ */
template <typename DH, typename Quadrature>
void reinit (const Mapping<dim> &mapping,
const DH &dof_handler,
const AdditionalData additional_data = AdditionalData());
/**
- * Initializes the data structures. Same as above, but with index set stored
- * in the DoFHandler for describing the locally owned degrees of freedom.
- */
+ * Initializes the data structures. Same as above, but with index set stored
+ * in the DoFHandler for describing the locally owned degrees of freedom.
+ */
template <typename DH, typename Quadrature>
void reinit (const Mapping<dim> &mapping,
const DH &dof_handler,
const AdditionalData additional_data = AdditionalData());
/**
- * Initializes the data structures. Same as above, but with mapping @p
- * MappingQ1.
- */
+ * Initializes the data structures. Same as above, but with mapping @p
+ * MappingQ1.
+ */
template <typename DH, typename Quadrature>
void reinit (const DH &dof_handler,
const ConstraintMatrix &constraint,
const AdditionalData additional_data = AdditionalData());
/**
- * Extracts the information needed to perform loops over cells. The
- * DoFHandler and ConstraintMatrix describe the layout of degrees of freedom,
- * the DoFHandler and the mapping describe the transformations from unit to
- * real cell, and the finite element underlying the DoFHandler together with
- * the quadrature formula describe the local operations. As opposed to the
- * scalar case treated with the other initialization functions, this function
- * allows for problems with two or more different finite elements. The
- * DoFHandlers to each element must be passed as pointers to the
- * initialization function. Note that the finite element underlying an
- * DoFHandler must either be scalar or contain several copies of the same
- * element. Mixing several different elements into one @p FE_System is not
- * allowed.
- *
- * This function also allows for using several quadrature formulas, e.g. when
- * the description contains independent integrations of elements of different
- * degrees. However, the number of different quadrature formulas can be sets
- * independently from the number of DoFHandlers, when several elements are
- * always integrated with the same quadrature formula.
- *
- * The @p IndexSet @p locally_owned_dofs is used to specify the parallel
- * partitioning with MPI. Usually, this needs not be specified, and the other
- * initialization function without and @p IndexSet description can be used,
- * which gets the partitioning information from the DoFHandler. This is the
- * most general initialization function.
- */
+ * Extracts the information needed to perform loops over cells. The
+ * DoFHandler and ConstraintMatrix describe the layout of degrees of
+ * freedom, the DoFHandler and the mapping describe the transformations from
+ * unit to real cell, and the finite element underlying the DoFHandler
+ * together with the quadrature formula describe the local operations. As
+ * opposed to the scalar case treated with the other initialization
+ * functions, this function allows for problems with two or more different
+ * finite elements. The DoFHandlers to each element must be passed as
+ * pointers to the initialization function. Note that the finite element
+ * underlying an DoFHandler must either be scalar or contain several copies
+ * of the same element. Mixing several different elements into one @p
+ * FE_System is not allowed.
+ *
+ * This function also allows for using several quadrature formulas, e.g.
+ * when the description contains independent integrations of elements of
+ * different degrees. However, the number of different quadrature formulas
+ * can be sets independently from the number of DoFHandlers, when several
+ * elements are always integrated with the same quadrature formula.
+ *
+ * The @p IndexSet @p locally_owned_dofs is used to specify the parallel
+ * partitioning with MPI. Usually, this needs not be specified, and the
+ * other initialization function without and @p IndexSet description can be
+ * used, which gets the partitioning information from the DoFHandler. This
+ * is the most general initialization function.
+ */
template <typename DH, typename Quadrature>
void reinit (const Mapping<dim> &mapping,
const std::vector<const DH *> &dof_handler,
const AdditionalData additional_data = AdditionalData());
/**
- * Initializes the data structures. Same as before, but now the index set
- * description of the locally owned range of degrees of freedom is taken from
- * the DoFHandler.
- */
+ * Initializes the data structures. Same as before, but now the index set
+ * description of the locally owned range of degrees of freedom is taken
+ * from the DoFHandler.
+ */
template <typename DH, typename Quadrature>
void reinit (const Mapping<dim> &mapping,
const std::vector<const DH *> &dof_handler,
const AdditionalData additional_data = AdditionalData());
/**
- * Initializes the data structures. Same as above, but with mapping @p
- * MappingQ1.
- */
+ * Initializes the data structures. Same as above, but with mapping @p
+ * MappingQ1.
+ */
template <typename DH, typename Quadrature>
void reinit (const std::vector<const DH *> &dof_handler,
const std::vector<const ConstraintMatrix *> &constraint,
const AdditionalData additional_data = AdditionalData());
/**
- * Initializes the data structures. Same as before, but now the index set
- * description of the locally owned range of degrees of freedom is taken from
- * the DoFHandler. Moreover, only a single quadrature formula is used, as
- * might be necessary when several components in a vector-valued problem are
- * integrated together based on the same quadrature formula.
- */
+ * Initializes the data structures. Same as before, but now the index set
+ * description of the locally owned range of degrees of freedom is taken
+ * from the DoFHandler. Moreover, only a single quadrature formula is used,
+ * as might be necessary when several components in a vector-valued problem
+ * are integrated together based on the same quadrature formula.
+ */
template <typename DH, typename Quadrature>
void reinit (const Mapping<dim> &mapping,
const std::vector<const DH *> &dof_handler,
const AdditionalData additional_data = AdditionalData());
/**
- * Initializes the data structures. Same as above, but with mapping @p
- * MappingQ1.
- */
+ * Initializes the data structures. Same as above, but with mapping @p
+ * MappingQ1.
+ */
template <typename DH, typename Quadrature>
void reinit (const std::vector<const DH *> &dof_handler,
const std::vector<const ConstraintMatrix *> &constraint,
get_constrained_dofs (const unsigned int fe_component = 0) const;
/**
- * Calls renumber_dofs function in dof_info which renumbers the degrees
- * of freedom according to the ordering for parallelization.
+ * Calls renumber_dofs function in dof_info which renumbers the degrees of
+ * freedom according to the ordering for parallelization.
*/
void renumber_dofs (std::vector<types::global_dof_index> &renumbering,
const unsigned int vector_component = 0);
namespace MatrixFreeOperators
{
/**
- * This class implements the operation of the action of the inverse of a mass
- * matrix on an element for the special case of an evaluation object with as
- * many quadrature points as there are cell degrees of freedom. It uses
- * algorithms from FEEvaluation and produces the exact mass matrix for DGQ
- * elements. This algorithm uses tensor products of inverse 1D shape matrices
- * over quadrature points, so the inverse operation is exactly as expensive as
- * applying the forward operator on each cell. Of course, for continuous
- * finite elements this operation does not produce the inverse of a mass
- * operation as the coupling between the elements cannot be considered by this
- * operation.
+ * This class implements the operation of the action of the inverse of a
+ * mass matrix on an element for the special case of an evaluation object
+ * with as many quadrature points as there are cell degrees of freedom. It
+ * uses algorithms from FEEvaluation and produces the exact mass matrix for
+ * DGQ elements. This algorithm uses tensor products of inverse 1D shape
+ * matrices over quadrature points, so the inverse operation is exactly as
+ * expensive as applying the forward operator on each cell. Of course, for
+ * continuous finite elements this operation does not produce the inverse of
+ * a mass operation as the coupling between the elements cannot be
+ * considered by this operation.
*
- * The equation may contain variable coefficients, so the user is required to
- * provide an array for the inverse of the local coefficient (this class
+ * The equation may contain variable coefficients, so the user is required
+ * to provide an array for the inverse of the local coefficient (this class
* provide a helper method 'fill_inverse_JxW_values' to get the inverse of a
* constant-coefficient operator).
*
* Applies the inverse mass matrix operation on an input array. It is
* assumed that the passed input and output arrays are of correct size,
* namely FEEval::dofs_per_cell * n_components long. The inverse of the
- * local coefficient (also containing the inverse JxW values) must be passed
- * as first argument. Passing more than one component in the coefficient is
- * allowed.
+ * local coefficient (also containing the inverse JxW values) must be
+ * passed as first argument. Passing more than one component in the
+ * coefficient is allowed.
*/
void apply(const AlignedVector<VectorizedArray<Number> > &inverse_coefficient,
const unsigned int n_actual_components,
/**
* Initializes the data fields. Takes a one-dimensional quadrature
* formula and a finite element as arguments and evaluates the shape
- * functions, gradients and Hessians on the one-dimensional unit
- * cell. This function assumes that the finite element is derived from a
- * one-dimensional element by a tensor product and that the zeroth shape
+ * functions, gradients and Hessians on the one-dimensional unit cell.
+ * This function assumes that the finite element is derived from a one-
+ * dimensional element by a tensor product and that the zeroth shape
* function in zero evaluates to one.
*/
template <int dim>
AlignedVector<VectorizedArray<Number> > shape_val_evenodd;
/**
- * Stores the shape gradients in a different format, namely the
- * so-called even-odd scheme where the symmetries in shape_gradients are
+ * Stores the shape gradients in a different format, namely the so-
+ * called even-odd scheme where the symmetries in shape_gradients are
* used for faster evaluation.
*/
AlignedVector<VectorizedArray<Number> > shape_gra_evenodd;
{
/**
* The namespace containing objects that can be used to assemble data
- * computed on cells and faces into global objects. This can reach
- * from collecting the total error estimate from cell and face
- * contributions to assembling matrices and multilevel matrices.
+ * computed on cells and faces into global objects. This can reach from
+ * collecting the total error estimate from cell and face contributions to
+ * assembling matrices and multilevel matrices.
*
* <h3>Data models</h3>
*
- * The class chosen from this namespace determines which data model is
- * used. For the local as well as the global objects, we have the
- * choice between two models:
+ * The class chosen from this namespace determines which data model is used.
+ * For the local as well as the global objects, we have the choice between
+ * two models:
*
* <h4>The comprehensive data model</h4>
*
- * This is the structure set up by the FESystem class. Globally, this
- * means, data is assembled into one residual vector and into one
- * matrix. These objects may be block vectors and block matrices, but
- * the process of assembling ignores this fact.
+ * This is the structure set up by the FESystem class. Globally, this means,
+ * data is assembled into one residual vector and into one matrix. These
+ * objects may be block vectors and block matrices, but the process of
+ * assembling ignores this fact.
*
* Similarly, there is only a single cell vector and cell matrix,
- * respectively, which is indexed by all degrees of freedom of the
- * FESystem. When building the cell matrix, it is necessary to
- * distinguish between the different components of the system and
- * select the right operator for each pair.
+ * respectively, which is indexed by all degrees of freedom of the FESystem.
+ * When building the cell matrix, it is necessary to distinguish between the
+ * different components of the system and select the right operator for each
+ * pair.
*
* <h4>The blocked data model</h4>
*
- * Here, all the blocks are treated separately (in spite of using
- * FESystem for its convenience in other places). For instance, no
- * block matrix is assembled, but a list of blocks, which can be
- * combined later by BlockMatrixArray. Locally, this means, that each
- * matrix block of a system is generated separately and assembled into
- * the corresponding global block.
+ * Here, all the blocks are treated separately (in spite of using FESystem
+ * for its convenience in other places). For instance, no block matrix is
+ * assembled, but a list of blocks, which can be combined later by
+ * BlockMatrixArray. Locally, this means, that each matrix block of a system
+ * is generated separately and assembled into the corresponding global
+ * block.
*
- * This approach is advantageous, if the number of matrices for each
- * block position in the global system is different. For instance,
- * block preconditioners for the Oseen problem require 3 pressure
- * matrices, but only one divergence and one advection-diffusion
- * operator for velocities.
+ * This approach is advantageous, if the number of matrices for each block
+ * position in the global system is different. For instance, block
+ * preconditioners for the Oseen problem require 3 pressure matrices, but
+ * only one divergence and one advection-diffusion operator for velocities.
*
* Additionally, this approach enables the construction of a system of
- * equations from building blocks for each equation and coupling
- * operator.
+ * equations from building blocks for each equation and coupling operator.
*
- * Nevertheless, since a separate FEValues object must be created for
- * each base element, it is not quite clear a priori, which data model
- * is more efficient.
+ * Nevertheless, since a separate FEValues object must be created for each
+ * base element, it is not quite clear a priori, which data model is more
+ * efficient.
*
* @ingroup MeshWorker
* @author Guido Kanschat, 2009
/**
* Assemble local residuals into global residuals.
*
- * The global residuals are expected as an FEVectors object.
- * The local residuals are block vectors.
+ * The global residuals are expected as an FEVectors object. The local
+ * residuals are block vectors.
*
* Depending on whether the BlockInfo object was initialize with
- * BlockInfo::initialize_local(), the comprehensive or block data
- * model is used locally.
+ * BlockInfo::initialize_local(), the comprehensive or block data model is
+ * used locally.
*
- * In the block model, each of the blocks of the local vectors
- * corresponds to the restriction of a single block of the system to
- * this cell (@ref GlossBlock). Thus, the size of this local block is
- * the number of degrees of freedom of the corresponding base element
- * of the FESystem.
+ * In the block model, each of the blocks of the local vectors corresponds
+ * to the restriction of a single block of the system to this cell (@ref
+ * GlossBlock). Thus, the size of this local block is the number of
+ * degrees of freedom of the corresponding base element of the FESystem.
*
* @todo Comprehensive model currently not implemented.
*
{
public:
/**
- * Copy the BlockInfo and the
- * matrix pointers into local
- * variables.
+ * Copy the BlockInfo and the matrix pointers into local variables.
*/
void initialize(const BlockInfo *block_info,
NamedData<VECTOR *> &residuals);
*/
void initialize(const ConstraintMatrix &constraints);
/**
- * Initialize the local data
- * in the
- * DoFInfo
- * object used later for
+ * Initialize the local data in the DoFInfo object used later for
* assembling.
*
- * The info object refers to
- * a cell if
- * <code>!face</code>, or
- * else to an interior or
- * boundary face.
+ * The info object refers to a cell if <code>!face</code>, or else to an
+ * interior or boundary face.
*/
template <class DOFINFO>
void initialize_info(DOFINFO &info, bool face) const;
/**
- * Assemble the local residuals
- * into the global residuals.
+ * Assemble the local residuals into the global residuals.
*/
template<class DOFINFO>
void assemble(const DOFINFO &info);
/**
- * Assemble both local residuals
- * into the global residuals.
+ * Assemble both local residuals into the global residuals.
*/
template<class DOFINFO>
void assemble(const DOFINFO &info1,
const DOFINFO &info2);
private:
/**
- * Assemble a single local
- * residual into the global.
+ * Assemble a single local residual into the global.
*/
void assemble(VECTOR &global,
const BlockVector<double> &local,
const std::vector<types::global_dof_index> &dof);
/**
- * The global matrices,
- * stored as a vector of
- * pointers.
+ * The global matrices, stored as a vector of pointers.
*/
NamedData<SmartPointer<VECTOR,
ResidualLocalBlocksToGlobalBlocks<VECTOR> > > residuals;
/**
* A helper class assembling local matrices into global matrices.
*
- * The global matrices are expected as a vector of MatrixBlock
- * objects, each containing a matrix object with a function
- * corresponding to SparseMatrix::add() and information on the block
- * row and column this matrix represents in a block system.
+ * The global matrices are expected as a vector of MatrixBlock objects,
+ * each containing a matrix object with a function corresponding to
+ * SparseMatrix::add() and information on the block row and column this
+ * matrix represents in a block system.
*
* The local matrices are expected as a similar vector of MatrixBlock
* objects, but containing a FullMatrix.
*
- * Like with ResidualLocalBlocksToGlobalBlocks, the initialization of
- * the BlockInfo object decides whether the comprehensive data model
- * or the block model is used.
+ * Like with ResidualLocalBlocksToGlobalBlocks, the initialization of the
+ * BlockInfo object decides whether the comprehensive data model or the
+ * block model is used.
*
* In the comprehensive model, each of the LocalMatrixBlocks has
* coordinates (0,0) and dimensions equal to the number of degrees of
* freedom of the FESystem.
*
- * In the comprehensive model, each block has its own block
- * coordinates and the size depends on the associated
- * FESystem::base_element(). These blocks can be generated separately
- * and will be assembled into the correct matrix block by this object.
+ * In the comprehensive model, each block has its own block coordinates
+ * and the size depends on the associated FESystem::base_element(). These
+ * blocks can be generated separately and will be assembled into the
+ * correct matrix block by this object.
*
* @ingroup MeshWorker
* @author Guido Kanschat, 2009
{
public:
/**
- * Constructor, initializing
- * the #threshold, which
- * limits how small numbers
- * may be to be entered into
- * the matrix.
+ * Constructor, initializing the #threshold, which limits how small
+ * numbers may be to be entered into the matrix.
*/
MatrixLocalBlocksToGlobalBlocks(double threshold = 1.e-12);
/**
- * Copy the BlockInfo and the
- * matrix pointers into local
- * variables and initialize
- * cell matrix vectors.
+ * Copy the BlockInfo and the matrix pointers into local variables and
+ * initialize cell matrix vectors.
*/
void initialize(const BlockInfo *block_info,
MatrixBlockVector<MATRIX> &matrices);
*/
void initialize(const ConstraintMatrix &constraints);
/**
- * Initialize the local data
- * in the
- * DoFInfo
- * object used later for
+ * Initialize the local data in the DoFInfo object used later for
* assembling.
*
- * The info object refers to
- * a cell if
- * <code>!face</code>, or
- * else to an interior or
- * boundary face.
+ * The info object refers to a cell if <code>!face</code>, or else to an
+ * interior or boundary face.
*/
template <class DOFINFO>
void initialize_info(DOFINFO &info, bool face) const;
/**
- * Assemble the local matrices
- * into the global matrices.
+ * Assemble the local matrices into the global matrices.
*/
template<class DOFINFO>
void assemble(const DOFINFO &info);
/**
- * Assemble all local matrices
- * into the global matrices.
+ * Assemble all local matrices into the global matrices.
*/
template<class DOFINFO>
void assemble(const DOFINFO &info1,
private:
/**
- * Assemble a single local
- * matrix into a global one.
+ * Assemble a single local matrix into a global one.
*/
void assemble(
MatrixBlock<MATRIX> &global,
const std::vector<types::global_dof_index> &dof2);
/**
- * The global matrices,
- * stored as a vector of
- * pointers.
+ * The global matrices, stored as a vector of pointers.
*/
SmartPointer<MatrixBlockVector<MATRIX>,
MatrixLocalBlocksToGlobalBlocks<MATRIX, number> > matrices;
MatrixLocalBlocksToGlobalBlocks<MATRIX,number> > constraints;
/**
- * The smallest positive
- * number that will be
- * entered into the global
- * matrix. All smaller
- * absolute values will be
- * treated as zero and will
+ * The smallest positive number that will be entered into the global
+ * matrix. All smaller absolute values will be treated as zero and will
* not be assembled.
*/
const double threshold;
/**
* A helper class assembling local matrices into global multilevel
* matrices. This class is the multilevel equivalent of
- * MatrixLocalBlocksToGlobalBlocks and documentation of that class
- * applies here to a large extend.
+ * MatrixLocalBlocksToGlobalBlocks and documentation of that class applies
+ * here to a large extend.
*
* The global matrices are expected as a vector of pointers to MatrixBlock
* objects, each containing a MGLevelObject with matrices with a function
- * corresponding to SparseMatrix::add() and information on the block
- * row and column this matrix represents in a block system.
+ * corresponding to SparseMatrix::add() and information on the block row
+ * and column this matrix represents in a block system.
*
* The local matrices are a similar vector of MatrixBlock objects, but
* containing a FullMatrix.
*
- * If local refinement occurs, the Multigrid method needs more
- * matrices, two for continuous elements and another two if numerical
- * fluxes are computed on interfaces. The second set can be added
- * using initialize_edge_flux(). Once added, the contributions in all
+ * If local refinement occurs, the Multigrid method needs more matrices,
+ * two for continuous elements and another two if numerical fluxes are
+ * computed on interfaces. The second set can be added using
+ * initialize_edge_flux(). Once added, the contributions in all
* participating matrices will be assembled from the cell and face
* matrices automatically.
*
MatrixPtrVectorPtr;
/**
- * Constructor, initializing
- * the #threshold, which
- * limits how small numbers
- * may be to be entered into
- * the matrix.
+ * Constructor, initializing the #threshold, which limits how small
+ * numbers may be to be entered into the matrix.
*/
MGMatrixLocalBlocksToGlobalBlocks(double threshold = 1.e-12);
/**
- * Copy the BlockInfo and the
- * matrix pointers into local
- * variables and initialize
- * cell matrix vectors.
+ * Copy the BlockInfo and the matrix pointers into local variables and
+ * initialize cell matrix vectors.
*/
void initialize(const BlockInfo *block_info,
MatrixPtrVector &matrices);
/**
- * Initialize the multilevel
- * constraints.
+ * Initialize the multilevel constraints.
*/
void initialize(const MGConstrainedDoFs &mg_constrained_dofs);
/**
- * Multigrid methods on
- * locally refined meshes
- * need additional
- * matrices. For
- * discontinuous Galerkin
- * methods, these are two
- * flux matrices across the
- * refinement edge, which are
- * set by this method.
+ * Multigrid methods on locally refined meshes need additional matrices.
+ * For discontinuous Galerkin methods, these are two flux matrices
+ * across the refinement edge, which are set by this method.
*/
void initialize_edge_flux(MatrixPtrVector &up, MatrixPtrVector &down);
/**
- * Multigrid methods on
- * locally refined meshes
- * need additional
- * matrices. For
- * discontinuous Galerkin
- * methods, these are two
- * flux matrices across the
- * refinement edge, which are
- * set by this method.
+ * Multigrid methods on locally refined meshes need additional matrices.
+ * For discontinuous Galerkin methods, these are two flux matrices
+ * across the refinement edge, which are set by this method.
*/
void initialize_interfaces (MatrixPtrVector &interface_in, MatrixPtrVector &interface_out);
/**
- * Initialize the local data
- * in the
- * DoFInfo
- * object used later for
+ * Initialize the local data in the DoFInfo object used later for
* assembling.
*
- * The info object refers to
- * a cell if
- * <code>!face</code>, or
- * else to an interior or
- * boundary face.
+ * The info object refers to a cell if <code>!face</code>, or else to an
+ * interior or boundary face.
*/
template <class DOFINFO>
void initialize_info(DOFINFO &info, bool face) const;
/**
- * Assemble the local matrices
- * into the global matrices.
+ * Assemble the local matrices into the global matrices.
*/
template<class DOFINFO>
void assemble(const DOFINFO &info);
/**
- * Assemble all local matrices
- * into the global matrices.
+ * Assemble all local matrices into the global matrices.
*/
template<class DOFINFO>
void assemble(const DOFINFO &info1,
private:
/**
- * Assemble a single local
- * matrix into a global one.
+ * Assemble a single local matrix into a global one.
*/
void assemble(
MATRIX &global,
bool transpose = false);
/**
- * Assemble a single local
- * matrix into a global one.
+ * Assemble a single local matrix into a global one.
*/
void assemble_fluxes(
MATRIX &global,
const unsigned int level2);
/**
- * Assemble a single local
- * matrix into a global one.
+ * Assemble a single local matrix into a global one.
*/
void assemble_up(
MATRIX &global,
const unsigned int level2);
/**
- * Assemble a single local
- * matrix into a global one.
+ * Assemble a single local matrix into a global one.
*/
void assemble_down(
MATRIX &global,
const unsigned int level2);
/**
- * Assemble a single local
- * matrix into a global one.
+ * Assemble a single local matrix into a global one.
*/
void assemble_in(
MATRIX &global,
const unsigned int level2);
/**
- * Assemble a single local
- * matrix into a global one.
+ * Assemble a single local matrix into a global one.
*/
void assemble_out(
MATRIX &global,
const unsigned int level2);
/**
- * The level matrices,
- * stored as a vector of
- * pointers.
+ * The level matrices, stored as a vector of pointers.
*/
MatrixPtrVectorPtr matrices;
/**
- * The flux matrix between
- * the fine and the coarse
- * level at refinement edges.
+ * The flux matrix between the fine and the coarse level at refinement
+ * edges.
*/
MatrixPtrVectorPtr flux_down;
/**
- * The flux matrix between
- * the coarse and the fine
- * level at refinement edges.
+ * The flux matrix between the coarse and the fine level at refinement
+ * edges.
*/
MatrixPtrVectorPtr flux_up;
/**
- * The interface matrix between
- * the fine and the coarse
- * level at refinement edges.
+ * The interface matrix between the fine and the coarse level at
+ * refinement edges.
*/
MatrixPtrVectorPtr interface_out;
/**
- * The interface matrix between
- * the coarse and the fine
- * level at refinement edges.
+ * The interface matrix between the coarse and the fine level at
+ * refinement edges.
*/
MatrixPtrVectorPtr interface_in;
/**
- * The smallest positive
- * number that will be
- * entered into the global
- * matrix. All smaller
- * absolute values will be
- * treated as zero and will
+ * The smallest positive number that will be entered into the global
+ * matrix. All smaller absolute values will be treated as zero and will
* not be assembled.
*/
const double threshold;
/**
- * A class containing information on geometry and degrees of freedom
- * of a mesh object.
+ * A class containing information on geometry and degrees of freedom of a
+ * mesh object.
*
- * The information in these objects is usually used by one of the
- * Assembler classes. It is also the kind of information which is
- * needed in mesh based matrices (often referred to as matrix free
- * methods).
+ * The information in these objects is usually used by one of the Assembler
+ * classes. It is also the kind of information which is needed in mesh based
+ * matrices (often referred to as matrix free methods).
*
* In addition to the information on degrees of freedom stored in this
- * class, it also provides the local computation space for the worker
- * object operating on it in LocalResults. This base class will automatically
- * be reinitialized on each cell, but initial setup is up to the user and
+ * class, it also provides the local computation space for the worker object
+ * operating on it in LocalResults. This base class will automatically be
+ * reinitialized on each cell, but initial setup is up to the user and
* should be done when initialize() for this class is called.
*
- * This class operates in two different modes, corresponding to the
- * data models discussed in the Assembler namespace documentation.
+ * This class operates in two different modes, corresponding to the data
+ * models discussed in the Assembler namespace documentation.
*
* The choice of the local data model is triggered by the vector
* BlockInfo::local_renumbering, which in turn is usually filled by
- * BlockInfo::initialize_local(). If this function has been used, or
- * the vector has been changed from zero-length, then local dof
- * indices stored in this object will automatically be renumbered to
- * reflect local block structure. This means, the first entries in
- * @p indices will refer to the first block of the system, then comes
- * the second block and so on.
+ * BlockInfo::initialize_local(). If this function has been used, or the
+ * vector has been changed from zero-length, then local dof indices stored
+ * in this object will automatically be renumbered to reflect local block
+ * structure. This means, the first entries in @p indices will refer to the
+ * first block of the system, then comes the second block and so on.
*
- * The BlockInfo object is stored as a pointer. Therefore, if the
- * block structure changes, for instance because of mesh refinement,
- * the DoFInfo class will automatically use the new structures.
+ * The BlockInfo object is stored as a pointer. Therefore, if the block
+ * structure changes, for instance because of mesh refinement, the DoFInfo
+ * class will automatically use the new structures.
*
* @ingroup MeshWorker
* @author Guido Kanschat, 2009
typename Triangulation<dim, spacedim>::face_iterator face;
/**
- * The number of the current
- * face on the current cell.
+ * The number of the current face on the current cell.
*
- * This number is
- * deal_II_numbers::invalid_unsigned_int
- * if the info object was
- * initialized with a cell.
+ * This number is deal_II_numbers::invalid_unsigned_int if the info object
+ * was initialized with a cell.
*/
unsigned int face_number;
/**
- * The number of the current
- * subface on the current
- * face
+ * The number of the current subface on the current face
*
- * This number is
- * deal_II_numbers::invalid_unsigned_int
- * if the info object was not
- * initialized with a subface.
+ * This number is deal_II_numbers::invalid_unsigned_int if the info object
+ * was not initialized with a subface.
*/
unsigned int sub_number;
std::vector<types::global_dof_index> indices;
/**
- * The DoF indices on the current cell, organized by local blocks.
- * The size of this vector is zero, unless local blocks are used.
+ * The DoF indices on the current cell, organized by local blocks. The
+ * size of this vector is zero, unless local blocks are used.
*/
std::vector<std::vector<types::global_dof_index> > indices_by_block;
/**
- * Constructor setting the
- * #block_info pointer.
+ * Constructor setting the #block_info pointer.
*/
DoFInfo(const BlockInfo &block_info);
/**
- * Constructor
- * leaving the #block_info
- * pointer empty, but setting
- * the #aux_local_indices.
+ * Constructor leaving the #block_info pointer empty, but setting the
+ * #aux_local_indices.
*/
DoFInfo (const DoFHandler<dim, spacedim> &dof_handler);
/**
- * Set the current cell and
- * fill @p indices.
+ * Set the current cell and fill @p indices.
*/
template <class DHCellIterator>
void reinit(const DHCellIterator &c);
const unsigned int face_no);
/**
- * Set the current subface and fill @p indices if the #cell
- * changed.
+ * Set the current subface and fill @p indices if the #cell changed.
*/
template <class DHCellIterator, class DHFaceIterator>
void reinit(const DHCellIterator &c,
const unsigned int subface_no);
/**
- * Switch to a new face of the same cell. Does not change @p
- * indices and does not reset data in LocalResults.
+ * Switch to a new face of the same cell. Does not change @p indices and
+ * does not reset data in LocalResults.
*/
template <class DHFaceIterator>
void set_face (const DHFaceIterator &f,
const unsigned int face_no);
/**
- * Switch to a new subface of the same cell. Does not change @p
- * indices and does not reset data in LocalResults.
+ * Switch to a new subface of the same cell. Does not change @p indices
+ * and does not reset data in LocalResults.
*/
template <class DHFaceIterator>
void set_subface (const DHFaceIterator &f,
SmartPointer<const BlockInfo,DoFInfo<dim,spacedim> > block_info;
/**
- * The structure refers to a cell with level data instead of
- * active data.
+ * The structure refers to a cell with level data instead of active data.
*/
bool level_cell;
private:
/**
- * Standard constructor, not setting any block indices. Use of
- * this constructor is not recommended, but it is needed for the
- * arrays in DoFInfoBox.
+ * Standard constructor, not setting any block indices. Use of this
+ * constructor is not recommended, but it is needed for the arrays in
+ * DoFInfoBox.
*/
DoFInfo ();
std::vector<types::global_dof_index> indices_org;
/**
- * An auxiliary local
- * BlockIndices object created
- * if #block_info is not set.
- * It contains just a single
- * block of the size of
- * degrees of freedom per cell.
+ * An auxiliary local BlockIndices object created if #block_info is not
+ * set. It contains just a single block of the size of degrees of freedom
+ * per cell.
*/
BlockIndices aux_local_indices;
/**
- * A class bundling the MeshWorker::DoFInfo objects used on a cell.
- *
- * @todo Currently, we are storing an object for the cells and two for
- * each face. We could gather all face data pertaining to the cell
- * itself in one object, saving a bit of memory and a few operations,
- * but sacrificing some cleanliness.
- *
- * @ingroup MeshWorker
- * @author Guido Kanschat, 2010
- */
+ * A class bundling the MeshWorker::DoFInfo objects used on a cell.
+ *
+ * @todo Currently, we are storing an object for the cells and two for each
+ * face. We could gather all face data pertaining to the cell itself in one
+ * object, saving a bit of memory and a few operations, but sacrificing some
+ * cleanliness.
+ *
+ * @ingroup MeshWorker
+ * @author Guido Kanschat, 2010
+ */
template <int dim, class DOFINFO>
class DoFInfoBox
{
public:
/**
- * Constructor copying the seed
- * into all other objects.
+ * Constructor copying the seed into all other objects.
*/
DoFInfoBox(const DOFINFO &seed);
/**
- * Copy constructor, taking
- * #cell and using it as a seed
- * in the other constructor.
+ * Copy constructor, taking #cell and using it as a seed in the other
+ * constructor.
*/
DoFInfoBox(const DoFInfoBox<dim, DOFINFO> &);
void reset();
/**
- * After all info objects have
- * been filled appropriately,
- * use the ASSEMBLER object
- * to assemble them into the
- * global data. See
- * MeshWorker::Assembler for
- * available classes.
+ * After all info objects have been filled appropriately, use the
+ * ASSEMBLER object to assemble them into the global data. See
+ * MeshWorker::Assembler for available classes.
*/
template <class ASSEMBLER>
void assemble(ASSEMBLER &ass) const;
DOFINFO exterior[GeometryInfo<dim>::faces_per_cell];
/**
- * A set of flags, indicating
- * whether data on an interior
- * face is available.
+ * A set of flags, indicating whether data on an interior face is
+ * available.
*/
bool interior_face_available[GeometryInfo<dim>::faces_per_cell];
/**
- * A set of flags, indicating
- * whether data on an exterior
- * face is available.
+ * A set of flags, indicating whether data on an exterior face is
+ * available.
*/
bool exterior_face_available[GeometryInfo<dim>::faces_per_cell];
/**
- * A flag to specify if the current object has been set to a valid
- * cell.
+ * A flag to specify if the current object has been set to a valid cell.
*/
bool cell_valid;
};
namespace Assembler
{
/**
- * The class assembling local contributions to a functional into
- * global functionals.
+ * The class assembling local contributions to a functional into global
+ * functionals.
*
*
*
{
public:
/**
- * Initialize local data to
- * store functionals. The
- * number <tt>n</tt> is the
- * number of functionals to
- * be computed.
+ * Initialize local data to store functionals. The number <tt>n</tt> is
+ * the number of functionals to be computed.
*/
void initialize(const unsigned int n);
/**
- * Initialize the local data
- * in the DoFInfo object used
- * later for assembling.
+ * Initialize the local data in the DoFInfo object used later for
+ * assembling.
*
- * The info object refers to
- * a cell if
- * <code>!face</code>, or
- * else to an interior or
- * boundary face.
+ * The info object refers to a cell if <code>!face</code>, or else to an
+ * interior or boundary face.
*/
template <class DOFINFO>
void initialize_info(DOFINFO &info, bool face);
/**
- * Assemble the local values
- * into the global vectors.
+ * Assemble the local values into the global vectors.
*/
template<class DOFINFO>
void assemble(const DOFINFO &info);
/**
- * Assemble both local values
- * into the global vectors.
+ * Assemble both local values into the global vectors.
*/
template<class DOFINFO>
void assemble(const DOFINFO &info1,
const DOFINFO &info2);
/**
- * The value of the ith entry
- * in #results.
+ * The value of the ith entry in #results.
*/
number operator() (const unsigned int i) const;
private:
/**
- * The values into which the
- * results are added.
+ * The values into which the results are added.
*/
std::vector<double> results;
};
{
public:
/**
- * The initialization function, specifying the @p results
- * vectors and whether face data should be collected separately.
+ * The initialization function, specifying the @p results vectors and
+ * whether face data should be collected separately.
*
- * @p results should contain two block vectors named "cells" and
- * "faces" (the latter only if @p separate_faces is true). In
- * each of the two, each block should have equal size and be
- * large enough to accommodate all user indices set in the cells
- * and faces covered by the loop it is used in. Typically, for
- * estimators, this is Triangulation::n_active_cells() and
- * Triangulation::n_faces(), respectively.
+ * @p results should contain two block vectors named "cells" and "faces"
+ * (the latter only if @p separate_faces is true). In each of the two,
+ * each block should have equal size and be large enough to accommodate
+ * all user indices set in the cells and faces covered by the loop it is
+ * used in. Typically, for estimators, this is
+ * Triangulation::n_active_cells() and Triangulation::n_faces(),
+ * respectively.
*
- * The use of BlockVector may seem cumbersome, but it allows us
- * to assemble several functionals at the same time, one in each
- * block. The typical situation for error estimate is just
- * having a single block in each vector.
+ * The use of BlockVector may seem cumbersome, but it allows us to
+ * assemble several functionals at the same time, one in each block. The
+ * typical situation for error estimate is just having a single block in
+ * each vector.
*/
void initialize(AnyData &results, bool separate_faces = true);
void initialize(NamedData<BlockVector<number>*> &results,
bool separate_faces = true);
/**
- * Initialize the local data
- * in the
- * DoFInfo
- * object used later for
+ * Initialize the local data in the DoFInfo object used later for
* assembling.
*
- * The info object refers to
- * a cell if
- * <code>!face</code>, or
- * else to an interior or
- * boundary face.
+ * The info object refers to a cell if <code>!face</code>, or else to an
+ * interior or boundary face.
*/
template <class DOFINFO>
void initialize_info(DOFINFO &info, bool face) const;
/**
- * Assemble the local values
- * into the global vectors.
+ * Assemble the local values into the global vectors.
*/
template<class DOFINFO>
void assemble(const DOFINFO &info);
/**
- * Assemble both local values
- * into the global vectors.
+ * Assemble both local values into the global vectors.
*/
template<class DOFINFO>
void assemble(const DOFINFO &info1,
const DOFINFO &info2);
/**
- * The value of the ith entry
- * in @p results.
+ * The value of the ith entry in @p results.
*/
number operator() (const unsigned int i) const;
private:
* Class for objects handed to local integration functions.
*
* Objects of this class contain one or more objects of type FEValues,
- * FEFaceValues or FESubfaceValues to be used in local
- * integration. They are stored in an array of pointers to the base
- * classes FEValuesBase. The template parameter VECTOR allows the
- * use of different data types for the global system.
+ * FEFaceValues or FESubfaceValues to be used in local integration. They are
+ * stored in an array of pointers to the base classes FEValuesBase. The
+ * template parameter VECTOR allows the use of different data types for the
+ * global system.
*
- * Additionally, this function contains space to store the values of
- * finite element functions stored in #global_data in the
- * quadrature points. These vectors are initialized automatically on
- * each cell or face. In order to avoid initializing unused vectors,
- * you can use initialize_selector() to select the vectors by name
- * that you actually want to use.
+ * Additionally, this function contains space to store the values of finite
+ * element functions stored in #global_data in the quadrature points. These
+ * vectors are initialized automatically on each cell or face. In order to
+ * avoid initializing unused vectors, you can use initialize_selector() to
+ * select the vectors by name that you actually want to use.
*
* <h3>Integration models</h3>
*
- * This class supports two local integration models, corresponding to
- * the data models in the documentation of the Assembler namespace.
- * One is the
- * standard model suggested by the use of FESystem. Namely, there is
- * one FEValuseBase object in this class, containing all shape
- * functions of the whole system, and having as many components as the
- * system. Using this model involves loops over all system shape
- * functions. It requires to identify the system components
- * for each shape function and to select the correct bilinear form,
- * usually in an @p if or @p switch statement.
+ * This class supports two local integration models, corresponding to the
+ * data models in the documentation of the Assembler namespace. One is the
+ * standard model suggested by the use of FESystem. Namely, there is one
+ * FEValuseBase object in this class, containing all shape functions of the
+ * whole system, and having as many components as the system. Using this
+ * model involves loops over all system shape functions. It requires to
+ * identify the system components for each shape function and to select the
+ * correct bilinear form, usually in an @p if or @p switch statement.
*
- * The second integration model builds one FEValuesBase object per
- * base element of the system. The degrees of freedom on each cell are
- * renumbered by block, such that they represent the same block
- * structure as the global system. Objects performing the integration
- * can then process each block separately, which improves reusability
- * of code considerably.
+ * The second integration model builds one FEValuesBase object per base
+ * element of the system. The degrees of freedom on each cell are renumbered
+ * by block, such that they represent the same block structure as the global
+ * system. Objects performing the integration can then process each block
+ * separately, which improves reusability of code considerably.
*
* @note As described in DoFInfo, the use of the local block model is
- * triggered by calling BlockInfo::initialize_local() before
- * using initialize() in this class.
+ * triggered by calling BlockInfo::initialize_local() before using
+ * initialize() in this class.
*
* @ingroup MeshWorker
* @author Guido Kanschat, 2009
IntegrationInfo();
/**
- * Copy constructor, creating a clone to be used by
- * WorksTream::run().
+ * Copy constructor, creating a clone to be used by WorksTream::run().
*/
IntegrationInfo(const IntegrationInfo<dim, spacedim> &other);
/**
- * Build all internal structures, in particular the FEValuesBase
- * objects and allocate space for data vectors.
+ * Build all internal structures, in particular the FEValuesBase objects
+ * and allocate space for data vectors.
*
* @param el is the finite element of the DoFHandler.
*
- * @param mapping is the Mapping object used to map the mesh
- * cells.
+ * @param mapping is the Mapping object used to map the mesh cells.
*
- * @param quadrature is a Quadrature formula used in the
- * constructor of the FEVALUES objects.
+ * @param quadrature is a Quadrature formula used in the constructor of
+ * the FEVALUES objects.
*
* @param flags are the UpdateFlags used in the constructor of the
* FEVALUES objects.
*
- * @param local_block_info is an optional parameter for systems of
- * PDE. If it is provided with reasonable data, then the degrees
- * of freedom on the cells will be re-ordered to reflect the block
- * structure of the system.
+ * @param local_block_info is an optional parameter for systems of PDE. If
+ * it is provided with reasonable data, then the degrees of freedom on the
+ * cells will be re-ordered to reflect the block structure of the system.
*/
template <class FEVALUES>
void initialize(const FiniteElement<dim,spacedim> &el,
void clear();
/**
- * Return a reference to the FiniteElement that was used to
- * initialize this object.
+ * Return a reference to the FiniteElement that was used to initialize
+ * this object.
*/
const FiniteElement<dim, spacedim> &finite_element() const;
bool multigrid;
/// Access to finite element
/**
- * This is the access function being used, if initialize() for a
- * single element was used (without the BlockInfo argument). It
- * throws an exception, if applied to a vector of elements.
+ * This is the access function being used, if initialize() for a single
+ * element was used (without the BlockInfo argument). It throws an
+ * exception, if applied to a vector of elements.
*/
const FEValuesBase<dim, spacedim> &fe_values () const;
/// Access to finite elements
/**
- * This access function must be used if the initalize() for a
- * group of elements was used (with a valid BlockInfo object).
+ * This access function must be used if the initalize() for a group of
+ * elements was used (with a valid BlockInfo object).
*/
const FEValuesBase<dim, spacedim> &fe_values (const unsigned int i) const;
/**
- * The vector containing the values of finite element functions in
- * the quadrature points.
+ * The vector containing the values of finite element functions in the
+ * quadrature points.
*
- * There is one vector per selected finite element function,
- * containing one vector for each component, containing vectors
- * with values for each quadrature point.
+ * There is one vector per selected finite element function, containing
+ * one vector for each component, containing vectors with values for each
+ * quadrature point.
*/
std::vector<std::vector<std::vector<double> > > values;
/**
- * The vector containing the derivatives of finite element
- * functions in the quadrature points.
+ * The vector containing the derivatives of finite element functions in
+ * the quadrature points.
*
- * There is one vector per selected finite element function,
- * containing one vector for each component, containing vectors
- * with values for each quadrature point.
+ * There is one vector per selected finite element function, containing
+ * one vector for each component, containing vectors with values for each
+ * quadrature point.
*/
std::vector<std::vector<std::vector<Tensor<1,dim> > > > gradients;
* The vector containing the second derivatives of finite element
* functions in the quadrature points.
*
- * There is one vector per selected finite element function,
- * containing one vector for each component, containing vectors
- * with values for each quadrature point.
+ * There is one vector per selected finite element function, containing
+ * one vector for each component, containing vectors with values for each
+ * quadrature point.
*/
std::vector<std::vector<std::vector<Tensor<2,dim> > > > hessians;
void reinit(const DoFInfo<dim, spacedim, number> &i);
/**
- * Use the finite element functions in #global_data and fill the
- * vectors #values, #gradients and #hessians.
+ * Use the finite element functions in #global_data and fill the vectors
+ * #values, #gradients and #hessians.
*/
template<typename number>
void fill_local_data(const DoFInfo<dim, spacedim, number> &info, bool split_fevalues);
/**
- * The global data vector used to compute function values in
- * quadrature points.
+ * The global data vector used to compute function values in quadrature
+ * points.
*/
std_cxx11::shared_ptr<VectorDataBase<dim, spacedim> > global_data;
SmartPointer<const FiniteElement<dim, spacedim>, IntegrationInfo<dim, spacedim> > fe_pointer;
/**
- * Use the finite element functions in #global_data and fill the
- * vectors #values, #gradients and #hessians with values according
- * to the selector.
+ * Use the finite element functions in #global_data and fill the vectors
+ * #values, #gradients and #hessians with values according to the
+ * selector.
*/
template <typename TYPE>
void fill_local_data(
};
/**
- * The object holding the scratch data for integrating over cells and
- * faces. IntegrationInfoBox serves three main purposes:
+ * The object holding the scratch data for integrating over cells and faces.
+ * IntegrationInfoBox serves three main purposes:
*
* <ol>
- * <li> It provides the interface needed by MeshWorker::loop(), namely
- * the two functions post_cell() and post_faces(), as well as
- * the data members #cell, #boundary, #face,
- * #subface, and #neighbor.
+ * <li> It provides the interface needed by MeshWorker::loop(), namely the
+ * two functions post_cell() and post_faces(), as well as the data members
+ * #cell, #boundary, #face, #subface, and #neighbor.
*
- * <li> It contains all information needed to initialize the FEValues
- * and FEFaceValues objects in the IntegrationInfo data members.
+ * <li> It contains all information needed to initialize the FEValues and
+ * FEFaceValues objects in the IntegrationInfo data members.
*
- * <li> It stores information on finite element vectors and whether
- * their data should be used to compute values or derivatives of
- * functions at quadrature points.
+ * <li> It stores information on finite element vectors and whether their
+ * data should be used to compute values or derivatives of functions at
+ * quadrature points.
*
- * <li> It makes educated guesses on quadrature rules and update
- * flags, so that minimal code has to be written when default
- * parameters are sufficient.
+ * <li> It makes educated guesses on quadrature rules and update flags, so
+ * that minimal code has to be written when default parameters are
+ * sufficient.
* </ol>
*
* In order to allow for sufficient generality, a few steps have to be
* undertaken to use this class.
*
* First, you should consider if you need values from any vectors in a
- * AnyData object. If so, fill the VectorSelector objects
- * #cell_selector, #boundary_selector and #face_selector with their names
- * and the data type (value, gradient, Hessian) to be extracted.
+ * AnyData object. If so, fill the VectorSelector objects #cell_selector,
+ * #boundary_selector and #face_selector with their names and the data type
+ * (value, gradient, Hessian) to be extracted.
*
- * Afterwards, you will need to consider UpdateFlags for FEValues
- * objects. A good start is initialize_update_flags(), which looks at
- * the selectors filled before and adds all the flags needed to get
- * the selection. Additional flags can be set with add_update_flags().
+ * Afterwards, you will need to consider UpdateFlags for FEValues objects. A
+ * good start is initialize_update_flags(), which looks at the selectors
+ * filled before and adds all the flags needed to get the selection.
+ * Additional flags can be set with add_update_flags().
*
- * Finally, we need to choose quadrature formulas. In the simplest
- * case, you might be happy with the default settings, which are
- * <i>n</i>-point Gauss formulas. If only derivatives of the shape
- * functions are used (#update_values is not set) <i>n</i> equals the
- * highest polynomial degree in the FiniteElement, if #update_values
- * is set, <i>n</i> is one higher than this degree. If you choose to
- * use Gauss formulas of other size, use initialize_gauss_quadrature()
- * with appropriate values. Otherwise, you can fill the variables
- * #cell_quadrature, #boundary_quadrature and #face_quadrature
- * directly.
+ * Finally, we need to choose quadrature formulas. In the simplest case, you
+ * might be happy with the default settings, which are <i>n</i>-point Gauss
+ * formulas. If only derivatives of the shape functions are used
+ * (#update_values is not set) <i>n</i> equals the highest polynomial degree
+ * in the FiniteElement, if #update_values is set, <i>n</i> is one higher
+ * than this degree. If you choose to use Gauss formulas of other size, use
+ * initialize_gauss_quadrature() with appropriate values. Otherwise, you can
+ * fill the variables #cell_quadrature, #boundary_quadrature and
+ * #face_quadrature directly.
*
- * In order to save time, you can set the variables boundary_fluxes
- * and interior_fluxes of the base class to false, thus telling the
+ * In order to save time, you can set the variables boundary_fluxes and
+ * interior_fluxes of the base class to false, thus telling the
* Meshworker::loop() not to loop over those faces.
*
- * All the information in here is used to set up IntegrationInfo
- * objects correctly, typically in an IntegrationInfoBox.
+ * All the information in here is used to set up IntegrationInfo objects
+ * correctly, typically in an IntegrationInfoBox.
*
* @ingroup MeshWorker
* @author Guido Kanschat, 2009
public:
/**
- * The type of the info object
- * for cells.
+ * The type of the info object for cells.
*/
typedef IntegrationInfo<dim, spacedim> CellInfo;
/**
* Initialize the IntegrationInfo objects contained.
*
- * Before doing so, add update flags necessary to produce the data
- * needed and also set uninitialized quadrature rules to Gauss
- * formulas, which integrate polynomial bilinear forms exactly.
+ * Before doing so, add update flags necessary to produce the data needed
+ * and also set uninitialized quadrature rules to Gauss formulas, which
+ * integrate polynomial bilinear forms exactly.
*/
void initialize(const FiniteElement<dim, spacedim> &el,
const Mapping<dim, spacedim> &mapping,
/**
* Initialize the IntegrationInfo objects contained.
*
- * Before doing so, add update flags necessary to produce the data
- * needed and also set uninitialized quadrature rules to Gauss
- * formulas, which integrate polynomial bilinear forms exactly.
+ * Before doing so, add update flags necessary to produce the data needed
+ * and also set uninitialized quadrature rules to Gauss formulas, which
+ * integrate polynomial bilinear forms exactly.
*/
template <typename VECTOR>
void initialize(const FiniteElement<dim, spacedim> &el,
/* @{ */
/**
- * Call this function before initialize() in order to guess the
- * update flags needed, based on the data selected.
- *
- * When computing face fluxes, we normally can use the geometry
- * (integration weights and normal vectors) from the original cell
- * and thus can avoid updating these values on the neighboring
- * cell. Set <tt>neighbor_geometry</tt> to true in order to
- * initialize these values as well.
- */
+ * Call this function before initialize() in order to guess the update
+ * flags needed, based on the data selected.
+ *
+ * When computing face fluxes, we normally can use the geometry
+ * (integration weights and normal vectors) from the original cell and
+ * thus can avoid updating these values on the neighboring cell. Set
+ * <tt>neighbor_geometry</tt> to true in order to initialize these values
+ * as well.
+ */
void initialize_update_flags(bool neighbor_geometry = false);
/**
void add_update_flags_face(const UpdateFlags flags);
/**
- * Add additional update flags to the ones already set in this
- * program. The four boolean flags indicate whether the additional
- * flags should be set for cell, boundary, interelement face for
- * the cell itself or neighbor cell, or any combination thereof.
+ * Add additional update flags to the ones already set in this program.
+ * The four boolean flags indicate whether the additional flags should be
+ * set for cell, boundary, interelement face for the cell itself or
+ * neighbor cell, or any combination thereof.
*/
void add_update_flags(const UpdateFlags flags,
const bool cell = true,
const bool neighbor = true);
/**
- * Assign n-point Gauss quadratures to each of the quadrature
- * rules. Here, a size of zero points means that no loop over
- * these grid entities should be performed.
+ * Assign n-point Gauss quadratures to each of the quadrature rules. Here,
+ * a size of zero points means that no loop over these grid entities
+ * should be performed.
*
- * If the parameter <tt>force</tt> is true, then all quadrature
- * sets are filled with new quadrature rules. If it is false, then
- * only empty rules are changed.
+ * If the parameter <tt>force</tt> is true, then all quadrature sets are
+ * filled with new quadrature rules. If it is false, then only empty rules
+ * are changed.
*/
void initialize_gauss_quadrature(unsigned int n_cell_points,
unsigned int n_boundary_points,
/**
* The set of update flags for interior face integration.
*
- * Defaults to #update_default, since quadrature weights are taken
- * from the other cell.
+ * Defaults to #update_default, since quadrature weights are taken from
+ * the other cell.
*/
UpdateFlags neighbor_flags;
/**
* Initialize the VectorSelector objects #cell_selector,
- * #boundary_selector and #face_selector in order to save
- * computational effort. If no selectors are used, then values for
- * all named vectors in DoFInfo::global_data will be computed in
- * all quadrature points.
+ * #boundary_selector and #face_selector in order to save computational
+ * effort. If no selectors are used, then values for all named vectors in
+ * DoFInfo::global_data will be computed in all quadrature points.
*
- * This function will also add UpdateFlags to the flags stored in
- * this class.
+ * This function will also add UpdateFlags to the flags stored in this
+ * class.
*/
/**
- * Select the vectors from DoFInfo::global_data that should be
- * computed in the quadrature points on cells.
+ * Select the vectors from DoFInfo::global_data that should be computed in
+ * the quadrature points on cells.
*/
MeshWorker::VectorSelector cell_selector;
/**
- * Select the vectors from DoFInfo::global_data that should be
- * computed in the quadrature points on boundary faces.
+ * Select the vectors from DoFInfo::global_data that should be computed in
+ * the quadrature points on boundary faces.
*/
MeshWorker::VectorSelector boundary_selector;
/**
- * Select the vectors from DoFInfo::global_data that should be
- * computed in the quadrature points on interior faces.
+ * Select the vectors from DoFInfo::global_data that should be computed in
+ * the quadrature points on interior faces.
*/
MeshWorker::VectorSelector face_selector;
*/
/* @{ */
/**
- * A callback function which is called in the loop over all cells,
- * after the action on a cell has been performed and before the
- * faces are dealt with.
+ * A callback function which is called in the loop over all cells, after
+ * the action on a cell has been performed and before the faces are dealt
+ * with.
*
- * In order for this function to have this effect, at least either
- * of the arguments <tt>boundary_worker</tt> or
- * <tt>face_worker</tt> arguments of loop() should be
- * nonzero. Additionally, <tt>cells_first</tt> should be true. If
- * <tt>cells_first</tt> is false, this function is called before
+ * In order for this function to have this effect, at least either of the
+ * arguments <tt>boundary_worker</tt> or <tt>face_worker</tt> arguments of
+ * loop() should be nonzero. Additionally, <tt>cells_first</tt> should be
+ * true. If <tt>cells_first</tt> is false, this function is called before
* any action on a cell is taken.
*
- * And empty function in this class, but can be replaced in other
- * classes given to loop() instead.
+ * And empty function in this class, but can be replaced in other classes
+ * given to loop() instead.
*
- * See loop() and cell_action() for more details of how this
- * function can be used.
+ * See loop() and cell_action() for more details of how this function can
+ * be used.
*/
template <class DOFINFO>
void post_cell(const DoFInfoBox<dim, DOFINFO> &);
/**
- * A callback function which is called in the loop over all cells,
- * after the action on the faces of a cell has been performed and
- * before the cell itself is dealt with (assumes
- * <tt>cells_first</tt> is false).
+ * A callback function which is called in the loop over all cells, after
+ * the action on the faces of a cell has been performed and before the
+ * cell itself is dealt with (assumes <tt>cells_first</tt> is false).
*
- * In order for this function to have a reasonable effect, at
- * least either of the arguments <tt>boundary_worker</tt> or
- * <tt>face_worker</tt> arguments of loop() should be
- * nonzero. Additionally, <tt>cells_first</tt> should be false.
+ * In order for this function to have a reasonable effect, at least either
+ * of the arguments <tt>boundary_worker</tt> or <tt>face_worker</tt>
+ * arguments of loop() should be nonzero. Additionally,
+ * <tt>cells_first</tt> should be false.
*
- * And empty function in this class, but can be replaced in other
- * classes given to loop() instead.
+ * And empty function in this class, but can be replaced in other classes
+ * given to loop() instead.
*
- * See loop() and cell_action() for more details of how this
- * function can be used.
+ * See loop() and cell_action() for more details of how this function can
+ * be used.
*/
template <class DOFINFO>
void post_faces(const DoFInfoBox<dim, DOFINFO> &);
*/
CellInfo boundary;
/**
- * The info object for a regular interior face, seen from the
- * first cell.
+ * The info object for a regular interior face, seen from the first cell.
*/
CellInfo face;
/**
- * The info object for the refined side of an interior face seen
- * from the first cell.
+ * The info object for the refined side of an interior face seen from the
+ * first cell.
*/
CellInfo subface;
/**
template <int dim, int spacedim> class IntegrationInfo;
/**
- * A local integrator object, which can be used to simplify the call
- * of loop(). Instead of providing the three local integration
- * functions separately, we bundle them as virtual functions in this
- * class.
+ * A local integrator object, which can be used to simplify the call of
+ * loop(). Instead of providing the three local integration functions
+ * separately, we bundle them as virtual functions in this class.
*
- * Additionally, since we cannot have a virtual null function, we
- * provide flags, which allow us to indicate, whether we want to
- * integrate on boundary and interior faces. Thes flags are true by
- * default, but can be modified by applications to speed up the loop.
+ * Additionally, since we cannot have a virtual null function, we provide
+ * flags, which allow us to indicate, whether we want to integrate on
+ * boundary and interior faces. Thes flags are true by default, but can be
+ * modified by applications to speed up the loop.
*
- * If a function is not overloaded in a derived class, but its usage
- * flag is true, the function will cause an exception
- * ExcPureFunction.
+ * If a function is not overloaded in a derived class, but its usage flag is
+ * true, the function will cause an exception ExcPureFunction.
*
* @ingroup MeshWorker
* @author Guido Kanschat
{
public:
/**
- * The constructor setting default values, namely all integration flags to true.
- */
+ * The constructor setting default values, namely all integration flags to
+ * true.
+ */
LocalIntegrator();
/**
- * The constructor setting integration flags to specified values.
- */
+ * The constructor setting integration flags to specified values.
+ */
LocalIntegrator(bool use_cell, bool use_boundary, bool use_face);
/**
- * The empty virtual destructor.
- */
+ * The empty virtual destructor.
+ */
~LocalIntegrator();
/**
- * Virtual function for integrating on cells. Throws exception
- * PureFunctionCalled if not overloaded by a derived class.
- */
+ * Virtual function for integrating on cells. Throws exception
+ * PureFunctionCalled if not overloaded by a derived class.
+ */
virtual void cell(DoFInfo<dim, spacedim, number> &dinfo,
IntegrationInfo<dim, spacedim> &info) const;
/**
- * Virtual function for integrating on boundary faces. Throws exception
- * PureFunctionCalled if not overloaded by a derived class.
- */
+ * Virtual function for integrating on boundary faces. Throws exception
+ * PureFunctionCalled if not overloaded by a derived class.
+ */
virtual void boundary(DoFInfo<dim, spacedim, number> &dinfo,
IntegrationInfo<dim, spacedim> &info) const;
/**
- * Virtual function for integrating on interior faces. Throws exception
- * PureFunctionCalled if not overloaded by a derived class.
- */
+ * Virtual function for integrating on interior faces. Throws exception
+ * PureFunctionCalled if not overloaded by a derived class.
+ */
virtual void face(DoFInfo<dim, spacedim, number> &dinfo1,
DoFInfo<dim, spacedim, number> &dinfo2,
IntegrationInfo<dim, spacedim> &info1,
IntegrationInfo<dim, spacedim> &info2) const;
/**
- * The flag indicating whether the cell integrator cell() is to be
- * used in the loop. Defaults to <tt>true</tt>.
- */
+ * The flag indicating whether the cell integrator cell() is to be used in
+ * the loop. Defaults to <tt>true</tt>.
+ */
bool use_cell;
/**
- * The flag indicating whether the boundary integrator boundary()
- * is to be used in the loop. Defaults to <tt>true</tt>.
- */
+ * The flag indicating whether the boundary integrator boundary() is to be
+ * used in the loop. Defaults to <tt>true</tt>.
+ */
bool use_boundary;
/**
- * The flag indicating whether the interior face integrator face()
- * is to be used in the loop. Defaults to <tt>true</tt>.
- */
+ * The flag indicating whether the interior face integrator face() is to
+ * be used in the loop. Defaults to <tt>true</tt>.
+ */
bool use_face;
/**
- * The names of the input vectors. If this vector is nonempty, it
- * can be used by application programs to automatically select
- * and verify the input vectors used for integration.
+ * The names of the input vectors. If this vector is nonempty, it can be
+ * used by application programs to automatically select and verify the
+ * input vectors used for integration.
*
- * @note This variable is currently not used by the library, but
- * it is provided to help develop application programs.
+ * @note This variable is currently not used by the library, but it is
+ * provided to help develop application programs.
*/
std::vector<std::string> input_vector_names;
/**
- * The names of the results produced. If this vector is nonempty,
- * it can be used by application programs to automatically assign
- * names to output values and/or verify the names of vectors.
+ * The names of the results produced. If this vector is nonempty, it can
+ * be used by application programs to automatically assign names to output
+ * values and/or verify the names of vectors.
*
- * @note This variable is currently not used by the library, but
- * it is provided to help develop application programs.
+ * @note This variable is currently not used by the library, but it is
+ * provided to help develop application programs.
*/
std::vector<std::string> output_names;
/**
* This error is thrown if one of the virtual functions cell(),
- * boundary(), or face() is called without being overloaded in a
- * derived class. Consider setting #use_cell, #use_boundary, and
- * #use_face to false, respectively.
+ * boundary(), or face() is called without being overloaded in a derived
+ * class. Consider setting #use_cell, #use_boundary, and #use_face to
+ * false, respectively.
*
* @ingroup Exceptions
*/
template<int,int> class MGDoFHandler;
/**
- * A collection of functions and classes for the mesh loops that are
- * an ubiquitous part of each finite element program.
+ * A collection of functions and classes for the mesh loops that are an
+ * ubiquitous part of each finite element program.
*
* The workhorse of this namespace is the loop() function, which implements a
- * completely generic loop over all mesh cells. Since the calls to
- * loop() are error-prone due to its generality, for many applications
- * it is advisable to derive a class from MeshWorker::LocalIntegrator
- * and use the less general integration_loop() instead.
+ * completely generic loop over all mesh cells. Since the calls to loop() are
+ * error-prone due to its generality, for many applications it is advisable to
+ * derive a class from MeshWorker::LocalIntegrator and use the less general
+ * integration_loop() instead.
*
- * The loop() depends on certain objects handed to it as
- * arguments. These objects are of two types, info objects like
- * DoFInfo and IntegrationInfo and worker objects like LocalWorker and
- * IntegrationWorker.
+ * The loop() depends on certain objects handed to it as arguments. These
+ * objects are of two types, info objects like DoFInfo and IntegrationInfo and
+ * worker objects like LocalWorker and IntegrationWorker.
*
- * Worker objects usually do two different jobs: first, they compute
- * the local contribution of a cell or face to the global
- * operation. Second, they assemble this local contribution into the
- * global result, whether a functional, a form or a bilinear
- * form. While the first job is particular to the problem being
- * solved, the second is generic and only depends on the data
- * structures. Therefore, base classes for workers assembling into
- * global data are provided in the namespace Assembler.
+ * Worker objects usually do two different jobs: first, they compute the local
+ * contribution of a cell or face to the global operation. Second, they
+ * assemble this local contribution into the global result, whether a
+ * functional, a form or a bilinear form. While the first job is particular to
+ * the problem being solved, the second is generic and only depends on the
+ * data structures. Therefore, base classes for workers assembling into global
+ * data are provided in the namespace Assembler.
*
* <h3>Template argument types</h3>
*
- * The functions loop() and cell_action() take some arguments which
- * are template parameters. Let us list the minimum requirements for
- * these classes here and describe their properties.
+ * The functions loop() and cell_action() take some arguments which are
+ * template parameters. Let us list the minimum requirements for these classes
+ * here and describe their properties.
*
* <h4>ITERATOR</h4>
*
*
* <h4>DOFINFO</h4>
*
- * For an example implementation, refer to the class template DoFInfo.
- * In order to work with cell_action() and loop(), DOFINFO needs to
- * follow the following interface.
+ * For an example implementation, refer to the class template DoFInfo. In
+ * order to work with cell_action() and loop(), DOFINFO needs to follow the
+ * following interface.
* @code
* class DOFINFO
* {
* };
* @endcode
*
- * The three private functions are called by DoFInfoBox and should not
- * be needed elsewhere. Obviously, they can be made public and then
- * the friend declaration at the end may be missing.
+ * The three private functions are called by DoFInfoBox and should not be
+ * needed elsewhere. Obviously, they can be made public and then the friend
+ * declaration at the end may be missing.
*
* Additionally, you will need at least one public constructor. Furthermore
- * DOFINFO is pretty useless yet: functions to interface with
- * INTEGRATIONINFO and ASSEMBLER are needed.
+ * DOFINFO is pretty useless yet: functions to interface with INTEGRATIONINFO
+ * and ASSEMBLER are needed.
*
- * DOFINFO objects are gathered in a DoFInfoBox. In those objects, we
- * store the results of local operations on each cell and its
- * faces. Once all this information has been gathered, an ASSEMBLER is
- * used to assemble it into golbal data.
+ * DOFINFO objects are gathered in a DoFInfoBox. In those objects, we store
+ * the results of local operations on each cell and its faces. Once all this
+ * information has been gathered, an ASSEMBLER is used to assemble it into
+ * golbal data.
*
* <h4>INFOBOX</h4>
*
- * This type is exemplified in IntegrationInfoBox. It collects the
- * input data for actions on cells and faces in INFO objects (see
- * below). It provides the following interface to loop() and
- * cell_action():
+ * This type is exemplified in IntegrationInfoBox. It collects the input data
+ * for actions on cells and faces in INFO objects (see below). It provides the
+ * following interface to loop() and cell_action():
*
* @code
* class INFOBOX
* };
* @endcode
*
- * The main purpose of this class is gathering the five INFO objects,
- * which contain the temporary data used on each cell or face. The
- * requirements on these objects are listed below. Here, we only note
- * that there need to be these 5 objects with the names listed above.
+ * The main purpose of this class is gathering the five INFO objects, which
+ * contain the temporary data used on each cell or face. The requirements on
+ * these objects are listed below. Here, we only note that there need to be
+ * these 5 objects with the names listed above.
*
- * The two function templates are call back functions called in
- * cell_action(). The first is called before the faces are worked on,
- * the second after the faces.
+ * The two function templates are call back functions called in cell_action().
+ * The first is called before the faces are worked on, the second after the
+ * faces.
*
* <h4>INFO</h4>
*
- * See IntegrationInfo for an example of these objects. They contain
- * the temporary data needed on each cell or face to compute the
- * result. The MeshWorker only uses the interface
+ * See IntegrationInfo for an example of these objects. They contain the
+ * temporary data needed on each cell or face to compute the result. The
+ * MeshWorker only uses the interface
*
* @code
* class INFO
*
* <h3>Simplified interfaces</h3>
*
- * Since the loop() is fairly general, a specialization
- * integration_loop() is available, which is a wrapper around loop()
- * with a simplified interface.
+ * Since the loop() is fairly general, a specialization integration_loop() is
+ * available, which is a wrapper around loop() with a simplified interface.
*
- * The integration_loop() function loop takes most of the information
- * that it needs to pass to loop() from an IntegrationInfoBox
- * object. Its use is explained in step-12, but in
- * short it requires functions that do the local integration on a
- * cell, interior or boundary face, and it needs an object (called
- * "assembler") that copies these local contributions into the global
+ * The integration_loop() function loop takes most of the information that it
+ * needs to pass to loop() from an IntegrationInfoBox object. Its use is
+ * explained in step-12, but in short it requires functions that do the local
+ * integration on a cell, interior or boundary face, and it needs an object
+ * (called "assembler") that copies these local contributions into the global
* matrix and right hand side objects.
*
- * Before we can run the integration loop, we have to initialize
- * several data structures in our IntegrationWorker and assembler
- * objects. For instance, we have to decide on the quadrature rule or
- * we may need more than the default update flags.
+ * Before we can run the integration loop, we have to initialize several data
+ * structures in our IntegrationWorker and assembler objects. For instance, we
+ * have to decide on the quadrature rule or we may need more than the default
+ * update flags.
*
* @ingroup MeshWorker
* @ingroup Integrators
{
/**
* The class providing the scrapbook to fill with results of local
- * integration. Depending on the task the mesh worker loop is
- * performing, local results can be of different types. They have
- * in common that they are the result of local integration over a cell
- * or face. Their actual type is determined by the Assember using
- * them. It is also the assembler setting the arrays of local results
- * to the sizes needed. Here is a list of the provided data types and
- * the assembers using them:
+ * integration. Depending on the task the mesh worker loop is performing,
+ * local results can be of different types. They have in common that they
+ * are the result of local integration over a cell or face. Their actual
+ * type is determined by the Assember using them. It is also the assembler
+ * setting the arrays of local results to the sizes needed. Here is a list
+ * of the provided data types and the assembers using them:
*
* <ol>
- * <li> n_values() numbers accessed with value(), and stored in the
- * data member #J.
+ * <li> n_values() numbers accessed with value(), and stored in the data
+ * member #J.
*
- * <li> n_vectors() vectors of the length of dofs on this cell,
- * accessed by vector(), and stored in #R.
- * <li> n_matrices() matrices of dimension dofs per cell in each
- * direction, accessed by matrix() with second argument
- * <tt>false</tt>. These are stored in #M1, and they are the matrices
- * coupling degrees of freedom in the same cell. For fluxes across
- * faces, there is an additional set #M2 of matrices of the same size, but
- * the dimension of the matrices being according to the degrees of
- * freedom on both cells. These are accessed with matrix(), using the
- * second argument <tt>true</tt>.
+ * <li> n_vectors() vectors of the length of dofs on this cell, accessed by
+ * vector(), and stored in #R.
+ * <li> n_matrices() matrices of dimension dofs per cell in each direction,
+ * accessed by matrix() with second argument <tt>false</tt>. These are
+ * stored in #M1, and they are the matrices coupling degrees of freedom in
+ * the same cell. For fluxes across faces, there is an additional set #M2 of
+ * matrices of the same size, but the dimension of the matrices being
+ * according to the degrees of freedom on both cells. These are accessed
+ * with matrix(), using the second argument <tt>true</tt>.
* </ol>
*
- * The local matrices initialized by reinit() of the info object and
- * then assembled into the global system by Assembler classes.
+ * The local matrices initialized by reinit() of the info object and then
+ * assembled into the global system by Assembler classes.
*
* @ingroup MeshWorker
* @author Guido Kanschat, 2009
/**
* The number of scalar values.
*
- * This number is set to a
- * nonzero value by Assember::CellsAndFaces
+ * This number is set to a nonzero value by Assember::CellsAndFaces
*
*/
unsigned int n_values () const;
/**
* The number of vectors.
*
- * This number is set to a
- * nonzero value by
- * Assember::ResidualSimple and
+ * This number is set to a nonzero value by Assember::ResidualSimple and
* Assember::ResidualLocalBlocksToGlobalBlocks.
*/
unsigned int n_vectors () const;
unsigned int n_matrices () const;
/**
- * The number of quadrature
- * points in quadrature_values().
+ * The number of quadrature points in quadrature_values().
*/
unsigned int n_quadrature_points() const;
/**
- * The number of values in each
- * quadrature point in
- * quadrature_values().
+ * The number of values in each quadrature point in quadrature_values().
*/
unsigned int n_quadrature_values() const;
/**
- * Access scalar value at index
- * @p i.
+ * Access scalar value at index @p i.
*/
number &value(unsigned int i);
/**
- * Read scalar value at index
- * @p i.
+ * Read scalar value at index @p i.
*/
number value(unsigned int i) const;
const BlockVector<number> &vector(unsigned int i) const;
/**
- * Access matrix at index @p
- * i. For results on internal
- * faces, a true value for @p
- * external refers to the flux
- * between cells, while false
- * refers to entries coupling
- * inside the cell.
+ * Access matrix at index @p i. For results on internal faces, a true
+ * value for @p external refers to the flux between cells, while false
+ * refers to entries coupling inside the cell.
*/
MatrixBlock<FullMatrix<number> > &matrix(unsigned int i, bool external = false);
/**
- * Read matrix at index @p
- * i. For results on internal
- * faces, a true value for @p
- * external refers to the flux
- * between cells, while false
- * refers to entries coupling
- * inside the cell.
+ * Read matrix at index @p i. For results on internal faces, a true value
+ * for @p external refers to the flux between cells, while false refers to
+ * entries coupling inside the cell.
*/
const MatrixBlock<FullMatrix<number> > &matrix(unsigned int i, bool external = false) const;
/**
- * Access to the vector
- * #quadrature_data of data
- * in quadrature points,
- * organized such that there is
- * a vector for each point,
- * containing one entry for
- * each component.
+ * Access to the vector #quadrature_data of data in quadrature points,
+ * organized such that there is a vector for each point, containing one
+ * entry for each component.
*/
Table<2, number> &quadrature_values();
void initialize_vectors(const unsigned int n);
/**
- * Allocate @p n local matrices. Additionally, set their block row
- * and column coordinates to zero. The matrices themselves are
- * resized by reinit().
+ * Allocate @p n local matrices. Additionally, set their block row and
+ * column coordinates to zero. The matrices themselves are resized by
+ * reinit().
*
* @note This function is usually only called by the assembler.
*/
void initialize_matrices(unsigned int n, bool both);
/**
- * Allocate a local matrix for each of the global ones in @p
- * matrices. Additionally, set their block row and column
- * coordinates. The matrices themselves are resized by reinit().
+ * Allocate a local matrix for each of the global ones in @p matrices.
+ * Additionally, set their block row and column coordinates. The matrices
+ * themselves are resized by reinit().
*
* @note This function is usually only called by the assembler.
*/
bool both);
/**
- * Allocate a local matrix
- * for each of the global
- * level objects in @p
- * matrices. Additionally,
- * set their block row and
- * column coordinates. The
- * matrices themselves are
- * resized by reinit().
+ * Allocate a local matrix for each of the global level objects in @p
+ * matrices. Additionally, set their block row and column coordinates. The
+ * matrices themselves are resized by reinit().
*
- * @note This function is
- * usually only called by the
- * assembler.
+ * @note This function is usually only called by the assembler.
*/
template <class MATRIX>
void initialize_matrices(const MGMatrixBlockVector<MATRIX> &matrices,
bool both);
/**
- * Initialize quadrature values to <tt>nv</tt> values in
- * <tt>np</tt> quadrature points.
+ * Initialize quadrature values to <tt>nv</tt> values in <tt>np</tt>
+ * quadrature points.
*/
void initialize_quadrature(unsigned int np, unsigned int nv);
/**
- * Reinitialize matrices for new cell. Does not resize any of the
- * data vectors stored in this object, but resizes the vectors in
- * #R and the matrices in #M1 and #M2 for hp and sets them to
- * zero.
+ * Reinitialize matrices for new cell. Does not resize any of the data
+ * vectors stored in this object, but resizes the vectors in #R and the
+ * matrices in #M1 and #M2 for hp and sets them to zero.
*/
void reinit(const BlockIndices &local_sizes);
std::vector<number> J;
/**
- * The local vectors. This field is public, so that local
- * integrators can write to it.
+ * The local vectors. This field is public, so that local integrators can
+ * write to it.
*/
std::vector<BlockVector<number> > R;
/**
- * The local matrices coupling degrees of freedom in the cell
- * itself or within the first cell on a face.
+ * The local matrices coupling degrees of freedom in the cell itself or
+ * within the first cell on a face.
*/
std::vector<MatrixBlock<FullMatrix<number> > > M1;
/**
- * The local matrices coupling test functions on the cell with
- * trial functions on the other cell.
+ * The local matrices coupling test functions on the cell with trial
+ * functions on the other cell.
*
* Only used on interior faces.
*/
*/
bool own_cells;
/**
- * Loop over cells not owned by this process. Defaults to <code>false</code>.
+ * Loop over cells not owned by this process. Defaults to
+ * <code>false</code>.
*/
bool ghost_cells;
};
/**
- * Loop over faces between a locally owned cell and a ghost cell:
- * - never: do not assembly these faces
- * - one: only one of the processes will assemble these faces (
- * from the finer side or the process with the lower mpi rank)
- * - both: both processes will assemble these faces
- * Note that these faces are never assembled from both sides on a single
- * process.
- * Default is one.
+ * Loop over faces between a locally owned cell and a ghost cell: - never:
+ * do not assembly these faces - one: only one of the processes will
+ * assemble these faces ( from the finer side or the process with the
+ * lower mpi rank) - both: both processes will assemble these faces Note
+ * that these faces are never assembled from both sides on a single
+ * process. Default is one.
*/
FaceOption faces_to_ghost;
/**
- * Loop over faces between two locally owned cells:
- * - never: do not assemble face terms
- * - one: assemble once (always coming from the finer side)
- * - both: assemble each face twice (not implemented for hanging nodes!)
- * Default is one.
+ * Loop over faces between two locally owned cells: - never: do not
+ * assemble face terms - one: assemble once (always coming from the finer
+ * side) - both: assemble each face twice (not implemented for hanging
+ * nodes!) Default is one.
*/
FaceOption own_faces;
/**
- * The function called by loop() to perform the required actions on a
- * cell and its faces. The three functions <tt>cell_worker</tt>,
+ * The function called by loop() to perform the required actions on a cell
+ * and its faces. The three functions <tt>cell_worker</tt>,
* <tt>boundary_worker</tt> and <tt>face_worker</tt> are the same ones
- * handed to loop(). While there we only run the loop over all cells,
- * here, we do a single cell and, if necessary, its faces, interior
- * and boundary.
+ * handed to loop(). While there we only run the loop over all cells, here,
+ * we do a single cell and, if necessary, its faces, interior and boundary.
*
- * Upon return, the DoFInfo objects in the DoFInfoBox are filled with
- * the data computed on the cell and each of the faces. Thus, after
- * the execution of this function, we are ready to call
- * DoFInfoBox::assemble() to distribute the local data into global
- * data.
+ * Upon return, the DoFInfo objects in the DoFInfoBox are filled with the
+ * data computed on the cell and each of the faces. Thus, after the
+ * execution of this function, we are ready to call DoFInfoBox::assemble()
+ * to distribute the local data into global data.
*
* @param cell is the cell we work on
- * @param dof_info is the object into which local results are
- * entered. It is expected to have been set up for the right types of
- * data.
- * @param info is the object containing additional data only needed
- * for internal processing.
+ * @param dof_info is the object into which local results are entered. It is
+ * expected to have been set up for the right types of data.
+ * @param info is the object containing additional data only needed for
+ * internal processing.
* @param cell_worker defines the local action on each cell.
* @param boundary_worker defines the local action on boundary faces
* @param face_worker defines the local action on interior faces.
- * @param loop_control control structure to specify what actions should be performed.
+ * @param loop_control control structure to specify what actions should be
+ * performed.
*
* @ingroup MeshWorker
* @author Guido Kanschat
/**
- * The main work function of this namespace. It is a loop over all
- * cells in an iterator range, in which cell_action() is called for
- * each cell. Unilaterally refined interior faces are handled
- * automatically by the loop.
- * Most of the work in this loop is done in cell_action(), which also
- * receives most of the parameters of this function. See the
- * documentation there for more details.
+ * The main work function of this namespace. It is a loop over all cells in
+ * an iterator range, in which cell_action() is called for each cell.
+ * Unilaterally refined interior faces are handled automatically by the
+ * loop. Most of the work in this loop is done in cell_action(), which also
+ * receives most of the parameters of this function. See the documentation
+ * there for more details.
*
- * If you don't want anything to be done on cells, interior or boundary faces
- * to happen, simply pass the Null pointer to one of the function
+ * If you don't want anything to be done on cells, interior or boundary
+ * faces to happen, simply pass the Null pointer to one of the function
* arguments.
*
* @ingroup MeshWorker
}
/**
- * @deprecated The simplification in this loop is
- * insignificant. Therefore, it is recommended to use loop() instead.
+ * @deprecated The simplification in this loop is insignificant. Therefore,
+ * it is recommended to use loop() instead.
*
* Simplified interface for loop() if specialized for integration.
*
/**
- * Simplified interface for loop() if specialized for integration,
- * using the virtual functions in LocalIntegrator.
+ * Simplified interface for loop() if specialized for integration, using the
+ * virtual functions in LocalIntegrator.
*
* @ingroup MeshWorker
* @author Guido Kanschat, 2009
{
/**
- * A class that, instead of assembling into a matrix or vector,
- * outputs the results on a cell to a gnuplot patch.
+ * A class that, instead of assembling into a matrix or vector, outputs
+ * the results on a cell to a gnuplot patch.
*
- * This assembler expects that LocalResults contains quadrature values
- * set with LocalResults::quadrature_value(). When it is initialized
- * with the number of quadrature points in a single (!) space
- * direction and the number of data fields to be displayed, it
- * initializes LocalResults automatically. The number of data fields
- * in local results will be increased by dim in order to accommodate
- * for the coordinates of the data points.
+ * This assembler expects that LocalResults contains quadrature values set
+ * with LocalResults::quadrature_value(). When it is initialized with the
+ * number of quadrature points in a single (!) space direction and the
+ * number of data fields to be displayed, it initializes LocalResults
+ * automatically. The number of data fields in local results will be
+ * increased by dim in order to accommodate for the coordinates of the
+ * data points.
*
- * While data slots for the space coordinates are allocated
- * automatically, these coordinates are not entered. It is up to the
- * user to enter the coordinates in the first dim data entries at
- * every point. This adds the flexibility to output transformed
- * coordinates or even something completely different.
+ * While data slots for the space coordinates are allocated automatically,
+ * these coordinates are not entered. It is up to the user to enter the
+ * coordinates in the first dim data entries at every point. This adds the
+ * flexibility to output transformed coordinates or even something
+ * completely different.
*
* @note In the current implementation, only cell data can be written.
*
GnuplotPatch();
/**
- * Initialize for writing
- * <i>n</i> data vectors. The
- * number of points is the
- * number of quadrature
- * points in a single
- * direction in a tensor
- * product formula. It must
- * match the number in the
- * actual Quadrature used to
- * create the patches. The
- * total number of data
- * vectors produced is <tt>n+dim</tt>
- * and the first dim should be
- * the space coordinates of
- * the points. Nevertheless,
- * it is up to the user to
- * set these values to
- * whatever is desired.
+ * Initialize for writing <i>n</i> data vectors. The number of points is
+ * the number of quadrature points in a single direction in a tensor
+ * product formula. It must match the number in the actual Quadrature
+ * used to create the patches. The total number of data vectors produced
+ * is <tt>n+dim</tt> and the first dim should be the space coordinates
+ * of the points. Nevertheless, it is up to the user to set these values
+ * to whatever is desired.
*/
void initialize (const unsigned int n_points,
const unsigned int n_vectors);
/**
- * Set the stream #os to
- * which data is written. If
- * no stream is selected with
- * this function, data goes
- * to @p deallog.
+ * Set the stream #os to which data is written. If no stream is selected
+ * with this function, data goes to @p deallog.
*/
void initialize_stream (std::ostream &stream);
/**
- * Initialize the local data
- * in the
- * DoFInfo
- * object used later for
+ * Initialize the local data in the DoFInfo object used later for
* assembling.
*
- * The info object refers to
- * a cell if
- * <code>!face</code>, or
- * else to an interior or
- * boundary face.
+ * The info object refers to a cell if <code>!face</code>, or else to an
+ * interior or boundary face.
*/
template <int dim>
void initialize_info(DoFInfo<dim> &info, bool face);
/**
- * Write the patch to the
- * output stream.
+ * Write the patch to the output stream.
*/
template<int dim>
void assemble(const DoFInfo<dim> &info);
private:
/**
- * Write the object T either
- * to the stream #os, if initialize_stream()
- * has been called, or to
- * @p deallog if no pointer has
- * been set.
+ * Write the object T either to the stream #os, if initialize_stream()
+ * has been called, or to @p deallog if no pointer has been set.
*/
template<typename T>
void write(const T &t) const;
/**
- * Write an end-of-line marker either
- * to the stream #os, if initialize_stream
- * has been called, or to
- * @p deallog if no pointer has
+ * Write an end-of-line marker either to the stream #os, if
+ * initialize_stream has been called, or to @p deallog if no pointer has
* been set.
*/
void write_endl () const;
/**
- * The number of output
- * components in each point.
+ * The number of output components in each point.
*/
unsigned int n_vectors;
/**
- * The number of points in
- * one direction.
+ * The number of points in one direction.
*/
unsigned int n_points;
#include <deal.II/multigrid/mg_constrained_dofs.h>
/**
- * @file
- * @brief MeshWorker::Assember objects for systems without block structure
+ * @file @brief MeshWorker::Assember objects for systems without block
+ * structure
*
- * The header containing the classes
- * MeshWorker::Assember::MatrixSimple,
- * MeshWorker::Assember::MGMatrixSimple,
- * MeshWorker::Assember::ResidualSimple, and
- * MeshWorker::Assember::SystemSimple.
+ * The header containing the classes MeshWorker::Assember::MatrixSimple,
+ * MeshWorker::Assember::MGMatrixSimple, MeshWorker::Assember::ResidualSimple,
+ * and MeshWorker::Assember::SystemSimple.
*/
DEAL_II_NAMESPACE_OPEN
/**
* Assemble residuals without block structure.
*
- * The data structure for this Assembler class is a simple vector on
- * each cell with entries from zero to
- * FiniteElementData::dofs_per_cell and a simple global vector with
- * entries numbered from zero to DoFHandler::n_dofs(). No BlockInfo is
- * required and the global vector may be any type of vector having
- * element access through <tt>operator() (unsigned int)</tt>
+ * The data structure for this Assembler class is a simple vector on each
+ * cell with entries from zero to FiniteElementData::dofs_per_cell and a
+ * simple global vector with entries numbered from zero to
+ * DoFHandler::n_dofs(). No BlockInfo is required and the global vector
+ * may be any type of vector having element access through <tt>operator()
+ * (unsigned int)</tt>
*
* @ingroup MeshWorker
* @author Guido Kanschat, 2009
{
public:
/**
- * Initialize with an AnyData object holding the result of
- * assembling.
+ * Initialize with an AnyData object holding the result of assembling.
*
- * Assembling currently writes into the first vector of <tt>results</tt>.
+ * Assembling currently writes into the first vector of
+ * <tt>results</tt>.
*/
void initialize(AnyData &results);
* @deprecated This function is of no effect. Only the block info
* structure in DoFInfo is being used.
*
- * Store information on the local block structure. If the
- * assembler is inititialized with this function,
- * initialize_info() will generate one local matrix for each
- * block row and column, which will be numbered
+ * Store information on the local block structure. If the assembler is
+ * inititialized with this function, initialize_info() will generate one
+ * local matrix for each block row and column, which will be numbered
* lexicographically, row by row.
*
- * In spite of using local block structure, all blocks will be
- * enteres into the same global matrix, disregarding any global
- * block structure.
+ * In spite of using local block structure, all blocks will be enteres
+ * into the same global matrix, disregarding any global block structure.
*/
void initialize_local_blocks(const BlockIndices &);
/**
- * Initialize the local data in the DoFInfo object used later
- * for assembling.
+ * Initialize the local data in the DoFInfo object used later for
+ * assembling.
*
- * The info object refers to a cell if <code>!face</code>, or
- * else to an interior or boundary face.
+ * The info object refers to a cell if <code>!face</code>, or else to an
+ * interior or boundary face.
*/
template <class DOFINFO>
void initialize_info(DOFINFO &info, bool face) const;
/**
* Assemble the local residuals into the global residuals.
*
- * Values are added to the previous contents. If constraints are
- * active, ConstraintMatrix::distribute_local_to_global() is
- * used.
+ * Values are added to the previous contents. If constraints are active,
+ * ConstraintMatrix::distribute_local_to_global() is used.
*/
template <class DOFINFO>
void assemble(const DOFINFO &info);
/**
* Assemble local matrices into a single global matrix. If this global
- * matrix has a block structure, this structure is not used, but
- * rather the global numbering of degrees of freedom.
+ * matrix has a block structure, this structure is not used, but rather
+ * the global numbering of degrees of freedom.
*
- * After being initialized with a SparseMatrix object (or another
- * matrix offering the same functionality as SparseMatrix::add()),
- * this class can be used in a MeshWorker::loop() to assemble the cell
- * and face matrices into the global matrix.
+ * After being initialized with a SparseMatrix object (or another matrix
+ * offering the same functionality as SparseMatrix::add()), this class can
+ * be used in a MeshWorker::loop() to assemble the cell and face matrices
+ * into the global matrix.
*
* If a ConstraintMatrix has been provided during initialization, this
- * matrix will be used
- * (ConstraintMatrix::distribute_local_to_global(), to be precise) to
- * enter the local matrix into the global sparse matrix.
+ * matrix will be used (ConstraintMatrix::distribute_local_to_global(), to
+ * be precise) to enter the local matrix into the global sparse matrix.
*
- * The assembler can handle two different types of local data. First,
- * by default, the obvious choice of taking a single local matrix with
- * dimensions equal to the number of degrees of freedom of the
- * cell. Alternatively, a local block structure can be initialized
- * in DoFInfo. After this, the local data will be
- * arranged as an array of n by n FullMatrix blocks, which are
- * ordered lexicographically in DoFInfo.
+ * The assembler can handle two different types of local data. First, by
+ * default, the obvious choice of taking a single local matrix with
+ * dimensions equal to the number of degrees of freedom of the cell.
+ * Alternatively, a local block structure can be initialized in DoFInfo.
+ * After this, the local data will be arranged as an array of n by n
+ * FullMatrix blocks, which are ordered lexicographically in DoFInfo.
*
* @ingroup MeshWorker
* @author Guido Kanschat, 2009
{
public:
/**
- * Constructor, initializing the #threshold, which limits how
- * small numbers may be to be entered into the matrix.
+ * Constructor, initializing the #threshold, which limits how small
+ * numbers may be to be entered into the matrix.
*/
MatrixSimple(double threshold = 1.e-12);
*/
void initialize(MATRIX &m);
/**
- * Initialize the constraints. After this function has been
- * called with a valid ConstraintMatrix, the function
- * ConstraintMatrix::distribute_local_to_global() will be used
- * by assemble() to distribute the cell and face matrices into a
- * global sparse matrix.
+ * Initialize the constraints. After this function has been called with
+ * a valid ConstraintMatrix, the function
+ * ConstraintMatrix::distribute_local_to_global() will be used by
+ * assemble() to distribute the cell and face matrices into a global
+ * sparse matrix.
*/
void initialize(const ConstraintMatrix &constraints);
* @deprecated This function is of no effect. Only the block info
* structure in DoFInfo is being used.
*
- * Store information on the local block structure. If the
- * assembler is inititialized with this function,
- * initialize_info() will generate one local matrix for each
- * block row and column, which will be numbered
+ * Store information on the local block structure. If the assembler is
+ * inititialized with this function, initialize_info() will generate one
+ * local matrix for each block row and column, which will be numbered
* lexicographically, row by row.
*
- * In spite of using local block structure, all blocks will be
- * enteres into the same global matrix, disregarding any global
- * block structure.
+ * In spite of using local block structure, all blocks will be enteres
+ * into the same global matrix, disregarding any global block structure.
*/
void initialize_local_blocks(const BlockIndices &);
/**
- * Initialize the local data in the DoFInfo object used later
- * for assembling.
+ * Initialize the local data in the DoFInfo object used later for
+ * assembling.
*
- * The info object refers to a cell if <code>!face</code>, or
- * else to an interior or boundary face.
+ * The info object refers to a cell if <code>!face</code>, or else to an
+ * interior or boundary face.
*/
template <class DOFINFO>
void initialize_info(DOFINFO &info, bool face) const;
void assemble(const DOFINFO &info);
/**
- * Assemble both local matrices in the info objects into the
- * global matrix.
+ * Assemble both local matrices in the info objects into the global
+ * matrix.
*/
template<class DOFINFO>
void assemble(const DOFINFO &info1,
const DOFINFO &info2);
private:
/**
- * Assemble a single matrix
- * into #matrix.
+ * Assemble a single matrix into #matrix.
*/
void assemble(const FullMatrix<double> &M,
const std::vector<types::global_dof_index> &i1,
const std::vector<types::global_dof_index> &i2);
/**
- * The global matrix being
- * assembled.
+ * The global matrix being assembled.
*/
SmartPointer<MATRIX,MatrixSimple<MATRIX> > matrix;
/**
- * A pointer to the object
- * containing constraints.
+ * A pointer to the object containing constraints.
*/
SmartPointer<const ConstraintMatrix,MatrixSimple<MATRIX> > constraints;
/**
- * The smallest positive number that will be entered into the
- * global matrix. All smaller absolute values will be treated as
- * zero and will not be assembled.
+ * The smallest positive number that will be entered into the global
+ * matrix. All smaller absolute values will be treated as zero and will
+ * not be assembled.
*/
const double threshold;
/**
- * Assemble local matrices into level matrices without using
- * block structure.
+ * Assemble local matrices into level matrices without using block
+ * structure.
*
- * @todo The matrix structures needed for assembling level matrices
- * with local refinement and continuous elements are missing.
+ * @todo The matrix structures needed for assembling level matrices with
+ * local refinement and continuous elements are missing.
*
* @ingroup MeshWorker
* @author Guido Kanschat, 2009
{
public:
/**
- * Constructor, initializing the #threshold, which limits how
- * small numbers may be to be entered into the matrix.
+ * Constructor, initializing the #threshold, which limits how small
+ * numbers may be to be entered into the matrix.
*/
MGMatrixSimple(double threshold = 1.e-12);
void initialize(const MGConstrainedDoFs &mg_constrained_dofs);
/**
- * @deprecated This function is of no effect. Only the block
- * info structure in DoFInfo is being used.
+ * @deprecated This function is of no effect. Only the block info
+ * structure in DoFInfo is being used.
*
- * Store information on the local block structure. If the
- * assembler is inititialized with this function,
- * initialize_info() will generate one local matrix for each
- * block row and column, which will be numbered
+ * Store information on the local block structure. If the assembler is
+ * inititialized with this function, initialize_info() will generate one
+ * local matrix for each block row and column, which will be numbered
* lexicographically, row by row.
*
- * In spite of using local block structure, all blocks will be
- * enteres into the same global matrix, disregarding any global
- * block structure.
+ * In spite of using local block structure, all blocks will be enteres
+ * into the same global matrix, disregarding any global block structure.
*/
void initialize_local_blocks(const BlockIndices &);
/**
- * Initialize the matrices #flux_up and #flux_down used for
- * local refinement with discontinuous Galerkin methods.
+ * Initialize the matrices #flux_up and #flux_down used for local
+ * refinement with discontinuous Galerkin methods.
*/
void initialize_fluxes(MGLevelObject<MATRIX> &flux_up,
MGLevelObject<MATRIX> &flux_down);
/**
- * Initialize the matrices #interface_in and #interface_out used
- * for local refinement with continuous Galerkin methods.
+ * Initialize the matrices #interface_in and #interface_out used for
+ * local refinement with continuous Galerkin methods.
*/
void initialize_interfaces(MGLevelObject<MATRIX> &interface_in,
MGLevelObject<MATRIX> &interface_out);
/**
- * Initialize the local data in the DoFInfo object used later
- * for assembling.
+ * Initialize the local data in the DoFInfo object used later for
+ * assembling.
*
- * The info object refers to a cell if <code>!face</code>, or
- * else to an interior or boundary face.
+ * The info object refers to a cell if <code>!face</code>, or else to an
+ * interior or boundary face.
*/
template <class DOFINFO>
void initialize_info(DOFINFO &info, bool face) const;
void assemble(const DOFINFO &info);
/**
- * Assemble both local matrices in the info objects into the
- * global matrices.
+ * Assemble both local matrices in the info objects into the global
+ * matrices.
*/
template<class DOFINFO>
void assemble(const DOFINFO &info1,
SmartPointer<MGLevelObject<MATRIX>,MGMatrixSimple<MATRIX> > matrix;
/**
- * The matrix used for face flux terms across the refinement
- * edge, coupling coarse to fine.
+ * The matrix used for face flux terms across the refinement edge,
+ * coupling coarse to fine.
*/
SmartPointer<MGLevelObject<MATRIX>,MGMatrixSimple<MATRIX> > flux_up;
/**
- * The matrix used for face flux terms across the refinement
- * edge, coupling fine to coarse.
+ * The matrix used for face flux terms across the refinement edge,
+ * coupling fine to coarse.
*/
SmartPointer<MGLevelObject<MATRIX>,MGMatrixSimple<MATRIX> > flux_down;
/**
- * The matrix used for face contributions for continuous
- * elements across the refinement edge, coupling coarse to fine.
+ * The matrix used for face contributions for continuous elements across
+ * the refinement edge, coupling coarse to fine.
*/
SmartPointer<MGLevelObject<MATRIX>,MGMatrixSimple<MATRIX> > interface_in;
/**
- * The matrix used for face contributions for continuous
- * elements across the refinement edge, coupling fine to coarse.
+ * The matrix used for face contributions for continuous elements across
+ * the refinement edge, coupling fine to coarse.
*/
SmartPointer<MGLevelObject<MATRIX>,MGMatrixSimple<MATRIX> > interface_out;
/**
SmartPointer<const MGConstrainedDoFs,MGMatrixSimple<MATRIX> > mg_constrained_dofs;
/**
- * The smallest positive number that will be entered into the
- * global matrix. All smaller absolute values will be treated as
- * zero and will not be assembled.
+ * The smallest positive number that will be entered into the global
+ * matrix. All smaller absolute values will be treated as zero and will
+ * not be assembled.
*/
const double threshold;
/**
- * Assemble a simple matrix and a simple right hand side at once. We
- * use a combination of MatrixSimple and ResidualSimple to achieve
- * this. Cell and face operators should fill the matrix and vector
- * objects in LocalResults and this class will assemble
- * them into matrix and vector objects.
+ * Assemble a simple matrix and a simple right hand side at once. We use a
+ * combination of MatrixSimple and ResidualSimple to achieve this. Cell
+ * and face operators should fill the matrix and vector objects in
+ * LocalResults and this class will assemble them into matrix and vector
+ * objects.
*
* @ingroup MeshWorker
* @author Guido Kanschat, 2009
{
public:
/**
- * Constructor setting the
- * threshold value in
- * MatrixSimple.
+ * Constructor setting the threshold value in MatrixSimple.
*/
SystemSimple(double threshold = 1.e-12);
/**
- * Store the two objects data
- * is assembled into.
+ * Store the two objects data is assembled into.
*/
void initialize(MATRIX &m, VECTOR &rhs);
/**
- * Initialize the constraints. After this function has been
- * called with a valid ConstraintMatrix, the function
- * ConstraintMatrix::distribute_local_to_global() will be used
- * by assemble() to distribute the cell and face matrices into a
- * global sparse matrix.
+ * Initialize the constraints. After this function has been called with
+ * a valid ConstraintMatrix, the function
+ * ConstraintMatrix::distribute_local_to_global() will be used by
+ * assemble() to distribute the cell and face matrices into a global
+ * sparse matrix.
*/
void initialize(const ConstraintMatrix &constraints);
/**
- * Initialize the local data
- * in the
- * DoFInfo
- * object used later for
+ * Initialize the local data in the DoFInfo object used later for
* assembling.
*
- * The info object refers to
- * a cell if
- * <code>!face</code>, or
- * else to an interior or
- * boundary face.
+ * The info object refers to a cell if <code>!face</code>, or else to an
+ * interior or boundary face.
*/
template <class DOFINFO>
void initialize_info(DOFINFO &info, bool face) const;
/**
- * Assemble the matrix
- * DoFInfo::M1[0]
- * into the global matrix.
+ * Assemble the matrix DoFInfo::M1[0] into the global matrix.
*/
template<class DOFINFO>
void assemble(const DOFINFO &info);
/**
- * Assemble both local
- * matrices in the info
- * objects into the global
+ * Assemble both local matrices in the info objects into the global
* matrix.
*/
template<class DOFINFO>
* A class that selects vectors from a list of named vectors.
*
* Since the number of vectors in an AnyData object may grow with every
- * nesting of applications or loops, it is important to be able to
- * select those, which are actually used in computing residuals etc.
- * This class organizes the selection.
+ * nesting of applications or loops, it is important to be able to select
+ * those, which are actually used in computing residuals etc. This class
+ * organizes the selection.
*
- * It is used for instance in IntegrationWorker to
- * determine which values, derivatives or second derivatives are
- * actually computed.
+ * It is used for instance in IntegrationWorker to determine which values,
+ * derivatives or second derivatives are actually computed.
*
* @ingroup MeshWorker
* @author Guido Kanschat 2009
public:
/**
* Add a vector to the selection of finite element functions. The
- * arguments are the name of the vector and indicators, which
- * information is to be extracted from the vector. The name refers
- * to an entry in a AnyData object, which will be identified by
- * initialize(). The three bool parameters indicate, whether
- * values, greadients and Hessians of the finite element function
- * are to be computed on each cell or face.
+ * arguments are the name of the vector and indicators, which information
+ * is to be extracted from the vector. The name refers to an entry in a
+ * AnyData object, which will be identified by initialize(). The three
+ * bool parameters indicate, whether values, greadients and Hessians of
+ * the finite element function are to be computed on each cell or face.
*/
void add(const std::string &name,
const bool values = true,
const bool hessians = false);
/**
- * Does the same as the function above but it is possible to
- * select a block of the global vector.
+ * Does the same as the function above but it is possible to select a
+ * block of the global vector.
*/
// void add(const std::string& name,
// const unsigned int selected_block,
// bool hessians = false);
/**
- * Initialize the selection field with a data vector. While add()
- * only enters the names of vectors, which will be used in the
- * integration loop over cells and faces, this function links the
- * names to actual vectos in a AnyData object.
+ * Initialize the selection field with a data vector. While add() only
+ * enters the names of vectors, which will be used in the integration loop
+ * over cells and faces, this function links the names to actual vectos in
+ * a AnyData object.
*
- * @note This function caches the index associated with a
- * name. Therefore, it must be called every time after the AnyData
- * object has changed.
+ * @note This function caches the index associated with a name. Therefore,
+ * it must be called every time after the AnyData object has changed.
*/
void initialize(const AnyData &);
unsigned int hessian_index (const unsigned int i) const;
/**
- * Print the contents of the
- * selection to the stream.
+ * Print the contents of the selection to the stream.
*/
template <class STREAM, typename DATA>
void print (STREAM &s, const AnyData &v) const;
protected:
/**
- * Selection of the vectors
- * used to compute values.
+ * Selection of the vectors used to compute values.
*/
NamedSelection value_selection;
};
/**
- * Based on VectorSelector, this is the class used by IntegrationInfo
- * to compute values of source vectors in quadrature points.
+ * Based on VectorSelector, this is the class used by IntegrationInfo to
+ * compute values of source vectors in quadrature points.
*
* @ingroup MeshWorker
* @author Guido Kanschat, 2009
*/
virtual ~VectorDataBase();
/**
- * The only function added to VectorSelector is an abstract
- * virtual function implemented in the derived class template and
- * called by IntegrationInfo.
+ * The only function added to VectorSelector is an abstract virtual
+ * function implemented in the derived class template and called by
+ * IntegrationInfo.
*
- * Depending on the selections made in our base class, this fills
- * the first three arguments with the local data of the finite
- * element functions. It is usually called either for the whole
- * FESystem, or for each base element separately.
+ * Depending on the selections made in our base class, this fills the
+ * first three arguments with the local data of the finite element
+ * functions. It is usually called either for the whole FESystem, or for
+ * each base element separately.
*
- * @param values is the vector filled with the values of the
- * finite element function in the quadrature points.
+ * @param values is the vector filled with the values of the finite
+ * element function in the quadrature points.
*
- * @param gradients is the vector filled with the derivatives of
- * the finite element function in the quadrature points.
+ * @param gradients is the vector filled with the derivatives of the
+ * finite element function in the quadrature points.
*
- * @param hessians is the vector filled with the second
- * derivatives of the finite element function in the quadrature
- * points.
+ * @param hessians is the vector filled with the second derivatives of the
+ * finite element function in the quadrature points.
*
- * @param fe is the FEValuesBase object which is used to compute
- * the function values. Its UpdateFlags must have been set
- * appropriately.
+ * @param fe is the FEValuesBase object which is used to compute the
+ * function values. Its UpdateFlags must have been set appropriately.
*
* @param index is the local index vector. If @p fe refers to base
- * elements of the system, this vector should be sorted by block
- * and the arguments @p start and @p size below specify the subset
- * of @p indices used.
+ * elements of the system, this vector should be sorted by block and the
+ * arguments @p start and @p size below specify the subset of @p indices
+ * used.
*
- * @param component is the first index in @p values, @p gradients
- * and @p hessians entered in this function.
+ * @param component is the first index in @p values, @p gradients and @p
+ * hessians entered in this function.
*
* @param n_comp is the number of components to be filled.
*
- * @param start is the first index of this block in @p indices, or
- * zero if no base elements are used.
+ * @param start is the first index of this block in @p indices, or zero if
+ * no base elements are used.
*
- * @param size is the number of dofs per cell of the current
- * element or base element.
+ * @param size is the number of dofs per cell of the current element or
+ * base element.
*/
virtual void fill(
std::vector<std::vector<std::vector<double> > > &values,
const unsigned int size) const;
/**
- * Fill the local data vector from level vectors. Performs exactly
- * what the other fill() does, but uses the cell level to access a
- * single level out of a hierarchy of level vectors, instead of a
- * global data vector on the active cells.
+ * Fill the local data vector from level vectors. Performs exactly what
+ * the other fill() does, but uses the cell level to access a single level
+ * out of a hierarchy of level vectors, instead of a global data vector on
+ * the active cells.
*/
virtual void mg_fill(
std::vector<std::vector<std::vector<double> > > &values,
/**
- * Based on VectorSelector, this is the class that implements the
- * function VectorDataBase::fill() for a certain type of vector, using
- * AnyData to identify vectors by name.
+ * Based on VectorSelector, this is the class that implements the function
+ * VectorDataBase::fill() for a certain type of vector, using AnyData to
+ * identify vectors by name.
*
* @ingroup MeshWorker
* @author Guido Kanschat, 2009
*/
VectorData();
/**
- * Constructor using a
- * prefilled VectorSelector
+ * Constructor using a prefilled VectorSelector
*/
VectorData(const VectorSelector &);
const unsigned int size) const;
/**
- * The memory used by this object.
- */
+ * The memory used by this object.
+ */
std::size_t memory_consumption () const;
};
/**
- * Based on VectorSelector, this is the class that implements the
- * function VectorDataBase::fill() for a certain type of multilevel vectors, using
+ * Based on VectorSelector, this is the class that implements the function
+ * VectorDataBase::fill() for a certain type of multilevel vectors, using
* AnyData to identify vectors by name.
*
* @ingroup MeshWorker
/**
* Multilevel matrix base. This class sets up the interface needed by
- * multilevel algorithms. It has no relation to the actual matrix type
- * and takes the vector class as only template argument.
+ * multilevel algorithms. It has no relation to the actual matrix type and
+ * takes the vector class as only template argument.
*
- * Usually, the derived class MGMatrix, operating on an
- * MGLevelObject of matrices will be sufficient for applications.
+ * Usually, the derived class MGMatrix, operating on an MGLevelObject of
+ * matrices will be sufficient for applications.
*
* @author Guido Kanschat, 2002
*/
virtual ~MGMatrixBase();
/**
- * Matrix-vector-multiplication on
- * a certain level.
+ * Matrix-vector-multiplication on a certain level.
*/
virtual void vmult (const unsigned int level,
VECTOR &dst,
const VECTOR &src) const = 0;
/**
- * Adding matrix-vector-multiplication on
- * a certain level.
+ * Adding matrix-vector-multiplication on a certain level.
*/
virtual void vmult_add (const unsigned int level,
VECTOR &dst,
const VECTOR &src) const = 0;
/**
- * Transpose
- * matrix-vector-multiplication on
- * a certain level.
+ * Transpose matrix-vector-multiplication on a certain level.
*/
virtual void Tvmult (const unsigned int level,
VECTOR &dst,
const VECTOR &src) const = 0;
/**
- * Adding transpose
- * matrix-vector-multiplication on
- * a certain level.
+ * Adding transpose matrix-vector-multiplication on a certain level.
*/
virtual void Tvmult_add (const unsigned int level,
VECTOR &dst,
/**
- * Base class for coarse grid solvers. This defines the virtual
- * parenthesis operator, being the interface used by multigrid
- * methods. Any implementation will be done by derived classes.
+ * Base class for coarse grid solvers. This defines the virtual parenthesis
+ * operator, being the interface used by multigrid methods. Any implementation
+ * will be done by derived classes.
*
* @author Guido Kanschat, 2002
*/
/**
* Base class used to declare the operations needed by a concrete class
* implementing prolongation and restriction of vectors in the multigrid
- * context. This class is abstract and has no implementation of
- * these operations.
+ * context. This class is abstract and has no implementation of these
+ * operations.
*
- * There are several derived classes, reflecting the fact that vector
- * types and numbering of the fine-grid discretization and of the
- * multi-level implementation are independent.
+ * There are several derived classes, reflecting the fact that vector types
+ * and numbering of the fine-grid discretization and of the multi-level
+ * implementation are independent.
*
- * If you use multigrid for a single PDF or for your complete system
- * of equations, you
- * will use MGTransferPrebuilt together with Multigrid. The vector
- * types used on the fine grid as well as for the multilevel
- * operations may be Vector or BlockVector. In both cases,
- * MGTransferPrebuilt will operate on all components of the solution.
+ * If you use multigrid for a single PDF or for your complete system of
+ * equations, you will use MGTransferPrebuilt together with Multigrid. The
+ * vector types used on the fine grid as well as for the multilevel operations
+ * may be Vector or BlockVector. In both cases, MGTransferPrebuilt will
+ * operate on all components of the solution.
*
- * @note For the following, it is important to realize the difference
- * between a solution @ref GlossComponent "component" and a solution
- * @ref GlossBlock "block". The distinction only applies if vector valued
- * elements are used, but is quite important then. This is reflected
- * in the fact that it is not possible right now to use transfer
- * classes based on MGTransferComponentBase for genuine vector valued
- * elements, but descendants of MGTransferBlockBase would have to be
- * applied. In the following text, we will use the term
+ * @note For the following, it is important to realize the difference between
+ * a solution @ref GlossComponent "component" and a solution @ref GlossBlock
+ * "block". The distinction only applies if vector valued elements are used,
+ * but is quite important then. This is reflected in the fact that it is not
+ * possible right now to use transfer classes based on MGTransferComponentBase
+ * for genuine vector valued elements, but descendants of MGTransferBlockBase
+ * would have to be applied. In the following text, we will use the term
* <em>block</em>, but remark that it might refer to components as well.
*
- * @todo update the following documentation, since it does not reflect
- * the latest changes in structure.
+ * @todo update the following documentation, since it does not reflect the
+ * latest changes in structure.
*
- * For mixed systems, it may be required to do multigrid only for a
- * single component or for some components. The classes
- * MGTransferSelect and MGTransferBlock handle these cases.
+ * For mixed systems, it may be required to do multigrid only for a single
+ * component or for some components. The classes MGTransferSelect and
+ * MGTransferBlock handle these cases.
*
- * MGTransferSelect is used if you use mutligrid (on Vector objects)
- * for a single component, possibly grouped using
- * <tt>mg_target_component</tt>.
+ * MGTransferSelect is used if you use mutligrid (on Vector objects) for a
+ * single component, possibly grouped using <tt>mg_target_component</tt>.
*
- * The class MGTransferBlock handles the case where your multigrid
- * method operates on BlockVector objects. These can contain all or a
- * consecutive set of the blocks of the complete system. Since most
- * smoothers cannot operate on block structures, it is not clear
- * whether this case is really useful. Therefore, a tested
- * implementation of this case will be supplied when needed.
+ * The class MGTransferBlock handles the case where your multigrid method
+ * operates on BlockVector objects. These can contain all or a consecutive set
+ * of the blocks of the complete system. Since most smoothers cannot operate
+ * on block structures, it is not clear whether this case is really useful.
+ * Therefore, a tested implementation of this case will be supplied when
+ * needed.
*
* @author Wolfgang Bangerth, Guido Kanschat, 1999, 2002, 2007
*/
{
public:
/**
- * Destructor. Does nothing here, but
- * needs to be declared virtual anyway.
+ * Destructor. Does nothing here, but needs to be declared virtual anyway.
*/
virtual ~MGTransferBase();
/**
- * Prolongate a vector from level
- * <tt>to_level-1</tt> to level
- * <tt>to_level</tt>. The previous
- * content of <tt>dst</tt> is
- * overwritten.
+ * Prolongate a vector from level <tt>to_level-1</tt> to level
+ * <tt>to_level</tt>. The previous content of <tt>dst</tt> is overwritten.
*
- * @arg src is a vector with as
- * many elements as there are
- * degrees of freedom on the
- * coarser level involved.
+ * @arg src is a vector with as many elements as there are degrees of
+ * freedom on the coarser level involved.
*
- * @arg dst has as many elements
- * as there are degrees of
- * freedom on the finer level.
+ * @arg dst has as many elements as there are degrees of freedom on the
+ * finer level.
*/
virtual void prolongate (const unsigned int to_level,
VECTOR &dst,
const VECTOR &src) const = 0;
/**
- * Restrict a vector from level
- * <tt>from_level</tt> to level
- * <tt>from_level-1</tt> and add
- * this restriction to
- * <tt>dst</tt>. If the region
- * covered by cells on level
- * <tt>from_level</tt> is smaller
- * than that of level
- * <tt>from_level-1</tt> (local
- * refinement), then some degrees
- * of freedom in <tt>dst</tt> are
- * active and will not be
- * altered. For the other degress
- * of freedom, the result of the
- * restriction is added.
+ * Restrict a vector from level <tt>from_level</tt> to level
+ * <tt>from_level-1</tt> and add this restriction to <tt>dst</tt>. If the
+ * region covered by cells on level <tt>from_level</tt> is smaller than that
+ * of level <tt>from_level-1</tt> (local refinement), then some degrees of
+ * freedom in <tt>dst</tt> are active and will not be altered. For the other
+ * degress of freedom, the result of the restriction is added.
*
- * @arg src is a vector with as
- * many elements as there are
- * degrees of freedom on the
- * finer level
+ * @arg src is a vector with as many elements as there are degrees of
+ * freedom on the finer level
*
- * @arg dst has as many elements as there
- * are degrees of freedom on the coarser
- * level.
+ * @arg dst has as many elements as there are degrees of freedom on the
+ * coarser level.
*
*/
virtual void restrict_and_add (const unsigned int from_level,
/**
- * Base class for multigrid smoothers. Does nothing but defining the
- * interface used by multigrid methods.
+ * Base class for multigrid smoothers. Does nothing but defining the interface
+ * used by multigrid methods.
*
* @author Guido Kanschat, 2002
*/
virtual void clear() = 0;
/**
- * Smoothing function. This is the
- * function used in multigrid
- * methods.
+ * Smoothing function. This is the function used in multigrid methods.
*/
virtual void smooth (const unsigned int level,
VECTOR &u,
/*@{*/
/**
- * General smoother class for block vectors. This class gives complete
- * freedom to the choice of a block smoother by being initialized with
- * a matrix and a smoother object. Therefore, the smoother object for
- * each level must be constructed by hand.
+ * General smoother class for block vectors. This class gives complete freedom
+ * to the choice of a block smoother by being initialized with a matrix and a
+ * smoother object. Therefore, the smoother object for each level must be
+ * constructed by hand.
*
* @author Guido Kanschat, 2005
*/
{
public:
/**
- * Constructor. Sets memory and
- * smoothing parameters.
+ * Constructor. Sets memory and smoothing parameters.
*/
MGSmootherBlock(VectorMemory<BlockVector<number> > &mem,
const unsigned int steps = 1,
const bool reverse = false);
/**
- * Initialize for matrices. The
- * parameter <tt>matrices</tt> can be
- * any object having functions
- * <tt>get_minlevel()</tt> and
- * <tt>get_maxlevel()</tt> as well as
- * an <tt>operator[]</tt> returning a
+ * Initialize for matrices. The parameter <tt>matrices</tt> can be any
+ * object having functions <tt>get_minlevel()</tt> and
+ * <tt>get_maxlevel()</tt> as well as an <tt>operator[]</tt> returning a
* reference to @p MATRIX.
*
- * The same convention is used
- * for the parameter
- * <tt>smoothers</tt>, such that
- * <tt>operator[]</tt> returns
- * the object doing the
- * block-smoothing on a single
- * level.
+ * The same convention is used for the parameter <tt>smoothers</tt>, such
+ * that <tt>operator[]</tt> returns the object doing the block-smoothing on
+ * a single level.
*
- * This function stores pointers
- * to the level matrices and
- * smoothing operator for each
- * level.
+ * This function stores pointers to the level matrices and smoothing
+ * operator for each level.
*/
template <class MGMATRIX, class MGRELAX>
void initialize (const MGMATRIX &matrices,
void clear ();
/**
- * Modify the number of smoothing
- * steps on finest level.
+ * Modify the number of smoothing steps on finest level.
*/
void set_steps (const unsigned int);
/**
- * Switch on/off variable
- * smoothing.
+ * Switch on/off variable smoothing.
*/
void set_variable (const bool);
/**
- * Switch on/off symmetric
- * smoothing.
+ * Switch on/off symmetric smoothing.
*/
void set_symmetric (const bool);
/**
- * Switch on/off transposed. This
- * is mutually exclusive with
- * reverse().
+ * Switch on/off transposed. This is mutually exclusive with reverse().
*/
void set_transpose (const bool);
/**
- * Switch on/off reversed. This
- * is mutually exclusive with
- * transpose().
+ * Switch on/off reversed. This is mutually exclusive with transpose().
*/
void set_reverse (const bool);
/**
- * Implementation of the
- * interface for @p Multigrid.
- * This function does nothing,
- * which by comparison with the
- * definition of this function
- * means that the the smoothing
- * operator equals the null
- * operator.
+ * Implementation of the interface for @p Multigrid. This function does
+ * nothing, which by comparison with the definition of this function means
+ * that the the smoothing operator equals the null operator.
*/
virtual void smooth (const unsigned int level,
BlockVector<number> &u,
/*@{*/
/**
- * Coarse grid solver using LAC iterative methods.
- * This is a little wrapper, transforming a triplet of iterative
- * solver, matrix and preconditioner into a coarse grid solver.
+ * Coarse grid solver using LAC iterative methods. This is a little wrapper,
+ * transforming a triplet of iterative solver, matrix and preconditioner into
+ * a coarse grid solver.
*
- * The type of the matrix (i.e. the template parameter @p MATRIX)
- * should be derived from @p Subscriptor to allow for the use of a
- * smart pointer to it.
+ * The type of the matrix (i.e. the template parameter @p MATRIX) should be
+ * derived from @p Subscriptor to allow for the use of a smart pointer to it.
*
* @author Guido Kanschat, 1999, Ralf Hartmann, 2002.
*/
MGCoarseGridLACIteration ();
/**
- * Constructor.
- * Store solver, matrix and
- * preconditioning method for later
+ * Constructor. Store solver, matrix and preconditioning method for later
* use.
*/
template<class MATRIX, class PRECOND>
void clear ();
/**
- * Implementation of the abstract
- * function.
- * Calls the solver method with
- * matrix, vectors and
- * preconditioner.
+ * Implementation of the abstract function. Calls the solver method with
+ * matrix, vectors and preconditioner.
*/
void operator() (const unsigned int level,
VECTOR &dst,
const VECTOR &src) const;
/**
- * Sets the matrix. This gives
- * the possibility to replace the
- * matrix that was given to the
- * constructor by a new matrix.
+ * Sets the matrix. This gives the possibility to replace the matrix that
+ * was given to the constructor by a new matrix.
*/
template <class MATRIX>
void set_matrix (const MATRIX &);
/**
- * Coarse grid solver by QR factorization implemented in the class Householder.
+ * Coarse grid solver by QR factorization implemented in the class
+ * Householder.
*
- * Upon initialization, the QR decomposition of the matrix is
- * computed. then, the operator() uses Householder::least_squares() to
- * compute the action of the inverse.
+ * Upon initialization, the QR decomposition of the matrix is computed. then,
+ * the operator() uses Householder::least_squares() to compute the action of
+ * the inverse.
*
* @author Guido Kanschat, 2003, 2012
*/
{
public:
/**
- * Constructor, taking the coarse
- * grid matrix.
+ * Constructor, taking the coarse grid matrix.
*/
MGCoarseGridHouseholder (const FullMatrix<number> *A = 0);
{
public:
/**
- * Constructor leaving an
- * uninitialized object.
+ * Constructor leaving an uninitialized object.
*/
MGCoarseGridSVD ();
/**
- * Initialize for a new
- * matrix. This resets the
- * dimensions to the
+ * Initialize for a new matrix. This resets the dimensions to the
*/
void initialize (const FullMatrix<number> &A, const double threshold = 0);
/**
- * Collection of boundary constraints and refinement edge constraints
- * for level vectors.
+ * Collection of boundary constraints and refinement edge constraints for
+ * level vectors.
*
* @ingroup mg
*/
typedef std::vector<std::set<types::global_dof_index> >::size_type size_dof;
/**
- * Fill the internal data structures with hanging node constraints
- * extracted from the dof handler object. Works with natural
- * boundary conditions only. There exists a sister function setting
- * up boundary constraints as well.
+ * Fill the internal data structures with hanging node constraints extracted
+ * from the dof handler object. Works with natural boundary conditions only.
+ * There exists a sister function setting up boundary constraints as well.
*
* This function ensures that on every level, degrees of freedom at interior
* edges of a refinement level are treated corrected but leaves degrees of
void clear();
/**
- * Determine whether a dof index is subject to a boundary
- * constraint.
+ * Determine whether a dof index is subject to a boundary constraint.
*/
bool is_boundary_index (const unsigned int level,
const types::global_dof_index index) const;
const types::global_dof_index index) const;
/**
- * @deprecated Use is_boundary_index() instead. The logic behind
- * this function here is unclear and for practical purposes, the
- * other is needed.
+ * @deprecated Use is_boundary_index() instead. The logic behind this
+ * function here is unclear and for practical purposes, the other is needed.
*
- * Determine whether a dof index is subject to a boundary
- * constraint.
+ * Determine whether a dof index is subject to a boundary constraint.
*/
bool at_refinement_edge_boundary (const unsigned int level,
const types::global_dof_index index) const DEAL_II_DEPRECATED;
/**
- * Return the indices of dofs for each level that are subject to
- * boundary constraints.
+ * Return the indices of dofs for each level that are subject to boundary
+ * constraints.
*/
const std::vector<std::set<types::global_dof_index> > &
get_boundary_indices () const;
* @deprecated Use at_refinement_edge() if possible, else
* get_refinement_edge_indices(unsigned int).
*
- * Return the indices of dofs for each level that lie on the
- * refinement edge (i.e. are on faces between cells of this level
- * and cells on the level below).
+ * Return the indices of dofs for each level that lie on the refinement edge
+ * (i.e. are on faces between cells of this level and cells on the level
+ * below).
*/
const std::vector<std::vector<bool> > &
get_refinement_edge_indices () const DEAL_II_DEPRECATED;
/**
- * Return the indices of dofs on the given level that lie on an
- * refinement edge (dofs on faces to neighbors that are coarser)
+ * Return the indices of dofs on the given level that lie on an refinement
+ * edge (dofs on faces to neighbors that are coarser)
*/
const IndexSet &
get_refinement_edge_indices (unsigned int level) const;
/**
- * @deprecated Use at_refinement_edge_boundary() if possible, else
- * use get_refinement_edge_boundary_indices().
+ * @deprecated Use at_refinement_edge_boundary() if possible, else use
+ * get_refinement_edge_boundary_indices().
*
- * Return the indices of dofs for each level that are in the
- * intersection of the sets returned by get_boundary_indices() and
+ * Return the indices of dofs for each level that are in the intersection of
+ * the sets returned by get_boundary_indices() and
* get_refinement_edge_indices().
*/
const std::vector<std::vector<bool> > &
get_refinement_edge_boundary_indices () const DEAL_II_DEPRECATED;
/**
- * @deprecated The function is_boundary_index() now returns false if
- * no boundary values are set.
+ * @deprecated The function is_boundary_index() now returns false if no
+ * boundary values are set.
*
* Return if boundary_indices need to be set or not.
*/
std::vector<std::set<types::global_dof_index> > boundary_indices;
/**
- * The degrees of freedom on the refinement edge between a level and
- * coarser cells.
+ * The degrees of freedom on the refinement edge between a level and coarser
+ * cells.
*/
std::vector<IndexSet> refinement_edge_indices;
/**
- * @deprecated All functionality of this class has been moved to
- * DoFHandler. Thus, this class is only a wrapper left in the library
- * for compatibility reasons.
+ * @deprecated All functionality of this class has been moved to DoFHandler.
+ * Thus, this class is only a wrapper left in the library for compatibility
+ * reasons.
*
- * This class manages degrees of freedom for a multilevel hierarchy of
- * grids. It does mostly the same as does the @p DoDHandler class,
- * but it uses a separate enumeration of the degrees of freedom on
- * each level. For example, a vertex has several DoF numbers, one for
- * each level of the triangulation on which it exists.
+ * This class manages degrees of freedom for a multilevel hierarchy of grids.
+ * It does mostly the same as does the @p DoDHandler class, but it uses a
+ * separate enumeration of the degrees of freedom on each level. For example,
+ * a vertex has several DoF numbers, one for each level of the triangulation
+ * on which it exists.
*
- * @todo This class has not yet been implemented for the use in the codimension
- * one case (<tt>spacedim != dim </tt>).
+ * @todo This class has not yet been implemented for the use in the
+ * codimension one case (<tt>spacedim != dim </tt>).
*
* @ingroup dofs
- * @author Wolfgang Bangerth, 1998, 1999 Markus Bürg, Timo Heister, Guido Kanschat, 2012
+ * @author Wolfgang Bangerth, 1998, 1999 Markus Bürg, Timo Heister, Guido
+ * Kanschat, 2012
*/
template <int dim, int spacedim=dim>
class MGDoFHandler : public DoFHandler<dim,spacedim>
typedef typename IteratorSelector::active_face_iterator active_face_iterator;
/**
- * Make the dimension and the space_dimension available
- * in function templates.
+ * Make the dimension and the space_dimension available in function
+ * templates.
*/
static const unsigned int dimension = dim;
static const unsigned int space_dimension = spacedim;
/**
- * Default constructor, which
- * will require a call to
- * initialize() later to set the Triangulation.
+ * Default constructor, which will require a call to initialize() later to
+ * set the Triangulation.
*/
MGDoFHandler ();
/**
- * Constructor. Take @p tria as
- * the triangulation to work on.
+ * Constructor. Take @p tria as the triangulation to work on.
*/
MGDoFHandler (const Triangulation<dim, spacedim> &tria);
virtual ~MGDoFHandler ();
/**
- * Go through the triangulation
- * and distribute the degrees of
- * freedoms needed for the given
- * finite element according to
- * the given distribution
- * method. We first call the
- * DoFHandler's function
- * and then distribute the
+ * Go through the triangulation and distribute the degrees of freedoms
+ * needed for the given finite element according to the given distribution
+ * method. We first call the DoFHandler's function and then distribute the
* levelwise numbers.
*
- * A copy of the transferred
- * finite element is stored.
+ * A copy of the transferred finite element is stored.
*/
virtual void distribute_dofs (const FiniteElement<dim,spacedim> &);
/**
- * @name Cell iterator functions
+ * @name Cell iterator functions
*/
/*@{*/
/**
- * Iterator to the first used
- * cell on level @p level.
+ * Iterator to the first used cell on level @p level.
*/
cell_iterator begin (const unsigned int level = 0) const;
/**
- * Iterator past the end; this
- * iterator serves for
- * comparisons of iterators with
- * past-the-end or
- * before-the-beginning states.
+ * Iterator past the end; this iterator serves for comparisons of iterators
+ * with past-the-end or before-the-beginning states.
*/
cell_iterator end () const;
/**
- * Return an iterator which is
- * the first iterator not on
- * level. If @p level is the
- * last level, then this returns
- * <tt>end()</tt>.
+ * Return an iterator which is the first iterator not on level. If @p level
+ * is the last level, then this returns <tt>end()</tt>.
*/
cell_iterator end (const unsigned int level) const;
/**
- * Iterators for MGDofHandler in one dimension. See the @ref Iterators module
- * for more information.
+ * Iterators for MGDofHandler in one dimension. See the @ref Iterators
+ * module for more information.
*/
template <int spacedim>
class Iterators<1,spacedim>
/**
- * Iterators for MGDofHandler in two dimensions. See the @ref Iterators module
- * for more information.
+ * Iterators for MGDofHandler in two dimensions. See the @ref Iterators
+ * module for more information.
*/
template <int spacedim>
class Iterators<2,spacedim>
/**
- * Iterators for MGDofHandler in three dimensions. See the @ref Iterators module
- * for more information.
+ * Iterators for MGDofHandler in three dimensions. See the @ref Iterators
+ * module for more information.
*/
template <int spacedim>
class Iterators<3,spacedim>
{
public:
/**
- * Default constructor for an
- * empty object.
+ * Default constructor for an empty object.
*/
Matrix();
/**
- * Constructor setting up
- * pointers to the matrices in
- * <tt>M</tt> by calling initialize().
+ * Constructor setting up pointers to the matrices in <tt>M</tt> by
+ * calling initialize().
*/
template <class MATRIX>
Matrix(const MGLevelObject<MATRIX> &M);
/**
- * Initialize the object such
- * that the level
- * multiplication uses the
+ * Initialize the object such that the level multiplication uses the
* matrices in <tt>M</tt>
*/
template <class MATRIX>
/**
- * Multilevel matrix selecting from block matrices. This class
- * implements the interface defined by MGMatrixBase. The
- * template parameter @p MATRIX should be a block matrix class like
- * BlockSparseMatrix or @p BlockSparseMatrixEZ. Then, this
- * class stores a pointer to a MGLevelObject of this matrix
- * class. In each @p vmult, the block selected on initialization will
- * be multiplied with the vector provided.
+ * Multilevel matrix selecting from block matrices. This class implements the
+ * interface defined by MGMatrixBase. The template parameter @p MATRIX should
+ * be a block matrix class like BlockSparseMatrix or @p BlockSparseMatrixEZ.
+ * Then, this class stores a pointer to a MGLevelObject of this matrix class.
+ * In each @p vmult, the block selected on initialization will be multiplied
+ * with the vector provided.
*
* @author Guido Kanschat, 2002
*/
{
public:
/**
- * Constructor. @p row and
- * @p col are the coordinate of
- * the selected block. The other
- * argument is handed over to the
- * @p SmartPointer constructor.
+ * Constructor. @p row and @p col are the coordinate of the selected block.
+ * The other argument is handed over to the @p SmartPointer constructor.
*/
MGMatrixSelect (const unsigned int row = 0,
const unsigned int col = 0,
MGLevelObject<MATRIX> *matrix = 0);
/**
- * Set the matrix object to be
- * used. The matrix object must
- * exist longer as the
- * @p MGMatrix object, since
- * only a pointer is stored.
+ * Set the matrix object to be used. The matrix object must exist longer as
+ * the @p MGMatrix object, since only a pointer is stored.
*/
void set_matrix (MGLevelObject<MATRIX> *M);
/**
- * Select the block for
- * multiplication.
+ * Select the block for multiplication.
*/
void select_block (const unsigned int row,
const unsigned int col);
/**
- * Matrix-vector-multiplication on
- * a certain level.
+ * Matrix-vector-multiplication on a certain level.
*/
virtual void vmult (const unsigned int level,
Vector<number> &dst,
const Vector<number> &src) const;
/**
- * Adding matrix-vector-multiplication on
- * a certain level.
+ * Adding matrix-vector-multiplication on a certain level.
*/
virtual void vmult_add (const unsigned int level,
Vector<number> &dst,
const Vector<number> &src) const;
/**
- * Transpose
- * matrix-vector-multiplication on
- * a certain level.
+ * Transpose matrix-vector-multiplication on a certain level.
*/
virtual void Tvmult (const unsigned int level,
Vector<number> &dst,
const Vector<number> &src) const;
/**
- * Adding transpose
- * matrix-vector-multiplication on
- * a certain level.
+ * Adding transpose matrix-vector-multiplication on a certain level.
*/
virtual void Tvmult_add (const unsigned int level,
Vector<number> &dst,
/*@{*/
/**
- * A base class for smoother handling information on smoothing.
- * While not adding to the abstract interface in MGSmootherBase, this
- * class stores information on the number and type of smoothing steps,
- * which in turn can be used by a derived class.
+ * A base class for smoother handling information on smoothing. While not
+ * adding to the abstract interface in MGSmootherBase, this class stores
+ * information on the number and type of smoothing steps, which in turn can be
+ * used by a derived class.
*
* @author Guido Kanschat 2009
*/
{
public:
/**
- * Constructor. Sets smoothing
- * parameters and creates a
- * private GrowingVectorMemory
- * object to be used to retrieve vectors.
+ * Constructor. Sets smoothing parameters and creates a private
+ * GrowingVectorMemory object to be used to retrieve vectors.
*/
MGSmoother(const unsigned int steps = 1,
const bool variable = false,
const bool transpose = false);
/**
- * @deprecated Since
- * GrowingVectorMemory now uses a
- * joint memory pool, it is
- * recommended to use the
- * constructor without the memory
- * object.
+ * @deprecated Since GrowingVectorMemory now uses a joint memory pool, it is
+ * recommended to use the constructor without the memory object.
*
- * Constructor. Sets memory and
- * smoothing parameters.
+ * Constructor. Sets memory and smoothing parameters.
*/
MGSmoother(VectorMemory<VECTOR> &mem,
const unsigned int steps = 1,
const bool transpose = false) DEAL_II_DEPRECATED;
/**
- * Modify the number of smoothing
- * steps on finest level.
+ * Modify the number of smoothing steps on finest level.
*/
void set_steps (const unsigned int);
/**
- * Switch on/off variable
- * smoothing.
+ * Switch on/off variable smoothing.
*/
void set_variable (const bool);
/**
- * Switch on/off symmetric
- * smoothing.
+ * Switch on/off symmetric smoothing.
*/
void set_symmetric (const bool);
/**
- * Switch on/off transposed
- * smoothing. The effect is
- * overriden by set_symmetric().
+ * Switch on/off transposed smoothing. The effect is overriden by
+ * set_symmetric().
*/
void set_transpose (const bool);
/**
- * Set @p debug to a nonzero value
- * to get debug information
- * logged to @p deallog. Increase
- * to get more information
+ * Set @p debug to a nonzero value to get debug information logged to @p
+ * deallog. Increase to get more information
*/
void set_debug (const unsigned int level);
private:
/**
- * The memory object to be used
- * if none is given to the
- * constructor.
+ * The memory object to be used if none is given to the constructor.
*/
GrowingVectorMemory<VECTOR> my_memory;
protected:
/**
- * Number of smoothing steps on
- * the finest level. If no
- * #variable smoothing is chosen,
- * this is the number of steps on
- * all levels.
+ * Number of smoothing steps on the finest level. If no #variable smoothing
+ * is chosen, this is the number of steps on all levels.
*/
unsigned int steps;
/**
- * Variable smoothing: double the
- * number of smoothing steps
- * whenever going to the next
- * coarser level
+ * Variable smoothing: double the number of smoothing steps whenever going
+ * to the next coarser level
*/
bool variable;
/**
- * Symmetric smoothing: in the
- * smoothing iteration, alternate
- * between the relaxation method
- * and its transpose.
+ * Symmetric smoothing: in the smoothing iteration, alternate between the
+ * relaxation method and its transpose.
*/
bool symmetric;
/**
- * Use the transpose of the
- * relaxation method instead of
- * the method itself. This has no
- * effect if #symmetric smoothing
- * is chosen.
+ * Use the transpose of the relaxation method instead of the method itself.
+ * This has no effect if #symmetric smoothing is chosen.
*/
bool transpose;
/**
- * Output debugging information
- * to @p deallog if this is
- * nonzero.
+ * Output debugging information to @p deallog if this is nonzero.
*/
unsigned int debug;
/**
- * Smoother doing nothing. This class is not useful for many applications other
- * than for testing some multigrid procedures. Also some applications might
- * get convergence without smoothing and then this class brings you the
+ * Smoother doing nothing. This class is not useful for many applications
+ * other than for testing some multigrid procedures. Also some applications
+ * might get convergence without smoothing and then this class brings you the
* cheapest possible multigrid.
*
* @author Guido Kanschat, 1999, 2002
{
public:
/**
- * Implementation of the
- * interface for @p Multigrid.
- * This function does nothing,
- * which by comparison with the
- * definition of this function
- * means that the the smoothing
- * operator equals the null
- * operator.
+ * Implementation of the interface for @p Multigrid. This function does
+ * nothing, which by comparison with the definition of this function means
+ * that the the smoothing operator equals the null operator.
*/
virtual void smooth (const unsigned int level,
VECTOR &u,
* performing one step of the smoothing scheme.
*
* This class performs smoothing on each level. The operation can be
- * controlled by several parameters. First, the relaxation parameter
- * @p omega is used in the underlying relaxation method. @p steps is
- * the number of relaxation steps on the finest level (on all levels
- * if @p variable is off). If @p variable is @p true, the number of
- * smoothing steps is doubled on each coarser level. This results in a
- * method having the complexity of the W-cycle, but saving grid
- * transfers. This is the method proposed by Bramble at al.
+ * controlled by several parameters. First, the relaxation parameter @p
+ * omega is used in the underlying relaxation method. @p steps is the number
+ * of relaxation steps on the finest level (on all levels if @p variable is
+ * off). If @p variable is @p true, the number of smoothing steps is doubled
+ * on each coarser level. This results in a method having the complexity of
+ * the W-cycle, but saving grid transfers. This is the method proposed by
+ * Bramble at al.
*
- * The option @p symmetric switches on alternating between the
- * smoother and its transpose in each step as proposed by Bramble.
+ * The option @p symmetric switches on alternating between the smoother and
+ * its transpose in each step as proposed by Bramble.
*
- * @p transpose uses the transposed smoothing operation using
- * <tt>Tstep</tt> instead of the regular <tt>step</tt> of the
- * relaxation scheme.
+ * @p transpose uses the transposed smoothing operation using <tt>Tstep</tt>
+ * instead of the regular <tt>step</tt> of the relaxation scheme.
*
- * If you are using block matrices, the second @p initialize function
- * offers the possibility to extract a single block for smoothing. In
- * this case, the multigrid method must be used only with the vector
- * associated to that single block.
+ * If you are using block matrices, the second @p initialize function offers
+ * the possibility to extract a single block for smoothing. In this case,
+ * the multigrid method must be used only with the vector associated to that
+ * single block.
*
* @author Guido Kanschat,
* @date 2003, 2009, 2010
{
public:
/**
- * Constructor. Sets memory and
- * smoothing parameters.
+ * Constructor. Sets memory and smoothing parameters.
*/
SmootherRelaxation(const unsigned int steps = 1,
const bool variable = false,
const bool transpose = false);
/**
- * Initialize for matrices. This
- * function initializes the
- * smoothing operator with the
- * same smoother for each level.
+ * Initialize for matrices. This function initializes the smoothing
+ * operator with the same smoother for each level.
*
- * @p additional_data is an
- * object of type
- * @p RELAX::AdditionalData and
- * is handed to the
- * initialization function of the
- * relaxation method.
+ * @p additional_data is an object of type @p RELAX::AdditionalData and is
+ * handed to the initialization function of the relaxation method.
*/
template <class MATRIX2>
void initialize (const MGLevelObject<MATRIX2> &matrices,
const typename RELAX::AdditionalData &additional_data = typename RELAX::AdditionalData());
/**
- * Initialize matrices and
- * additional data for each
- * level.
+ * Initialize matrices and additional data for each level.
*
- * If minimal or maximal level of
- * the two objects differ, the
- * greatest common range is
- * utilized. This way, smoothing
- * can be restricted to certain
- * levels even if the matrix was
- * generated for all levels.
+ * If minimal or maximal level of the two objects differ, the greatest
+ * common range is utilized. This way, smoothing can be restricted to
+ * certain levels even if the matrix was generated for all levels.
*/
template <class MATRIX2, class DATA>
void initialize (const MGLevelObject<MATRIX2> &matrices,
const MGLevelObject<DATA> &additional_data);
/**
- * Initialize for matrix
- * blocks. This function
- * initializes the smoothing
- * operator with the same
- * smoother for each level.
+ * Initialize for matrix blocks. This function initializes the smoothing
+ * operator with the same smoother for each level.
*
- * @p additional_data is an
- * object of type
- * @p RELAX::AdditionalData and
- * is handed to the
- * initialization function of the
- * relaxation method.
+ * @p additional_data is an object of type @p RELAX::AdditionalData and is
+ * handed to the initialization function of the relaxation method.
*/
// template <class MATRIX2>
// void initialize (const MGLevelObject<MatrixBlock<MATRIX2> >& matrices,
* performing one step of the smoothing scheme.
*
* This class performs smoothing on each level. The operation can be
- * controlled by several parameters. First, the relaxation parameter
- * @p omega is used in the underlying relaxation method. @p steps is
- * the number of relaxation steps on the finest level (on all levels
- * if @p variable is off). If @p variable is @p true, the number of
- * smoothing steps is doubled on each coarser level. This results in a
- * method having the complexity of the W-cycle, but saving grid
- * transfers. This is the method proposed by Bramble at al.
+ * controlled by several parameters. First, the relaxation parameter @p omega
+ * is used in the underlying relaxation method. @p steps is the number of
+ * relaxation steps on the finest level (on all levels if @p variable is off).
+ * If @p variable is @p true, the number of smoothing steps is doubled on each
+ * coarser level. This results in a method having the complexity of the
+ * W-cycle, but saving grid transfers. This is the method proposed by Bramble
+ * at al.
*
- * The option @p symmetric switches on alternating between the
- * smoother and its transpose in each step as proposed by Bramble.
+ * The option @p symmetric switches on alternating between the smoother and
+ * its transpose in each step as proposed by Bramble.
*
- * @p transpose uses the transposed smoothing operation using
- * <tt>Tstep</tt> instead of the regular <tt>step</tt> of the
- * relaxation scheme.
+ * @p transpose uses the transposed smoothing operation using <tt>Tstep</tt>
+ * instead of the regular <tt>step</tt> of the relaxation scheme.
*
- * If you are using block matrices, the second @p initialize function
- * offers the possibility to extract a single block for smoothing. In
- * this case, the multigrid method must be used only with the vector
- * associated to that single block.
+ * If you are using block matrices, the second @p initialize function offers
+ * the possibility to extract a single block for smoothing. In this case, the
+ * multigrid method must be used only with the vector associated to that
+ * single block.
*
* The library contains instantiation for <tt>SparseMatrix<.></tt> and
- * <tt>Vector<.></tt>, where the template arguments are all combinations of
- * @p float and @p double. Additional instantiations may be created
- * by including the file mg_smoother.templates.h.
+ * <tt>Vector<.></tt>, where the template arguments are all combinations of @p
+ * float and @p double. Additional instantiations may be created by including
+ * the file mg_smoother.templates.h.
*
- * @note If '--enable-mgcompatibility' was used on configuring
- * deal.II, this class behaves like MGSmootherPrecondition.
+ * @note If '--enable-mgcompatibility' was used on configuring deal.II, this
+ * class behaves like MGSmootherPrecondition.
*
* @author Guido Kanschat, 2003
*/
const bool transpose = false);
/**
- * Constructor. Sets memory and
- * smoothing parameters.
+ * Constructor. Sets memory and smoothing parameters.
*
- * @deprecated Use the constructor without the vector memory
- * object
+ * @deprecated Use the constructor without the vector memory object
*/
MGSmootherRelaxation(VectorMemory<VECTOR> &mem,
const unsigned int steps = 1,
const bool transpose = false) DEAL_II_DEPRECATED;
/**
- * Initialize for matrices. This
- * function stores pointers to
- * the level matrices and
- * initializes the smoothing
- * operator with the same smoother
+ * Initialize for matrices. This function stores pointers to the level
+ * matrices and initializes the smoothing operator with the same smoother
* for each level.
*
- * @p additional_data is an
- * object of type
- * @p RELAX::AdditionalData and
- * is handed to the
- * initialization function of the
- * relaxation method.
+ * @p additional_data is an object of type @p RELAX::AdditionalData and is
+ * handed to the initialization function of the relaxation method.
*/
template <class MATRIX2>
void initialize (const MGLevelObject<MATRIX2> &matrices,
const typename RELAX::AdditionalData &additional_data = typename RELAX::AdditionalData());
/**
- * Initialize for matrices. This
- * function stores pointers to
- * the level matrices and
- * initializes the smoothing
- * operator with the according
+ * Initialize for matrices. This function stores pointers to the level
+ * matrices and initializes the smoothing operator with the according
* smoother for each level.
*
- * @p additional_data is an
- * object of type
- * @p RELAX::AdditionalData and
- * is handed to the
- * initialization function of the
- * relaxation method.
+ * @p additional_data is an object of type @p RELAX::AdditionalData and is
+ * handed to the initialization function of the relaxation method.
*/
template <class MATRIX2, class DATA>
void initialize (const MGLevelObject<MATRIX2> &matrices,
const MGLevelObject<DATA> &additional_data);
/**
- * Initialize for single blocks
- * of matrices. Of this block
- * matrix, the block indicated by
- * @p block_row and
- * @p block_col is selected on
- * each level. This function
- * stores pointers to the level
- * matrices and initializes the
- * smoothing operator with the
- * same smoother for each
- * level.
+ * Initialize for single blocks of matrices. Of this block matrix, the block
+ * indicated by @p block_row and @p block_col is selected on each level.
+ * This function stores pointers to the level matrices and initializes the
+ * smoothing operator with the same smoother for each level.
*
- * @p additional_data is an
- * object of type
- * @p RELAX::AdditionalData and
- * is handed to the
- * initialization function of the
- * relaxation method.
+ * @p additional_data is an object of type @p RELAX::AdditionalData and is
+ * handed to the initialization function of the relaxation method.
*/
template <class MATRIX2, class DATA>
void initialize (const MGLevelObject<MATRIX2> &matrices,
const unsigned int block_col);
/**
- * Initialize for single blocks
- * of matrices. Of this block
- * matrix, the block indicated by
- * @p block_row and
- * @p block_col is selected on
- * each level. This function
- * stores pointers to the level
- * matrices and initializes the
- * smoothing operator with the
- * according smoother for each
- * level.
+ * Initialize for single blocks of matrices. Of this block matrix, the block
+ * indicated by @p block_row and @p block_col is selected on each level.
+ * This function stores pointers to the level matrices and initializes the
+ * smoothing operator with the according smoother for each level.
*
- * @p additional_data is an
- * object of type
- * @p RELAX::AdditionalData and
- * is handed to the
- * initialization function of the
- * relaxation method.
+ * @p additional_data is an object of type @p RELAX::AdditionalData and is
+ * handed to the initialization function of the relaxation method.
*/
template <class MATRIX2, class DATA>
void initialize (const MGLevelObject<MATRIX2> &matrices,
const VECTOR &rhs) const;
/**
- * Object containing relaxation
- * methods.
+ * Object containing relaxation methods.
*/
MGLevelObject<RELAX> smoothers;
* Smoother using preconditioner classes.
*
* This class performs smoothing on each level. The operation can be
- * controlled by several parameters. First, the relaxation parameter
- * @p omega is used in the underlying relaxation method. @p steps is
- * the number of relaxation steps on the finest level (on all levels
- * if @p variable is off). If @p variable is @p true, the number of
- * smoothing steps is doubled on each coarser level. This results in a
- * method having the complexity of the W-cycle, but saving grid
- * transfers. This is the method proposed by Bramble at al.
+ * controlled by several parameters. First, the relaxation parameter @p omega
+ * is used in the underlying relaxation method. @p steps is the number of
+ * relaxation steps on the finest level (on all levels if @p variable is off).
+ * If @p variable is @p true, the number of smoothing steps is doubled on each
+ * coarser level. This results in a method having the complexity of the
+ * W-cycle, but saving grid transfers. This is the method proposed by Bramble
+ * at al.
*
- * The option @p symmetric switches on alternating between the
- * smoother and its transpose in each step as proposed by Bramble.
+ * The option @p symmetric switches on alternating between the smoother and
+ * its transpose in each step as proposed by Bramble.
*
- * @p transpose uses the transposed smoothing operation using
- * <tt>Tvmult</tt> instead of the regular <tt>vmult</tt> of the
- * relaxation scheme.
+ * @p transpose uses the transposed smoothing operation using <tt>Tvmult</tt>
+ * instead of the regular <tt>vmult</tt> of the relaxation scheme.
*
- * If you are using block matrices, the second @p initialize function
- * offers the possibility to extract a single block for smoothing. In
- * this case, the multigrid method must be used only with the vector
- * associated to that single block.
+ * If you are using block matrices, the second @p initialize function offers
+ * the possibility to extract a single block for smoothing. In this case, the
+ * multigrid method must be used only with the vector associated to that
+ * single block.
*
* The library contains instantiation for <tt>SparseMatrix<.></tt> and
- * <tt>Vector<.></tt>, where the template arguments are all combinations of
- * @p float and @p double. Additional instantiations may be created
- * by including the file mg_smoother.templates.h.
+ * <tt>Vector<.></tt>, where the template arguments are all combinations of @p
+ * float and @p double. Additional instantiations may be created by including
+ * the file mg_smoother.templates.h.
*
* @author Guido Kanschat, 2009
*/
const bool transpose = false);
/**
- * Constructor. Sets memory and
- * smoothing parameters.
+ * Constructor. Sets memory and smoothing parameters.
*
- * @deprecated Use the constructor without the vector memory
- * object
+ * @deprecated Use the constructor without the vector memory object
*/
MGSmootherPrecondition(VectorMemory<VECTOR> &mem,
const unsigned int steps = 1,
const bool transpose = false) DEAL_II_DEPRECATED;
/**
- * Initialize for matrices. This
- * function stores pointers to
- * the level matrices and
- * initializes the smoothing
- * operator with the same smoother
+ * Initialize for matrices. This function stores pointers to the level
+ * matrices and initializes the smoothing operator with the same smoother
* for each level.
*
- * @p additional_data is an
- * object of type
- * @p PRECONDITIONER::AdditionalData and
- * is handed to the
- * initialization function of the
- * relaxation method.
+ * @p additional_data is an object of type @p PRECONDITIONER::AdditionalData
+ * and is handed to the initialization function of the relaxation method.
*/
template <class MATRIX2>
void initialize (const MGLevelObject<MATRIX2> &matrices,
const typename PRECONDITIONER::AdditionalData &additional_data = typename PRECONDITIONER::AdditionalData());
/**
- * Initialize for matrices. This
- * function stores pointers to
- * the level matrices and
- * initializes the smoothing
- * operator with the according
+ * Initialize for matrices. This function stores pointers to the level
+ * matrices and initializes the smoothing operator with the according
* smoother for each level.
*
- * @p additional_data is an
- * object of type
- * @p PRECONDITIONER::AdditionalData and
- * is handed to the
- * initialization function of the
- * relaxation method.
+ * @p additional_data is an object of type @p PRECONDITIONER::AdditionalData
+ * and is handed to the initialization function of the relaxation method.
*/
template <class MATRIX2, class DATA>
void initialize (const MGLevelObject<MATRIX2> &matrices,
const MGLevelObject<DATA> &additional_data);
/**
- * Initialize for single blocks
- * of matrices. Of this block
- * matrix, the block indicated by
- * @p block_row and
- * @p block_col is selected on
- * each level. This function
- * stores pointers to the level
- * matrices and initializes the
- * smoothing operator with the
- * same smoother for each
- * level.
+ * Initialize for single blocks of matrices. Of this block matrix, the block
+ * indicated by @p block_row and @p block_col is selected on each level.
+ * This function stores pointers to the level matrices and initializes the
+ * smoothing operator with the same smoother for each level.
*
- * @p additional_data is an
- * object of type
- * @p PRECONDITIONER::AdditionalData and
- * is handed to the
- * initialization function of the
- * relaxation method.
+ * @p additional_data is an object of type @p PRECONDITIONER::AdditionalData
+ * and is handed to the initialization function of the relaxation method.
*/
template <class MATRIX2, class DATA>
void initialize (const MGLevelObject<MATRIX2> &matrices,
const unsigned int block_col);
/**
- * Initialize for single blocks
- * of matrices. Of this block
- * matrix, the block indicated by
- * @p block_row and
- * @p block_col is selected on
- * each level. This function
- * stores pointers to the level
- * matrices and initializes the
- * smoothing operator with the
- * according smoother for each
- * level.
+ * Initialize for single blocks of matrices. Of this block matrix, the block
+ * indicated by @p block_row and @p block_col is selected on each level.
+ * This function stores pointers to the level matrices and initializes the
+ * smoothing operator with the according smoother for each level.
*
- * @p additional_data is an
- * object of type
- * @p PRECONDITIONER::AdditionalData and
- * is handed to the
- * initialization function of the
- * relaxation method.
+ * @p additional_data is an object of type @p PRECONDITIONER::AdditionalData
+ * and is handed to the initialization function of the relaxation method.
*/
template <class MATRIX2, class DATA>
void initialize (const MGLevelObject<MATRIX2> &matrices,
const VECTOR &rhs) const;
/**
- * Object containing relaxation
- * methods.
+ * Object containing relaxation methods.
*/
MGLevelObject<PRECONDITIONER> smoothers;
/* @{ */
/**
- * This is a collection of functions operating on, and manipulating
- * the numbers of degrees of freedom in a multilevel triangulation. It
- * is similar in purpose and function to the @p DoFTools class, but
- * operates on levels of DoFHandler
- * objects. See there and the documentation of the member functions
+ * This is a collection of functions operating on, and manipulating the
+ * numbers of degrees of freedom in a multilevel triangulation. It is similar
+ * in purpose and function to the @p DoFTools class, but operates on levels of
+ * DoFHandler objects. See there and the documentation of the member functions
* for more information.
*
* @author Wolfgang Bangerth, Guido Kanschat, 1999 - 2005, 2012
namespace MGTools
{
/**
- * Compute row length vector for
- * multilevel methods.
+ * Compute row length vector for multilevel methods.
*/
template <int dim, int spacedim>
void
const DoFTools::Coupling flux_couplings = DoFTools::none);
/**
- * Compute row length vector for
- * multilevel methods with
- * optimization for block
- * couplings.
+ * Compute row length vector for multilevel methods with optimization for
+ * block couplings.
*/
template <int dim, int spacedim>
void
const Table<2,DoFTools::Coupling> &flux_couplings);
/**
- * Write the sparsity structure
- * of the matrix belonging to the
- * specified @p level. The sparsity pattern
- * is not compressed, so before
- * creating the actual matrix
- * you have to compress the
- * matrix yourself, using
+ * Write the sparsity structure of the matrix belonging to the specified @p
+ * level. The sparsity pattern is not compressed, so before creating the
+ * actual matrix you have to compress the matrix yourself, using
* <tt>SparseMatrixStruct::compress()</tt>.
*
- * There is no need to consider
- * hanging nodes here, since only
- * one level is considered.
+ * There is no need to consider hanging nodes here, since only one level is
+ * considered.
*/
template <class DH, class SparsityPattern>
void
const unsigned int level);
/**
- * Make a sparsity pattern including fluxes
- * of discontinuous Galerkin methods.
- * @ref make_sparsity_pattern
- * @ref DoFTools
+ * Make a sparsity pattern including fluxes of discontinuous Galerkin
+ * methods. @ref make_sparsity_pattern @ref DoFTools
*/
template <int dim, class SparsityPattern, int spacedim>
void
const unsigned int level);
/**
- * Create sparsity pattern for
- * the fluxes at refinement
- * edges. The matrix maps a
- * function of the fine level
- * space @p level to the coarser
- * space.
+ * Create sparsity pattern for the fluxes at refinement edges. The matrix
+ * maps a function of the fine level space @p level to the coarser space.
*
* make_flux_sparsity_pattern()
*/
SparsityPattern &sparsity,
const unsigned int level);
/**
- * This function does the same as
- * the other with the same name,
- * but it gets two additional
- * coefficient matrices. A matrix
- * entry will only be generated
- * for two basis functions, if
- * there is a non-zero entry
- * linking their associated
- * components in the coefficient
- * matrix.
+ * This function does the same as the other with the same name, but it gets
+ * two additional coefficient matrices. A matrix entry will only be
+ * generated for two basis functions, if there is a non-zero entry linking
+ * their associated components in the coefficient matrix.
*
- * There is one matrix for
- * couplings in a cell and one
- * for the couplings occurring in
- * fluxes.
+ * There is one matrix for couplings in a cell and one for the couplings
+ * occurring in fluxes.
*/
template <int dim, class SparsityPattern, int spacedim>
void
const Table<2,DoFTools::Coupling> &flux_mask);
/**
- * Create sparsity pattern for
- * the fluxes at refinement
- * edges. The matrix maps a
- * function of the fine level
- * space @p level to the coarser
- * space. This is the version
- * restricting the pattern to the
- * elements actually needed.
+ * Create sparsity pattern for the fluxes at refinement edges. The matrix
+ * maps a function of the fine level space @p level to the coarser space.
+ * This is the version restricting the pattern to the elements actually
+ * needed.
*
* make_flux_sparsity_pattern()
*/
const Table<2,DoFTools::Coupling> &flux_mask);
/**
- * Count the dofs block-wise
- * on each level.
+ * Count the dofs block-wise on each level.
*
- * Result is a vector containing
- * for each level a vector
- * containing the number of dofs
- * for each block (access is
- * <tt>result[level][block]</tt>).
+ * Result is a vector containing for each level a vector containing the
+ * number of dofs for each block (access is <tt>result[level][block]</tt>).
*/
template <class DH>
void
std::vector<unsigned int> target_block = std::vector<unsigned int>());
/**
- * Count the dofs component-wise
- * on each level.
+ * Count the dofs component-wise on each level.
*
- * Result is a vector containing
- * for each level a vector
- * containing the number of dofs
- * for each component (access is
+ * Result is a vector containing for each level a vector containing the
+ * number of dofs for each component (access is
* <tt>result[level][component]</tt>).
*/
template <int dim, int spacedim>
std::vector<unsigned int> target_component = std::vector<unsigned int>());
/**
- * @deprecated Wrapper for the
- * other function with same name,
- * introduced for compatibility.
+ * @deprecated Wrapper for the other function with same name, introduced for
+ * compatibility.
*/
template <int dim, int spacedim>
void
const ComponentMask &component_mask = ComponentMask());
/**
- * The same function as above, but return
- * an IndexSet rather than a
+ * The same function as above, but return an IndexSet rather than a
* std::set<unsigned int> on each level.
*/
template <int dim, int spacedim>
const bool preserve_symmetry) DEAL_II_DEPRECATED;
/**
- * For each level in a multigrid hierarchy, produce an IndexSet
- * that indicates which of the degrees of freedom are along
- * interfaces of this level to cells that only exist on coarser
- * levels.
+ * For each level in a multigrid hierarchy, produce an IndexSet that
+ * indicates which of the degrees of freedom are along interfaces of this
+ * level to cells that only exist on coarser levels.
*/
template <int dim, int spacedim>
void
std::vector<IndexSet> &interface_dofs);
/**
- * As above but with a deprecated data structure. This makes one additional copy.
+ * As above but with a deprecated data structure. This makes one additional
+ * copy.
*/
template <int dim, int spacedim>
void
* Implementation of the MGTransferBase interface for which the transfer
* operations are prebuilt upon construction of the object of this class as
* matrices. This is the fast way, since it only needs to build the operation
- * once by looping over all cells and storing the result in a matrix for
- * each level, but requires additional memory.
+ * once by looping over all cells and storing the result in a matrix for each
+ * level, but requires additional memory.
*
- * See MGTransferBase to find out which of the transfer classes
- * is best for your needs.
+ * See MGTransferBase to find out which of the transfer classes is best for
+ * your needs.
*
* @author Wolfgang Bangerth, Guido Kanschat
* @date 1999, 2000, 2001, 2002, 2003, 2004, 2012
{
public:
/**
- * Constructor without constraint
- * matrices. Use this constructor
- * only with discontinuous finite
- * elements or with no local
- * refinement.
+ * Constructor without constraint matrices. Use this constructor only with
+ * discontinuous finite elements or with no local refinement.
*/
MGTransferPrebuilt ();
/**
- * Constructor with constraints. Equivalent to the default
- * constructor followed by initialize_constraints().
+ * Constructor with constraints. Equivalent to the default constructor
+ * followed by initialize_constraints().
*/
MGTransferPrebuilt (const ConstraintMatrix &constraints,
const MGConstrainedDoFs &mg_constrained_dofs);
void clear ();
/**
- * Actually build the prolongation
- * matrices for each level.
+ * Actually build the prolongation matrices for each level.
*/
template <int dim, int spacedim>
void build_matrices (const DoFHandler<dim,spacedim> &mg_dof);
const VECTOR &src) const;
/**
- * Transfer from a vector on the
- * global grid to vectors defined
- * on each of the levels
- * separately, i.a. an @p MGVector.
+ * Transfer from a vector on the global grid to vectors defined on each of
+ * the levels separately, i.a. an @p MGVector.
*/
template <int dim, class InVector, int spacedim>
void
const InVector &src) const;
/**
- * Transfer from multi-level vector to
- * normal vector.
+ * Transfer from multi-level vector to normal vector.
*
- * Copies data from active
- * portions of an MGVector into
- * the respective positions of a
- * <tt>Vector<number></tt>. In order to
- * keep the result consistent,
- * constrained degrees of freedom
- * are set to zero.
+ * Copies data from active portions of an MGVector into the respective
+ * positions of a <tt>Vector<number></tt>. In order to keep the result
+ * consistent, constrained degrees of freedom are set to zero.
*/
template <int dim, class OutVector, int spacedim>
void
const MGLevelObject<VECTOR> &src) const;
/**
- * Add a multi-level vector to a
- * normal vector.
+ * Add a multi-level vector to a normal vector.
*
- * Works as the previous
- * function, but probably not for
- * continuous elements.
+ * Works as the previous function, but probably not for continuous elements.
*/
template <int dim, class OutVector, int spacedim>
void
const MGLevelObject<VECTOR> &src) const;
/**
- * If this object operates on
- * BlockVector objects, we need
- * to describe how the individual
- * vector components are mapped
- * to the blocks of a vector. For
- * example, for a Stokes system,
- * we have dim+1 vector
- * components for velocity and
- * pressure, but we may want to
- * use block vectors with only
- * two blocks for all velocities
- * in one block, and the pressure
- * variables in the other.
+ * If this object operates on BlockVector objects, we need to describe how
+ * the individual vector components are mapped to the blocks of a vector.
+ * For example, for a Stokes system, we have dim+1 vector components for
+ * velocity and pressure, but we may want to use block vectors with only two
+ * blocks for all velocities in one block, and the pressure variables in the
+ * other.
*
- * By default, if this function
- * is not called, block vectors
- * have as many blocks as the
- * finite element has vector
- * components. However, this can
- * be changed by calling this
- * function with an array that
- * describes how vector
- * components are to be grouped
- * into blocks. The meaning of
- * the argument is the same as
- * the one given to the
- * DoFTools::count_dofs_per_component
+ * By default, if this function is not called, block vectors have as many
+ * blocks as the finite element has vector components. However, this can be
+ * changed by calling this function with an array that describes how vector
+ * components are to be grouped into blocks. The meaning of the argument is
+ * the same as the one given to the DoFTools::count_dofs_per_component
* function.
*/
void
std::vector<std_cxx11::shared_ptr<typename internal::MatrixSelector<VECTOR>::Sparsity> > prolongation_sparsities;
/**
- * The actual prolongation matrix. column indices belong to the dof
- * indices of the mother cell, i.e. the coarse level. while row
- * indices belong to the child cell, i.e. the fine level.
+ * The actual prolongation matrix. column indices belong to the dof indices
+ * of the mother cell, i.e. the coarse level. while row indices belong to
+ * the child cell, i.e. the fine level.
*/
std::vector<std_cxx11::shared_ptr<typename internal::MatrixSelector<VECTOR>::Matrix> > prolongation_matrices;
* Mapping for the copy_to_mg() and copy_from_mg() functions. Here only
* index pairs locally owned
*
- * The data is organized as follows: one vector per level. Each
- * element of these vectors contains first the global index, then
- * the level index.
+ * The data is organized as follows: one vector per level. Each element of
+ * these vectors contains first the global index, then the level index.
*/
std::vector<std::vector<std::pair<types::global_dof_index, unsigned int> > >
copy_indices;
/**
- * Additional degrees of freedom for the copy_to_mg()
- * function. These are the ones where the global degree of freedom
- * is locally owned and the level degree of freedom is not.
+ * Additional degrees of freedom for the copy_to_mg() function. These are
+ * the ones where the global degree of freedom is locally owned and the
+ * level degree of freedom is not.
*
* Organization of the data is like for #copy_indices_mine.
*/
copy_indices_to_me;
/**
- * Additional degrees of freedom for the copy_from_mg()
- * function. These are the ones where the level degree of freedom
- * is locally owned and the global degree of freedom is not.
+ * Additional degrees of freedom for the copy_from_mg() function. These are
+ * the ones where the level degree of freedom is locally owned and the
+ * global degree of freedom is not.
*
* Organization of the data is like for #copy_indices_mine.
*/
/**
- * The vector that stores what
- * has been given to the
- * set_component_to_block_map()
- * function.
+ * The vector that stores what has been given to the
+ * set_component_to_block_map() function.
*/
std::vector<unsigned int> component_to_block_map;
/**
- * Degrees of freedom on the
- * refinement edge excluding
- * those on the boundary.
+ * Degrees of freedom on the refinement edge excluding those on the
+ * boundary.
*/
std::vector<std::vector<bool> > interface_dofs;
/**
- * The constraints of the global
- * system.
+ * The constraints of the global system.
*/
SmartPointer<const ConstraintMatrix, MGTransferPrebuilt<VECTOR> > constraints;
/**
- * The mg_constrained_dofs of the level
- * systems.
+ * The mg_constrained_dofs of the level systems.
*/
SmartPointer<const MGConstrainedDoFs, MGTransferPrebuilt<VECTOR> > mg_constrained_dofs;
namespace
{
/**
- * Adjust vectors on all levels to
- * correct size. Here, we just
- * count the numbers of degrees
- * of freedom on each level and
- * @p reinit each level vector
- * to this length.
- * For compatibility reasons with
- * the next function
- * the target_component is added
- * here but is not used.
+ * Adjust vectors on all levels to correct size. Here, we just count the
+ * numbers of degrees of freedom on each level and @p reinit each level
+ * vector to this length. For compatibility reasons with the next function
+ * the target_component is added here but is not used.
*/
template <int dim, typename number, int spacedim>
void
}
/**
- * Adjust vectors on all levels to
- * correct size. Here, we just
- * count the numbers of degrees
- * of freedom on each level and
- * @p reinit each level vector
- * to this length. The target_component
- * is handed to MGTools::count_dofs_per_block.
- * See for documentation there.
+ * Adjust vectors on all levels to correct size. Here, we just count the
+ * numbers of degrees of freedom on each level and @p reinit each level
+ * vector to this length. The target_component is handed to
+ * MGTools::count_dofs_per_block. See for documentation there.
*/
template <int dim, typename number, int spacedim>
void
#ifdef DEAL_II_WITH_TRILINOS
/**
- * Adjust vectors on all levels to
- * correct size. Here, we just
- * count the numbers of degrees
- * of freedom on each level and
- * @p reinit each level vector
- * to this length.
+ * Adjust vectors on all levels to correct size. Here, we just count the
+ * numbers of degrees of freedom on each level and @p reinit each level
+ * vector to this length.
*/
template <int dim, int spacedim>
void
/**
* Implementation of matrix generation for MGTransferBlock.
*
- * This is the base class for MGTransfer objects for systems of
- * equations where multigrid is applied only to one ore some blocks,
- * where a @ref GlossBlock comprises all degrees of freedom generated
- * by one base element.
+ * This is the base class for MGTransfer objects for systems of equations
+ * where multigrid is applied only to one ore some blocks, where a @ref
+ * GlossBlock comprises all degrees of freedom generated by one base element.
*
* @author Guido Kanschat, 2001-2003
*/
{
public:
/**
- * Constructor without constraint
- * matrices. Use this constructor
- * only with discontinuous finite
- * elements or with no local
- * refinement.
+ * Constructor without constraint matrices. Use this constructor only with
+ * discontinuous finite elements or with no local refinement.
*/
MGTransferBlockBase ();
/**
protected:
/**
- * Actually build the prolongation
- * matrices for each level.
+ * Actually build the prolongation matrices for each level.
*
- * This function is only called
- * by derived classes. These can
- * also set the member variables
- * #selected and others to
- * restrict the transfer matrices
+ * This function is only called by derived classes. These can also set the
+ * member variables #selected and others to restrict the transfer matrices
* to certain blocks.
*/
template <int dim, int spacedim>
/**
* Flag of selected blocks.
*
- * The transfer operators only act
- * on the blocks having a
- * <tt>true</tt> entry here.
+ * The transfer operators only act on the blocks having a <tt>true</tt>
+ * entry here.
*/
//TODO: rename this to block_mask, in the same way as has already been done in MGTransferComponent, and give it type BlockMask
std::vector<bool> selected;
/**
- * Number of blocks of multigrid
- * vector.
+ * Number of blocks of multigrid vector.
*/
unsigned int n_mg_blocks;
/**
- * For each block of the whole
- * block vector, list to what
- * block of the multigrid vector
- * it is mapped. Since depending
- * on #selected, there may be
- * fewer mutlilevel blocks than
- * original blocks, some of the
- * entries may be illegal
- * unsigned integers.
+ * For each block of the whole block vector, list to what block of the
+ * multigrid vector it is mapped. Since depending on #selected, there may be
+ * fewer mutlilevel blocks than original blocks, some of the entries may be
+ * illegal unsigned integers.
*/
//TODO: rename this to mg_block_mask, in the same way as has already been done in MGTransferComponent, and give it type BlockMask
std::vector<unsigned int> mg_block;
std::vector<types::global_dof_index> block_start;
/**
- * Start index of each block on
- * all levels.
+ * Start index of each block on all levels.
*/
std::vector<std::vector<types::global_dof_index> > mg_block_start;
/**
- * Call build_matrices()
- * function first.
+ * Call build_matrices() function first.
*/
DeclException0(ExcMatricesNotBuilt);
protected:
/**
- * The actual prolongation matrix.
- * column indices belong to the
- * dof indices of the mother cell,
- * i.e. the coarse level.
- * while row indices belong to the
- * child cell, i.e. the fine level.
+ * The actual prolongation matrix. column indices belong to the dof indices
+ * of the mother cell, i.e. the coarse level. while row indices belong to
+ * the child cell, i.e. the fine level.
*/
std::vector<std_cxx11::shared_ptr<BlockSparseMatrix<double> > > prolongation_matrices;
/**
- * Mapping for the
- * <tt>copy_to/from_mg</tt>-functions.
- * The indices into this vector
- * are (in this order): global
- * block number, level
- * number. The data is first the
- * global index inside the block,
- * then the level index inside
+ * Mapping for the <tt>copy_to/from_mg</tt>-functions. The indices into this
+ * vector are (in this order): global block number, level number. The data
+ * is first the global index inside the block, then the level index inside
* the block.
- */
+ */
std::vector<std::vector<std::vector<std::pair<unsigned int, unsigned int> > > >
copy_indices;
/**
- * The constraints of the global
- * system.
+ * The constraints of the global system.
*/
SmartPointer<const ConstraintMatrix, MGTransferBlockBase> constraints;
/**
- * The mg_constrained_dofs of the level
- * systems.
+ * The mg_constrained_dofs of the level systems.
*/
SmartPointer<const MGConstrainedDoFs, MGTransferBlockBase> mg_constrained_dofs;
};
/**
- * Implementation of the MGTransferBase interface for block
- * matrices and block vectors.
+ * Implementation of the MGTransferBase interface for block matrices and block
+ * vectors.
*
* @warning This class is in an untested state. If you use it and you
* encounter problems, please contact Guido Kanschat.
*
- * In addition to the functionality of
- * MGTransferPrebuilt, the operation may be restricted to
- * certain blocks of the vector.
+ * In addition to the functionality of MGTransferPrebuilt, the operation may
+ * be restricted to certain blocks of the vector.
*
- * If the restricted mode is chosen, block vectors used in the
- * transfer routines may only have as many blocks as there are
- * @p trues in the selected-field.
+ * If the restricted mode is chosen, block vectors used in the transfer
+ * routines may only have as many blocks as there are @p trues in the
+ * selected-field.
*
- * See MGTransferBase to find out which of the transfer classes
- * is best for your needs.
+ * See MGTransferBase to find out which of the transfer classes is best for
+ * your needs.
*
* @author Guido Kanschat, 2001, 2002
*/
virtual ~MGTransferBlock ();
/**
- * Initialize additional #factors
- * and #memory if the restriction
- * of the blocks is to be
- * weighted differently.
+ * Initialize additional #factors and #memory if the restriction of the
+ * blocks is to be weighted differently.
*/
void initialize (const std::vector<number> &factors,
VectorMemory<Vector<number> > &memory);
/**
- * Build the prolongation
- * matrices for each level.
+ * Build the prolongation matrices for each level.
*
- * This function is a front-end
- * for the same function in
+ * This function is a front-end for the same function in
* MGTransferBlockBase.
*/
template<int dim, int spacedim>
const BlockVector<number> &src) const;
/**
- * Transfer from a vector on the
- * global grid to a multilevel
- * vector.
+ * Transfer from a vector on the global grid to a multilevel vector.
*
- * The action for discontinuous
- * elements is as follows: on an
- * active mesh cell, the global
- * vector entries are simply
- * copied to the corresponding
- * entries of the level
- * vector. Then, these values are
- * restricted down to the
- * coarsest level.
+ * The action for discontinuous elements is as follows: on an active mesh
+ * cell, the global vector entries are simply copied to the corresponding
+ * entries of the level vector. Then, these values are restricted down to
+ * the coarsest level.
*/
template <int dim, typename number2, int spacedim>
void
const BlockVector<number2> &src) const;
/**
- * Transfer from multi-level vector to
- * normal vector.
+ * Transfer from multi-level vector to normal vector.
*
- * Copies data from active
- * portions of a multilevel
- * vector into the respective
- * positions of a global vector.
+ * Copies data from active portions of a multilevel vector into the
+ * respective positions of a global vector.
*/
template <int dim, typename number2, int spacedim>
void
const MGLevelObject<BlockVector<number> > &src) const;
/**
- * Add a multi-level vector to a
- * normal vector.
+ * Add a multi-level vector to a normal vector.
*
- * Works as the previous
- * function, but probably not for
- * continuous elements.
+ * Works as the previous function, but probably not for continuous elements.
*/
template <int dim, typename number2, int spacedim>
void
private:
/**
- * Optional multiplication
- * factors for each
- * block. Requires
- * initialization of #memory.
+ * Optional multiplication factors for each block. Requires initialization
+ * of #memory.
*/
std::vector<number> factors;
/**
- * Memory pool required if
- * additional multiplication
- * using #factors is desired.
+ * Memory pool required if additional multiplication using #factors is
+ * desired.
*/
SmartPointer<VectorMemory<Vector<number> >,MGTransferBlock<number> > memory;
};
//TODO:[GK] Update documentation for copy_* functions
/**
- * Implementation of the MGTransferBase interface for block matrices
- * and simple vectors. This class uses MGTransferBlockBase selecting a
- * single block. The intergrid transfer operators are implemented for
- * Vector objects, The copy functions between regular and multigrid
- * vectors for Vector and BlockVector.
+ * Implementation of the MGTransferBase interface for block matrices and
+ * simple vectors. This class uses MGTransferBlockBase selecting a single
+ * block. The intergrid transfer operators are implemented for Vector objects,
+ * The copy functions between regular and multigrid vectors for Vector and
+ * BlockVector.
*
- * See MGTransferBase to find out which of the transfer classes
- * is best for your needs.
+ * See MGTransferBase to find out which of the transfer classes is best for
+ * your needs.
*
* @author Guido Kanschat, 2001, 2002, 2003
*/
{
public:
/**
- * Constructor without constraint
- * matrices. Use this constructor
- * only with discontinuous finite
- * elements or with no local
- * refinement.
+ * Constructor without constraint matrices. Use this constructor only with
+ * discontinuous finite elements or with no local refinement.
*/
MGTransferBlockSelect ();
/**
virtual ~MGTransferBlockSelect ();
/**
- * Actually build the prolongation
- * matrices for grouped blocks.
+ * Actually build the prolongation matrices for grouped blocks.
*
- * This function is a front-end
- * for the same function in
+ * This function is a front-end for the same function in
* MGTransferBlockBase.
*
- * @arg selected: Number of the
- * block of the global vector
- * to be copied from and to the
- * multilevel vector.
+ * @arg selected: Number of the block of the global vector to be copied from
+ * and to the multilevel vector.
*
- * @arg mg_selected: Number
- * of the component for which the
- * transfer matrices should be
- * built.
+ * @arg mg_selected: Number of the component for which the transfer matrices
+ * should be built.
*/
template<int dim, int spacedim>
void build_matrices (const DoFHandler<dim,spacedim> &dof,
unsigned int selected);
/**
- * Change selected
- * block. Handle with care!
+ * Change selected block. Handle with care!
*/
void select (const unsigned int block);
const Vector<number> &src) const;
/**
- * Transfer a single block from a
- * vector on the global grid to a
- * multilevel vector.
+ * Transfer a single block from a vector on the global grid to a multilevel
+ * vector.
*/
template <int dim, typename number2, int spacedim>
void
const Vector<number2> &src) const;
/**
- * Transfer from multilevel vector to
- * normal vector.
+ * Transfer from multilevel vector to normal vector.
*
- * Copies data from active
- * portions of an multilevel
- * vector into the respective
- * positions of a Vector.
+ * Copies data from active portions of an multilevel vector into the
+ * respective positions of a Vector.
*/
template <int dim, typename number2, int spacedim>
void
const MGLevelObject<Vector<number> > &src) const;
/**
- * Add a multi-level vector to a
- * normal vector.
+ * Add a multi-level vector to a normal vector.
*
- * Works as the previous
- * function, but probably not for
- * continuous elements.
+ * Works as the previous function, but probably not for continuous elements.
*/
template <int dim, typename number2, int spacedim>
void
const MGLevelObject<Vector<number> > &src) const;
/**
- * Transfer a block from a vector
- * on the global grid to
- * multilevel vectors. Only the
- * block selected is transfered.
+ * Transfer a block from a vector on the global grid to multilevel vectors.
+ * Only the block selected is transfered.
*/
template <int dim, typename number2, int spacedim>
void
const BlockVector<number2> &src) const;
/**
- * Transfer from multilevel vector to
- * normal vector.
+ * Transfer from multilevel vector to normal vector.
*
- * Copies data from active
- * portions of a multilevel
- * vector into the respective
- * positions of a global
- * BlockVector.
+ * Copies data from active portions of a multilevel vector into the
+ * respective positions of a global BlockVector.
*/
template <int dim, typename number2, int spacedim>
void
const MGLevelObject<Vector<number> > &src) const;
/**
- * Add a multi-level vector to a
- * normal vector.
+ * Add a multi-level vector to a normal vector.
*
- * Works as the previous
- * function, but probably not for
- * continuous elements.
+ * Works as the previous function, but probably not for continuous elements.
*/
template <int dim, typename number2, int spacedim>
void
private:
/**
- * Implementation of the public
- * function.
+ * Implementation of the public function.
*/
template <int dim, class OutVector, int spacedim>
void
const unsigned int offset) const;
/**
- * Implementation of the public
- * function.
+ * Implementation of the public function.
*/
template <int dim, class OutVector, int spacedim>
void
const unsigned int offset) const;
/**
- * Actual implementation of
- * copy_to_mg().
+ * Actual implementation of copy_to_mg().
*/
template <int dim, class InVector, int spacedim>
void
/**
* Implementation of matrix generation for component wise multigrid transfer.
*
- * @note MGTransferBlockBase is probably the more logical
- * class. Still eventually, a class should be developed allowing to
- * select multiple components.
+ * @note MGTransferBlockBase is probably the more logical class. Still
+ * eventually, a class should be developed allowing to select multiple
+ * components.
*
* @author Guido Kanschat, 2001-2003
*/
protected:
/**
- * Actually build the prolongation
- * matrices for each level.
+ * Actually build the prolongation matrices for each level.
*
- * This function is only called
- * by derived classes. These can
- * also set the member variables
- * <code>selected_component</code> and <code>mg_selected_component</code> member variables to
- * restrict the transfer matrices
- * to certain components.
- * Furthermore, they use
- * <code>target_component</code> and
- * <code>mg_target_component</code> for
- * re-ordering and grouping of
- * components.
+ * This function is only called by derived classes. These can also set the
+ * member variables <code>selected_component</code> and
+ * <code>mg_selected_component</code> member variables to restrict the
+ * transfer matrices to certain components. Furthermore, they use
+ * <code>target_component</code> and <code>mg_target_component</code> for
+ * re-ordering and grouping of components.
*/
template <int dim, int spacedim>
void build_matrices (const DoFHandler<dim,spacedim> &dof,
/**
* Flag of selected components.
*
- * The transfer operators only act
- * on the components having a
- * <tt>true</tt> entry here. If
- * renumbering by
- * #target_component is used,
- * this refers to the
- * <b>renumbered</b> components.
+ * The transfer operators only act on the components having a <tt>true</tt>
+ * entry here. If renumbering by #target_component is used, this refers to
+ * the <b>renumbered</b> components.
*/
ComponentMask component_mask;
/**
* Flag of selected components.
*
- * The transfer operators only act
- * on the components having a
- * <tt>true</tt> entry here. If
- * renumbering by
- * #mg_target_component is used,
- * this refers to the
- * <b>renumbered</b> components.
+ * The transfer operators only act on the components having a <tt>true</tt>
+ * entry here. If renumbering by #mg_target_component is used, this refers
+ * to the <b>renumbered</b> components.
*/
ComponentMask mg_component_mask;
/**
- * Target component of the
- * fine-level vector if
- * renumbering is required.
+ * Target component of the fine-level vector if renumbering is required.
*/
std::vector<unsigned int> target_component;
/**
- * Target component if
- * renumbering of level vectors
- * is required.
+ * Target component if renumbering of level vectors is required.
*/
std::vector<unsigned int> mg_target_component;
std::vector<types::global_dof_index> component_start;
/**
- * Start index of each component on
- * all levels.
+ * Start index of each component on all levels.
*/
std::vector<std::vector<types::global_dof_index> > mg_component_start;
/**
- * Call build_matrices()
- * function first.
+ * Call build_matrices() function first.
*/
DeclException0(ExcMatricesNotBuilt);
protected:
/**
- * The actual prolongation matrix.
- * column indices belong to the
- * dof indices of the mother cell,
- * i.e. the coarse level.
- * while row indices belong to the
- * child cell, i.e. the fine level.
+ * The actual prolongation matrix. column indices belong to the dof indices
+ * of the mother cell, i.e. the coarse level. while row indices belong to
+ * the child cell, i.e. the fine level.
*/
std::vector<std_cxx11::shared_ptr<BlockSparseMatrix<double> > > prolongation_matrices;
/**
- * Holds the mapping for the
- * <tt>copy_to/from_mg</tt>-functions.
- * The data is first the global
- * index, then the level index.
+ * Holds the mapping for the <tt>copy_to/from_mg</tt>-functions. The data is
+ * first the global index, then the level index.
*/
std::vector<std::vector<std::pair<types::global_dof_index, unsigned int> > >
copy_to_and_from_indices;
/**
- * Store the boundary_indices.
- * These are needed for the
- * boundary values in the
- * restriction matrix.
+ * Store the boundary_indices. These are needed for the boundary values in
+ * the restriction matrix.
*/
std::vector<std::set<types::global_dof_index> > boundary_indices;
};
//TODO: Use same kind of template argument as MGTransferSelect
/**
- * Implementation of the MGTransferBase interface for block
- * matrices and simple vectors. This class uses MGTransferComponentBase
- * selecting a single component or grouping several components into a
- * single block. The transfer operators themselves are implemented for
- * Vector and BlockVector objects.
+ * Implementation of the MGTransferBase interface for block matrices and
+ * simple vectors. This class uses MGTransferComponentBase selecting a single
+ * component or grouping several components into a single block. The transfer
+ * operators themselves are implemented for Vector and BlockVector objects.
*
- * See MGTransferBase to find out which of the transfer classes
- * is best for your needs.
+ * See MGTransferBase to find out which of the transfer classes is best for
+ * your needs.
*
* @author Guido Kanschat, 2001, 2002, 2003
*/
{
public:
/**
- * Constructor without constraint
- * matrices. Use this constructor
- * only with discontinuous finite
- * elements or with no local
- * refinement.
+ * Constructor without constraint matrices. Use this constructor only with
+ * discontinuous finite elements or with no local refinement.
*/
MGTransferSelect ();
//TODO: rewrite docs; make sure defaulted args are actually allowed
/**
- * Actually build the prolongation
- * matrices for grouped components.
+ * Actually build the prolongation matrices for grouped components.
*
- * This function is a front-end
- * for the same function in
+ * This function is a front-end for the same function in
* MGTransferComponentBase.
*
- * @arg selected: Number of the
- * block of the global vector
- * to be copied from and to the
- * multilevel vector. This number
- * refers to the renumbering by
+ * @arg selected: Number of the block of the global vector to be copied from
+ * and to the multilevel vector. This number refers to the renumbering by
* <tt>target_component</tt>.
*
- * @arg mg_selected: Number
- * of the block for which the
- * transfer matrices should be
- * built.
+ * @arg mg_selected: Number of the block for which the transfer matrices
+ * should be built.
*
- * If <tt>mg_target_component</tt> is
- * present, this refers to the
- * renumbered components.
+ * If <tt>mg_target_component</tt> is present, this refers to the renumbered
+ * components.
*
- * @arg target_component: this
- * argument allows grouping and
- * renumbering of components in
- * the fine-level vector (see
- * DoFRenumbering::component_wise).
+ * @arg target_component: this argument allows grouping and renumbering of
+ * components in the fine-level vector (see DoFRenumbering::component_wise).
*
- * @arg mg_target_component: this
- * argument allows grouping and
- * renumbering of components in
- * the level vectors (see
- * DoFRenumbering::component_wise). It
- * also affects the behavior of
- * the <tt>selected</tt> argument
+ * @arg mg_target_component: this argument allows grouping and renumbering
+ * of components in the level vectors (see DoFRenumbering::component_wise).
+ * It also affects the behavior of the <tt>selected</tt> argument
*
- * @arg boundary_indices: holds the
- * boundary indices on each level.
+ * @arg boundary_indices: holds the boundary indices on each level.
*/
template <int dim, int spacedim>
void build_matrices (const DoFHandler<dim,spacedim> &dof,
);
/**
- * Change selected
- * component. Handle with care!
+ * Change selected component. Handle with care!
*/
void select (const unsigned int component,
const unsigned int mg_component = numbers::invalid_unsigned_int);
const Vector<number> &src) const;
/**
- * Transfer from a vector on the
- * global grid to a multilevel vector.
+ * Transfer from a vector on the global grid to a multilevel vector.
*/
template <int dim, typename number2, int spacedim>
void
const Vector<number2> &src) const;
/**
- * Transfer from multilevel vector to
- * normal vector.
+ * Transfer from multilevel vector to normal vector.
*
- * Copies data from active
- * portions of an multilevel
- * vector into the respective
- * positions of a Vector.
+ * Copies data from active portions of an multilevel vector into the
+ * respective positions of a Vector.
*/
template <int dim, typename number2, int spacedim>
void
const MGLevelObject<Vector<number> > &src) const;
/**
- * Add a multi-level vector to a
- * normal vector.
+ * Add a multi-level vector to a normal vector.
*
- * Works as the previous
- * function, but probably not for
- * continuous elements.
+ * Works as the previous function, but probably not for continuous elements.
*/
template <int dim, typename number2, int spacedim>
void
const MGLevelObject<Vector<number> > &src) const;
/**
- * Transfer from a vector on the
- * global grid to multilevel vectors.
+ * Transfer from a vector on the global grid to multilevel vectors.
*/
template <int dim, typename number2, int spacedim>
void
const BlockVector<number2> &src) const;
/**
- * Transfer from multilevel vector to
- * normal vector.
+ * Transfer from multilevel vector to normal vector.
*
- * Copies data from active
- * portions of a multilevel
- * vector into the respective
- * positions of a global
- * BlockVector.
+ * Copies data from active portions of a multilevel vector into the
+ * respective positions of a global BlockVector.
*/
template <int dim, typename number2, int spacedim>
void
const MGLevelObject<Vector<number> > &src) const;
/**
- * Add a multi-level vector to a
- * normal vector.
+ * Add a multi-level vector to a normal vector.
*
- * Works as the previous
- * function, but probably not for
- * continuous elements.
+ * Works as the previous function, but probably not for continuous elements.
*/
template <int dim, typename number2, int spacedim>
void
private:
/**
- * Implementation of the public
- * function.
+ * Implementation of the public function.
*/
template <int dim, class OutVector, int spacedim>
void
const MGLevelObject<Vector<number> > &src) const;
/**
- * Implementation of the public
- * function.
+ * Implementation of the public function.
*/
template <int dim, class OutVector, int spacedim>
void
const MGLevelObject<Vector<number> > &src) const;
/**
- * Actual implementation of
- * copy_to_mg().
+ * Actual implementation of copy_to_mg().
*/
template <int dim, class InVector, int spacedim>
void
unsigned int mg_selected_component;
/**
- * The degrees of freedom on the
- * the refinement edges. For each
- * level (outer vector) and each
- * dof index (inner vector), this
- * bool is true if the level
- * degree of freedom is on the
- * refinement edge towards the
- * lower level excluding boundary dofs.
+ * The degrees of freedom on the the refinement edges. For each level (outer
+ * vector) and each dof index (inner vector), this bool is true if the level
+ * degree of freedom is on the refinement edge towards the lower level
+ * excluding boundary dofs.
*/
std::vector<std::vector<bool> > interface_dofs;
/**
- * The constraints of the global
- * system.
+ * The constraints of the global system.
*/
public:
SmartPointer<const ConstraintMatrix> constraints;
* Implementation of the multigrid method.
*
* @warning multigrid on locally refined meshes only works with
- * <b>discontinuous finite elements</b> right now. It is not clear,
- * whether the paradigm of local smoothing we use is applicable to
- * continuous elements with hanging nodes; in fact, most people you
- * meet on conferences seem to deny this.
+ * <b>discontinuous finite elements</b> right now. It is not clear, whether
+ * the paradigm of local smoothing we use is applicable to continuous elements
+ * with hanging nodes; in fact, most people you meet on conferences seem to
+ * deny this.
*
- * The function which starts a multigrid cycle on the finest level is
- * cycle(). Depending on the cycle type chosen with the constructor
- * (see enum Cycle), this function triggers one of the cycles
- * level_v_step() or level_step(), where the latter one can do
- * different types of cycles.
+ * The function which starts a multigrid cycle on the finest level is cycle().
+ * Depending on the cycle type chosen with the constructor (see enum Cycle),
+ * this function triggers one of the cycles level_v_step() or level_step(),
+ * where the latter one can do different types of cycles.
*
* Using this class, it is expected that the right hand side has been
- * converted from a vector living on the locally finest level to a
- * multilevel vector. This is a nontrivial operation, usually
- * initiated automatically by the class PreconditionMG and performed
- * by the classes derived from MGTransferBase.
+ * converted from a vector living on the locally finest level to a multilevel
+ * vector. This is a nontrivial operation, usually initiated automatically by
+ * the class PreconditionMG and performed by the classes derived from
+ * MGTransferBase.
*
- * @note The interface of this class is still very clumsy. In
- * particular, you will have to set up quite a few auxiliary objects
- * before you can use it. Unfortunately, it seems that this can be
- * avoided only be restricting the flexibility of this class in an
- * unacceptable way.
+ * @note The interface of this class is still very clumsy. In particular, you
+ * will have to set up quite a few auxiliary objects before you can use it.
+ * Unfortunately, it seems that this can be avoided only be restricting the
+ * flexibility of this class in an unacceptable way.
*
* @author Guido Kanschat, 1999 - 2005
*/
typedef const VECTOR const_vector_type;
/**
- * Constructor. The
- * DoFHandler is used to
- * determine the highest possible
- * level. <tt>transfer</tt> is an
- * object performing prolongation
- * and restriction.
+ * Constructor. The DoFHandler is used to determine the highest possible
+ * level. <tt>transfer</tt> is an object performing prolongation and
+ * restriction.
*
- * This function already
- * initializes the vectors which
- * will be used later in the
- * course of the
- * computations. You should
- * therefore create objects of
+ * This function already initializes the vectors which will be used later in
+ * the course of the computations. You should therefore create objects of
* this type as late as possible.
*/
template <int dim>
Cycle cycle = v_cycle);
/**
- * Experimental constructor for
- * cases in which no DoFHandler
- * is available.
+ * Experimental constructor for cases in which no DoFHandler is available.
*
* @warning Not intended for general use.
*/
Cycle cycle = v_cycle);
/**
- * Reinit this class according to
- * #minlevel and #maxlevel.
+ * Reinit this class according to #minlevel and #maxlevel.
*/
void reinit (const unsigned int minlevel,
const unsigned int maxlevel);
/**
- * Execute one multigrid
- * cycle. The type of cycle is
- * selected by the constructor
- * argument cycle. See the enum
- * Cycle for available types.
+ * Execute one multigrid cycle. The type of cycle is selected by the
+ * constructor argument cycle. See the enum Cycle for available types.
*/
void cycle ();
/**
- * Execute one step of the
- * V-cycle algorithm. This
- * function assumes, that the
- * multilevel vector #defect is
- * filled with the residual of an
- * outer defect correction
- * scheme. This is usually taken
- * care of by
- * PreconditionMG). After
- * vcycle(), the result is in the
- * multilevel vector
- * #solution. See
- * <tt>copy_*_mg</tt> in class
- * MGTools if you want to use
+ * Execute one step of the V-cycle algorithm. This function assumes, that
+ * the multilevel vector #defect is filled with the residual of an outer
+ * defect correction scheme. This is usually taken care of by
+ * PreconditionMG). After vcycle(), the result is in the multilevel vector
+ * #solution. See <tt>copy_*_mg</tt> in class MGTools if you want to use
* these vectors yourself.
*
- * The actual work for this
- * function is done in
- * level_v_step().
+ * The actual work for this function is done in level_v_step().
*/
void vcycle ();
/**
- * @deprecated This function is
- * purely experimental and will
- * probably never be implemented
- * in a way that it can be
- * released.
+ * @deprecated This function is purely experimental and will probably never
+ * be implemented in a way that it can be released.
*
- * Perform a multigrid cycle with
- * a vector which is already a
- * level vector. Use of this
- * function assumes that there is
- * NO local refinement and that
- * both vectors are on the finest
- * level of this Multigrid
- * object.
+ * Perform a multigrid cycle with a vector which is already a level vector.
+ * Use of this function assumes that there is NO local refinement and that
+ * both vectors are on the finest level of this Multigrid object.
*/
void vmult(VECTOR &dst, const VECTOR &src) const DEAL_II_DEPRECATED;
/**
- * @deprecated This function is
- * purely experimental and will
- * probably never be implemented
- * in a way that it can be
- * released.
+ * @deprecated This function is purely experimental and will probably never
+ * be implemented in a way that it can be released.
*
- * Perform a multigrid cycle with
- * a vector which is already a
- * level vector. Use of this
- * function assumes that there is
- * NO local refinement and that
- * both vectors are on the finest
- * level of this Multigrid
- * object.
+ * Perform a multigrid cycle with a vector which is already a level vector.
+ * Use of this function assumes that there is NO local refinement and that
+ * both vectors are on the finest level of this Multigrid object.
*/
void vmult_add(VECTOR &dst, const VECTOR &src) const DEAL_II_DEPRECATED;
/**
- * @deprecated Even worse than
- * vmult(), this function is not
- * even implemented, but just
- * declared such that certain
- * objects relying on it can be
- * constructed.
+ * @deprecated Even worse than vmult(), this function is not even
+ * implemented, but just declared such that certain objects relying on it
+ * can be constructed.
*/
void Tvmult(VECTOR &dst, const VECTOR &src) const DEAL_II_DEPRECATED;
/**
- * @deprecated Even worse than
- * vmult(), this function is not
- * even implemented, but just
- * declared such that certain
- * objects relying on it can be
- * constructed.
+ * @deprecated Even worse than vmult(), this function is not even
+ * implemented, but just declared such that certain objects relying on it
+ * can be constructed.
*/
void Tvmult_add(VECTOR &dst, const VECTOR &src) const DEAL_II_DEPRECATED;
/**
- * Set additional matrices to
- * correct residual computation
- * at refinement edges. Since we
- * only smoothen in the interior
- * of the refined part of the
- * mesh, the coupling across the
- * refinement edge is
- * missing. This coupling is
- * provided by these two
- * matrices.
+ * Set additional matrices to correct residual computation at refinement
+ * edges. Since we only smoothen in the interior of the refined part of the
+ * mesh, the coupling across the refinement edge is missing. This coupling
+ * is provided by these two matrices.
*
- * @note While
- * <tt>edge_out.vmult</tt> is
- * used, for the second argument,
- * we use
- * <tt>edge_in.Tvmult</tt>. Thus,
- * <tt>edge_in</tt> should be
- * assembled in transposed
- * form. This saves a second
- * sparsity pattern for
- * <tt>edge_in</tt>. In
- * particular, for symmetric
- * operators, both arguments can
- * refer to the same matrix,
- * saving assembling of one of
- * them.
+ * @note While <tt>edge_out.vmult</tt> is used, for the second argument, we
+ * use <tt>edge_in.Tvmult</tt>. Thus, <tt>edge_in</tt> should be assembled
+ * in transposed form. This saves a second sparsity pattern for
+ * <tt>edge_in</tt>. In particular, for symmetric operators, both arguments
+ * can refer to the same matrix, saving assembling of one of them.
*/
void set_edge_matrices (const MGMatrixBase<VECTOR> &edge_out,
const MGMatrixBase<VECTOR> &edge_in);
/**
- * Set additional matrices to
- * correct residual computation
- * at refinement edges. These
- * matrices originate from
- * discontinuous Galerkin methods
- * (see FE_DGQ etc.), where they
- * correspond to the edge fluxes
- * at the refinement edge between
- * two levels.
+ * Set additional matrices to correct residual computation at refinement
+ * edges. These matrices originate from discontinuous Galerkin methods (see
+ * FE_DGQ etc.), where they correspond to the edge fluxes at the refinement
+ * edge between two levels.
*
- * @note While
- * <tt>edge_down.vmult</tt> is
- * used, for the second argument,
- * we use
- * <tt>edge_up.Tvmult</tt>. Thus,
- * <tt>edge_up</tt> should be
- * assembled in transposed
- * form. This saves a second
- * sparsity pattern for
- * <tt>edge_up</tt>. In
- * particular, for symmetric
- * operators, both arguments can
- * refer to the same matrix,
- * saving assembling of one of
- * them.
+ * @note While <tt>edge_down.vmult</tt> is used, for the second argument, we
+ * use <tt>edge_up.Tvmult</tt>. Thus, <tt>edge_up</tt> should be assembled
+ * in transposed form. This saves a second sparsity pattern for
+ * <tt>edge_up</tt>. In particular, for symmetric operators, both arguments
+ * can refer to the same matrix, saving assembling of one of them.
*/
void set_edge_flux_matrices (const MGMatrixBase<VECTOR> &edge_down,
const MGMatrixBase<VECTOR> &edge_up);
/**
- * Return the finest level for
- * multigrid.
+ * Return the finest level for multigrid.
*/
unsigned int get_maxlevel() const;
/**
- * Return the coarsest level for
- * multigrid.
+ * Return the coarsest level for multigrid.
*/
unsigned int get_minlevel() const;
/**
- * Set the highest level for
- * which the multilevel method is
- * performed. By default, this is
- * the finest level of the
- * Triangulation; therefore, this
- * function will only accept
- * arguments smaller than the
- * current #maxlevel and not
- * smaller than the current
- * #minlevel.
+ * Set the highest level for which the multilevel method is performed. By
+ * default, this is the finest level of the Triangulation; therefore, this
+ * function will only accept arguments smaller than the current #maxlevel
+ * and not smaller than the current #minlevel.
*/
void set_maxlevel (const unsigned int);
/**
- * Set the coarse level for which
- * the multilevel method is
- * performed. By default, this is
- * zero. Accepted are
- * non-negative values not larger than
+ * Set the coarse level for which the multilevel method is performed. By
+ * default, this is zero. Accepted are non-negative values not larger than
* than the current #maxlevel.
*
- * If <tt>relative</tt> ist
- * <tt>true</tt>, then this
- * function determins the number
- * of levels used, that is, it
- * sets #minlevel to
+ * If <tt>relative</tt> ist <tt>true</tt>, then this function determins the
+ * number of levels used, that is, it sets #minlevel to
* #maxlevel-<tt>level</tt>.
*
- * @note The mesh on the coarsest
- * level must cover the whole
- * domain. There may not be
- * hanging nodes on #minlevel.
+ * @note The mesh on the coarsest level must cover the whole domain. There
+ * may not be hanging nodes on #minlevel.
*
- * @note If #minlevel is set to a
- * nonzero value, do not forget
- * to adjust your coarse grid
- * solver!
+ * @note If #minlevel is set to a nonzero value, do not forget to adjust
+ * your coarse grid solver!
*/
void set_minlevel (const unsigned int level,
bool relative = false);
void set_cycle(Cycle);
/**
- * Set the debug level. Higher
- * values will create more
- * debugging output during the
- * multigrid cycles.
+ * Set the debug level. Higher values will create more debugging output
+ * during the multigrid cycles.
*/
void set_debug (const unsigned int);
private:
/**
- * The V-cycle multigrid method.
- * <tt>level</tt> is the level the
- * function starts on. It
- * will usually be called for the
- * highest level from outside,
- * but will then call itself
- * recursively for <tt>level-1</tt>,
- * unless we are on #minlevel
- * where the coarse grid solver
- * solves the problem exactly.
+ * The V-cycle multigrid method. <tt>level</tt> is the level the function
+ * starts on. It will usually be called for the highest level from outside,
+ * but will then call itself recursively for <tt>level-1</tt>, unless we are
+ * on #minlevel where the coarse grid solver solves the problem exactly.
*/
void level_v_step (const unsigned int level);
/**
- * The actual W-cycle or F-cycle
- * multigrid method.
- * <tt>level</tt> is the level
- * the function starts on. It
- * will usually be called for the
- * highest level from outside,
- * but will then call itself
- * recursively for
- * <tt>level-1</tt>, unless we
- * are on #minlevel where the
- * coarse grid solver solves the
- * problem exactly.
+ * The actual W-cycle or F-cycle multigrid method. <tt>level</tt> is the
+ * level the function starts on. It will usually be called for the highest
+ * level from outside, but will then call itself recursively for
+ * <tt>level-1</tt>, unless we are on #minlevel where the coarse grid solver
+ * solves the problem exactly.
*/
void level_step (const unsigned int level, Cycle cycle);
public:
/**
- * Input vector for the
- * cycle. Contains the defect of
- * the outer method projected to
- * the multilevel vectors.
+ * Input vector for the cycle. Contains the defect of the outer method
+ * projected to the multilevel vectors.
*/
MGLevelObject<VECTOR> defect;
/**
- * The solution update after the
- * multigrid step.
+ * The solution update after the multigrid step.
*/
MGLevelObject<VECTOR> solution;
MGLevelObject<VECTOR> t;
/**
- * Auxiliary vector for W- and
- * F-cycles. Left uninitialized
- * in V-cycle.
+ * Auxiliary vector for W- and F-cycles. Left uninitialized in V-cycle.
*/
MGLevelObject<VECTOR> defect2;
SmartPointer<const MGSmootherBase<VECTOR>,Multigrid<VECTOR> > post_smooth;
/**
- * Edge matrix from the interior
- * of the refined part to the
- * refinement edge.
+ * Edge matrix from the interior of the refined part to the refinement edge.
*
- * @note Only <tt>vmult</tt> is
- * used for these matrices.
+ * @note Only <tt>vmult</tt> is used for these matrices.
*/
SmartPointer<const MGMatrixBase<VECTOR> > edge_out;
/**
- * Transpose edge matrix from the
- * refinement edge to the
- * interior of the refined part.
+ * Transpose edge matrix from the refinement edge to the interior of the
+ * refined part.
*
- * @note Only <tt>Tvmult</tt> is
- * used for these matrices.
+ * @note Only <tt>Tvmult</tt> is used for these matrices.
*/
SmartPointer<const MGMatrixBase<VECTOR> > edge_in;
/**
* Edge matrix from fine to coarse.
*
- * @note Only <tt>vmult</tt> is
- * used for these matrices.
+ * @note Only <tt>vmult</tt> is used for these matrices.
*/
SmartPointer<const MGMatrixBase<VECTOR>,Multigrid<VECTOR> > edge_down;
/**
* Transpose edge matrix from coarse to fine.
*
- * @note Only <tt>Tvmult</tt> is
- * used for these matrices.
+ * @note Only <tt>Tvmult</tt> is used for these matrices.
*/
SmartPointer<const MGMatrixBase<VECTOR>,Multigrid<VECTOR> > edge_up;
/**
- * Level for debug
- * output. Defaults to zero and
- * can be set by set_debug().
+ * Level for debug output. Defaults to zero and can be set by set_debug().
*/
unsigned int debug;
/**
- * Multi-level preconditioner.
- * Here, we collect all information needed for multi-level preconditioning
- * and provide the standard interface for LAC iterative methods.
+ * Multi-level preconditioner. Here, we collect all information needed for
+ * multi-level preconditioning and provide the standard interface for LAC
+ * iterative methods.
*
- * Furthermore, it needs functions <tt>void copy_to_mg(const VECTOR&)</tt>
- * to store @p src in the right hand side of the multi-level method and
- * <tt>void copy_from_mg(VECTOR&)</tt> to store the result of the v-cycle in @p dst.
+ * Furthermore, it needs functions <tt>void copy_to_mg(const VECTOR&)</tt> to
+ * store @p src in the right hand side of the multi-level method and <tt>void
+ * copy_from_mg(VECTOR&)</tt> to store the result of the v-cycle in @p dst.
*
* @author Guido Kanschat, 1999, 2000, 2001, 2002
*/
{
public:
/**
- * Constructor.
- * Arguments are the multigrid object,
- * pre-smoother, post-smoother and
- * coarse grid solver.
+ * Constructor. Arguments are the multigrid object, pre-smoother, post-
+ * smoother and coarse grid solver.
*/
PreconditionMG(const DoFHandler<dim> &dof_handler,
Multigrid<VECTOR> &mg,
bool empty () const;
/**
- * Preconditioning operator.
- * Calls the @p vcycle function
- * of the @p MG object passed to
- * the constructor.
+ * Preconditioning operator. Calls the @p vcycle function of the @p MG
+ * object passed to the constructor.
*
- * This is the operator used by
- * LAC iterative solvers.
+ * This is the operator used by LAC iterative solvers.
*/
template<class VECTOR2>
void vmult (VECTOR2 &dst,
const VECTOR2 &src) const;
/**
- * Preconditioning operator.
- * Calls the @p vcycle function
- * of the @p MG object passed to
- * the constructor.
+ * Preconditioning operator. Calls the @p vcycle function of the @p MG
+ * object passed to the constructor.
*/
template<class VECTOR2>
void vmult_add (VECTOR2 &dst,
/**
* Tranposed preconditioning operator.
*
- * Not implemented, but the
- * definition may be needed.
+ * Not implemented, but the definition may be needed.
*/
template<class VECTOR2>
void Tvmult (VECTOR2 &dst,
/**
* Tranposed preconditioning operator.
*
- * Not implemented, but the
- * definition may be needed.
+ * Not implemented, but the definition may be needed.
*/
template<class VECTOR2>
void Tvmult_add (VECTOR2 &dst,
namespace mg
{
/**
- * Handler and storage for all five SparseMatrix object involved in
- * using multigrid with local refinement.
+ * Handler and storage for all five SparseMatrix object involved in using
+ * multigrid with local refinement.
*
* @author Baerbel Janssen, Guido Kanschat
* @date 2013
namespace DataComponentInterpretation
{
/**
- * The members of this enum are used to
- * describe the logical interpretation of
- * what the various components of a
- * vector-valued data set mean. For
- * example, if one has a finite element
- * for the Stokes equations in 2d,
- * representing components $(u,v,p)$, one
- * would like to indicate that the first
- * two, $u$ and $v$, represent a logical
- * vector so that later on when we
- * generate graphical output we can hand
- * them off to a visualization program
- * that will automatically know to render
- * them as a vector field, rather than as
- * two separate and independent scalar
- * fields.
+ * The members of this enum are used to describe the logical interpretation
+ * of what the various components of a vector-valued data set mean. For
+ * example, if one has a finite element for the Stokes equations in 2d,
+ * representing components $(u,v,p)$, one would like to indicate that the
+ * first two, $u$ and $v$, represent a logical vector so that later on when
+ * we generate graphical output we can hand them off to a visualization
+ * program that will automatically know to render them as a vector field,
+ * rather than as two separate and independent scalar fields.
*
- * By passing a set of enums of the
- * current kind to the
- * DataOut_DoFData::add_data_vector
- * functions, this can be achieved.
+ * By passing a set of enums of the current kind to the
+ * DataOut_DoFData::add_data_vector functions, this can be achieved.
*
- * See the step-22 tutorial
- * program for an example on how this
- * information can be used in practice.
+ * See the step-22 tutorial program for an example on how this information
+ * can be used in practice.
*
* @author Wolfgang Bangerth, 2007
*/
enum DataComponentInterpretation
{
/**
- * Indicates that a component of a
- * data set corresponds to a scalar
- * field independent of the others.
+ * Indicates that a component of a data set corresponds to a scalar field
+ * independent of the others.
*/
component_is_scalar,
/**
- * Indicates that a component of a
- * data set is part of a
- * vector-valued quantity.
+ * Indicates that a component of a data set is part of a vector-valued
+ * quantity.
*/
component_is_part_of_vector
};
* This class is the main class to provide output of data described by finite
* element fields defined on a collection of cells.
*
- * This class is an actual implementation of the functionality proposed by
- * the DataOut_DoFData class. It offers a function build_patches() that
- * generates the patches to be written in some graphics format from the data
- * stored in the base class. Most of the interface and an example of its
- * use is described in the documentation of the base class.
+ * This class is an actual implementation of the functionality proposed by the
+ * DataOut_DoFData class. It offers a function build_patches() that generates
+ * the patches to be written in some graphics format from the data stored in
+ * the base class. Most of the interface and an example of its use is
+ * described in the documentation of the base class.
*
* The only thing this class offers is the function build_patches() which
* loops over all cells of the triangulation stored by the
* mesh.
*
* Note that after having called build_patches() once, you can call one or
- * more of the write() functions of DataOutInterface. You can therefore
- * output the same data in more than one format without having to rebuild
- * the patches.
+ * more of the write() functions of DataOutInterface. You can therefore output
+ * the same data in more than one format without having to rebuild the
+ * patches.
*
*
* <h3>User interface information</h3>
*
* The base classes of this class, DataOutBase, DataOutInterface and
* DataOut_DoFData() offer several interfaces of their own. Refer to the
- * DataOutBase class's documentation for a discussion of the different
- * output formats presently supported, DataOutInterface for ways of
- * selecting which format to use upon output at run-time and without
- * the need to adapt your program when new formats become available, as
- * well as for flags to determine aspects of output. The DataOut_DoFData()
- * class's documentation has an example of using nodal data to generate
- * output.
+ * DataOutBase class's documentation for a discussion of the different output
+ * formats presently supported, DataOutInterface for ways of selecting which
+ * format to use upon output at run-time and without the need to adapt your
+ * program when new formats become available, as well as for flags to
+ * determine aspects of output. The DataOut_DoFData() class's documentation
+ * has an example of using nodal data to generate output.
*
*
* <h3>Extensions</h3>
* region of the domain (for example in parallel programs such as the step-18
* example program), or for some other reason.
*
- * For this, internally build_patches() does not generate
- * the sequence of cells to be converted into patches itself, but relies
- * on the two functions first_cell() and next_cell(). By default, they
- * return the first active cell, and the next active cell, respectively.
- * Since they are @p virtual functions, you can write your own class
- * derived from DataOut in which you overload these two functions to select other
- * cells for output. This may, for example, include only cells that are
- * in parts of a domain (e.g., if you don't care about the solution elsewhere,
- * think for example a buffer region in which you attenuate outgoing waves
- * in the Perfectly Matched Layer method) or if you don't want output to
- * be generated at all levels of an adaptively refined mesh because this
- * creates too much data (in this case, the set of cells returned by
- * your implementations of first_cell() and next_cell() will include
- * non-active cells, and DataOut::build_patches() will simply take
- * interpolated values of the solution instead of the exact values on these
- * cells children for output). Once you derive your own class, you would
- * just create an object of this type instead of an object of type DataOut,
- * and everything else will remain the same.
+ * For this, internally build_patches() does not generate the sequence of
+ * cells to be converted into patches itself, but relies on the two functions
+ * first_cell() and next_cell(). By default, they return the first active
+ * cell, and the next active cell, respectively. Since they are @p virtual
+ * functions, you can write your own class derived from DataOut in which you
+ * overload these two functions to select other cells for output. This may,
+ * for example, include only cells that are in parts of a domain (e.g., if you
+ * don't care about the solution elsewhere, think for example a buffer region
+ * in which you attenuate outgoing waves in the Perfectly Matched Layer
+ * method) or if you don't want output to be generated at all levels of an
+ * adaptively refined mesh because this creates too much data (in this case,
+ * the set of cells returned by your implementations of first_cell() and
+ * next_cell() will include non-active cells, and DataOut::build_patches()
+ * will simply take interpolated values of the solution instead of the exact
+ * values on these cells children for output). Once you derive your own class,
+ * you would just create an object of this type instead of an object of type
+ * DataOut, and everything else will remain the same.
*
* The two functions are not constant, so you may store information within
* your derived class about the last accessed cell. This is useful if the
* this pair of functions and they return a non-active cell, then an exception
* will be thrown.
*
- * @pre This class only makes sense if the first template
- * argument, <code>dim</code> equals the dimension of the
- * DoFHandler type given as the second template argument, i.e., if
- * <code>dim == DH::dimension</code>. This redundancy is a historical
- * relic from the time where the library had only a single DoFHandler
- * class and this class consequently only a single template argument.
+ * @pre This class only makes sense if the first template argument,
+ * <code>dim</code> equals the dimension of the DoFHandler type given as the
+ * second template argument, i.e., if <code>dim == DH::dimension</code>. This
+ * redundancy is a historical relic from the time where the library had only a
+ * single DoFHandler class and this class consequently only a single template
+ * argument.
*
* @ingroup output
* @author Wolfgang Bangerth, 1999
* which originate from cells at the boundary of the domain can be computed
* using the mapping, i.e. a higher order mapping leads to a representation
* of a curved boundary by using more subdivisions. Some mappings like
- * MappingQEulerian result in curved cells in the interior of the
- * domain. However, there is nor easy way to get this information from the
- * Mapping. Thus the last argument @p curved_region take one of three values
+ * MappingQEulerian result in curved cells in the interior of the domain.
+ * However, there is nor easy way to get this information from the Mapping.
+ * Thus the last argument @p curved_region take one of three values
* resulting in no curved cells at all, curved cells at the boundary
* (default) or curved cells in the whole domain.
*
* do this for a number of different vector types. Fortunately, they all
* have the same interface. So the way we go is to have a base class that
* provides the functions to access the vector's information, and to have
- * a derived template class that can be instantiated for each vector
- * type. Since the vectors all have the same interface, this is no big
- * problem, as they can all use the same general templatized code.
+ * a derived template class that can be instantiated for each vector type.
+ * Since the vectors all have the same interface, this is no big problem,
+ * as they can all use the same general templatized code.
*
* @author Wolfgang Bangerth, 2004
*/
* data_out.clear();
* @endcode
*
- * attach_dof_handler() tells this class that all future operations
- * are to take place with the DoFHandler object and the triangulation
- * it lives on. We then add the solution vector and the error
- * estimator; note that they have different dimensions, because the
- * solution is a nodal vector, here consisting of two components
- * ("x-displacement" and "y-displacement") while the error estimator
- * probably is a vector holding cell data. When attaching a data
- * vector, you have to give a name to each component of the vector,
- * which is done through an object of type <tt>vector<string></tt> as
- * second argument; if only one component is in the vector, for
- * example if we are adding cell data as in the second case, or if the
- * finite element used by the DoFHandler has only one component, then
- * you can use the second add_data_vector() function which takes a @p
- * string instead of the <tt>vector<string></tt>.
+ * attach_dof_handler() tells this class that all future operations are to
+ * take place with the DoFHandler object and the triangulation it lives on. We
+ * then add the solution vector and the error estimator; note that they have
+ * different dimensions, because the solution is a nodal vector, here
+ * consisting of two components ("x-displacement" and "y-displacement") while
+ * the error estimator probably is a vector holding cell data. When attaching
+ * a data vector, you have to give a name to each component of the vector,
+ * which is done through an object of type <tt>vector<string></tt> as second
+ * argument; if only one component is in the vector, for example if we are
+ * adding cell data as in the second case, or if the finite element used by
+ * the DoFHandler has only one component, then you can use the second
+ * add_data_vector() function which takes a @p string instead of the
+ * <tt>vector<string></tt>.
*
* The add_data_vector() functions have additional arguments (with default
* values) that can be used to specify certain transformations. In particular,
* it allows to attach DataPostprocessor arguments to compute derived
- * information from a data vector at each point at which the field will
- * be evaluated so that it can be written to a file (for example, the
- * Mach number in hypersonic flow can be computed from density and velocities;
- * step-29 also shows an example); another piece of information
- * specified through arguments with default values is how certain output
- * components should be interpreted, i.e. whether each component of the data
- * is logically an independent scalar field, or whether some of them together
- * form logically a vector-field (see the
+ * information from a data vector at each point at which the field will be
+ * evaluated so that it can be written to a file (for example, the Mach number
+ * in hypersonic flow can be computed from density and velocities; step-29
+ * also shows an example); another piece of information specified through
+ * arguments with default values is how certain output components should be
+ * interpreted, i.e. whether each component of the data is logically an
+ * independent scalar field, or whether some of them together form logically a
+ * vector-field (see the
* DataComponentInterpretation::DataComponentInterpretation enum, and the @ref
* step_22 "step-22" tutorial program).
*
- * It should be noted that this class does not copy the vector given to it through
- * the add_data_vector() functions, for memory consumption reasons. It only
- * stores a reference to it, so it is in your responsibility to make sure that
- * the data vectors exist long enough.
+ * It should be noted that this class does not copy the vector given to it
+ * through the add_data_vector() functions, for memory consumption reasons. It
+ * only stores a reference to it, so it is in your responsibility to make sure
+ * that the data vectors exist long enough.
*
* After adding all data vectors, you need to call a function which generates
* the patches for output from the stored data. Derived classes name this
- * function build_patches(). Finally, you write() the data in one format or other,
- * to a file.
+ * function build_patches(). Finally, you write() the data in one format or
+ * other, to a file.
*
- * Please note that in the example above, an object of type DataOut was
- * used, i.e. an object of a derived class. This is necessary since this
- * class does not provide means to actually generate the patches, only aids to
- * store and access data.
+ * Please note that in the example above, an object of type DataOut was used,
+ * i.e. an object of a derived class. This is necessary since this class does
+ * not provide means to actually generate the patches, only aids to store and
+ * access data.
*
- * Note that the base class of this class, DataOutInterface offers
- * several functions to ease programming with run-time determinable
- * output formats (i.e. you need not use a fixed format by calling
- * DataOutInterface::write_xxx in the above example, but you can
- * select it by a run-time parameter without having to write the
- * <tt>if () ... else ...</tt> clauses yourself), and also functions
- * and classes offering ways to control the appearance of the output
- * by setting flags for each output format.
+ * Note that the base class of this class, DataOutInterface offers several
+ * functions to ease programming with run-time determinable output formats
+ * (i.e. you need not use a fixed format by calling
+ * DataOutInterface::write_xxx in the above example, but you can select it by
+ * a run-time parameter without having to write the <tt>if () ... else
+ * ...</tt> clauses yourself), and also functions and classes offering ways to
+ * control the appearance of the output by setting flags for each output
+ * format.
*
*
* <h3>Information for derived classes</h3>
*
- * What is actually missing this class is a way to produce the patches
- * for output itself, from the stored data and degree of freedom
- * information. Since this task is often application dependent it is
- * left to derived classes. For example, in many applications, it
- * might be wanted to limit the depth of output to a certain number of
- * refinement levels and write data from finer cells only in a way
- * interpolated to coarser cells, to reduce the amount of
- * output. Also, it might be wanted to use different numbers of
- * subdivisions on different cells when forming a patch, for example
- * to accomplish for different polynomial degrees of the trial space
- * on different cells. Also, the output need not necessarily consist
- * of a patch for each cell, but might be made up of patches for
- * faces, of other things. Take a look at derived classes to what is
- * possible in this respect.
+ * What is actually missing this class is a way to produce the patches for
+ * output itself, from the stored data and degree of freedom information.
+ * Since this task is often application dependent it is left to derived
+ * classes. For example, in many applications, it might be wanted to limit the
+ * depth of output to a certain number of refinement levels and write data
+ * from finer cells only in a way interpolated to coarser cells, to reduce the
+ * amount of output. Also, it might be wanted to use different numbers of
+ * subdivisions on different cells when forming a patch, for example to
+ * accomplish for different polynomial degrees of the trial space on different
+ * cells. Also, the output need not necessarily consist of a patch for each
+ * cell, but might be made up of patches for faces, of other things. Take a
+ * look at derived classes to what is possible in this respect.
*
- * For this reason, it is left to a derived class to provide a
- * function, named usually build_patches() or the like, which fills
- * the #patches array of this class.
+ * For this reason, it is left to a derived class to provide a function, named
+ * usually build_patches() or the like, which fills the #patches array of this
+ * class.
*
- * Regarding the templates of this class, it needs three values: first
- * the space dimension in which the triangulation and the DoF handler
- * operate, second the dimension of the objects which the patches
- * represent. Although in most cases they are equal, there are also
- * classes for which this does not hold, for example if one outputs
- * the result of a computation exploiting rotational symmetry in the
- * original domain (in which the space dimension of the output would
- * be one higher than that of the DoF handler, see the
- * DataOut_Rotation() class), or one might conceive that one could
- * write a class that only outputs the solution on a cut through the
- * domain, in which case the space dimension of the output is less
- * than that of the DoF handler. The last template argument denotes
- * the dimension of the space into which the patches are embedded;
- * usually, this dimension is the same as the dimensio of the patches
- * themselves (which is also the default value of the template
- * parameter), but there might be cases where this is not so. For
- * example, in the DataOut_Faces() class, patches are generated
- * from faces of the triangulation. Thus, the dimension of the patch
- * is one less than the dimension of the embedding space, which is, in
- * this case, equal to the dimension of the triangulation and DoF
- * handler. However, for the cut through the domain mentioned above,
- * if the cut is a straight one, then the cut can be embedded into a
- * space of one dimension lower than the dimension of the
- * triangulation, so that the last template parameter has the same
+ * Regarding the templates of this class, it needs three values: first the
+ * space dimension in which the triangulation and the DoF handler operate,
+ * second the dimension of the objects which the patches represent. Although
+ * in most cases they are equal, there are also classes for which this does
+ * not hold, for example if one outputs the result of a computation exploiting
+ * rotational symmetry in the original domain (in which the space dimension of
+ * the output would be one higher than that of the DoF handler, see the
+ * DataOut_Rotation() class), or one might conceive that one could write a
+ * class that only outputs the solution on a cut through the domain, in which
+ * case the space dimension of the output is less than that of the DoF
+ * handler. The last template argument denotes the dimension of the space into
+ * which the patches are embedded; usually, this dimension is the same as the
+ * dimensio of the patches themselves (which is also the default value of the
+ * template parameter), but there might be cases where this is not so. For
+ * example, in the DataOut_Faces() class, patches are generated from faces of
+ * the triangulation. Thus, the dimension of the patch is one less than the
+ * dimension of the embedding space, which is, in this case, equal to the
+ * dimension of the triangulation and DoF handler. However, for the cut
+ * through the domain mentioned above, if the cut is a straight one, then the
+ * cut can be embedded into a space of one dimension lower than the dimension
+ * of the triangulation, so that the last template parameter has the same
* value as the second one.
*
* @ingroup output
* mapping between nodes and node values.
*
* This call is optional: If you add data vectors with specified DoFHandler
- * object, then that contains all information needed to generate the
- * output. This call is useful when you only output cell vectors and no
- * DoFHandler at all, in which case it provides the geometry.
+ * object, then that contains all information needed to generate the output.
+ * This call is useful when you only output cell vectors and no DoFHandler
+ * at all, in which case it provides the geometry.
*/
void attach_triangulation (const Triangulation<DH::dimension,
DH::space_dimension> &);
* given. However, there are corner cases where this automatic determination
* does not work. One example is if you compute with piecewise constant
* elements and have a scalar solution, then there are as many cells as
- * there are degrees of freedom (though they may be numbered
- * differently). Another possibility is if you have a 1d mesh embedded in 2d
- * space and the mesh consists of a closed curve of cells; in this case,
- * there are as many nodes as there are cells, and when using a Q1 element
- * you will have as many degrees of freedom as there are cells. In these
- * cases, you can change the last argument of the function from its default
- * value #type_automatic to either #type_dof_data or #type_cell_data,
- * depending on what the vector represents. Apart from such corner cases,
- * you can leave the argument at its default value and let the function
- * determine the type of the vector itself.
+ * there are degrees of freedom (though they may be numbered differently).
+ * Another possibility is if you have a 1d mesh embedded in 2d space and the
+ * mesh consists of a closed curve of cells; in this case, there are as many
+ * nodes as there are cells, and when using a Q1 element you will have as
+ * many degrees of freedom as there are cells. In these cases, you can
+ * change the last argument of the function from its default value
+ * #type_automatic to either #type_dof_data or #type_cell_data, depending on
+ * what the vector represents. Apart from such corner cases, you can leave
+ * the argument at its default value and let the function determine the type
+ * of the vector itself.
*
* If it is a vector holding DoF data, the names given shall be one for each
* component of the underlying finite element. If it is a finite element
* DataComponentInterpretation::component_is_scalar, indicating that all
* output components are independent scalar fields. However, if the given
* data vector represents logical vectors, you may pass a vector that
- * contains values
- * DataComponentInterpretation::component_is_part_of_vector. In the example
- * above, one would pass in a vector with components
+ * contains values DataComponentInterpretation::component_is_part_of_vector.
+ * In the example above, one would pass in a vector with components
* (DataComponentInterpretation::component_is_part_of_vector,
* DataComponentInterpretation::component_is_part_of_vector,
* DataComponentInterpretation::component_is_scalar) for (u,v,p).
* includes all of the usual vector types, but also IndexSet (see step-41
* for a use of this).
*
- * @note The DataPostprocessor object (i.e., in reality the object of your derived
- * class) has to live until the DataOut object is destroyed as the latter keeps
- * a pointer to the former and will complain if the object pointed to is
- * destroyed while the latter still has a pointer to it. If both the data
- * postprocessor and DataOut objects are local variables of a function
- * (as they are, for example, in step-29), then you can avoid this
+ * @note The DataPostprocessor object (i.e., in reality the object of your
+ * derived class) has to live until the DataOut object is destroyed as the
+ * latter keeps a pointer to the former and will complain if the object
+ * pointed to is destroyed while the latter still has a pointer to it. If
+ * both the data postprocessor and DataOut objects are local variables of a
+ * function (as they are, for example, in step-29), then you can avoid this
* error by declaring the data postprocessor variable before the DataOut
* variable as objects are destroyed in reverse order of declaration.
*/
/**
* Release the pointers to the data vectors and the DoF handler. You have to
* set all data entries again using the add_data_vector() function. The
- * pointer to the dof handler is cleared as well, along with all other
- * data. In effect, this function resets everything to a virgin state.
+ * pointer to the dof handler is cleared as well, along with all other data.
+ * In effect, this function resets everything to a virgin state.
*/
virtual void clear ();
namespace DataOutFaces
{
/**
- * A derived class for use in the
- * DataOutFaces class. This is
- * a class for the
- * AdditionalData kind of data
- * structure discussed in the
- * documentation of the
- * WorkStream context.
+ * A derived class for use in the DataOutFaces class. This is a class for
+ * the AdditionalData kind of data structure discussed in the
+ * documentation of the WorkStream context.
*/
template <int dim, int spacedim>
struct ParallelData : public internal::DataOut::ParallelDataBase<dim,spacedim>
/**
- * This class generates output from faces of a triangulation. It might
- * be used to generate output only for the surface of the
- * triangulation (this is the default of this class), or for all faces
- * of active cells, as specified in the constructor.
- * The output of this class is a set of
- * patches (as defined by the class DataOutBase::Patch()), one for
- * each face for which output is to be generated. These patches can
- * then be written in several graphical data formats by the functions
- * of the underlying classes.
+ * This class generates output from faces of a triangulation. It might be used
+ * to generate output only for the surface of the triangulation (this is the
+ * default of this class), or for all faces of active cells, as specified in
+ * the constructor. The output of this class is a set of patches (as defined
+ * by the class DataOutBase::Patch()), one for each face for which output is
+ * to be generated. These patches can then be written in several graphical
+ * data formats by the functions of the underlying classes.
*
* <h3>Interface</h3>
*
- * The interface of this class is copied from the DataOut
- * class. Furthermore, they share the common parent class
- * DataOut_DoFData. See the reference of these two classes for a
- * discussion of the interface.
+ * The interface of this class is copied from the DataOut class. Furthermore,
+ * they share the common parent class DataOut_DoFData. See the reference of
+ * these two classes for a discussion of the interface.
*
*
* <h3>Extending this class</h3>
*
- * The sequence of faces to generate patches from is generated in the
- * same way as in the DataOut class; see there for a description of
- * the respective interface. The functions generating the sequence of
- * faces which shall be used to generate output, are called
- * first_face() and next_face().
+ * The sequence of faces to generate patches from is generated in the same way
+ * as in the DataOut class; see there for a description of the respective
+ * interface. The functions generating the sequence of faces which shall be
+ * used to generate output, are called first_face() and next_face().
*
- * Since we need to initialize objects of type FEValues with the
- * faces generated from these functions, it is not sufficient that
- * they only return face iterators. Rather, we need a pair of cell and
- * the number of the face, as the values of finite element fields need
- * not necessarily be unique on a face (think of discontinuous finite
- * elements, where the value of the finite element field depend on the
- * direction from which you approach a face, thus it is necessary to
- * use a pair of cell and face, rather than only a face
- * iterator). Therefore, this class defines a @p typedef which
- * creates a type @p FaceDescriptor that is an abbreviation for a
- * pair of cell iterator and face number. The functions @p first_face
- * and @p next_face operate on objects of this type.
+ * Since we need to initialize objects of type FEValues with the faces
+ * generated from these functions, it is not sufficient that they only return
+ * face iterators. Rather, we need a pair of cell and the number of the face,
+ * as the values of finite element fields need not necessarily be unique on a
+ * face (think of discontinuous finite elements, where the value of the finite
+ * element field depend on the direction from which you approach a face, thus
+ * it is necessary to use a pair of cell and face, rather than only a face
+ * iterator). Therefore, this class defines a @p typedef which creates a type
+ * @p FaceDescriptor that is an abbreviation for a pair of cell iterator and
+ * face number. The functions @p first_face and @p next_face operate on
+ * objects of this type.
*
- * Extending this class might, for example, be useful if you only want
- * output from certain portions of the boundary, e.g. as indicated by
- * the boundary indicator of the respective faces. However, it is also
- * conceivable that one generates patches not from boundary faces, but
- * from interior faces that are selected due to other criteria; one
- * application might be to use only those faces where one component of
- * the solution attains a certain value, in order to display the
- * values of other solution components on these faces. Other
- * applications certainly exist, for which the author is not
- * imaginative enough.
+ * Extending this class might, for example, be useful if you only want output
+ * from certain portions of the boundary, e.g. as indicated by the boundary
+ * indicator of the respective faces. However, it is also conceivable that one
+ * generates patches not from boundary faces, but from interior faces that are
+ * selected due to other criteria; one application might be to use only those
+ * faces where one component of the solution attains a certain value, in order
+ * to display the values of other solution components on these faces. Other
+ * applications certainly exist, for which the author is not imaginative
+ * enough.
*
- * @pre This class only makes sense if the first template
- * argument, <code>dim</code> equals the dimension of the
- * DoFHandler type given as the second template argument, i.e., if
- * <code>dim == DH::dimension</code>. This redundancy is a historical
- * relic from the time where the library had only a single DoFHandler
- * class and this class consequently only a single template argument.
+ * @pre This class only makes sense if the first template argument,
+ * <code>dim</code> equals the dimension of the DoFHandler type given as the
+ * second template argument, i.e., if <code>dim == DH::dimension</code>. This
+ * redundancy is a historical relic from the time where the library had only a
+ * single DoFHandler class and this class consequently only a single template
+ * argument.
*
- * @todo Reimplement this whole class using actual FEFaceValues and MeshWorker.
+ * @todo Reimplement this whole class using actual FEFaceValues and
+ * MeshWorker.
*
* @ingroup output
* @author Wolfgang Bangerth, Guido Kanschat, 2000, 2011
{
public:
/**
- * An abbreviation for the dimension of the DoFHandler object we work
- * with. Faces are then <code>dimension-1</code> dimensional objects.
+ * An abbreviation for the dimension of the DoFHandler object we work with.
+ * Faces are then <code>dimension-1</code> dimensional objects.
*/
static const unsigned int dimension = DH::dimension;
static const unsigned int space_dimension = DH::space_dimension;
/**
- * Typedef to the iterator type
- * of the dof handler class under
+ * Typedef to the iterator type of the dof handler class under
* consideration.
*/
typedef typename DataOut_DoFData<DH,dimension-1,
dimension>::cell_iterator cell_iterator;
/**
- * Constructor determining
- * whether a surface mesh
- * (default) or the whole wire
- * basket is written.
+ * Constructor determining whether a surface mesh (default) or the whole
+ * wire basket is written.
*/
DataOutFaces (const bool surface_only = true);
/**
- * This is the central function
- * of this class since it builds
- * the list of patches to be
- * written by the low-level
- * functions of the base
- * class. See the general
- * documentation of this class
- * for further information.
+ * This is the central function of this class since it builds the list of
+ * patches to be written by the low-level functions of the base class. See
+ * the general documentation of this class for further information.
*
- * The function supports
- * multithreading, if deal.II is
- * compiled in multithreading
- * mode.
+ * The function supports multithreading, if deal.II is compiled in
+ * multithreading mode.
*/
virtual void
build_patches (const unsigned int n_subdivisions = 0);
/**
- * Same as above, except that the
- * additional first parameter
- * defines a mapping that is to
- * be used in the generation of
- * output. If
- * <tt>n_subdivisions>1</tt>, the
- * points interior of subdivided
- * patches which originate from
- * cells at the boundary of the
- * domain can be computed using the
- * mapping, i.e. a higher order
- * mapping leads to a
- * representation of a curved
- * boundary by using more
- * subdivisions.
+ * Same as above, except that the additional first parameter defines a
+ * mapping that is to be used in the generation of output. If
+ * <tt>n_subdivisions>1</tt>, the points interior of subdivided patches
+ * which originate from cells at the boundary of the domain can be computed
+ * using the mapping, i.e. a higher order mapping leads to a representation
+ * of a curved boundary by using more subdivisions.
*
- * Even for non-curved cells the
- * mapping argument can be used
- * for the Eulerian mappings (see
- * class MappingQ1Eulerian) where
- * a mapping is used not only to
- * determine the position of
- * points interior to a cell, but
- * also of the vertices. It
- * offers an opportunity to watch
- * the solution on a deformed
- * triangulation on which the
- * computation was actually
- * carried out, even if the mesh
- * is internally stored in its
- * undeformed configuration and
- * the deformation is only
- * tracked by an additional
- * vector that holds the
+ * Even for non-curved cells the mapping argument can be used for the
+ * Eulerian mappings (see class MappingQ1Eulerian) where a mapping is used
+ * not only to determine the position of points interior to a cell, but also
+ * of the vertices. It offers an opportunity to watch the solution on a
+ * deformed triangulation on which the computation was actually carried out,
+ * even if the mesh is internally stored in its undeformed configuration and
+ * the deformation is only tracked by an additional vector that holds the
* deformation of each vertex.
*
- * @todo The @p mapping argument should be
- * replaced by a hp::MappingCollection in
- * case of a hp::DoFHandler.
+ * @todo The @p mapping argument should be replaced by a
+ * hp::MappingCollection in case of a hp::DoFHandler.
*/
virtual void build_patches (const Mapping<dimension> &mapping,
const unsigned int n_subdivisions = 0);
/**
- * Declare a way to describe a
- * face which we would like to
- * generate output for. The usual
- * way would, of course, be to
- * use an object of type
- * <tt>DoFHandler<dim>::face_iterator</tt>,
- * but since we have to describe
- * faces to objects of type
- * FEValues, we can only
- * represent faces by pairs of a
- * cell and the number of the
- * face. This pair is here
- * aliased to a name that is
- * better to type.
+ * Declare a way to describe a face which we would like to generate output
+ * for. The usual way would, of course, be to use an object of type
+ * <tt>DoFHandler<dim>::face_iterator</tt>, but since we have to describe
+ * faces to objects of type FEValues, we can only represent faces by pairs
+ * of a cell and the number of the face. This pair is here aliased to a name
+ * that is better to type.
*/
typedef typename std::pair<cell_iterator,unsigned int> FaceDescriptor;
/**
- * Return the first face which we
- * want output for. The default
- * implementation returns the
- * first face of an active cell
- * or the first such on the
- * boundary.
+ * Return the first face which we want output for. The default
+ * implementation returns the first face of an active cell or the first such
+ * on the boundary.
*
- * For more general sets,
- * overload this function in a
- * derived class.
+ * For more general sets, overload this function in a derived class.
*/
virtual FaceDescriptor first_face ();
/**
- * Return the next face after
- * which we want output
- * for. If there are no more
- * faces, <tt>dofs->end()</tt> is
- * returned as the first
- * component of the return value.
+ * Return the next face after which we want output for. If there are no more
+ * faces, <tt>dofs->end()</tt> is returned as the first component of the
+ * return value.
*
- * The default implementation
- * returns the next face of an
- * active cell, or the next such
- * on the boundary.
+ * The default implementation returns the next face of an active cell, or
+ * the next such on the boundary.
*
- * This function traverses the
- * mesh cell by cell (active
- * only), and then through all
- * faces of the cell. As a
- * result, interior faces are
- * output twice.
-
- * This function can be
- * overloaded in a derived
- * class to select a different
- * set of faces. Note that the
- * default implementation assumes
- * that the given @p face is
- * active, which is guaranteed as
- * long as first_face() is also
- * used from the default
- * implementation. Overloading
- * only one of the two functions
- * should be done with care.
+ * This function traverses the mesh cell by cell (active only), and then
+ * through all faces of the cell. As a result, interior faces are output
+ * twice. This function can be overloaded in a derived class to select a
+ * different set of faces. Note that the default implementation assumes that
+ * the given @p face is active, which is guaranteed as long as first_face()
+ * is also used from the default implementation. Overloading only one of the
+ * two functions should be done with care.
*/
virtual FaceDescriptor next_face (const FaceDescriptor &face);
private:
/**
- * Parameter deciding between
- * surface meshes and full wire
- * basket.
+ * Parameter deciding between surface meshes and full wire basket.
*/
const bool surface_only;
/**
- * Build one patch. This function
- * is called in a WorkStream
- * context.
+ * Build one patch. This function is called in a WorkStream context.
*/
void build_one_patch (const FaceDescriptor *cell_and_face,
internal::DataOutFaces::ParallelData<dimension, dimension> &data,
namespace DataOutRotation
{
/**
- * A derived class for use in the
- * DataOutFaces class. This is
- * a class for the
- * AdditionalData kind of data
- * structure discussed in the
- * documentation of the
- * WorkStream class.
+ * A derived class for use in the DataOutFaces class. This is a class for
+ * the AdditionalData kind of data structure discussed in the
+ * documentation of the WorkStream class.
*/
template <int dim, int spacedim>
struct ParallelData : public internal::DataOut::ParallelDataBase<dim,spacedim>
/**
- * This class generates output in the full domain of computations that
- * were done using rotational symmetry of domain and solution. In
- * particular, if a computation of a three dimensional problem with
- * rotational symmetry around the @p z-axis (i.e. in the
- * @p r-z-plane) was done, then this class can be used to generate
- * the output in the original @p x-y-z space. In order to do so, it
- * generates from each cell in the computational mesh a cell in the
- * space with dimension one greater than that of the DoFHandler
- * object. The resulting output will then consist of hexahedra forming
- * an object that has rotational symmetry around the z-axis. As most
- * graphical programs can not represent ring-like structures, the
- * angular (rotation) variable is discretized into a finite number of
- * intervals as well; the number of these intervals must be given to
- * the @p build_patches function. It is noted, however, that while
- * this function generates nice pictures of the whole domain, it often
- * produces <em>very</em> large output files.
+ * This class generates output in the full domain of computations that were
+ * done using rotational symmetry of domain and solution. In particular, if a
+ * computation of a three dimensional problem with rotational symmetry around
+ * the @p z-axis (i.e. in the @p r-z-plane) was done, then this class can be
+ * used to generate the output in the original @p x-y-z space. In order to do
+ * so, it generates from each cell in the computational mesh a cell in the
+ * space with dimension one greater than that of the DoFHandler object. The
+ * resulting output will then consist of hexahedra forming an object that has
+ * rotational symmetry around the z-axis. As most graphical programs can not
+ * represent ring-like structures, the angular (rotation) variable is
+ * discretized into a finite number of intervals as well; the number of these
+ * intervals must be given to the @p build_patches function. It is noted,
+ * however, that while this function generates nice pictures of the whole
+ * domain, it often produces <em>very</em> large output files.
*
*
* <h3>Interface</h3>
*
- * The interface of this class is copied from the DataOut
- * class. Furthermore, they share the common parent class
- * DataOut_DoFData(). See the reference of these two classes for a
- * discussion of the interface and how to extend it by deriving
- * further classes from this class.
+ * The interface of this class is copied from the DataOut class. Furthermore,
+ * they share the common parent class DataOut_DoFData(). See the reference of
+ * these two classes for a discussion of the interface and how to extend it by
+ * deriving further classes from this class.
*
*
* <h3>Details for 1d computations</h3>
*
- * The one coordinate in the triangulation used by the
- * DoFHandler object passed to this class is taken as the radial
- * variable, and the output will then be either a circle or a ring
- * domain. It is in the user's responsibility to assure that the
- * radial coordinate only attains non-negative values.
+ * The one coordinate in the triangulation used by the DoFHandler object
+ * passed to this class is taken as the radial variable, and the output will
+ * then be either a circle or a ring domain. It is in the user's
+ * responsibility to assure that the radial coordinate only attains non-
+ * negative values.
*
*
* <h3>Details for 2d computations</h3>
*
- * We consider the computation (represented by the DoFHandler
- * object that is attached to this class) to have happened in the
- * @p r-z-plane, where @p r is the radial variable and @p z denotes
- * the axis of revolution around which the solution is symmetric. The
- * output is in @p x-y-z space, where the radial dependence is
- * transformed to the @p x-y plane. At present, it is not possible to
- * exchange the meaning of the first and second variable of the plane
- * in which the simulation was made, i.e. generate output from a
- * simulation where the first variable denoted the symmetry axis, and
- * the second denoted the radial variable. You have to take that into
- * account when first programming your application.
+ * We consider the computation (represented by the DoFHandler object that is
+ * attached to this class) to have happened in the @p r-z-plane, where @p r is
+ * the radial variable and @p z denotes the axis of revolution around which
+ * the solution is symmetric. The output is in @p x-y-z space, where the
+ * radial dependence is transformed to the @p x-y plane. At present, it is not
+ * possible to exchange the meaning of the first and second variable of the
+ * plane in which the simulation was made, i.e. generate output from a
+ * simulation where the first variable denoted the symmetry axis, and the
+ * second denoted the radial variable. You have to take that into account when
+ * first programming your application.
*
- * It is in the responsibility of the user to make sure that the
- * radial variable attains only non-negative values.
+ * It is in the responsibility of the user to make sure that the radial
+ * variable attains only non-negative values.
*
- * @pre This class only makes sense if the first template
- * argument, <code>dim</code> equals the dimension of the
- * DoFHandler type given as the second template argument, i.e., if
- * <code>dim == DH::dimension</code>. This redundancy is a historical
- * relic from the time where the library had only a single DoFHandler
- * class and this class consequently only a single template argument.
+ * @pre This class only makes sense if the first template argument,
+ * <code>dim</code> equals the dimension of the DoFHandler type given as the
+ * second template argument, i.e., if <code>dim == DH::dimension</code>. This
+ * redundancy is a historical relic from the time where the library had only a
+ * single DoFHandler class and this class consequently only a single template
+ * argument.
*
* @ingroup output
* @author Wolfgang Bangerth, 2000
{
public:
/**
- * An abbreviation for the dimension of the DoFHandler object we work
- * with. Faces are then <code>dimension-1</code> dimensional objects.
+ * An abbreviation for the dimension of the DoFHandler object we work with.
+ * Faces are then <code>dimension-1</code> dimensional objects.
*/
static const unsigned int dimension = DH::dimension;
static const unsigned int space_dimension = DH::space_dimension;
/**
- * Typedef to the iterator type
- * of the dof handler class under
+ * Typedef to the iterator type of the dof handler class under
* consideration.
*/
typedef typename DataOut_DoFData<DH,dimension+1>::cell_iterator cell_iterator;
/**
- * This is the central function
- * of this class since it builds
- * the list of patches to be
- * written by the low-level
- * functions of the base
- * class. See the general
- * documentation of this class
- * for further information.
+ * This is the central function of this class since it builds the list of
+ * patches to be written by the low-level functions of the base class. See
+ * the general documentation of this class for further information.
*
- * In addition to the same
- * parameters as found in the
- * respective function of the
- * DataOut class, the first
- * parameter denotes into how
- * many intervals the angular
- * (rotation) variable is to be
- * subdivided.
+ * In addition to the same parameters as found in the respective function of
+ * the DataOut class, the first parameter denotes into how many intervals
+ * the angular (rotation) variable is to be subdivided.
*
- * The function supports
- * multithreading, if deal.II is
- * compiled in multithreading
- * mode.
+ * The function supports multithreading, if deal.II is compiled in
+ * multithreading mode.
*/
virtual void build_patches (const unsigned int n_patches_per_circle,
const unsigned int n_subdivisions = 0);
/**
- * Return the first cell which we
- * want output for. The default
- * implementation returns the
- * first @ref GlossActive "active cell",
- * but you might want to
- * return other cells in a
- * derived class.
+ * Return the first cell which we want output for. The default
+ * implementation returns the first @ref GlossActive "active cell", but you
+ * might want to return other cells in a derived class.
*/
virtual cell_iterator first_cell ();
/**
- * Return the next cell after @p cell which
- * we want output for.
- * If there are no more cells,
- * <tt>dofs->end()</tt> shall be returned.
+ * Return the next cell after @p cell which we want output for. If there are
+ * no more cells, <tt>dofs->end()</tt> shall be returned.
*
- * The default
- * implementation returns the next
- * active cell, but you might want
- * to return other cells in a derived
- * class. Note that the default
- * implementation assumes that
- * the given @p cell is active, which
- * is guaranteed as long as @p first_cell
- * is also used from the default
- * implementation. Overloading only one
- * of the two functions might not be
- * a good idea.
+ * The default implementation returns the next active cell, but you might
+ * want to return other cells in a derived class. Note that the default
+ * implementation assumes that the given @p cell is active, which is
+ * guaranteed as long as @p first_cell is also used from the default
+ * implementation. Overloading only one of the two functions might not be a
+ * good idea.
*/
virtual cell_iterator next_cell (const cell_iterator &cell);
private:
/**
- * Builds every @p n_threads's
- * patch. This function may be
- * called in parallel.
- * If multithreading is not
- * used, the function is called
- * once and generates all patches.
+ * Builds every @p n_threads's patch. This function may be called in
+ * parallel. If multithreading is not used, the function is called once and
+ * generates all patches.
*/
void
build_one_patch (const cell_iterator *cell,
template <int dim, int spacedim> class DoFHandler;
/**
- * This class is used to stack the output from several computations
- * into one output file by stacking the data sets in another
- * co-ordinate direction orthogonal to the space directions. The most
- * common use is to stack the results of several time steps into one
- * space-time output file, or for example to connect the results of
- * solutions of a parameter dependent equation for several parameter
- * value together into one. The interface is mostly modelled after the
- * DataOut class, see there for some more documentation.
+ * This class is used to stack the output from several computations into one
+ * output file by stacking the data sets in another co-ordinate direction
+ * orthogonal to the space directions. The most common use is to stack the
+ * results of several time steps into one space-time output file, or for
+ * example to connect the results of solutions of a parameter dependent
+ * equation for several parameter value together into one. The interface is
+ * mostly modelled after the DataOut class, see there for some more
+ * documentation.
*
- * We will explain the concept for a time dependent problem, but
- * instead of the time any parameter can be substituted. In our
- * example, a solution of an equation is computed for each discrete
- * time level. This is then added to an object of the present class
- * and after all time levels are added, a space-time plot will be
- * written in any of the output formats supported by the base
- * class. Upon output, the (spatial) solution on each time level is
- * extended into the time direction by writing it twice, once for the
- * time level itself and once for a time equal to the time level minus
- * a given time step. These two copies are connected, to form a
- * space-time slab, with constant values in time.
+ * We will explain the concept for a time dependent problem, but instead of
+ * the time any parameter can be substituted. In our example, a solution of an
+ * equation is computed for each discrete time level. This is then added to an
+ * object of the present class and after all time levels are added, a space-
+ * time plot will be written in any of the output formats supported by the
+ * base class. Upon output, the (spatial) solution on each time level is
+ * extended into the time direction by writing it twice, once for the time
+ * level itself and once for a time equal to the time level minus a given time
+ * step. These two copies are connected, to form a space-time slab, with
+ * constant values in time.
*
- * Due to the piecewise constant output in time, the written solution
- * will in general be discontinuous at discrete time levels, but the
- * output is still sufficient in most cases. More sophisticated
- * interpolations in time may be added in the future.
+ * Due to the piecewise constant output in time, the written solution will in
+ * general be discontinuous at discrete time levels, but the output is still
+ * sufficient in most cases. More sophisticated interpolations in time may be
+ * added in the future.
*
*
* <h3>Example of Use</h3>
*
- * The following little example shall illustrate the different steps
- * of use of this class. It is assumed that the finite element used is
- * composed of two components, @p u and @p v, that the solution vector
- * is named @p solution and that a vector @p error is computed which
- * contains an error indicator for each spatial cell.
+ * The following little example shall illustrate the different steps of use of
+ * this class. It is assumed that the finite element used is composed of two
+ * components, @p u and @p v, that the solution vector is named @p solution
+ * and that a vector @p error is computed which contains an error indicator
+ * for each spatial cell.
*
- * Note that unlike for the DataOut class it is necessary to first
- * declare data vectors and the names of the components before first
- * use. This is because on all time levels the same data should be
- * present to produce reasonable time-space output. The output is
- * generated with two subdivisions in each space and time direction,
- * which is suitable for quadratic finite elements in space, for
- * example.
+ * Note that unlike for the DataOut class it is necessary to first declare
+ * data vectors and the names of the components before first use. This is
+ * because on all time levels the same data should be present to produce
+ * reasonable time-space output. The output is generated with two subdivisions
+ * in each space and time direction, which is suitable for quadratic finite
+ * elements in space, for example.
*
* @code
* DataOutStack<dim> data_out_stack;
{
public:
/**
- * Data type declaring the two types
- * of vectors which are used in this
+ * Data type declaring the two types of vectors which are used in this
* class.
*/
enum VectorType { cell_vector, dof_vector };
/**
- * Destructor. Only declared to make
- * it @p virtual.
+ * Destructor. Only declared to make it @p virtual.
*/
virtual ~DataOutStack ();
/**
- * Start the next set of data for a
- * specific parameter value. The argument
- * @p parameter_step denotes the interval
- * (in backward direction, counted from
- * @p parameter_value) with which the
- * output will be extended in parameter
- * direction, i.e. orthogonal to the
- * space directions.
+ * Start the next set of data for a specific parameter value. The argument
+ * @p parameter_step denotes the interval (in backward direction, counted
+ * from @p parameter_value) with which the output will be extended in
+ * parameter direction, i.e. orthogonal to the space directions.
*/
void new_parameter_value (const double parameter_value,
const double parameter_step);
/**
- * Attach the DoF handler for the
- * grid and data associated with the
- * parameter previously set by
- * @p new_parameter_value.
+ * Attach the DoF handler for the grid and data associated with the
+ * parameter previously set by @p new_parameter_value.
*
- * This has to happen before adding
- * data vectors for the present
- * parameter value.
+ * This has to happen before adding data vectors for the present parameter
+ * value.
*/
void attach_dof_handler (const DH &dof_handler);
/**
- * Declare a data vector. The @p vector_type
- * argument determines whether the data
- * vector will be considered as DoF or
- * cell data.
+ * Declare a data vector. The @p vector_type argument determines whether the
+ * data vector will be considered as DoF or cell data.
*
- * This version may be called if the
- * finite element presently used by the
- * DoFHandler (and previously attached
- * to this object) has only one component
- * and therefore only one name needs to
- * be given.
+ * This version may be called if the finite element presently used by the
+ * DoFHandler (and previously attached to this object) has only one
+ * component and therefore only one name needs to be given.
*/
void declare_data_vector (const std::string &name,
const VectorType vector_type);
/**
- * Declare a data vector. The @p vector_type
- * argument determines whether the data
- * vector will be considered as DoF or
- * cell data.
+ * Declare a data vector. The @p vector_type argument determines whether the
+ * data vector will be considered as DoF or cell data.
*
- * This version must be called if the
- * finite element presently used by the
- * DoFHandler (and previously attached
- * to this object) has more than one
- * component and therefore more than one
- * name needs to be given. However, you
- * can also call this function with a
- * <tt>std::vector@<std::string@></tt> containing only one
- * element if the finite element has
- * only one component.
+ * This version must be called if the finite element presently used by the
+ * DoFHandler (and previously attached to this object) has more than one
+ * component and therefore more than one name needs to be given. However,
+ * you can also call this function with a
+ * <tt>std::vector@<std::string@></tt> containing only one element if the
+ * finite element has only one component.
*/
void declare_data_vector (const std::vector<std::string> &name,
const VectorType vector_type);
/**
- * Add a data vector for the presently
- * set value of the parameter.
+ * Add a data vector for the presently set value of the parameter.
*
- * This version may be called if the
- * finite element presently used by the
- * DoFHandler (and previously attached
- * to this object) has only one component
- * and therefore only one name needs to
- * be given.
+ * This version may be called if the finite element presently used by the
+ * DoFHandler (and previously attached to this object) has only one
+ * component and therefore only one name needs to be given.
*
- * If @p vec is a vector with
- * multiple components this
- * function will generate
- * distinct names for all
- * components by appending an
- * underscore and the number of
- * each component to @p name
+ * If @p vec is a vector with multiple components this function will
+ * generate distinct names for all components by appending an underscore and
+ * the number of each component to @p name
*
- * The data vector must have been
- * registered using the @p declare_data_vector
- * function before actually using it the
- * first time.
+ * The data vector must have been registered using the @p
+ * declare_data_vector function before actually using it the first time.
*
- * Note that a copy of this vector is
- * stored until @p finish_parameter_value
- * is called the next time, so if you are
- * short of memory you may want to call
- * this function only after all
- * computations involving large matrices
+ * Note that a copy of this vector is stored until @p finish_parameter_value
+ * is called the next time, so if you are short of memory you may want to
+ * call this function only after all computations involving large matrices
* are already done.
*/
template <typename number>
const std::string &name);
/**
- * Add a data vector for the presently
- * set value of the parameter.
+ * Add a data vector for the presently set value of the parameter.
*
- * This version must be called if the
- * finite element presently used by the
- * DoFHandler (and previously attached
- * to this object) has more than one
- * component and therefore more than one
- * name needs to be given. However, you
- * can also call this function with a
- * <tt>std::vector@<std::string@></tt> containing only one
- * element if the finite element has
- * only one component.
+ * This version must be called if the finite element presently used by the
+ * DoFHandler (and previously attached to this object) has more than one
+ * component and therefore more than one name needs to be given. However,
+ * you can also call this function with a
+ * <tt>std::vector@<std::string@></tt> containing only one element if the
+ * finite element has only one component.
*
- * The data vector must have been
- * registered using the @p declare_data_vector
- * function before actually using it the
- * first time.
+ * The data vector must have been registered using the @p
+ * declare_data_vector function before actually using it the first time.
*
- * Note that a copy of this vector is
- * stored until @p finish_parameter_value
- * is called the next time, so if you are
- * short of memory you may want to call
- * this function only after all
- * computations involving large matrices
+ * Note that a copy of this vector is stored until @p finish_parameter_value
+ * is called the next time, so if you are short of memory you may want to
+ * call this function only after all computations involving large matrices
* are already done.
*/
template <typename number>
const std::vector<std::string> &names);
/**
- * Actually build the patches for output
- * by the base classes from the data
- * stored in the data vectors and using
- * the previously attached DoFHandler
+ * Actually build the patches for output by the base classes from the data
+ * stored in the data vectors and using the previously attached DoFHandler
* object.
*
- * By @p n_subdivisions you can decide
- * into how many subdivisions (in each
- * space and parameter direction) each
- * patch is divided. This is useful
- * if higher order elements are used.
- * Note however, that the number of
- * subdivisions in parameter direction
- * is always the same as the one is space
- * direction for technical reasons.
+ * By @p n_subdivisions you can decide into how many subdivisions (in each
+ * space and parameter direction) each patch is divided. This is useful if
+ * higher order elements are used. Note however, that the number of
+ * subdivisions in parameter direction is always the same as the one is
+ * space direction for technical reasons.
*/
void build_patches (const unsigned int n_subdivisions = 0);
/**
- * Release all data that is no
- * more needed once @p build_patches
- * was called and all other transactions
- * for a given parameter value are done.
+ * Release all data that is no more needed once @p build_patches was called
+ * and all other transactions for a given parameter value are done.
*
* Couterpart of @p new_parameter_value.
*/
void finish_parameter_value ();
/**
- * Clear all data presently stored
- * in this object.
+ * Clear all data presently stored in this object.
*/
void clear ();
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
double parameter;
/**
- * Present parameter step, i.e.
- * length of the parameter interval
- * to be written next.
+ * Present parameter step, i.e. length of the parameter interval to be
+ * written next.
*/
double parameter_step;
/**
- * DoF handler to be used for the data
- * corresponding to the present parameter
- * value.
+ * DoF handler to be used for the data corresponding to the present
+ * parameter value.
*/
SmartPointer<const DH,DataOutStack<dim,spacedim,DH> > dof_handler;
/**
- * List of patches of all past and
- * present parameter value data sets.
+ * List of patches of all past and present parameter value data sets.
*/
std::vector< dealii::DataOutBase::Patch<dim+1,dim+1> > patches;
/**
- * Structure holding data vectors
- * (cell and dof data) for the present
+ * Structure holding data vectors (cell and dof data) for the present
* parameter value.
*/
struct DataVector
Vector<double> data;
/**
- * Names of the different components
- * within each such data set.
+ * Names of the different components within each such data set.
*/
std::vector<std::string> names;
/**
- * Determine an estimate for
- * the memory consumption (in
- * bytes) of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
};
std::vector<DataVector> cell_data;
/**
- * This is the function through
- * which derived classes propagate
- * preprocessed data in the form of
- * Patch structures (declared in
- * the base class DataOutBase) to
- * the actual output function.
+ * This is the function through which derived classes propagate preprocessed
+ * data in the form of Patch structures (declared in the base class
+ * DataOutBase) to the actual output function.
*/
virtual const std::vector< dealii::DataOutBase::Patch<dim+1,dim+1> > & get_patches () const;
/**
- * Virtual function through
- * which the names of data sets are
- * obtained by the output functions
- * of the base class.
+ * Virtual function through which the names of data sets are obtained by the
+ * output functions of the base class.
*/
virtual std::vector<std::string> get_dataset_names () const;
};
/**
- * This class provides an interface to compute derived quantities from
- * a solution that can then be output in graphical formats for visualization,
+ * This class provides an interface to compute derived quantities from a
+ * solution that can then be output in graphical formats for visualization,
* using facilities such as the DataOut class.
*
* For the (graphical) output of a FE solution one frequently wants to include
* derived quantities, which are calculated from the values of the solution
* and possibly the first and second derivates of the solution. Examples are
- * the calculation of Mach numbers from velocity and density in supersonic flow
- * computations, or the computation of the magnitude of a complex-valued
+ * the calculation of Mach numbers from velocity and density in supersonic
+ * flow computations, or the computation of the magnitude of a complex-valued
* solution as demonstrated in step-29. Other uses are shown in step-32 and
- * step-33. This class offers the interface to perform such
- * postprocessing. Given the values and derivatives of the solution at those
- * points where we want to generated output, the functions of this class can
- * be overloaded to compute new quantities.
+ * step-33. This class offers the interface to perform such postprocessing.
+ * Given the values and derivatives of the solution at those points where we
+ * want to generated output, the functions of this class can be overloaded to
+ * compute new quantities.
*
- * A data vector and an object of a class derived from the current one can
- * be given to the DataOut::add_data_vector() function (and similarly for
- * DataOutRotation and DataOutFaces). This will cause
- * DataOut::build_patches() to compute the derived quantities instead of using
- * the data provided by the data vector (typically the solution vector). Note
- * that the DataPostprocessor object (i.e., in reality the object of your derived
- * class) has to live until the DataOut object is destroyed as the latter keeps
- * a pointer to the former and will complain if the object pointed to is
+ * A data vector and an object of a class derived from the current one can be
+ * given to the DataOut::add_data_vector() function (and similarly for
+ * DataOutRotation and DataOutFaces). This will cause DataOut::build_patches()
+ * to compute the derived quantities instead of using the data provided by the
+ * data vector (typically the solution vector). Note that the
+ * DataPostprocessor object (i.e., in reality the object of your derived
+ * class) has to live until the DataOut object is destroyed as the latter
+ * keeps a pointer to the former and will complain if the object pointed to is
* destroyed while the latter still has a pointer to it. If both the data
- * postprocessor and DataOut objects are local variables of a function
- * (as they are, for example, in step-29), then you can avoid this
- * error by declaring the data postprocessor variable before the DataOut
- * variable as objects are destroyed in reverse order of declaration.
+ * postprocessor and DataOut objects are local variables of a function (as
+ * they are, for example, in step-29), then you can avoid this error by
+ * declaring the data postprocessor variable before the DataOut variable as
+ * objects are destroyed in reverse order of declaration.
*
- * In order not to perform needless calculations, DataPostprocessor
- * has to provide information which input data is needed for the
- * calculation of the derived quantities, i.e. whether it needs the
- * values, the first derivative and/or the second derivative of the
- * provided data. DataPostprocessor objects which are used in
- * combination with a DataOutFaces object can also ask for the normal
- * vectors at each point. The information which data is needed has to
- * be provided via the UpdateFlags returned by the virtual function
- * get_needed_update_flags(). It is your responsibility to use only
- * those values which were updated in the calculation of derived
- * quantities. The DataOut object will provide references to the
- * requested data in the call to compute_derived_quantities_scalar()
- * or compute_derived_quantities_vector() (DataOut decides which of
- * the two functions to call depending on whether the finite element
- * in use has only a single, or multiple vector components; note that
- * this is only determined by the number of components in the finite
- * element in use, and not by whether the data computed by a class
- * derived from the current one is scalar or vector valued).
+ * In order not to perform needless calculations, DataPostprocessor has to
+ * provide information which input data is needed for the calculation of the
+ * derived quantities, i.e. whether it needs the values, the first derivative
+ * and/or the second derivative of the provided data. DataPostprocessor
+ * objects which are used in combination with a DataOutFaces object can also
+ * ask for the normal vectors at each point. The information which data is
+ * needed has to be provided via the UpdateFlags returned by the virtual
+ * function get_needed_update_flags(). It is your responsibility to use only
+ * those values which were updated in the calculation of derived quantities.
+ * The DataOut object will provide references to the requested data in the
+ * call to compute_derived_quantities_scalar() or
+ * compute_derived_quantities_vector() (DataOut decides which of the two
+ * functions to call depending on whether the finite element in use has only a
+ * single, or multiple vector components; note that this is only determined by
+ * the number of components in the finite element in use, and not by whether
+ * the data computed by a class derived from the current one is scalar or
+ * vector valued).
*
- * Furthermore, derived classes have to implement the get_names()
- * function, where the number of output variables returned
- * by the latter function has to match the size of the vector returned by the
- * former. Furthermore, this number has to match the number of computed
- * quantities, of course.
+ * Furthermore, derived classes have to implement the get_names() function,
+ * where the number of output variables returned by the latter function has to
+ * match the size of the vector returned by the former. Furthermore, this
+ * number has to match the number of computed quantities, of course.
*
*
* <h3>Use in simpler cases</h3>
*
- * Deriving from the current class allows to implement very general postprocessors.
- * For example, in the step-32 program, we implement a postprocessor that
- * takes a solution that consists of velocity, pressure and temperature (dim+2
- * components) and computes a variety of output quantities, some of which
- * are vector valued and some of which are scalar. On the other hand,
- * in step-29 we implement a postprocessor that only computes the magnitude
- * of a complex number given by a two-component finite element. It seems silly
- * to have to implement four virtual functions for this
- * (compute_derived_quantities_scalar() or compute_derived_quantities_vector(),
- * get_names(), get_update_flags() and get_data_component_interpretation()).
+ * Deriving from the current class allows to implement very general
+ * postprocessors. For example, in the step-32 program, we implement a
+ * postprocessor that takes a solution that consists of velocity, pressure and
+ * temperature (dim+2 components) and computes a variety of output quantities,
+ * some of which are vector valued and some of which are scalar. On the other
+ * hand, in step-29 we implement a postprocessor that only computes the
+ * magnitude of a complex number given by a two-component finite element. It
+ * seems silly to have to implement four virtual functions for this
+ * (compute_derived_quantities_scalar() or
+ * compute_derived_quantities_vector(), get_names(), get_update_flags() and
+ * get_data_component_interpretation()).
*
* To this end there are two classes DataPostprocessorScalar and
- * DataPostprocessorVector that are meant to be used if the output quantity
- * is either a single scalar or a single vector (here used meaning to have
+ * DataPostprocessorVector that are meant to be used if the output quantity is
+ * either a single scalar or a single vector (here used meaning to have
* exactly dim components). When using these classes, one only has to write a
* constructor that passes the name of the output variable and the update
- * flags to the constructor of the base class and overload the function
- * that actually computes the results.
+ * flags to the constructor of the base class and overload the function that
+ * actually computes the results.
*
* @ingroup output
* @author Tobias Leicht, 2007
{
public:
/**
- * Virtual desctructor for safety. Does not
- * do anything.
+ * Virtual desctructor for safety. Does not do anything.
*/
virtual ~DataPostprocessor ();
/**
* @deprecated
*
- * This function only exists for backward
- * compatibility as this is the interface
- * provided by previous versions of the
- * library. The default implementation of
- * the other function of same name below
- * calls this function by simply dropping
- * the argument that denotes the
- * evaluation points. Since this function
- * might at one point go away, you should
+ * This function only exists for backward compatibility as this is the
+ * interface provided by previous versions of the library. The default
+ * implementation of the other function of same name below calls this
+ * function by simply dropping the argument that denotes the evaluation
+ * points. Since this function might at one point go away, you should
* overload the other function instead.
*/
virtual
std::vector<Vector<double> > &computed_quantities) const DEAL_II_DEPRECATED;
/**
- * This is the main function which actually
- * performs the postprocessing. The last
- * argument is a reference to the
- * postprocessed data which has correct
- * size already and must be filled by this
- * function. @p uh is a reference to a
- * vector of data values at all points, @p
- * duh the same for gradients, @p dduh for
- * second derivatives and @p normals is a
- * reference to the normal vectors. Note,
- * that the last four references will only
- * contain valid data, if the respective
- * flags are returned by @p
- * get_needed_update_flags, otherwise those
- * vectors will be in an unspecified
- * state. @p normals will always be an
- * empty vector when working on cells, not
- * on faces.
+ * This is the main function which actually performs the postprocessing. The
+ * last argument is a reference to the postprocessed data which has correct
+ * size already and must be filled by this function. @p uh is a reference to
+ * a vector of data values at all points, @p duh the same for gradients, @p
+ * dduh for second derivatives and @p normals is a reference to the normal
+ * vectors. Note, that the last four references will only contain valid
+ * data, if the respective flags are returned by @p get_needed_update_flags,
+ * otherwise those vectors will be in an unspecified state. @p normals will
+ * always be an empty vector when working on cells, not on faces.
*
- * This function is called when
- * the original data vector
- * represents scalar data,
- * i.e. the finite element in use
- * has only a single vector
- * component.
+ * This function is called when the original data vector represents scalar
+ * data, i.e. the finite element in use has only a single vector component.
*/
virtual
void
/**
* @deprecated
*
- * This function only exists for backward
- * compatibility as this is the interface
- * provided by previous versions of the
- * library. The default implementation of
- * the other function of same name below
- * calls this function by simply dropping
- * the argument that denotes the
- * evaluation points. Since this function
- * might at one point go away, you should
+ * This function only exists for backward compatibility as this is the
+ * interface provided by previous versions of the library. The default
+ * implementation of the other function of same name below calls this
+ * function by simply dropping the argument that denotes the evaluation
+ * points. Since this function might at one point go away, you should
* overload the other function instead.
*/
virtual
std::vector<Vector<double> > &computed_quantities) const DEAL_II_DEPRECATED;
/**
- * Same as the
- * compute_derived_quantities_scalar()
- * function, but this function is called
- * when the original data vector
- * represents vector data, i.e. the
- * finite element in use has multiple
- * vector components.
+ * Same as the compute_derived_quantities_scalar() function, but this
+ * function is called when the original data vector represents vector data,
+ * i.e. the finite element in use has multiple vector components.
*/
virtual
void
std::vector<Vector<double> > &computed_quantities) const;
/**
- * Return the vector of strings describing
- * the names of the computed quantities.
+ * Return the vector of strings describing the names of the computed
+ * quantities.
*/
virtual std::vector<std::string> get_names () const = 0;
/**
- * This functions returns
- * information about how the
- * individual components of
- * output files that consist of
- * more than one data set are to
- * be interpreted.
+ * This functions returns information about how the individual components of
+ * output files that consist of more than one data set are to be
+ * interpreted.
*
- * For example, if one has a finite
- * element for the Stokes equations in
- * 2d, representing components (u,v,p),
- * one would like to indicate that the
- * first two, u and v, represent a
- * logical vector so that later on when
- * we generate graphical output we can
- * hand them off to a visualization
- * program that will automatically know
- * to render them as a vector field,
- * rather than as two separate and
- * independent scalar fields.
+ * For example, if one has a finite element for the Stokes equations in 2d,
+ * representing components (u,v,p), one would like to indicate that the
+ * first two, u and v, represent a logical vector so that later on when we
+ * generate graphical output we can hand them off to a visualization program
+ * that will automatically know to render them as a vector field, rather
+ * than as two separate and independent scalar fields.
*
- * The default implementation of this
- * function returns a vector of values
- * DataComponentInterpretation::component_is_scalar,
- * indicating that all output components
- * are independent scalar
- * fields. However, if a derived class
- * produces data that represents vectors,
- * it may return a vector that contains
- * values
- * DataComponentInterpretation::component_is_part_of_vector. In
- * the example above, one would return a
- * vector with components
+ * The default implementation of this function returns a vector of values
+ * DataComponentInterpretation::component_is_scalar, indicating that all
+ * output components are independent scalar fields. However, if a derived
+ * class produces data that represents vectors, it may return a vector that
+ * contains values DataComponentInterpretation::component_is_part_of_vector.
+ * In the example above, one would return a vector with components
* (DataComponentInterpretation::component_is_part_of_vector,
* DataComponentInterpretation::component_is_part_of_vector,
- * DataComponentInterpretation::component_is_scalar)
- * for (u,v,p).
+ * DataComponentInterpretation::component_is_scalar) for (u,v,p).
*/
virtual
std::vector<DataComponentInterpretation::DataComponentInterpretation>
get_data_component_interpretation () const;
/**
- * Return, which data has to be provided to
- * compute the derived quantities. This has
- * to be a combination of @p update_values,
- * @p update_gradients and @p
- * update_hessians. If the
- * DataPostprocessor is to be used in
- * combination with DataOutFaces, you may
- * also ask for a update of normals via the
- * @p update_normal_vectors flag.
+ * Return, which data has to be provided to compute the derived quantities.
+ * This has to be a combination of @p update_values, @p update_gradients and
+ * @p update_hessians. If the DataPostprocessor is to be used in combination
+ * with DataOutFaces, you may also ask for a update of normals via the @p
+ * update_normal_vectors flag.
*/
virtual UpdateFlags get_needed_update_flags () const = 0;
};
/**
- * This class provides a simpler interface to the functionality offered by
- * the DataPostprocessor class in case one wants to compute only a
- * single scalar quantity from the finite element field passed to the
- * DataOut class. For this particular case, it is clear what the returned
- * value of DataPostprocessor::get_data_component_interpretation() should
- * be and we pass the values returned by get_names() and get_needed_update_flags()
- * to the constructor so that derived classes do not have to implement these
+ * This class provides a simpler interface to the functionality offered by the
+ * DataPostprocessor class in case one wants to compute only a single scalar
+ * quantity from the finite element field passed to the DataOut class. For
+ * this particular case, it is clear what the returned value of
+ * DataPostprocessor::get_data_component_interpretation() should be and we
+ * pass the values returned by get_names() and get_needed_update_flags() to
+ * the constructor so that derived classes do not have to implement these
* functions by hand.
*
* All derived classes have to do is implement a constructor and overload
{
public:
/**
- * Constructor. Take the name of the single scalar variable
- * computed by classes derived from the current one, as well
- * as the update flags necessary to compute this quantity.
+ * Constructor. Take the name of the single scalar variable computed by
+ * classes derived from the current one, as well as the update flags
+ * necessary to compute this quantity.
*
- * @param name The name by which the scalar variable
- * computed by this class should be made available in
- * graphical output files.
- * @param update_flags This has
- * to be a combination of @p update_values,
- * @p update_gradients and @p
- * update_hessians. If the
- * DataPostprocessor is to be used in
- * combination with DataOutFaces, you may
- * also ask for a update of normals via the
- * @p update_normal_vectors flag.
- **/
+ * @param name The name by which the scalar variable computed by this class
+ * should be made available in graphical output files.
+ * @param update_flags This has to be a combination of @p update_values, @p
+ * update_gradients and @p update_hessians. If the DataPostprocessor is to
+ * be used in combination with DataOutFaces, you may also ask for a update
+ * of normals via the @p update_normal_vectors flag.
+ */
DataPostprocessorScalar (const std::string &name,
const UpdateFlags update_flags);
/**
- * Return the vector of strings describing
- * the names of the computed quantities.
- * Given the purpose of this class, this
- * is a vector with a single entry equal
- * to the name given to the constructor.
+ * Return the vector of strings describing the names of the computed
+ * quantities. Given the purpose of this class, this is a vector with a
+ * single entry equal to the name given to the constructor.
*/
virtual std::vector<std::string> get_names () const;
/**
- * This functions returns
- * information about how the
- * individual components of
- * output files that consist of
- * more than one data set are to
- * be interpreted. Since the current
- * class is meant to be used for a
- * single scalar result variable,
- * the returned value is obviously
+ * This functions returns information about how the individual components of
+ * output files that consist of more than one data set are to be
+ * interpreted. Since the current class is meant to be used for a single
+ * scalar result variable, the returned value is obviously
* DataComponentInterpretation::component_is_scalar.
*/
virtual
get_data_component_interpretation () const;
/**
- * Return, which data has to be provided to
- * compute the derived quantities.
- * The flags returned here are the ones
- * passed to the constructor of this
+ * Return, which data has to be provided to compute the derived quantities.
+ * The flags returned here are the ones passed to the constructor of this
* class.
*/
virtual UpdateFlags get_needed_update_flags () const;
private:
/**
- * Copies of the two arguments given to the constructor of this
- * class.
+ * Copies of the two arguments given to the constructor of this class.
*/
const std::string name;
const UpdateFlags update_flags;
/**
- * This class provides a simpler interface to the functionality offered by
- * the DataPostprocessor class in case one wants to compute only a
- * single vector quantity (defined as having exactly dim components)
- * from the finite element field passed to the
- * DataOut class. For this particular case, it is clear what the returned
- * value of DataPostprocessor::get_data_component_interpretation() should
- * be and we pass the values returned by get_names() and get_needed_update_flags()
- * to the constructor so that derived classes do not have to implement these
+ * This class provides a simpler interface to the functionality offered by the
+ * DataPostprocessor class in case one wants to compute only a single vector
+ * quantity (defined as having exactly dim components) from the finite element
+ * field passed to the DataOut class. For this particular case, it is clear
+ * what the returned value of
+ * DataPostprocessor::get_data_component_interpretation() should be and we
+ * pass the values returned by get_names() and get_needed_update_flags() to
+ * the constructor so that derived classes do not have to implement these
* functions by hand.
*
* All derived classes have to do is implement a constructor and overload
* either DataPostprocessor::compute_derived_quantities_scalar() or
* DataPostprocessor::compute_derived_quantities_vector().
*
- * An example of how the closely related class DataPostprocessorScalar is
- * used can be found in step-29.
+ * An example of how the closely related class DataPostprocessorScalar is used
+ * can be found in step-29.
*
* @ingroup output
* @author Wolfgang Bangerth, 2011
{
public:
/**
- * Constructor. Take the name of the single vector variable
- * computed by classes derived from the current one, as well
- * as the update flags necessary to compute this quantity.
+ * Constructor. Take the name of the single vector variable computed by
+ * classes derived from the current one, as well as the update flags
+ * necessary to compute this quantity.
*
- * @param name The name by which the vector variable
- * computed by this class should be made available in
- * graphical output files.
- * @param update_flags This has
- * to be a combination of @p update_values,
- * @p update_gradients and @p
- * update_hessians. If the
- * DataPostprocessor is to be used in
- * combination with DataOutFaces, you may
- * also ask for a update of normals via the
- * @p update_normal_vectors flag.
- **/
+ * @param name The name by which the vector variable computed by this class
+ * should be made available in graphical output files.
+ * @param update_flags This has to be a combination of @p update_values, @p
+ * update_gradients and @p update_hessians. If the DataPostprocessor is to
+ * be used in combination with DataOutFaces, you may also ask for a update
+ * of normals via the @p update_normal_vectors flag.
+ */
DataPostprocessorVector (const std::string &name,
const UpdateFlags update_flags);
/**
- * Return the vector of strings describing
- * the names of the computed quantities.
- * Given the purpose of this class, this
- * is a vector with dim entries all equal
- * to the name given to the constructor.
+ * Return the vector of strings describing the names of the computed
+ * quantities. Given the purpose of this class, this is a vector with dim
+ * entries all equal to the name given to the constructor.
*/
virtual std::vector<std::string> get_names () const;
/**
- * This functions returns
- * information about how the
- * individual components of
- * output files that consist of
- * more than one data set are to
- * be interpreted. Since the current
- * class is meant to be used for a
- * single vector result variable,
- * the returned value is obviously
- * DataComponentInterpretation::component_is_part
- * repeated dim times.
+ * This functions returns information about how the individual components of
+ * output files that consist of more than one data set are to be
+ * interpreted. Since the current class is meant to be used for a single
+ * vector result variable, the returned value is obviously
+ * DataComponentInterpretation::component_is_part repeated dim times.
*/
virtual
std::vector<DataComponentInterpretation::DataComponentInterpretation>
get_data_component_interpretation () const;
/**
- * Return which data has to be provided to
- * compute the derived quantities.
- * The flags returned here are the ones
- * passed to the constructor of this
+ * Return which data has to be provided to compute the derived quantities.
+ * The flags returned here are the ones passed to the constructor of this
* class.
*/
virtual UpdateFlags get_needed_update_flags () const;
private:
/**
- * Copies of the two arguments given to the constructor of this
- * class.
+ * Copies of the two arguments given to the constructor of this class.
*/
const std::string name;
const UpdateFlags update_flags;
/**
- * This namespace provides functions that compute a cell-wise approximation of the norm of a
- * derivative of a finite element field by taking difference quotients
- * between neighboring cells. This is a rather simple but efficient
- * form to get an error indicator, since it can be computed with
- * relatively little numerical effort and yet gives a reasonable
- * approximation.
+ * This namespace provides functions that compute a cell-wise approximation of
+ * the norm of a derivative of a finite element field by taking difference
+ * quotients between neighboring cells. This is a rather simple but efficient
+ * form to get an error indicator, since it can be computed with relatively
+ * little numerical effort and yet gives a reasonable approximation.
*
- * The way the difference quotients are computed on cell $K$ is the
- * following (here described for the approximation of the gradient of
- * a finite element field, but see below for higher derivatives): let
- * $K'$ be a neighboring cell, and let $y_{K'}=x_{K'}-x_K$ be the
- * distance vector between the centers of the two cells, then
- * $ \frac{u_h(x_{K'}) - u_h(x_K)}{ \|y_{K'}\| }$
- * is an approximation of the directional derivative
- * $ \nabla u(x_K) \cdot \frac{y_{K'}}{ \|y_{K'}\| }.$
- * By multiplying both terms by $\frac{y_{K'}}{ \|y_{K'}\| }$ from the
- * left and summing over all neighbors $K'$, we obtain
- * $ \sum_{K'} \left( \frac{y_{K'}}{ \|y_{K'}\|}
- * \frac{y_{K'}^T}{ \|y_{K'}\| } \right) \nabla u(x_K)
- * \approx
- * \sum_{K'} \left( \frac{y_{K'}}{ \|y_{K'}\|}
- * \frac{u_h(x_{K'}) - u_h(x_K)}{ \|y_{K'}\| } \right).$
+ * The way the difference quotients are computed on cell $K$ is the following
+ * (here described for the approximation of the gradient of a finite element
+ * field, but see below for higher derivatives): let $K'$ be a neighboring
+ * cell, and let $y_{K'}=x_{K'}-x_K$ be the distance vector between the
+ * centers of the two cells, then $ \frac{u_h(x_{K'}) - u_h(x_K)}{ \|y_{K'}\|
+ * }$ is an approximation of the directional derivative $ \nabla u(x_K) \cdot
+ * \frac{y_{K'}}{ \|y_{K'}\| }.$ By multiplying both terms by $\frac{y_{K'}}{
+ * \|y_{K'}\| }$ from the left and summing over all neighbors $K'$, we obtain
+ * $ \sum_{K'} \left( \frac{y_{K'}}{ \|y_{K'}\|} \frac{y_{K'}^T}{ \|y_{K'}\| }
+ * \right) \nabla u(x_K) \approx \sum_{K'} \left( \frac{y_{K'}}{ \|y_{K'}\|}
+ * \frac{u_h(x_{K'}) - u_h(x_K)}{ \|y_{K'}\| } \right).$
*
- * Thus, if the matrix
- * $ Y = \sum_{K'} \left( \frac{y_{K'}}{\|y_{K'}\|}
- * \frac{y_{K'}^T}{ \|y_{K'}\| } \right)$ is
- * regular (which is the case when the vectors $y_{K'}$ to all neighbors span
- * the whole space), we can obtain an approximation to the true gradient by
- * $ \nabla u(x_K)
- * \approx
- * Y^{-1} \sum_{K'} \left( \frac{y_{K'}}{\|y_{K'}\|}
- * \frac{u_h(x_{K'}) - u_h(x_K)}{ \|y_{K'}\| }
- * \right).$
- * This is a quantity that is easily computed. The value returned for
- * each cell when calling the @p approximate_gradient function of
- * this class is the $l_2$ norm of this approximation to the
- * gradient. To make this a useful quantity, you may want to scale
- * each element by the correct power of the respective cell size.
+ * Thus, if the matrix $ Y = \sum_{K'} \left( \frac{y_{K'}}{\|y_{K'}\|}
+ * \frac{y_{K'}^T}{ \|y_{K'}\| } \right)$ is regular (which is the case when
+ * the vectors $y_{K'}$ to all neighbors span the whole space), we can obtain
+ * an approximation to the true gradient by $ \nabla u(x_K) \approx Y^{-1}
+ * \sum_{K'} \left( \frac{y_{K'}}{\|y_{K'}\|} \frac{u_h(x_{K'}) - u_h(x_K)}{
+ * \|y_{K'}\| } \right).$ This is a quantity that is easily computed. The
+ * value returned for each cell when calling the @p approximate_gradient
+ * function of this class is the $l_2$ norm of this approximation to the
+ * gradient. To make this a useful quantity, you may want to scale each
+ * element by the correct power of the respective cell size.
*
- * The computation of this quantity must fail if a cell has only
- * neighbors for which the direction vectors $y_K$ do not span the
- * whole space, since then the matrix $Y$ is no longer invertible. If
- * this happens, you will get an error similar to this one:
+ * The computation of this quantity must fail if a cell has only neighbors for
+ * which the direction vectors $y_K$ do not span the whole space, since then
+ * the matrix $Y$ is no longer invertible. If this happens, you will get an
+ * error similar to this one:
* @code
* --------------------------------------------------------
* An error occurred in line <749> of file <source/numerics/derivative_approximation.cc> in function
* (none)
* --------------------------------------------------------
* @endcode
- * As can easily be verified, this can only happen on very
- * coarse grids, when some cells and all their neighbors have not been
- * refined even once. You should therefore only call the functions of
- * this class if all cells are at least once refined. In practice this
- * is not much of a restriction.
+ * As can easily be verified, this can only happen on very coarse grids, when
+ * some cells and all their neighbors have not been refined even once. You
+ * should therefore only call the functions of this class if all cells are at
+ * least once refined. In practice this is not much of a restriction.
*
*
* <h3>Approximation of higher derivatives</h3>
*
- * Similar to the reasoning above, approximations to higher
- * derivatives can be computed in a similar fashion. For example, the
- * tensor of second derivatives is approximated by the formula
- * $ \nabla^2 u(x_K)
- * \approx
- * Y^{-1}
- * \sum_{K'}
- * \left(
- * \frac{y_{K'}}{\|y_{K'}\|} \otimes
- * \frac{\nabla u_h(x_{K'}) - \nabla u_h(x_K)}{ \|y_{K'}\| }
- * \right),
- * $
- * where $\otimes$ denotes the outer product of two vectors. Note that
- * unlike the true tensor of second derivatives, its approximation is
- * not necessarily symmetric. This is due to the fact that in the
- * derivation, it is not clear whether we shall consider as projected
- * second derivative the term $\nabla^2 u y_{KK'}$ or $y_{KK'}^T
- * \nabla^2 u$. Depending on which choice we take, we obtain one
- * approximation of the tensor of second derivatives or its
- * transpose. To avoid this ambiguity, as result we take the
- * symmetrized form, which is the mean value of the approximation and
- * its transpose.
+ * Similar to the reasoning above, approximations to higher derivatives can be
+ * computed in a similar fashion. For example, the tensor of second
+ * derivatives is approximated by the formula $ \nabla^2 u(x_K) \approx Y^{-1}
+ * \sum_{K'} \left( \frac{y_{K'}}{\|y_{K'}\|} \otimes \frac{\nabla u_h(x_{K'})
+ * - \nabla u_h(x_K)}{ \|y_{K'}\| } \right), $ where $\otimes$ denotes the
+ * outer product of two vectors. Note that unlike the true tensor of second
+ * derivatives, its approximation is not necessarily symmetric. This is due to
+ * the fact that in the derivation, it is not clear whether we shall consider
+ * as projected second derivative the term $\nabla^2 u y_{KK'}$ or $y_{KK'}^T
+ * \nabla^2 u$. Depending on which choice we take, we obtain one approximation
+ * of the tensor of second derivatives or its transpose. To avoid this
+ * ambiguity, as result we take the symmetrized form, which is the mean value
+ * of the approximation and its transpose.
*
- * The returned value on each cell is the spectral norm of the
- * approximated tensor of second derivatives, i.e. the largest
- * eigenvalue by absolute value. This equals the largest curvature of
- * the finite element field at each cell, and the spectral norm is the
- * matrix norm associated to the $l_2$ vector norm.
+ * The returned value on each cell is the spectral norm of the approximated
+ * tensor of second derivatives, i.e. the largest eigenvalue by absolute
+ * value. This equals the largest curvature of the finite element field at
+ * each cell, and the spectral norm is the matrix norm associated to the $l_2$
+ * vector norm.
*
- * Even higher than the second derivative can be obtained along the
- * same lines as exposed above.
+ * Even higher than the second derivative can be obtained along the same lines
+ * as exposed above.
*
*
* <h3>Refinement indicators based on the derivatives</h3>
*
- * If you would like to base a refinement criterion upon these
- * approximation of the derivatives, you will have to scale the results
- * of this class by an appropriate power of the mesh width. For
- * example, since
- * $\|u-u_h\|^2_{L_2} \le C h^2 \|\nabla u\|^2_{L_2}$, it might be the
- * right thing to scale the indicators as $\eta_K = h \|\nabla u\|_K$,
- * i.e. $\eta_K = h^{1+d/2} \|\nabla u\|_{\infty;K}$, i.e. the right
- * power is $1+d/2$.
+ * If you would like to base a refinement criterion upon these approximation
+ * of the derivatives, you will have to scale the results of this class by an
+ * appropriate power of the mesh width. For example, since $\|u-u_h\|^2_{L_2}
+ * \le C h^2 \|\nabla u\|^2_{L_2}$, it might be the right thing to scale the
+ * indicators as $\eta_K = h \|\nabla u\|_K$, i.e. $\eta_K = h^{1+d/2}
+ * \|\nabla u\|_{\infty;K}$, i.e. the right power is $1+d/2$.
*
- * Likewise, for the second derivative, one should choose a power of
- * the mesh size $h$ one higher than for the gradient.
+ * Likewise, for the second derivative, one should choose a power of the mesh
+ * size $h$ one higher than for the gradient.
*
*
* <h3>Implementation</h3>
*
- * The formulae for the computation of approximations to the gradient
- * and to the tensor of second derivatives shown above are very much
- * alike. The basic difference is that in one case the finite
- * difference quotient is a scalar, while in the other case it is a
- * vector. For higher derivatives, this would be a tensor of even
- * higher rank. We then have to form the outer product of this
- * difference quotient with the distance vector $y_{KK'}$, symmetrize
- * it, contract it with the matrix $Y^{-1}$ and compute its norm. To
- * make the implementation simpler and to allow for code reuse, all
- * these operations that are dependent on the actual order of the
- * derivatives to be approximated, as well as the computation of the
- * quantities entering the difference quotient, have been separated
- * into auxiliary nested classes (names @p Gradient and
- * @p SecondDerivative) and the main algorithm is simply passed one
- * or the other data types and asks them to perform the order
- * dependent operations. The main framework that is independent of
- * this, such as finding all active neighbors, or setting up the
- * matrix $Y$ is done in the main function @p approximate.
+ * The formulae for the computation of approximations to the gradient and to
+ * the tensor of second derivatives shown above are very much alike. The basic
+ * difference is that in one case the finite difference quotient is a scalar,
+ * while in the other case it is a vector. For higher derivatives, this would
+ * be a tensor of even higher rank. We then have to form the outer product of
+ * this difference quotient with the distance vector $y_{KK'}$, symmetrize it,
+ * contract it with the matrix $Y^{-1}$ and compute its norm. To make the
+ * implementation simpler and to allow for code reuse, all these operations
+ * that are dependent on the actual order of the derivatives to be
+ * approximated, as well as the computation of the quantities entering the
+ * difference quotient, have been separated into auxiliary nested classes
+ * (names @p Gradient and @p SecondDerivative) and the main algorithm is
+ * simply passed one or the other data types and asks them to perform the
+ * order dependent operations. The main framework that is independent of this,
+ * such as finding all active neighbors, or setting up the matrix $Y$ is done
+ * in the main function @p approximate.
*
- * Due to this way of operation, the class may be easily extended for
- * higher oder derivatives than are presently implemented. Basically,
- * only an additional class along the lines of the derivative
- * descriptor classes @p Gradient and @p SecondDerivative has to be
- * implemented, with the respective typedefs and functions replaced by
- * the appropriate analogues for the derivative that is to be
- * approximated.
+ * Due to this way of operation, the class may be easily extended for higher
+ * oder derivatives than are presently implemented. Basically, only an
+ * additional class along the lines of the derivative descriptor classes @p
+ * Gradient and @p SecondDerivative has to be implemented, with the respective
+ * typedefs and functions replaced by the appropriate analogues for the
+ * derivative that is to be approximated.
*
* @ingroup numerics
* @author Wolfgang Bangerth, 2000
namespace Algorithms
{
/**
- * An output operator writing a separate file in each step and
- * writing the vectors as finite element functions with respect to a
- * given DoFHandler.
+ * An output operator writing a separate file in each step and writing the
+ * vectors as finite element functions with respect to a given DoFHandler.
*/
template <class VECTOR, int dim, int spacedim=dim>
class DoFOutputOperator : public OutputOperator<VECTOR>
/**
- * Print intermediate solutions in solvers. This is derived from a
- * solver class provided as template argument. It implements the
- * @p print_vector function of the solver using a
- * DoFHandler. This way, the intermediate vectors can be viewed
- * as finite element functions. This class might be used first to
- * understand how solvers work (for example to visualize the smoothing
- * properties of various solvers, e.g. in a multigrid context), and
- * second to investigate why and how a solver fails to solve certain
- * classes of problems.
+ * Print intermediate solutions in solvers. This is derived from a solver
+ * class provided as template argument. It implements the @p print_vector
+ * function of the solver using a DoFHandler. This way, the intermediate
+ * vectors can be viewed as finite element functions. This class might be used
+ * first to understand how solvers work (for example to visualize the
+ * smoothing properties of various solvers, e.g. in a multigrid context), and
+ * second to investigate why and how a solver fails to solve certain classes
+ * of problems.
*
- * Objects of this class are provided with a solver class through a
- * template argument, and with a file name (as a string), with which a
- * new file is constructed in each iteration (named
- * <tt>basename.[step].[suffix]</tt>) and into which the solution is
- * written as a finite element field using the DataOut class.
- * Please note that this class may produce enormous amounts of data!
+ * Objects of this class are provided with a solver class through a template
+ * argument, and with a file name (as a string), with which a new file is
+ * constructed in each iteration (named <tt>basename.[step].[suffix]</tt>) and
+ * into which the solution is written as a finite element field using the
+ * DataOut class. Please note that this class may produce enormous amounts of
+ * data!
*
* @ingroup output
* @author Guido Kanschat, 2000
{
public:
/**
- * Constructor. First, we take
- * the arguments needed for the
- * solver. @p data_out is the
- * object doing the output as a
- * finite element function.
+ * Constructor. First, we take the arguments needed for the solver. @p
+ * data_out is the object doing the output as a finite element function.
*
- * One output file with the name
- * <tt>basename.[step].[suffix]</tt>
- * will be produced for each
- * iteration step.
+ * One output file with the name <tt>basename.[step].[suffix]</tt> will be
+ * produced for each iteration step.
*/
DoFPrintSolverStep (SolverControl &control,
VectorMemory<VECTOR> &mem,
const std::string &basename);
/**
- * Call-back function for the
- * iterative method.
+ * Call-back function for the iterative method.
*/
virtual void print_vectors (const unsigned int step,
const VECTOR &x,
/**
- * Implementation of the error indicator by Kelly, Gago, Zienkiewicz
- * and Babuska. This error indicator tries to approximate the error
- * per cell by integration of the jump of the gradient of the
- * solution along the faces of each cell. It can be understood as a
- * gradient recovery estimator; see the survey of Ainsworth for a
- * complete discussion.
+ * Implementation of the error indicator by Kelly, Gago, Zienkiewicz and
+ * Babuska. This error indicator tries to approximate the error per cell by
+ * integration of the jump of the gradient of the solution along the faces of
+ * each cell. It can be understood as a gradient recovery estimator; see the
+ * survey of Ainsworth for a complete discussion.
*
- * @note In spite of the name, this is not truly an a posteriori
- * error estimator, even if applied to the Poisson problem only. It
- * gives good hints for mesh refinement, but the estimate is not to
- * be trusted. For higher order trial spaces the integrals computed
- * here tend to zero faster than the error itself, thus ruling out
- * the values as error estimators.
+ * @note In spite of the name, this is not truly an a posteriori error
+ * estimator, even if applied to the Poisson problem only. It gives good hints
+ * for mesh refinement, but the estimate is not to be trusted. For higher
+ * order trial spaces the integrals computed here tend to zero faster than the
+ * error itself, thus ruling out the values as error estimators.
*
- * The error estimator really only estimates the error for the generalized
- * Poisson equation $-\nabla\cdot a(x) \nabla u = f$ with either Dirichlet
- * boundary conditions or generalized Neumann boundary conditions involving
- * the conormal derivative $a\frac{du}{dn} = g$.
+ * The error estimator really only estimates the error for the generalized
+ * Poisson equation $-\nabla\cdot a(x) \nabla u = f$ with either Dirichlet
+ * boundary conditions or generalized Neumann boundary conditions involving
+ * the conormal derivative $a\frac{du}{dn} = g$.
*
- * The error estimator returns a vector of estimated errors per cell which
- * can be used to feed the <tt>Triangulation<dim>::refine_*</tt> functions. This
- * vector contains elements of data type @p float, rather than @p double,
- * since accuracy is not so important here, and since this can save rather
- * a lot of memory, when using many cells.
+ * The error estimator returns a vector of estimated errors per cell which can
+ * be used to feed the <tt>Triangulation<dim>::refine_*</tt> functions. This
+ * vector contains elements of data type @p float, rather than @p double,
+ * since accuracy is not so important here, and since this can save rather a
+ * lot of memory, when using many cells.
*
*
- * <h3>Implementation</h3>
+ * <h3>Implementation</h3>
*
- * In principle, the implementation of the error estimation is simple: let
- * \f[
- * \eta_K^2 = \frac h{24} \int_{\partial K} \left[a \frac{\partial u_h}{\partial n}\right]^2 do
- * \f]
- * be the error estimator for cell $K$. $[\cdot]$ denotes the jump of the
- * argument at the face. In the paper of Ainsworth, $h$ is divided by $24$,
- * but this factor is a bit esoteric, stemming from interpolation estimates
- * and stability constants which may hold for the Poisson problem, but may
- * not hold for more general situations. In the implementation, this factor
- * is considered, but may lead to wrong results. You may scale the vector
- * appropriately afterwards.
+ * In principle, the implementation of the error estimation is simple: let \f[
+ * \eta_K^2 = \frac h{24} \int_{\partial K} \left[a \frac{\partial
+ * u_h}{\partial n}\right]^2 do \f] be the error estimator for cell $K$.
+ * $[\cdot]$ denotes the jump of the argument at the face. In the paper of
+ * Ainsworth, $h$ is divided by $24$, but this factor is a bit esoteric,
+ * stemming from interpolation estimates and stability constants which may
+ * hold for the Poisson problem, but may not hold for more general situations.
+ * In the implementation, this factor is considered, but may lead to wrong
+ * results. You may scale the vector appropriately afterwards.
*
- * To perform the integration, use is made of the FEFaceValues and
- * FESubfaceValues classes. The integration is performed by looping
- * over all cells and integrating over faces that are not yet treated.
- * This way we avoid integration on faces twice, once for each time we
- * visit one of the adjacent cells. In a second loop over all cells, we
- * sum up the contributions of the faces (which are the integrated
- * square of the jumps) of each cell and take the square root.
+ * To perform the integration, use is made of the FEFaceValues and
+ * FESubfaceValues classes. The integration is performed by looping over all
+ * cells and integrating over faces that are not yet treated. This way we
+ * avoid integration on faces twice, once for each time we visit one of the
+ * adjacent cells. In a second loop over all cells, we sum up the
+ * contributions of the faces (which are the integrated square of the jumps)
+ * of each cell and take the square root.
*
- * The integration is done using a quadrature formula on the face.
- * For linear trial functions (FEQ1), the QGauss2 or even the
- * QMidpoint rule will suffice. For higher order elements, it is
- * necessary to utilize higher order quadrature formulae as well.
+ * The integration is done using a quadrature formula on the face. For linear
+ * trial functions (FEQ1), the QGauss2 or even the QMidpoint rule will
+ * suffice. For higher order elements, it is necessary to utilize higher order
+ * quadrature formulae as well.
*
- * We store the contribution of each face in a @p map, as provided by the
- * C++ standard library, with the iterator pointing to that face being the
- * key into the map. In fact, we do not store the indicator per face, but
- * only the integral listed above. When looping the second time over all
- * cells, we have to sum up the contributions of the faces, multiply them
- * with $\frac h{24}$ and take the square root. By doing the multiplication
- * with $h$ in the second loop, we avoid problems to decide with which $h$
- * to multiply, that of the cell on the one or that of the cell on the other
- * side of the face.
+ * We store the contribution of each face in a @p map, as provided by the C++
+ * standard library, with the iterator pointing to that face being the key
+ * into the map. In fact, we do not store the indicator per face, but only the
+ * integral listed above. When looping the second time over all cells, we have
+ * to sum up the contributions of the faces, multiply them with $\frac h{24}$
+ * and take the square root. By doing the multiplication with $h$ in the
+ * second loop, we avoid problems to decide with which $h$ to multiply, that
+ * of the cell on the one or that of the cell on the other side of the face.
*
- * $h$ is taken to be the greatest length of the diagonals of the cell. For
- * more or less uniform cells without deformed angles, this coincides with
- * the diameter of the cell.
+ * $h$ is taken to be the greatest length of the diagonals of the cell. For
+ * more or less uniform cells without deformed angles, this coincides with the
+ * diameter of the cell.
*
*
- * <h3>Vector-valued functions</h3>
+ * <h3>Vector-valued functions</h3>
*
- * If the finite element field for which the error is to be estimated
- * is vector-valued, i.e. the finite element has more than one
- * component, then all the above can be applied to all or only some
- * components at the same time. The main function of this class takes
- * a list of flags denoting the components for which components the
- * error estimator is to be applied; by default, it is a list of only
- * @p trues, meaning that all variables shall be treated.
+ * If the finite element field for which the error is to be estimated is
+ * vector-valued, i.e. the finite element has more than one component, then
+ * all the above can be applied to all or only some components at the same
+ * time. The main function of this class takes a list of flags denoting the
+ * components for which components the error estimator is to be applied; by
+ * default, it is a list of only @p trues, meaning that all variables shall be
+ * treated.
*
- * In case the different components of a field have different
- * physical meaning (for example velocity and pressure in the Stokes
- * equations), it would be senseless to use the same coefficient for
- * all components. In that case, you can pass a function with as many
- * components as there are components in the finite element field and
- * each component of the error estimator will then be weighted by the
- * respective component in this coefficient function. In the other
- * case, when all components have the same meaning (for example the
- * displacements in Lame's equations of elasticity), you can specify
- * a scalar coefficient which will then be used for all components.
+ * In case the different components of a field have different physical meaning
+ * (for example velocity and pressure in the Stokes equations), it would be
+ * senseless to use the same coefficient for all components. In that case, you
+ * can pass a function with as many components as there are components in the
+ * finite element field and each component of the error estimator will then be
+ * weighted by the respective component in this coefficient function. In the
+ * other case, when all components have the same meaning (for example the
+ * displacements in Lame's equations of elasticity), you can specify a scalar
+ * coefficient which will then be used for all components.
*
*
- * <h3>%Boundary values</h3>
+ * <h3>%Boundary values</h3>
*
- * If the face is at the boundary, i.e. there is no neighboring cell to which
- * the jump in the gradiend could be computed, there are two possibilities:
- * <ul>
- * <li> The face belongs to a Dirichlet boundary. Then the face is not
- * considered, which can be justified looking at a dual problem technique and
- * should hold exactly if the boundary can be approximated exactly by the
- * finite element used (i.e. it is a linear boundary for linear finite elements,
- * quadratic for isoparametric quadratic elements, etc). For boundaries which
- * can not be exactly approximated, one should consider the difference
- * $z-z_h$ on the face, $z$ being a dual problem's solution which is zero at
- * the true boundary and $z_h$ being an approximation, which in most cases
- * will be zero on the numerical boundary. Since on the numerical boundary
- * $z$ will not be zero in general, we would get another term here, but this
- * one is neglected for practical reasons, in the hope that the error made
- * here will tend to zero faster than the energy error we wish to estimate.
+ * If the face is at the boundary, i.e. there is no neighboring cell to which
+ * the jump in the gradiend could be computed, there are two possibilities:
+ * <ul>
+ * <li> The face belongs to a Dirichlet boundary. Then the face is not
+ * considered, which can be justified looking at a dual problem technique and
+ * should hold exactly if the boundary can be approximated exactly by the
+ * finite element used (i.e. it is a linear boundary for linear finite
+ * elements, quadratic for isoparametric quadratic elements, etc). For
+ * boundaries which can not be exactly approximated, one should consider the
+ * difference $z-z_h$ on the face, $z$ being a dual problem's solution which
+ * is zero at the true boundary and $z_h$ being an approximation, which in
+ * most cases will be zero on the numerical boundary. Since on the numerical
+ * boundary $z$ will not be zero in general, we would get another term here,
+ * but this one is neglected for practical reasons, in the hope that the error
+ * made here will tend to zero faster than the energy error we wish to
+ * estimate.
*
- * Though no integration is necessary, in the list of face contributions we
- * store a zero for this face, which makes summing up the contributions of
- * the different faces to the cells easier.
+ * Though no integration is necessary, in the list of face contributions we
+ * store a zero for this face, which makes summing up the contributions of the
+ * different faces to the cells easier.
*
- * <li> The face belongs to a Neumann boundary. In this case, the
- * contribution of the face $F\in\partial K$ looks like
- * \f[ \int_F \left|g-a\frac{\partial u_h}{\partial n}\right|^2 ds \f]
- * where $g$ is the Neumann boundary function. If the finite element is
- * vector-valued, then obviously the function denoting the Neumann boundary
- * conditions needs to be vector-valued as well.
+ * <li> The face belongs to a Neumann boundary. In this case, the
+ * contribution of the face $F\in\partial K$ looks like \f[ \int_F
+ * \left|g-a\frac{\partial u_h}{\partial n}\right|^2 ds \f] where $g$ is the
+ * Neumann boundary function. If the finite element is vector-valued, then
+ * obviously the function denoting the Neumann boundary conditions needs to be
+ * vector-valued as well.
*
- * <li> No other boundary conditions are considered.
- * </ul>
+ * <li> No other boundary conditions are considered.
+ * </ul>
*
- * In practice, if you have Robin boundary conditions or are too lazy to
- * accurately describe Neumann values, then this is rarely an issue: if you
- * don't say anything in the map about a particular part of the boundary then
- * the Kelly indicator will simply assume that the solution is correct on
- * that part of the boundary and not touch it. Of course, if you have a have
- * a Neumann or Robin boundary, that isn't quite true, there is going to be a
- * difference between the normal derivative of the numerical solution and the
- * Neumann values these normal derivatives should equal. So if we simply
- * ignore those parts of the boundary, we'll underestimate the error. In
- * practice, this rarely appears to be a problem -- you may not refine the
- * cell this time around but you'll probably refine it in the next refinement
- * step and everything is good again. After all, for all problems but the
- * Laplace equation, the Kelly indicator is only an indicator, not an
- * estimator, and so the values it computes are not exact error
- * representations anyway.
+ * In practice, if you have Robin boundary conditions or are too lazy to
+ * accurately describe Neumann values, then this is rarely an issue: if you
+ * don't say anything in the map about a particular part of the boundary then
+ * the Kelly indicator will simply assume that the solution is correct on that
+ * part of the boundary and not touch it. Of course, if you have a have a
+ * Neumann or Robin boundary, that isn't quite true, there is going to be a
+ * difference between the normal derivative of the numerical solution and the
+ * Neumann values these normal derivatives should equal. So if we simply
+ * ignore those parts of the boundary, we'll underestimate the error. In
+ * practice, this rarely appears to be a problem -- you may not refine the
+ * cell this time around but you'll probably refine it in the next refinement
+ * step and everything is good again. After all, for all problems but the
+ * Laplace equation, the Kelly indicator is only an indicator, not an
+ * estimator, and so the values it computes are not exact error
+ * representations anyway.
*
*
- * <h3>Handling of hanging nodes</h3>
+ * <h3>Handling of hanging nodes</h3>
*
- * The integration along faces with hanging nodes is quite tricky, since one
- * of the elements has to be shifted one level up or down. See the
- * documentation for the FESubFaceValues class for more information about
- * technical issues regarding this topic.
+ * The integration along faces with hanging nodes is quite tricky, since one
+ * of the elements has to be shifted one level up or down. See the
+ * documentation for the FESubFaceValues class for more information about
+ * technical issues regarding this topic.
*
- * In praxi, since we integrate over each face only once, we do this when we
- * are on the coarser one of the two cells adjacent to a subface (a subface
- * is defined to be the child of a face; seen from the coarse cell, it is a
- * subface, while seen from the refined cell it is one of its faces). The
- * reason is that finding neighborship information is a bit easier then, but
- * that's all practical reasoning, nothing fundamental.
+ * In praxi, since we integrate over each face only once, we do this when we
+ * are on the coarser one of the two cells adjacent to a subface (a subface is
+ * defined to be the child of a face; seen from the coarse cell, it is a
+ * subface, while seen from the refined cell it is one of its faces). The
+ * reason is that finding neighborship information is a bit easier then, but
+ * that's all practical reasoning, nothing fundamental.
*
- * Since we integrate from the coarse side of the face, we have the mother
- * face readily at hand and store the result of the integration over that
- * mother face (being the sum of the integrals along the subfaces) in the
- * abovementioned map of integrals as well. This consumes some memory more
- * than needed, but makes the summing up of the face contributions to the
- * cells easier, since then we have the information from all faces of all
- * cells at hand and need not think about explicitly determining whether
- * a face was refined or not. The same applies for boundary faces, see
- * above.
+ * Since we integrate from the coarse side of the face, we have the mother
+ * face readily at hand and store the result of the integration over that
+ * mother face (being the sum of the integrals along the subfaces) in the
+ * abovementioned map of integrals as well. This consumes some memory more
+ * than needed, but makes the summing up of the face contributions to the
+ * cells easier, since then we have the information from all faces of all
+ * cells at hand and need not think about explicitly determining whether a
+ * face was refined or not. The same applies for boundary faces, see above.
*
*
- * <h3>Multiple solution vectors</h3>
+ * <h3>Multiple solution vectors</h3>
*
- * In some cases, for example in time-dependent problems, one would
- * like to compute the error estimates for several solution vectors
- * on the same grid at once, with the same coefficients, boundary
- * condition object, etc, e.g. for the solutions on several
- * successive time steps. One could then call the functions of this
- * class several times for each solution. However, the largest factor
- * in the computation of the error estimates (in terms of computing
- * time) is initialization of FEFaceValues and FESubFaceValues
- * objects, and iterating through all faces and subfaces. If the
- * solution vectors live on the same grid, this effort can be reduced
- * significantly by treating all solution vectors at the same time,
- * initializing the FEFaceValues objects only once per cell and for
- * all solution vectors at once, and also only looping through the
- * triangulation only once. For this reason, besides the @p estimate
- * function in this class that takes a single input vector and
- * returns a single output vector, there is also a function that
- * accepts several in- and output vectors at the same time.
+ * In some cases, for example in time-dependent problems, one would like to
+ * compute the error estimates for several solution vectors on the same grid
+ * at once, with the same coefficients, boundary condition object, etc, e.g.
+ * for the solutions on several successive time steps. One could then call the
+ * functions of this class several times for each solution. However, the
+ * largest factor in the computation of the error estimates (in terms of
+ * computing time) is initialization of FEFaceValues and FESubFaceValues
+ * objects, and iterating through all faces and subfaces. If the solution
+ * vectors live on the same grid, this effort can be reduced significantly by
+ * treating all solution vectors at the same time, initializing the
+ * FEFaceValues objects only once per cell and for all solution vectors at
+ * once, and also only looping through the triangulation only once. For this
+ * reason, besides the @p estimate function in this class that takes a single
+ * input vector and returns a single output vector, there is also a function
+ * that accepts several in- and output vectors at the same time.
*
- * @ingroup numerics
- * @author Wolfgang Bangerth, 1998, 1999, 2000, 2004, 2006; parallelization by Thomas Richter, 2000
+ * @ingroup numerics
+ * @author Wolfgang Bangerth, 1998, 1999, 2000, 2004, 2006; parallelization by
+ * Thomas Richter, 2000
*/
template <int dim, int spacedim=dim>
class KellyErrorEstimator
* parameters are as in the general case used for 2d and higher.
*
* The parameter n_threads is no longer used and will be ignored.
- * Multithreading is not presently
- * implemented for 1d, but we retain the respective parameter for
- * compatibility with the function signature in the general case.
+ * Multithreading is not presently implemented for 1d, but we retain the
+ * respective parameter for compatibility with the function signature in the
+ * general case.
*/
template <typename InputVector, class DH>
static void estimate (const Mapping<1,spacedim> &mapping,
{
/**
- * This is an interpolation function for the given dof handler and
- * the given solution vector. The points at which this function can
- * be evaluated MUST be inside the domain of the dof handler, but
- * except from this, no other requirement is given. This function is
- * rather slow, as it needs to construct a quadrature object for the
- * point (or set of points) where you want to evaluate your finite
- * element function. In order to do so, it needs to find out where
- * the points lie.
+ * This is an interpolation function for the given dof handler and the given
+ * solution vector. The points at which this function can be evaluated MUST
+ * be inside the domain of the dof handler, but except from this, no other
+ * requirement is given. This function is rather slow, as it needs to
+ * construct a quadrature object for the point (or set of points) where you
+ * want to evaluate your finite element function. In order to do so, it
+ * needs to find out where the points lie.
*
- * If you know in advance in which cell your points lie, you can
- * accelerate things a bit, by calling set_active_cell before
- * asking for values or gradients of the function. If you don't do
- * this, and your points don't lie in the cell that is currently
- * stored, the function GridTools::find_cell_around_point is called
- * to find out where the point is. You can specify an optional
- * mapping to use when looking for points in the grid. If you don't
- * do so, this function uses a Q1 mapping.
+ * If you know in advance in which cell your points lie, you can accelerate
+ * things a bit, by calling set_active_cell before asking for values or
+ * gradients of the function. If you don't do this, and your points don't
+ * lie in the cell that is currently stored, the function
+ * GridTools::find_cell_around_point is called to find out where the point
+ * is. You can specify an optional mapping to use when looking for points in
+ * the grid. If you don't do so, this function uses a Q1 mapping.
*
* Once the FEFieldFunction knows where the points lie, it creates a
* quadrature formula for those points, and calls
- * FEValues::get_function_values or FEValues::get_function_grads with
- * the given quadrature points.
+ * FEValues::get_function_values or FEValues::get_function_grads with the
+ * given quadrature points.
*
- * If you only need the quadrature points but not the values of the
- * finite element function (you might want this for the adjoint
- * interpolation), you can also use the function @p
- * compute_point_locations alone.
+ * If you only need the quadrature points but not the values of the finite
+ * element function (you might want this for the adjoint interpolation), you
+ * can also use the function @p compute_point_locations alone.
*
* An example of how to use this function is the following:
*
* \code
*
- * // Generate two triangulations
- * Triangulation<dim> tria_1;
+ * // Generate two triangulations Triangulation<dim> tria_1;
* Triangulation<dim> tria_2;
*
- * // Read the triangulations from files, or build them up, or get
- * // them from some place... Assume that tria_2 is *entirely*
- * // included in tria_1
- * ...
+ * // Read the triangulations from files, or build them up, or get // them
+ * from some place... Assume that tria_2 is *entirely* // included in
+ * tria_1 ...
*
- * // Associate a dofhandler and a solution to the first
- * // triangulation
- * DoFHandler<dim> dh1(tria_1);
- * Vector<double> solution_1;
+ * // Associate a dofhandler and a solution to the first // triangulation
+ * DoFHandler<dim> dh1(tria_1); Vector<double> solution_1;
*
- * // Do the same with the second
- * DoFHandler<dim> dh2;
- * Vector<double> solution_2;
+ * // Do the same with the second DoFHandler<dim> dh2; Vector<double>
+ * solution_2;
*
- * // Setup the system, assemble matrices, solve problems and get the
- * // nobel prize on the first domain...
- * ...
+ * // Setup the system, assemble matrices, solve problems and get the //
+ * nobel prize on the first domain... ...
*
- * // Now project it to the second domain
- * FEFieldFunction<dim> fe_function_1 (dh_1, solution_1);
- * VectorTools::project(dh_2, constraints_2, quad, fe_function_1, solution_2);
+ * // Now project it to the second domain FEFieldFunction<dim> fe_function_1
+ * (dh_1, solution_1); VectorTools::project(dh_2, constraints_2, quad,
+ * fe_function_1, solution_2);
*
- * // Or interpolate it...
- * Vector<double> solution_3;
+ * // Or interpolate it... Vector<double> solution_3;
* VectorTools::interpolate(dh_2, fe_function_1, solution_3);
*
* \endcode
* The snippet of code above will work assuming that the second
* triangulation is entirely included in the first one.
*
- * FEFieldFunction is designed to be an easy way to get the results of
- * your computations across different, possibly non matching,
- * grids. No knowledge of the location of the points is assumed in
- * this class, which makes it rely entirely on the
- * GridTools::find_active_cell_around_point utility for its
- * job. However the class can be fed an "educated guess" of where the
+ * FEFieldFunction is designed to be an easy way to get the results of your
+ * computations across different, possibly non matching, grids. No knowledge
+ * of the location of the points is assumed in this class, which makes it
+ * rely entirely on the GridTools::find_active_cell_around_point utility for
+ * its job. However the class can be fed an "educated guess" of where the
* points that will be computed actually are by using the
* FEFieldFunction::set_active_cell method, so if you have a smart way to
- * tell where your points are, you will save a lot of computational
- * time by letting this class know.
+ * tell where your points are, you will save a lot of computational time by
+ * letting this class know.
*
*
* <h3>Using FEFieldFunction with parallel::distributed::Triangulation</h3>
* and evaluating the solution at a particular point, not every processor
* will own the cell at which the solution is evaluated. Rather, it may be
* that the cell in which this point is found is in fact a ghost or
- * artificial cell (see @ref GlossArtificialCell and
- * @ref GlossGhostCell). If the cell is artificial, we have no access
- * to the solution there and functions that evaluate the solution at
- * such a point will trigger an exception of type
- * FEFieldFunction::ExcPointNotAvailableHere. The same kind of exception
- * will also be produced if the cell is a ghost cell: On such cells, one
- * could in principle evaluate the solution, but it becomes easier if we
- * do not allow to do so because then there is exactly one processor in
- * a parallel distributed computation that can indeed evaluate the
- * solution. Consequently, it is clear which processor is responsible
+ * artificial cell (see @ref GlossArtificialCell and @ref GlossGhostCell).
+ * If the cell is artificial, we have no access to the solution there and
+ * functions that evaluate the solution at such a point will trigger an
+ * exception of type FEFieldFunction::ExcPointNotAvailableHere. The same
+ * kind of exception will also be produced if the cell is a ghost cell: On
+ * such cells, one could in principle evaluate the solution, but it becomes
+ * easier if we do not allow to do so because then there is exactly one
+ * processor in a parallel distributed computation that can indeed evaluate
+ * the solution. Consequently, it is clear which processor is responsible
* for producing output if the point evaluation is done as a postprocessing
* step.
*
- * To deal with this situation, you will want to use code as follows
- * when, for example, evaluating the solution at the origin (here using
- * a parallel TrilinosWrappers vector to hold the solution):
+ * To deal with this situation, you will want to use code as follows when,
+ * for example, evaluating the solution at the origin (here using a parallel
+ * TrilinosWrappers vector to hold the solution):
* @code
* Functions::FEFieldFunction<dim,DoFHandler<dim>,TrilinosWrappers::MPI::Vector>
* solution_function (dof_handler, solution);
* ...do something...;
* @endcode
*
- * @note To C++, <code>Functions::FEFieldFunction<dim>::ExcPointNotAvailableHere</code>
- * and <code>Functions::FEFieldFunction<dim,DoFHandler<dim>,TrilinosWrappers::MPI::Vector>::ExcPointNotAvailableHere</code>
- * are distinct types. You need to make sure that the type of the exception you
- * catch matches the type of the object that throws it, as shown in
- * the example above.
+ * @note To C++,
+ * <code>Functions::FEFieldFunction<dim>::ExcPointNotAvailableHere</code>
+ * and <code>Functions::FEFieldFunction<dim,DoFHandler<dim>,TrilinosWrappers
+ * ::MPI::Vector>::ExcPointNotAvailableHere</code> are distinct types. You
+ * need to make sure that the type of the exception you catch matches the
+ * type of the object that throws it, as shown in the example above.
*
* @ingroup functions
* @author Luca Heltai, 2006, Markus Buerg, 2012, Wolfgang Bangerth, 2013
{
public:
/**
- * Construct a vector
- * function. A smart pointers
- * is stored to the dof
- * handler, so you have to make
- * sure that it make sense for
- * the entire lifetime of this
- * object. The number of
- * components of this functions
- * is equal to the number of
- * components of the finite
- * element object. If a mapping
- * is specified, that is what
- * is used to find out where
- * the points lay. Otherwise
- * the standard Q1 mapping is
- * used.
+ * Construct a vector function. A smart pointers is stored to the dof
+ * handler, so you have to make sure that it make sense for the entire
+ * lifetime of this object. The number of components of this functions is
+ * equal to the number of components of the finite element object. If a
+ * mapping is specified, that is what is used to find out where the points
+ * lay. Otherwise the standard Q1 mapping is used.
*/
FEFieldFunction (const DH &dh,
const VECTOR &data_vector,
const Mapping<dim> &mapping = StaticMappingQ1<dim>::mapping);
/**
- * Set the current cell. If you
- * know in advance where your
- * points lie, you can tell
- * this object by calling this
- * function. This will speed
- * things up a little.
+ * Set the current cell. If you know in advance where your points lie, you
+ * can tell this object by calling this function. This will speed things
+ * up a little.
*/
void set_active_cell (const typename DH::active_cell_iterator &newcell);
/**
- * Get one vector value at the
- * given point. It is
- * inefficient to use single
- * points. If you need more
- * than one at a time, use the
- * vector_value_list()
- * function. For efficiency
- * reasons, it is better if all
- * the points lie on the same
- * cell. This is not mandatory,
- * however it does speed things
- * up.
+ * Get one vector value at the given point. It is inefficient to use
+ * single points. If you need more than one at a time, use the
+ * vector_value_list() function. For efficiency reasons, it is better if
+ * all the points lie on the same cell. This is not mandatory, however it
+ * does speed things up.
*
- * @note When using this function on a parallel::distributed::Triangulation
- * you may get an exception when trying to evaluate the solution at a
- * point that does not lie in a locally owned cell (see
- * @ref GlossLocallyOwnedCell). See the section in the general
- * documentation of this class for more information.
+ * @note When using this function on a
+ * parallel::distributed::Triangulation you may get an exception when
+ * trying to evaluate the solution at a point that does not lie in a
+ * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+ * the general documentation of this class for more information.
*/
virtual void vector_value (const Point<dim> &p,
Vector<double> &values) const;
/**
- * Return the value of the
- * function at the given
- * point. Unless there is only
- * one component (i.e. the
- * function is scalar), you
- * should state the component
- * you want to have evaluated;
- * it defaults to zero,
- * i.e. the first component.
- * It is inefficient to use
- * single points. If you need
- * more than one at a time, use
- * the vector_value_list
- * function. For efficiency
- * reasons, it is better if all
- * the points lie on the same
- * cell. This is not mandatory,
- * however it does speed things
- * up.
+ * Return the value of the function at the given point. Unless there is
+ * only one component (i.e. the function is scalar), you should state the
+ * component you want to have evaluated; it defaults to zero, i.e. the
+ * first component. It is inefficient to use single points. If you need
+ * more than one at a time, use the vector_value_list function. For
+ * efficiency reasons, it is better if all the points lie on the same
+ * cell. This is not mandatory, however it does speed things up.
*
- * @note When using this function on a parallel::distributed::Triangulation
- * you may get an exception when trying to evaluate the solution at a
- * point that does not lie in a locally owned cell (see
- * @ref GlossLocallyOwnedCell). See the section in the general
- * documentation of this class for more information.
+ * @note When using this function on a
+ * parallel::distributed::Triangulation you may get an exception when
+ * trying to evaluate the solution at a point that does not lie in a
+ * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+ * the general documentation of this class for more information.
*/
virtual double value (const Point< dim > &p,
const unsigned int component = 0) const;
/**
- * Set @p values to the point
- * values of the specified
- * component of the function at
- * the @p points. It is assumed
- * that @p values already has
- * the right size, i.e. the
- * same size as the points
- * array. This is rather
- * efficient if all the points
- * lie on the same cell. If
- * this is not the case, things
- * may slow down a bit.
+ * Set @p values to the point values of the specified component of the
+ * function at the @p points. It is assumed that @p values already has the
+ * right size, i.e. the same size as the points array. This is rather
+ * efficient if all the points lie on the same cell. If this is not the
+ * case, things may slow down a bit.
*
- * @note When using this function on a parallel::distributed::Triangulation
- * you may get an exception when trying to evaluate the solution at a
- * point that does not lie in a locally owned cell (see
- * @ref GlossLocallyOwnedCell). See the section in the general
- * documentation of this class for more information.
+ * @note When using this function on a
+ * parallel::distributed::Triangulation you may get an exception when
+ * trying to evaluate the solution at a point that does not lie in a
+ * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+ * the general documentation of this class for more information.
*/
virtual void value_list (const std::vector<Point< dim > > &points,
std::vector< double > &values,
/**
- * Set @p values to the point
- * values of the function at
- * the @p points. It is assumed
- * that @p values already has
- * the right size, i.e. the
- * same size as the points
- * array. This is rather
- * efficient if all the points
- * lie on the same cell. If
- * this is not the case, things
- * may slow down a bit.
+ * Set @p values to the point values of the function at the @p points. It
+ * is assumed that @p values already has the right size, i.e. the same
+ * size as the points array. This is rather efficient if all the points
+ * lie on the same cell. If this is not the case, things may slow down a
+ * bit.
*
- * @note When using this function on a parallel::distributed::Triangulation
- * you may get an exception when trying to evaluate the solution at a
- * point that does not lie in a locally owned cell (see
- * @ref GlossLocallyOwnedCell). See the section in the general
- * documentation of this class for more information.
+ * @note When using this function on a
+ * parallel::distributed::Triangulation you may get an exception when
+ * trying to evaluate the solution at a point that does not lie in a
+ * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+ * the general documentation of this class for more information.
*/
virtual void vector_value_list (const std::vector<Point< dim > > &points,
std::vector< Vector<double> > &values) const;
/**
- * Return the gradient of all
- * components of the function
- * at the given point. It is
- * inefficient to use single
- * points. If you need more
- * than one at a time, use the
- * vector_value_list
- * function. For efficiency
- * reasons, it is better if all
- * the points lie on the same
- * cell. This is not mandatory,
- * however it does speed things
- * up.
+ * Return the gradient of all components of the function at the given
+ * point. It is inefficient to use single points. If you need more than
+ * one at a time, use the vector_value_list function. For efficiency
+ * reasons, it is better if all the points lie on the same cell. This is
+ * not mandatory, however it does speed things up.
*
- * @note When using this function on a parallel::distributed::Triangulation
- * you may get an exception when trying to evaluate the solution at a
- * point that does not lie in a locally owned cell (see
- * @ref GlossLocallyOwnedCell). See the section in the general
- * documentation of this class for more information.
+ * @note When using this function on a
+ * parallel::distributed::Triangulation you may get an exception when
+ * trying to evaluate the solution at a point that does not lie in a
+ * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+ * the general documentation of this class for more information.
*/
virtual void
vector_gradient (const Point< dim > &p,
std::vector< Tensor< 1, dim > > &gradients) const;
/**
- * Return the gradient of the
- * specified component of the
- * function at the given point.
- * It is inefficient to use
- * single points. If you need
- * more than one at a time, use
- * the vector_value_list
- * function. For efficiency
- * reasons, it is better if all
- * the points lie on the same
- * cell. This is not mandatory,
- * however it does speed things
- * up.
+ * Return the gradient of the specified component of the function at the
+ * given point. It is inefficient to use single points. If you need more
+ * than one at a time, use the vector_value_list function. For efficiency
+ * reasons, it is better if all the points lie on the same cell. This is
+ * not mandatory, however it does speed things up.
*
- * @note When using this function on a parallel::distributed::Triangulation
- * you may get an exception when trying to evaluate the solution at a
- * point that does not lie in a locally owned cell (see
- * @ref GlossLocallyOwnedCell). See the section in the general
- * documentation of this class for more information.
+ * @note When using this function on a
+ * parallel::distributed::Triangulation you may get an exception when
+ * trying to evaluate the solution at a point that does not lie in a
+ * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+ * the general documentation of this class for more information.
*/
virtual Tensor<1,dim> gradient(const Point< dim > &p,
const unsigned int component = 0)const;
/**
- * Return the gradient of all
- * components of the function
- * at all the given points.
- * This is rather efficient if
- * all the points lie on the
- * same cell. If this is not
- * the case, things may slow
- * down a bit.
+ * Return the gradient of all components of the function at all the given
+ * points. This is rather efficient if all the points lie on the same
+ * cell. If this is not the case, things may slow down a bit.
*
- * @note When using this function on a parallel::distributed::Triangulation
- * you may get an exception when trying to evaluate the solution at a
- * point that does not lie in a locally owned cell (see
- * @ref GlossLocallyOwnedCell). See the section in the general
- * documentation of this class for more information.
+ * @note When using this function on a
+ * parallel::distributed::Triangulation you may get an exception when
+ * trying to evaluate the solution at a point that does not lie in a
+ * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+ * the general documentation of this class for more information.
*/
virtual void
vector_gradient_list (const std::vector< Point< dim > > &p,
std::vector< Tensor< 1, dim > > > &gradients) const;
/**
- * Return the gradient of the
- * specified component of the
- * function at all the given
- * points. This is rather
- * efficient if all the points
- * lie on the same cell. If
- * this is not the case, things
- * may slow down a bit.
+ * Return the gradient of the specified component of the function at all
+ * the given points. This is rather efficient if all the points lie on
+ * the same cell. If this is not the case, things may slow down a bit.
*
- * @note When using this function on a parallel::distributed::Triangulation
- * you may get an exception when trying to evaluate the solution at a
- * point that does not lie in a locally owned cell (see
- * @ref GlossLocallyOwnedCell). See the section in the general
- * documentation of this class for more information.
+ * @note When using this function on a
+ * parallel::distributed::Triangulation you may get an exception when
+ * trying to evaluate the solution at a point that does not lie in a
+ * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+ * the general documentation of this class for more information.
*/
virtual void
gradient_list (const std::vector< Point< dim > > &p,
/**
- * Compute the Laplacian of a
- * given component at point <tt>p</tt>.
+ * Compute the Laplacian of a given component at point <tt>p</tt>.
*
- * @note When using this function on a parallel::distributed::Triangulation
- * you may get an exception when trying to evaluate the solution at a
- * point that does not lie in a locally owned cell (see
- * @ref GlossLocallyOwnedCell). See the section in the general
- * documentation of this class for more information.
+ * @note When using this function on a
+ * parallel::distributed::Triangulation you may get an exception when
+ * trying to evaluate the solution at a point that does not lie in a
+ * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+ * the general documentation of this class for more information.
*/
virtual double
laplacian (const Point<dim> &p,
const unsigned int component = 0) const;
/**
- * Compute the Laplacian of all
- * components at point <tt>p</tt> and
- * store them in <tt>values</tt>.
+ * Compute the Laplacian of all components at point <tt>p</tt> and store
+ * them in <tt>values</tt>.
*
- * @note When using this function on a parallel::distributed::Triangulation
- * you may get an exception when trying to evaluate the solution at a
- * point that does not lie in a locally owned cell (see
- * @ref GlossLocallyOwnedCell). See the section in the general
- * documentation of this class for more information.
+ * @note When using this function on a
+ * parallel::distributed::Triangulation you may get an exception when
+ * trying to evaluate the solution at a point that does not lie in a
+ * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+ * the general documentation of this class for more information.
*/
virtual void
vector_laplacian (const Point<dim> &p,
Vector<double> &values) const;
/**
- * Compute the Laplacian of one
- * component at a set of points.
+ * Compute the Laplacian of one component at a set of points.
*
- * @note When using this function on a parallel::distributed::Triangulation
- * you may get an exception when trying to evaluate the solution at a
- * point that does not lie in a locally owned cell (see
- * @ref GlossLocallyOwnedCell). See the section in the general
- * documentation of this class for more information.
+ * @note When using this function on a
+ * parallel::distributed::Triangulation you may get an exception when
+ * trying to evaluate the solution at a point that does not lie in a
+ * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+ * the general documentation of this class for more information.
*/
virtual void
laplacian_list (const std::vector<Point<dim> > &points,
const unsigned int component = 0) const;
/**
- * Compute the Laplacians of all
- * components at a set of points.
+ * Compute the Laplacians of all components at a set of points.
*
- * @note When using this function on a parallel::distributed::Triangulation
- * you may get an exception when trying to evaluate the solution at a
- * point that does not lie in a locally owned cell (see
- * @ref GlossLocallyOwnedCell). See the section in the general
- * documentation of this class for more information.
+ * @note When using this function on a
+ * parallel::distributed::Triangulation you may get an exception when
+ * trying to evaluate the solution at a point that does not lie in a
+ * locally owned cell (see @ref GlossLocallyOwnedCell). See the section in
+ * the general documentation of this class for more information.
*/
virtual void
vector_laplacian_list (const std::vector<Point<dim> > &points,
std::vector<Vector<double> > &values) const;
/**
- * Create quadrature
- * rules. This function groups
- * the points into blocks that
- * live in the same cell, and
- * fills up three vectors: @p
- * cells, @p qpoints and @p
- * maps. The first is a list of
- * the cells that contain the
- * points, the second is a list
- * of quadrature points
- * matching each cell of the
- * first list, and the third
- * contains the index of the
- * given quadrature points,
- * i.e., @p points[maps[3][4]]
- * ends up as the 5th
- * quadrature point in the 4th
- * cell. This is where
- * optimization would
- * help. This function returns
- * the number of cells that
- * contain the given set of
- * points.
+ * Create quadrature rules. This function groups the points into blocks
+ * that live in the same cell, and fills up three vectors: @p cells, @p
+ * qpoints and @p maps. The first is a list of the cells that contain the
+ * points, the second is a list of quadrature points matching each cell of
+ * the first list, and the third contains the index of the given
+ * quadrature points, i.e., @p points[maps[3][4]] ends up as the 5th
+ * quadrature point in the 4th cell. This is where optimization would
+ * help. This function returns the number of cells that contain the given
+ * set of points.
*/
unsigned int
compute_point_locations(const std::vector<Point<dim> > &points,
SmartPointer<const DH,FEFieldFunction<dim, DH, VECTOR> > dh;
/**
- * A reference to the actual
- * data vector.
+ * A reference to the actual data vector.
*/
const VECTOR &data_vector;
/**
- * A reference to the mapping
- * being used.
+ * A reference to the mapping being used.
*/
const Mapping<dim> &mapping;
mutable cell_hint_t cell_hint;
/**
- * Store the number of
- * components of this function.
+ * Store the number of components of this function.
*/
const unsigned int n_components;
/**
- * Given a cell, return the
- * reference coordinates of the
- * given point within this cell
- * if it indeed lies within the
- * cell. Otherwise return an
- * uninitialized
- * boost::optional object.
- */
+ * Given a cell, return the reference coordinates of the given point
+ * within this cell if it indeed lies within the cell. Otherwise return an
+ * uninitialized boost::optional object.
+ */
boost::optional<Point<dim> >
get_reference_coordinates (const typename DH::active_cell_iterator &cell,
const Point<dim> &point) const;
/**
- * This class provides some facilities to generate 2d and 3d histograms.
- * It is used by giving it one or several data sets and a rule how to
- * break the range of values therein into intervals (e.g. linear spacing
- * or logarithmic spacing of intervals). The values are then sorted into
- * the different intervals and the number of values in each interval is
- * stored for output later. In case only one data set was given, the
- * resulting histogram will be a 2d one, while it will be a 3d one if
- * more than one data set was given. For more than one data set, the same
- * intervals are used for each of them anyway, to make comparison easier.
+ * This class provides some facilities to generate 2d and 3d histograms. It is
+ * used by giving it one or several data sets and a rule how to break the
+ * range of values therein into intervals (e.g. linear spacing or logarithmic
+ * spacing of intervals). The values are then sorted into the different
+ * intervals and the number of values in each interval is stored for output
+ * later. In case only one data set was given, the resulting histogram will be
+ * a 2d one, while it will be a 3d one if more than one data set was given.
+ * For more than one data set, the same intervals are used for each of them
+ * anyway, to make comparison easier.
*
*
* <h3>Ways to generate the intervals</h3>
* At present, the following schemes for interval spacing are implemented:
* <ul>
* <li> Linear spacing: The intervals are distributed in constant steps
- * between the minimum and maximum values of the data.
- * <li> Logaritmic spacing: The intervals are distributed in constant
- * steps between the minimum and maximum values of the logs of the values.
- * This scheme is only useful if the data has only positive values.
- * Negative and zero values are sorted into the leftmost interval.
+ * between the minimum and maximum values of the data.
+ * <li> Logaritmic spacing: The intervals are distributed in constant steps
+ * between the minimum and maximum values of the logs of the values. This
+ * scheme is only useful if the data has only positive values. Negative and
+ * zero values are sorted into the leftmost interval.
* </ul>
*
- * To keep programs extendible, you can use the two functions
- * @p get_interval_spacing_names and @p parse_interval_spacing, which always
- * give you a complete list of spacing formats presently supported and are
- * able to generate the respective value of the @p enum. If you use them,
- * you can write your program in a way such that it only needs to be
- * recompiled to take effect of newly added formats, without changing your
- * code.
+ * To keep programs extendible, you can use the two functions @p
+ * get_interval_spacing_names and @p parse_interval_spacing, which always give
+ * you a complete list of spacing formats presently supported and are able to
+ * generate the respective value of the @p enum. If you use them, you can
+ * write your program in a way such that it only needs to be recompiled to
+ * take effect of newly added formats, without changing your code.
*
*
* <h3>Output formats</h3>
{
public:
/**
- * Definition of several ways to arrange
- * the spacing of intervals.
+ * Definition of several ways to arrange the spacing of intervals.
*/
enum IntervalSpacing
{
/**
- * Take several lists of values, each on
- * to produce one histogram that will
+ * Take several lists of values, each on to produce one histogram that will
* then be arrange one behind each other.
*
- * Using several data sets at once allows
- * to compare them more easily, since
- * the intervals into which the data is
- * sorted is the same for all data sets.
+ * Using several data sets at once allows to compare them more easily, since
+ * the intervals into which the data is sorted is the same for all data
+ * sets.
*
- * The histograms will be arranged such
- * that the computed intervals of the
- * <tt>values[i][j]</tt> form the x-range,
- * and the number of values in each
- * interval will be the y-range (for
- * 2d plots) or the z-range (for 3d
- * plots). For 3d plots, the @p y_values
- * parameter is used to assign each
- * data set a value in the y direction,
- * which is the depth coordinate in the
- * resulting plot. For 2d plots,
- * the @p y_values are ignored.
+ * The histograms will be arranged such that the computed intervals of the
+ * <tt>values[i][j]</tt> form the x-range, and the number of values in each
+ * interval will be the y-range (for 2d plots) or the z-range (for 3d
+ * plots). For 3d plots, the @p y_values parameter is used to assign each
+ * data set a value in the y direction, which is the depth coordinate in the
+ * resulting plot. For 2d plots, the @p y_values are ignored.
*
- * If you give only one data set, i.e.
- * <tt>values.size()==1</tt>, then the
- * resulting histogram will be a 2d
- * one.
+ * If you give only one data set, i.e. <tt>values.size()==1</tt>, then the
+ * resulting histogram will be a 2d one.
*
- * @p n_intervals denotes the number of
- * intervals into which the data will be
- * sorted; @p interval_spacing denotes
- * the way the bounds of the intervals
- * are computed. Refer to the general
- * documentation for more information
- * on this.
+ * @p n_intervals denotes the number of intervals into which the data will
+ * be sorted; @p interval_spacing denotes the way the bounds of the
+ * intervals are computed. Refer to the general documentation for more
+ * information on this.
*/
template <typename number>
void evaluate (const std::vector<Vector<number> > &values,
const IntervalSpacing interval_spacing = linear);
/**
- * This function is only a wrapper
- * to the above one in case you have
- * only one data set.
+ * This function is only a wrapper to the above one in case you have only
+ * one data set.
*/
template <typename number>
void evaluate (const Vector<number> &values,
const IntervalSpacing interval_spacing = linear);
/**
- * Write the histogram computed by
- * the @p evaluate function to a
- * stream in a format suitable to
- * the GNUPLOT program. The function
- * generates 2d or 3d histograms.
+ * Write the histogram computed by the @p evaluate function to a stream in a
+ * format suitable to the GNUPLOT program. The function generates 2d or 3d
+ * histograms.
*/
void write_gnuplot (std::ostream &out) const;
/**
- * Return allowed names for the interval
- * spacing as string. At present this
+ * Return allowed names for the interval spacing as string. At present this
* is "linear|logarithmic".
*/
static std::string get_interval_spacing_names ();
/**
- * Get a string containing one of the
- * names returned by the above function
- * and return the respective value of
- * @p IntervalSpacing. Throw an error
- * if the string is no valid one.
+ * Get a string containing one of the names returned by the above function
+ * and return the respective value of @p IntervalSpacing. Throw an error if
+ * the string is no valid one.
*/
static IntervalSpacing parse_interval_spacing (const std::string &name);
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
private:
/**
- * Structure denoting one
- * interval.
+ * Structure denoting one interval.
*/
struct Interval
{
/**
- * Constructor. Sets the
- * bounds and sets the number of
- * values in this interval to zero.
+ * Constructor. Sets the bounds and sets the number of values in this
+ * interval to zero.
*/
Interval (const double left_point,
const double right_point);
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
double right_point;
/**
- * Number of values in this
- * interval.
+ * Number of values in this interval.
*/
unsigned int content;
};
/**
- * "Less-than" operation which
- * finds the minimal positive value
- * by sorting zero and negative value
- * to be larger than the largest positive
- * number. Used to find the lower bound
- * of the leftmost interval in the
- * logarithmic case interval spacing
- * scheme.
+ * "Less-than" operation which finds the minimal positive value by sorting
+ * zero and negative value to be larger than the largest positive number.
+ * Used to find the lower bound of the leftmost interval in the logarithmic
+ * case interval spacing scheme.
*
- * Return @p true, if (<tt>n1<n2</tt>,
- * and (<tt>n1>0</tt> or <tt>n2<0</tt>)), or
- * (n2<n1 and n1>0 and n2<=0). This
- * in effect sorts all negativ
- * numbers to be larger than the
- * largest positive number.
+ * Return @p true, if (<tt>n1<n2</tt>, and (<tt>n1>0</tt> or
+ * <tt>n2<0</tt>)), or (n2<n1 and n1>0 and n2<=0). This in effect sorts all
+ * negativ numbers to be larger than the largest positive number.
*/
template <typename number>
static bool logarithmic_less (const number n1,
const number n2);
/**
- * Vector holding one set of intervals
- * for each data set given to the
- * @p evaluate function.
+ * Vector holding one set of intervals for each data set given to the @p
+ * evaluate function.
*/
std::vector<std::vector<Interval> > intervals;
/**
- * Values for the depth axis of 3d
- * histograms. Stored in the @p evaluate
+ * Values for the depth axis of 3d histograms. Stored in the @p evaluate
* function.
*/
std::vector<double> y_values;
/**
- * This namespace provides functions that assemble certain standard matrices for a
- * given triangulation, using a given finite element, a given mapping and a
- * quadrature formula.
+ * This namespace provides functions that assemble certain standard matrices
+ * for a given triangulation, using a given finite element, a given mapping
+ * and a quadrature formula.
*
*
* <h3>Conventions for all functions</h3>
*
- * There exist two versions of each function. One with a Mapping
- * argument and one without. If a code uses a mapping different from
- * MappingQ1 the functions <em>with</em> mapping argument should
- * be used. Code that uses only MappingQ1 may also use the
- * functions <em>without</em> Mapping argument. Each of these
- * latter functions create a MappingQ1 object and just call the
- * respective functions with that object as mapping argument.
+ * There exist two versions of each function. One with a Mapping argument and
+ * one without. If a code uses a mapping different from MappingQ1 the
+ * functions <em>with</em> mapping argument should be used. Code that uses
+ * only MappingQ1 may also use the functions <em>without</em> Mapping
+ * argument. Each of these latter functions create a MappingQ1 object and just
+ * call the respective functions with that object as mapping argument.
*
- * All functions take a sparse matrix object to hold the matrix to be
- * created. The functions assume that the matrix is initialized with a
- * sparsity pattern (SparsityPattern) corresponding to the given degree
- * of freedom handler, i.e. the sparsity structure is already as needed.
- * You can do this by calling the DoFTools::make_sparsity_pattern()
- * function.
+ * All functions take a sparse matrix object to hold the matrix to be created.
+ * The functions assume that the matrix is initialized with a sparsity pattern
+ * (SparsityPattern) corresponding to the given degree of freedom handler,
+ * i.e. the sparsity structure is already as needed. You can do this by
+ * calling the DoFTools::make_sparsity_pattern() function.
*
* Furthermore it is assumed that no relevant data is in the matrix. Some
* entries will be overwritten and some others will contain invalid data if
* the matrix wasn't empty before. Therefore you may want to clear the matrix
* before assemblage.
*
- * By default, all created matrices are `raw': they are not condensed,
- * i.e. hanging nodes are not eliminated. The reason is that you may
- * want to add several matrices and could then condense afterwards
- * only once, instead of for every matrix. To actually do computations
- * with these matrices, you have to condense the matrix using the
- * ConstraintMatrix::condense function; you also have to
- * condense the right hand side accordingly and distribute the
+ * By default, all created matrices are `raw': they are not condensed, i.e.
+ * hanging nodes are not eliminated. The reason is that you may want to add
+ * several matrices and could then condense afterwards only once, instead of
+ * for every matrix. To actually do computations with these matrices, you have
+ * to condense the matrix using the ConstraintMatrix::condense function; you
+ * also have to condense the right hand side accordingly and distribute the
* solution afterwards. Alternatively, you can give an optional argument
* ConstraintMatrix that writes cell matrix (and vector) entries with
* distribute_local_to_global into the global matrix and vector. This way,
- * adding several matrices from different sources is more complicated and
- * you should make sure that you do not mix different ways of applying
- * constraints. Particular caution is necessary when the given
- * constraint matrix contains inhomogeneous constraints: In that case, the
- * matrix assembled this way must be the only matrix (or you need to
- * assemble the <b>same</b> right hand side for <b>every</b> matrix
- * you generate and add together).
+ * adding several matrices from different sources is more complicated and you
+ * should make sure that you do not mix different ways of applying
+ * constraints. Particular caution is necessary when the given constraint
+ * matrix contains inhomogeneous constraints: In that case, the matrix
+ * assembled this way must be the only matrix (or you need to assemble the
+ * <b>same</b> right hand side for <b>every</b> matrix you generate and add
+ * together).
*
- * If you want to use boundary conditions with the matrices generated
- * by the functions of this class in addition to the ones in a possible
- * constraint matrix, you have to use a function like
- * <tt>ProblemBase<>::apply_dirichlet_bc</tt> to matrix and right hand
- * side.
+ * If you want to use boundary conditions with the matrices generated by the
+ * functions of this class in addition to the ones in a possible constraint
+ * matrix, you have to use a function like
+ * <tt>ProblemBase<>::apply_dirichlet_bc</tt> to matrix and right hand side.
*
*
* <h3>Supported matrices</h3>
*
* At present there are functions to create the following matrices:
* <ul>
- * <li> @p create_mass_matrix: create the matrix with entries
- * $m_{ij} = \int_\Omega \phi_i(x) \phi_j(x) dx$ by numerical
- * quadrature. Here, the $\phi_i$ are the basis functions of the
- * finite element space given.
+ * <li> @p create_mass_matrix: create the matrix with entries $m_{ij} =
+ * \int_\Omega \phi_i(x) \phi_j(x) dx$ by numerical quadrature. Here, the
+ * $\phi_i$ are the basis functions of the finite element space given.
*
- * A coefficient may be given to evaluate
- * $m_{ij} = \int_\Omega a(x) \phi_i(x) \phi_j(x) dx$ instead.
+ * A coefficient may be given to evaluate $m_{ij} = \int_\Omega a(x) \phi_i(x)
+ * \phi_j(x) dx$ instead.
*
- * <li> @p create_laplace_matrix: create the matrix with entries
- * $a_{ij} = \int_\Omega \nabla\phi_i(x) \nabla\phi_j(x) dx$ by
- * numerical quadrature.
+ * <li> @p create_laplace_matrix: create the matrix with entries $a_{ij} =
+ * \int_\Omega \nabla\phi_i(x) \nabla\phi_j(x) dx$ by numerical quadrature.
*
- * Again, a coefficient may be given to evaluate
- * $a_{ij} = \int_\Omega a(x) \nabla\phi_i(x) \nabla\phi_j(x) dx$ instead.
+ * Again, a coefficient may be given to evaluate $a_{ij} = \int_\Omega a(x)
+ * \nabla\phi_i(x) \nabla\phi_j(x) dx$ instead.
* </ul>
*
- * Make sure that the order of the Quadrature formula given to these
- * functions is sufficiently high to compute the matrices with the
- * required accuracy. For the choice of this quadrature rule you need
- * to take into account the polynomial degree of the FiniteElement
- * basis functions, the roughness of the coefficient @p a, as well as
- * the degree of the given @p Mapping (if any).
+ * Make sure that the order of the Quadrature formula given to these functions
+ * is sufficiently high to compute the matrices with the required accuracy.
+ * For the choice of this quadrature rule you need to take into account the
+ * polynomial degree of the FiniteElement basis functions, the roughness of
+ * the coefficient @p a, as well as the degree of the given @p Mapping (if
+ * any).
*
- * Note, that for vector-valued elements the mass matrix and the
- * laplace matrix is implemented in such a way that each component
- * couples only with itself, i.e. there is no coupling of shape
- * functions belonging to different components. If the degrees of
- * freedom have been sorted according to their vector component (e.g.,
- * using DoFRenumbering::component_wise()), then the resulting
- * matrices will be block diagonal.
+ * Note, that for vector-valued elements the mass matrix and the laplace
+ * matrix is implemented in such a way that each component couples only with
+ * itself, i.e. there is no coupling of shape functions belonging to different
+ * components. If the degrees of freedom have been sorted according to their
+ * vector component (e.g., using DoFRenumbering::component_wise()), then the
+ * resulting matrices will be block diagonal.
*
- * If the finite element for which the mass matrix or the Laplace
- * matrix is to be built has more than one component, the functions
- * accept a single coefficient as well as a vector valued coefficient
- * function. For the latter case, the number of components must
- * coincide with the number of components of the system finite
- * element.
+ * If the finite element for which the mass matrix or the Laplace matrix is to
+ * be built has more than one component, the functions accept a single
+ * coefficient as well as a vector valued coefficient function. For the latter
+ * case, the number of components must coincide with the number of components
+ * of the system finite element.
*
*
* <h3>Matrices on the boundary</h3>
*
* <h3>Right hand sides</h3>
*
- * In many cases, you will not only want to build the matrix, but also
- * a right hand side, which will give a vector with
- * $f_i = \int_\Omega f(x) \phi_i(x) dx$. For this purpose, each function
- * exists in two versions, one only building the matrix and one also
- * building the right hand side vector. If you want to create a right
- * hand side vector without creating a matrix, you can use the
- * VectorTools::create_right_hand_side() function. The use of the
- * latter may be useful if you want to create many right hand side
- * vectors.
+ * In many cases, you will not only want to build the matrix, but also a right
+ * hand side, which will give a vector with $f_i = \int_\Omega f(x) \phi_i(x)
+ * dx$. For this purpose, each function exists in two versions, one only
+ * building the matrix and one also building the right hand side vector. If
+ * you want to create a right hand side vector without creating a matrix, you
+ * can use the VectorTools::create_right_hand_side() function. The use of the
+ * latter may be useful if you want to create many right hand side vectors.
*
* @ingroup numerics
* @author Wolfgang Bangerth, 1998, Ralf Hartmann, 2001
namespace MatrixCreator
{
/**
- * Assemble the mass matrix. If no coefficient is given (i.e., if
- * the pointer to a function object is zero as it is by default),
- * the coefficient is taken as being constant and equal to one.
+ * Assemble the mass matrix. If no coefficient is given (i.e., if the
+ * pointer to a function object is zero as it is by default), the
+ * coefficient is taken as being constant and equal to one.
*
* If the library is configured to use multithreading, this function works
* in parallel.
*
- * The optional argument @p constraints allows to apply constraints
- * on the resulting matrix directly. Note, however, that this
- * becomes difficult when you have inhomogeneous constraints and
- * later want to add several such matrices, for example in time
- * dependent settings such as the main loop of step-26.
+ * The optional argument @p constraints allows to apply constraints on the
+ * resulting matrix directly. Note, however, that this becomes difficult
+ * when you have inhomogeneous constraints and later want to add several
+ * such matrices, for example in time dependent settings such as the main
+ * loop of step-26.
*
* See the general doc of this class for more information.
*/
const ConstraintMatrix &constraints = ConstraintMatrix());
/**
- * Assemble the mass matrix and a right hand side vector. If no
- * coefficient is given (i.e., if the pointer to a function object
- * is zero as it is by default), the coefficient is taken as being
- * constant and equal to one.
+ * Assemble the mass matrix and a right hand side vector. If no coefficient
+ * is given (i.e., if the pointer to a function object is zero as it is by
+ * default), the coefficient is taken as being constant and equal to one.
*
* If the library is configured to use multithreading, this function works
* in parallel.
*
* The optional argument @p constraints allows to apply constraints on the
- * resulting matrix directly. Note, however, that this
- * becomes difficult when you have inhomogeneous constraints and
- * later want to add several such matrices, for example in time
- * dependent settings such as the main loop of step-26.
+ * resulting matrix directly. Note, however, that this becomes difficult
+ * when you have inhomogeneous constraints and later want to add several
+ * such matrices, for example in time dependent settings such as the main
+ * loop of step-26.
*
* See the general doc of this class for more information.
*/
std::vector<unsigned int> component_mapping = std::vector<unsigned int>());
/**
- * Assemble the Laplace matrix. If no coefficient is given (i.e., if
- * the pointer to a function object is zero as it is by default),
- * the coefficient is taken as being constant and equal to one.
+ * Assemble the Laplace matrix. If no coefficient is given (i.e., if the
+ * pointer to a function object is zero as it is by default), the
+ * coefficient is taken as being constant and equal to one.
*
* If the library is configured to use multithreading, this function works
* in parallel.
*
* The optional argument @p constraints allows to apply constraints on the
- * resulting matrix directly. Note, however, that this
- * becomes difficult when you have inhomogeneous constraints and
- * later want to add several such matrices, for example in time
- * dependent settings such as the main loop of step-26.
+ * resulting matrix directly. Note, however, that this becomes difficult
+ * when you have inhomogeneous constraints and later want to add several
+ * such matrices, for example in time dependent settings such as the main
+ * loop of step-26.
*
* See the general doc of this class for more information.
*/
* in parallel.
*
* The optional argument @p constraints allows to apply constraints on the
- * resulting matrix directly. Note, however, that this
- * becomes difficult when you have inhomogeneous constraints and
- * later want to add several such matrices, for example in time
- * dependent settings such as the main loop of step-26.
+ * resulting matrix directly. Note, however, that this becomes difficult
+ * when you have inhomogeneous constraints and later want to add several
+ * such matrices, for example in time dependent settings such as the main
+ * loop of step-26.
*
* See the general doc of this class for more information.
*/
/**
- * Provide a collection of functions operating on matrices. These include
- * the application of boundary conditions to a linear system of equations
- * and others.
+ * Provide a collection of functions operating on matrices. These include the
+ * application of boundary conditions to a linear system of equations and
+ * others.
*
*
* <h3>Boundary conditions</h3>
*
- * The apply_boundary_values() function inserts boundary conditions
- * into a system of equations. To actually do this you have to
- * specify a list of degree of freedom indices along with the values
- * these degrees of freedom shall assume. To see how to get such a
- * list, see the discussion of the
+ * The apply_boundary_values() function inserts boundary conditions into a
+ * system of equations. To actually do this you have to specify a list of
+ * degree of freedom indices along with the values these degrees of freedom
+ * shall assume. To see how to get such a list, see the discussion of the
* VectorTools::interpolate_boundary_values function.
*
* There are two ways to incorporate fixed degrees of freedom such as boundary
* particular structure.
*
* Finding which rows contain an entry in the column for which we are
- * presently performing a Gauss elimination step is either difficult
- * or very simple, depending on the circumstances. If the sparsity
- * pattern is symmetric (whether the matrix is symmetric is irrelevant
- * here), then we can infer the rows which have a nonzero entry in the
- * present column by looking at which columns in the present row are
- * nonempty. In this case, we only need to look into a fixed number of
- * rows and need not search all rows. On the other hand, if the
- * sparsity pattern is nonsymmetric, then we need to use an iterative
- * solver which can handle nonsymmetric matrices in any case, so there
- * may be no need to do the Gauss elimination anyway. In fact, this is
- * the way the function works: it takes a parameter
- * (@p eliminate_columns) that specifies whether the sparsity pattern
- * is symmetric; if so, then the column is eliminated and the right
- * hand side is also modified accordingly. If not, then only the row
- * is deleted and the column is not touched at all, and all right hand
- * side values apart from the one corresponding to the present row
- * remain unchanged.
- *
- * If the sparsity pattern for your matrix is non-symmetric, you must
- * set the value of this parameter to @p false in any case, since then
- * we can't eliminate the column without searching all rows, which
- * would be too expensive (if @p N be the number of rows, and @p m the
- * number of nonzero elements per row, then eliminating one column is
- * an <tt>O(N*log(m))</tt> operation, since searching in each row takes
- * <tt>log(m)</tt> operations). If your sparsity pattern is symmetric, but
- * your matrix is not, then you might specify @p false as well. If your
- * sparsity pattern and matrix are both symmetric, you might want to
- * specify @p true (the complexity of eliminating one row is then
- * <tt>O(m*log(m))</tt>, since we only have to search @p m rows for the
- * respective element of the column). Given the fact that @p m is
- * roughly constant, irrespective of the discretization, and that the
- * number of boundary nodes is <tt>sqrt(N)</tt> in 2d, the algorithm for
- * symmetric sparsity patterns is <tt>O(sqrt(N)*m*log(m))</tt>, while it
- * would be <tt>O(N*sqrt(N)*log(m))</tt> for the general case; the latter
- * is too expensive to be performed.
- *
- * It seems as if we had to make clear not to overwrite the lines of
- * other boundary nodes when doing the Gauss elimination
- * step. However, since we reset the right hand side when passing such
- * a node, it is not a problem to change the right hand side values of
- * other boundary nodes not yet processed. It would be a problem to
- * change those entries of nodes already processed, but since the
- * matrix entry of the present column on the row of an already
- * processed node is zero, the Gauss step does not change the right
- * hand side. We need therefore not take special care of other
- * boundary nodes.
+ * presently performing a Gauss elimination step is either difficult or very
+ * simple, depending on the circumstances. If the sparsity pattern is
+ * symmetric (whether the matrix is symmetric is irrelevant here), then we can
+ * infer the rows which have a nonzero entry in the present column by looking
+ * at which columns in the present row are nonempty. In this case, we only
+ * need to look into a fixed number of rows and need not search all rows. On
+ * the other hand, if the sparsity pattern is nonsymmetric, then we need to
+ * use an iterative solver which can handle nonsymmetric matrices in any case,
+ * so there may be no need to do the Gauss elimination anyway. In fact, this
+ * is the way the function works: it takes a parameter (@p eliminate_columns)
+ * that specifies whether the sparsity pattern is symmetric; if so, then the
+ * column is eliminated and the right hand side is also modified accordingly.
+ * If not, then only the row is deleted and the column is not touched at all,
+ * and all right hand side values apart from the one corresponding to the
+ * present row remain unchanged.
+ *
+ * If the sparsity pattern for your matrix is non-symmetric, you must set the
+ * value of this parameter to @p false in any case, since then we can't
+ * eliminate the column without searching all rows, which would be too
+ * expensive (if @p N be the number of rows, and @p m the number of nonzero
+ * elements per row, then eliminating one column is an <tt>O(N*log(m))</tt>
+ * operation, since searching in each row takes <tt>log(m)</tt> operations).
+ * If your sparsity pattern is symmetric, but your matrix is not, then you
+ * might specify @p false as well. If your sparsity pattern and matrix are
+ * both symmetric, you might want to specify @p true (the complexity of
+ * eliminating one row is then <tt>O(m*log(m))</tt>, since we only have to
+ * search @p m rows for the respective element of the column). Given the fact
+ * that @p m is roughly constant, irrespective of the discretization, and that
+ * the number of boundary nodes is <tt>sqrt(N)</tt> in 2d, the algorithm for
+ * symmetric sparsity patterns is <tt>O(sqrt(N)*m*log(m))</tt>, while it would
+ * be <tt>O(N*sqrt(N)*log(m))</tt> for the general case; the latter is too
+ * expensive to be performed.
+ *
+ * It seems as if we had to make clear not to overwrite the lines of other
+ * boundary nodes when doing the Gauss elimination step. However, since we
+ * reset the right hand side when passing such a node, it is not a problem to
+ * change the right hand side values of other boundary nodes not yet
+ * processed. It would be a problem to change those entries of nodes already
+ * processed, but since the matrix entry of the present column on the row of
+ * an already processed node is zero, the Gauss step does not change the right
+ * hand side. We need therefore not take special care of other boundary nodes.
*
* To make solving faster, we preset the solution vector with the right
* boundary values (as to why this is necessary, see the discussion below in
* bit more stable. A refined algorithm would set the entry to the mean of the
* other diagonal entries, but this seems to be too expensive.
*
- * In some cases, it might be interesting to solve several times with
- * the same matrix, but for different right hand sides or boundary
- * values. However, since the modification for boundary values of the
- * right hand side vector depends on the original matrix, this is not
- * possible without storing the original matrix somewhere and applying
- * the @p apply_boundary_conditions function to a copy of it each
- * time we want to solve. In that case, you can use the
- * FilteredMatrix class in the @p LAC sublibrary. There you can
- * also find a formal (mathematical) description of the process of
- * modifying the matrix and right hand side vectors for boundary
- * values.
+ * In some cases, it might be interesting to solve several times with the same
+ * matrix, but for different right hand sides or boundary values. However,
+ * since the modification for boundary values of the right hand side vector
+ * depends on the original matrix, this is not possible without storing the
+ * original matrix somewhere and applying the @p apply_boundary_conditions
+ * function to a copy of it each time we want to solve. In that case, you can
+ * use the FilteredMatrix class in the @p LAC sublibrary. There you can also
+ * find a formal (mathematical) description of the process of modifying the
+ * matrix and right hand side vectors for boundary values.
*
*
* <h3>Local elimination</h3>
*
- * The second way of handling boundary values is to modify the local
- * matrix and vector contributions appropriately before transferring
- * them into the global sparse matrix and vector. This is what
- * local_apply_boundary_values() does. The advantage is that we save
- * the call to the apply_boundary_values function (which is expensive
- * because it has to work on sparse data structures). On the other
- * hand, the local_apply_boundary_values() function is called many
- * times, even if we only have a very small number of fixed boundary
- * nodes, and the main drawback is that this function doesn't work as
- * expected if there are hanging nodes that also need to be
- * treated. The reason that this function doesn't work is that it is
- * meant to be run before distribution into the global matrix,
- * i.e. before hanging nodes are distributed; since hanging nodes can
- * be constrained to a boundary node, the treatment of hanging nodes
- * can add entries again to rows and columns corresponding to boundary
- * values and that we have already vacated in the local elimination
- * step. To make things worse, in 3d constrained nodes can even lie on
- * the boundary. Thus, it is imperative that boundary node elimination
- * happens @em after hanging node elimination, but this can't be
- * achieved with local elimination of boundary nodes unless there are
- * no hanging node constraints at all.
- *
- * Local elimination has one additional drawback: we don't have access
- * to the solution vector, only to the local contributions to the
- * matrix and right hand side. The problem with this is subtle, but
- * can lead to very hard to find difficulties: when we eliminate a
- * degree of freedom, we delete the row and column of this unknown,
- * and set the diagonal entry to some positive value. To make the
- * problem more or less well-conditioned, we set this diagonal entry
- * to the absolute value of its prior value if that was non-zero, or
- * to the average magnitude of all other nonzero diagonal
- * elements. Then we set the right hand side value such that the
- * resulting solution entry has the right value as given by the
- * boundary values. Since we add these contributions up over all local
- * contributions, the diagonal entry and the respective value in the
- * right hand side are added up correspondingly, so that the entry in
- * the solution of the linear system is still valid.
+ * The second way of handling boundary values is to modify the local matrix
+ * and vector contributions appropriately before transferring them into the
+ * global sparse matrix and vector. This is what local_apply_boundary_values()
+ * does. The advantage is that we save the call to the apply_boundary_values
+ * function (which is expensive because it has to work on sparse data
+ * structures). On the other hand, the local_apply_boundary_values() function
+ * is called many times, even if we only have a very small number of fixed
+ * boundary nodes, and the main drawback is that this function doesn't work as
+ * expected if there are hanging nodes that also need to be treated. The
+ * reason that this function doesn't work is that it is meant to be run before
+ * distribution into the global matrix, i.e. before hanging nodes are
+ * distributed; since hanging nodes can be constrained to a boundary node, the
+ * treatment of hanging nodes can add entries again to rows and columns
+ * corresponding to boundary values and that we have already vacated in the
+ * local elimination step. To make things worse, in 3d constrained nodes can
+ * even lie on the boundary. Thus, it is imperative that boundary node
+ * elimination happens @em after hanging node elimination, but this can't be
+ * achieved with local elimination of boundary nodes unless there are no
+ * hanging node constraints at all.
+ *
+ * Local elimination has one additional drawback: we don't have access to the
+ * solution vector, only to the local contributions to the matrix and right
+ * hand side. The problem with this is subtle, but can lead to very hard to
+ * find difficulties: when we eliminate a degree of freedom, we delete the row
+ * and column of this unknown, and set the diagonal entry to some positive
+ * value. To make the problem more or less well-conditioned, we set this
+ * diagonal entry to the absolute value of its prior value if that was non-
+ * zero, or to the average magnitude of all other nonzero diagonal elements.
+ * Then we set the right hand side value such that the resulting solution
+ * entry has the right value as given by the boundary values. Since we add
+ * these contributions up over all local contributions, the diagonal entry and
+ * the respective value in the right hand side are added up correspondingly,
+ * so that the entry in the solution of the linear system is still valid.
*
* A problem arises, however, if the diagonal entries so chosen are not
* appropriate for the linear system. Consider, for example, a mixed Laplace
* if we eliminate boundary values, we delete some rows and columns, but we
* also introduce a few entries on the diagonal of the lower right block, so
* that we get the system <tt>[[A' B'][C'^T X]]</tt>. The diagonal entries in
- * the matrix @p X will be of the same order of magnitude as those in @p
- * A. Now, if we solve this system in the Schur complement formulation, we
- * have to invert the matrix <tt>X-C'^TA'^{-1}B'</tt>. Deleting rows and
- * columns above makes sure that boundary nodes indeed have empty rows and
- * columns in the Schur complement as well, except for the entries in @p
- * X. However, the entries in @p X may be of significantly different orders of
- * magnitude than those in <tt>C'^TA'^{-1}B'</tt>! If this is the case, we may
- * run into trouble with iterative solvers. For example, assume that we start
- * with zero entries in the solution vector and that the entries in @p X are
- * several orders of magnitude too small; in this case, iterative solvers will
- * compute the residual vector in each step and form correction vectors, but
- * since the entries in @p X are so small, the residual contributions for
- * boundary nodes are really small, despite the fact that the boundary nodes
- * are still at values close to zero and not in accordance with the prescribed
- * boundary values. Since the residual is so small, the corrections the
- * iterative solver computes are very small, and in the end the solver will
- * indicate convergence to a small total residual with the boundary values
- * still being significantly wrong.
+ * the matrix @p X will be of the same order of magnitude as those in @p A.
+ * Now, if we solve this system in the Schur complement formulation, we have
+ * to invert the matrix <tt>X-C'^TA'^{-1}B'</tt>. Deleting rows and columns
+ * above makes sure that boundary nodes indeed have empty rows and columns in
+ * the Schur complement as well, except for the entries in @p X. However, the
+ * entries in @p X may be of significantly different orders of magnitude than
+ * those in <tt>C'^TA'^{-1}B'</tt>! If this is the case, we may run into
+ * trouble with iterative solvers. For example, assume that we start with zero
+ * entries in the solution vector and that the entries in @p X are several
+ * orders of magnitude too small; in this case, iterative solvers will compute
+ * the residual vector in each step and form correction vectors, but since the
+ * entries in @p X are so small, the residual contributions for boundary nodes
+ * are really small, despite the fact that the boundary nodes are still at
+ * values close to zero and not in accordance with the prescribed boundary
+ * values. Since the residual is so small, the corrections the iterative
+ * solver computes are very small, and in the end the solver will indicate
+ * convergence to a small total residual with the boundary values still being
+ * significantly wrong.
*
* We avoid this problem in the global elimination process described above by
- * 'priming' the solution vector with the correct values for boundary
- * nodes. However, we can't do this for the local elimination
- * process. Therefore, if you experience a problem like the one above, you
- * need to either increase the diagonal entries in @p X to a size that matches
- * those in the other part of the Schur complement, or, simpler, prime the
- * solution vector before you start the solver.
+ * 'priming' the solution vector with the correct values for boundary nodes.
+ * However, we can't do this for the local elimination process. Therefore, if
+ * you experience a problem like the one above, you need to either increase
+ * the diagonal entries in @p X to a size that matches those in the other part
+ * of the Schur complement, or, simpler, prime the solution vector before you
+ * start the solver.
*
- * In conclusion, local elimination of boundary nodes only works if
- * there are no hanging nodes and even then doesn't always work fully
- * satisfactorily.
+ * In conclusion, local elimination of boundary nodes only works if there are
+ * no hanging nodes and even then doesn't always work fully satisfactorily.
*
* @ingroup numerics
* @author Wolfgang Bangerth, 1998, 2000, 2004, 2005
namespace MatrixTools
{
/**
- * Import namespace MatrixCreator for
- * backward compatibility with older
- * versions of deal.II in which these
- * namespaces were classes and class
- * MatrixTools was publicly derived from
- * class MatrixCreator.
+ * Import namespace MatrixCreator for backward compatibility with older
+ * versions of deal.II in which these namespaces were classes and class
+ * MatrixTools was publicly derived from class MatrixCreator.
*/
using namespace MatrixCreator;
/**
- * Apply Dirichlet boundary conditions
- * to the system matrix and vectors
- * as described in the general
- * documentation.
+ * Apply Dirichlet boundary conditions to the system matrix and vectors as
+ * described in the general documentation.
*/
template <typename number>
void
const bool eliminate_columns = true);
/**
- * Apply Dirichlet boundary
- * conditions to the system
- * matrix and vectors as
- * described in the general
- * documentation. This function
- * works for block sparse
- * matrices and block vectors
+ * Apply Dirichlet boundary conditions to the system matrix and vectors as
+ * described in the general documentation. This function works for block
+ * sparse matrices and block vectors
*/
template <typename number>
void
#ifdef DEAL_II_WITH_PETSC
/**
- * Apply Dirichlet boundary conditions to
- * the system matrix and vectors as
- * described in the general
- * documentation. This function works on
- * the classes that are used to wrap
- * PETSc objects.
+ * Apply Dirichlet boundary conditions to the system matrix and vectors as
+ * described in the general documentation. This function works on the
+ * classes that are used to wrap PETSc objects.
*
- * Note that this function is not very
- * efficient: it needs to alternatingly
- * read and write into the matrix, a
- * situation that PETSc does not handle
- * too well. In addition, we only get rid
- * of rows corresponding to boundary
- * nodes, but the corresponding case of
- * deleting the respective columns
- * (i.e. if @p eliminate_columns is @p
- * true) is not presently implemented,
- * and probably will never because it is
- * too expensive without direct access to
- * the PETSc data structures. (This leads
- * to the situation where the action
- * indicated by the default value of the
- * last argument is actually not
- * implemented; that argument has
- * <code>true</code> as its default value
- * to stay consistent with the other
- * functions of same name in this class.)
- * A third reason against this function
- * is that it doesn't handle the case
- * where the matrix is distributed across
- * an MPI system.
+ * Note that this function is not very efficient: it needs to alternatingly
+ * read and write into the matrix, a situation that PETSc does not handle
+ * too well. In addition, we only get rid of rows corresponding to boundary
+ * nodes, but the corresponding case of deleting the respective columns
+ * (i.e. if @p eliminate_columns is @p true) is not presently implemented,
+ * and probably will never because it is too expensive without direct access
+ * to the PETSc data structures. (This leads to the situation where the
+ * action indicated by the default value of the last argument is actually
+ * not implemented; that argument has <code>true</code> as its default value
+ * to stay consistent with the other functions of same name in this class.)
+ * A third reason against this function is that it doesn't handle the case
+ * where the matrix is distributed across an MPI system.
*
- * This function is used in
- * step-17 and
- * step-18.
+ * This function is used in step-17 and step-18.
*/
void
apply_boundary_values (const std::map<types::global_dof_index,double> &boundary_values,
const bool eliminate_columns = true);
/**
- * Same function, but for parallel PETSc
- * matrices.
+ * Same function, but for parallel PETSc matrices.
*/
void
apply_boundary_values (const std::map<types::global_dof_index,double> &boundary_values,
const bool eliminate_columns = true);
/**
- * Same function, but for
- * parallel PETSc matrices. Note
- * that this function only
- * operates on the local range of
- * the parallel matrix, i.e. it
- * only eliminates rows
- * corresponding to degrees of
- * freedom for which the row is
- * stored on the present
- * processor. All other boundary
- * nodes are ignored, and it
- * doesn't matter whether they
- * are present in the first
- * argument to this function or
- * not. A consequence of this,
- * however, is that this function
- * has to be called from all
- * processors that participate in
- * sharing the contents of the
- * given matrices and vectors. It
- * is also implied that the local
- * range for all objects passed
- * to this function is the same.
+ * Same function, but for parallel PETSc matrices. Note that this function
+ * only operates on the local range of the parallel matrix, i.e. it only
+ * eliminates rows corresponding to degrees of freedom for which the row is
+ * stored on the present processor. All other boundary nodes are ignored,
+ * and it doesn't matter whether they are present in the first argument to
+ * this function or not. A consequence of this, however, is that this
+ * function has to be called from all processors that participate in sharing
+ * the contents of the given matrices and vectors. It is also implied that
+ * the local range for all objects passed to this function is the same.
*/
void
apply_boundary_values (const std::map<types::global_dof_index,double> &boundary_values,
#ifdef DEAL_II_WITH_TRILINOS
/**
- * Apply Dirichlet boundary
- * conditions to the system matrix
- * and vectors as described in the
- * general documentation. This
- * function works on the classes
- * that are used to wrap Trilinos
- * objects.
+ * Apply Dirichlet boundary conditions to the system matrix and vectors as
+ * described in the general documentation. This function works on the
+ * classes that are used to wrap Trilinos objects.
*
- * Note that this function is not
- * very efficient: it needs to
- * alternatingly read and write
- * into the matrix, a situation
- * that Trilinos does not handle
- * too well. In addition, we only
- * get rid of rows corresponding to
- * boundary nodes, but the
- * corresponding case of deleting
- * the respective columns (i.e. if
- * @p eliminate_columns is @p true)
- * is not presently implemented,
- * and probably will never because
- * it is too expensive without
- * direct access to the Trilinos
- * data structures. (This leads to
- * the situation where the action
- * indicated by the default value
- * of the last argument is actually
- * not implemented; that argument
- * has <code>true</code> as its
- * default value to stay consistent
- * with the other functions of same
- * name in this class.) A third
- * reason against this function is
- * that it doesn't handle the case
- * where the matrix is distributed
- * across an MPI system.
+ * Note that this function is not very efficient: it needs to alternatingly
+ * read and write into the matrix, a situation that Trilinos does not handle
+ * too well. In addition, we only get rid of rows corresponding to boundary
+ * nodes, but the corresponding case of deleting the respective columns
+ * (i.e. if @p eliminate_columns is @p true) is not presently implemented,
+ * and probably will never because it is too expensive without direct access
+ * to the Trilinos data structures. (This leads to the situation where the
+ * action indicated by the default value of the last argument is actually
+ * not implemented; that argument has <code>true</code> as its default value
+ * to stay consistent with the other functions of same name in this class.)
+ * A third reason against this function is that it doesn't handle the case
+ * where the matrix is distributed across an MPI system.
*/
void
apply_boundary_values (const std::map<types::global_dof_index,double> &boundary_values,
const bool eliminate_columns = true);
/**
- * This function does the same as
- * the one above, except now
- * working on block structures.
+ * This function does the same as the one above, except now working on block
+ * structures.
*/
void
apply_boundary_values (const std::map<types::global_dof_index,double> &boundary_values,
const bool eliminate_columns = true);
/**
- * Apply Dirichlet boundary
- * conditions to the system matrix
- * and vectors as described in the
- * general documentation. This
- * function works on the classes
- * that are used to wrap Trilinos
- * objects.
+ * Apply Dirichlet boundary conditions to the system matrix and vectors as
+ * described in the general documentation. This function works on the
+ * classes that are used to wrap Trilinos objects.
*
- * Note that this function is not
- * very efficient: it needs to
- * alternatingly read and write
- * into the matrix, a situation
- * that Trilinos does not handle
- * too well. In addition, we only
- * get rid of rows corresponding to
- * boundary nodes, but the
- * corresponding case of deleting
- * the respective columns (i.e. if
- * @p eliminate_columns is @p true)
- * is not presently implemented,
- * and probably will never because
- * it is too expensive without
- * direct access to the Trilinos
- * data structures. (This leads to
- * the situation where the action
- * indicated by the default value
- * of the last argument is actually
- * not implemented; that argument
- * has <code>true</code> as its
- * default value to stay consistent
- * with the other functions of same
- * name in this class.) This
- * function does work on MPI vector
- * types.
+ * Note that this function is not very efficient: it needs to alternatingly
+ * read and write into the matrix, a situation that Trilinos does not handle
+ * too well. In addition, we only get rid of rows corresponding to boundary
+ * nodes, but the corresponding case of deleting the respective columns
+ * (i.e. if @p eliminate_columns is @p true) is not presently implemented,
+ * and probably will never because it is too expensive without direct access
+ * to the Trilinos data structures. (This leads to the situation where the
+ * action indicated by the default value of the last argument is actually
+ * not implemented; that argument has <code>true</code> as its default value
+ * to stay consistent with the other functions of same name in this class.)
+ * This function does work on MPI vector types.
*/
void
apply_boundary_values (const std::map<types::global_dof_index,double> &boundary_values,
const bool eliminate_columns = true);
/**
- * This function does the same as
- * the one above, except now working
- * on block structures.
+ * This function does the same as the one above, except now working on block
+ * structures.
*/
void
apply_boundary_values (const std::map<types::global_dof_index,double> &boundary_values,
#endif
/**
- * Rather than applying boundary
- * values to the global matrix
- * and vector after creating the
- * global matrix, this function
- * does so during assembly, by
- * modifying the local matrix and
- * vector contributions. If you
- * call this function on all
- * local contributions, the
- * resulting matrix will have the
- * same entries, and the final
- * call to
- * apply_boundary_values() on the
- * global system will not be
- * necessary.
+ * Rather than applying boundary values to the global matrix and vector
+ * after creating the global matrix, this function does so during assembly,
+ * by modifying the local matrix and vector contributions. If you call this
+ * function on all local contributions, the resulting matrix will have the
+ * same entries, and the final call to apply_boundary_values() on the global
+ * system will not be necessary.
*
- * Since this function does not
- * have to work on the
- * complicated data structures of
- * sparse matrices, it is
- * relatively cheap. It may
- * therefore be a win if you have
- * many fixed degrees of freedom
- * (e.g. boundary nodes), or if
- * access to the sparse matrix is
- * expensive (e.g. for block
- * sparse matrices, or for PETSc
- * or trilinos
- * matrices). However, it doesn't
- * work as expected if there are
- * also hanging nodes to be
- * considered. More caveats are
- * listed in the general
- * documentation of this class.
+ * Since this function does not have to work on the complicated data
+ * structures of sparse matrices, it is relatively cheap. It may therefore
+ * be a win if you have many fixed degrees of freedom (e.g. boundary nodes),
+ * or if access to the sparse matrix is expensive (e.g. for block sparse
+ * matrices, or for PETSc or trilinos matrices). However, it doesn't work as
+ * expected if there are also hanging nodes to be considered. More caveats
+ * are listed in the general documentation of this class.
*/
void
local_apply_boundary_values (const std::map<types::global_dof_index,double> &boundary_values,
namespace PointValueHistory
{
/**
- * A class that stores the data needed
- * to reference the support points
- * closest to one requested point.
+ * A class that stores the data needed to reference the support points
+ * closest to one requested point.
*/
template <int dim>
class PointGeometryData
* at ahead of time, as well as giving each solution vector that they want to
* record a mnemonic name. Then, for each step the user calls one of the three
* available "evaluate field" methods to store the data from each time step,
- * and the class extracts data for the requested
- * points to store it. Finally, once the computation is finished, the user can
- * request output files to be generated; these files are in Gnuplot format but
- * are basically just regular text and can easily be imported into other
- * programs well, for example into spreadsheets.
+ * and the class extracts data for the requested points to store it. Finally,
+ * once the computation is finished, the user can request output files to be
+ * generated; these files are in Gnuplot format but are basically just regular
+ * text and can easily be imported into other programs well, for example into
+ * spreadsheets.
*
* The user can store extra variables which do not relate to mesh location
- * specifying n_independent_variables. The class then expects
- * a std::vector of size n_independent_variables to be added during each step
- * using the method @p push_back_independent. This may be used for example for
- * recording external input, logging solver performance data such as time
- * taken to solve the step and solver steps before convergence, saving
- * norms calculated, or simply saving the time, number of time step, or number
- * of nonlinear iteration along with the data evaluated from the mesh.
+ * specifying n_independent_variables. The class then expects a std::vector of
+ * size n_independent_variables to be added during each step using the method
+ * @p push_back_independent. This may be used for example for recording
+ * external input, logging solver performance data such as time taken to solve
+ * the step and solver steps before convergence, saving norms calculated, or
+ * simply saving the time, number of time step, or number of nonlinear
+ * iteration along with the data evaluated from the mesh.
*
* The three "evaluate field" methods each have different strengths and
* weaknesses making each suitable for different contexts:
* <ol>
- * <li>Firstly, the @p evaluate_field version that does not take a @p DataPostprocessor object
- * selects the nearest support point (see @ref GlossSupport "this entry in the glossary")
- * to a given point to
- * extract data from. This makes the code that needs to be run at each time step very short,
- * since looping over the mesh to extract the needed dof_index can be done
- * just once at the start. However, this method is not suitable for
+ * <li>Firstly, the @p evaluate_field version that does not take a @p
+ * DataPostprocessor object selects the nearest support point (see @ref
+ * GlossSupport "this entry in the glossary") to a given point to extract data
+ * from. This makes the code that needs to be run at each time step very
+ * short, since looping over the mesh to extract the needed dof_index can be
+ * done just once at the start. However, this method is not suitable for
* FiniteElement objects that do not assign dofs to actual mesh locations
- * (i.e. FEs without @ref GlossSupport "support points") or if adaptive mesh refinement is used.
- * The reason for the latter restriction is that the location of the closest
- * support point to a given point may change upon mesh refinement.
- * The class will throw an exception if any change to the triangulation is made
- * (Although the nearest support point could be re-computed upon mesh refinement,
- * the location of the support point will most likely change slightly, making the interpretation
- * of the data difficult, hence this is not implemented currently.)
+ * (i.e. FEs without @ref GlossSupport "support points") or if adaptive mesh
+ * refinement is used. The reason for the latter restriction is that the
+ * location of the closest support point to a given point may change upon mesh
+ * refinement. The class will throw an exception if any change to the
+ * triangulation is made (Although the nearest support point could be re-
+ * computed upon mesh refinement, the location of the support point will most
+ * likely change slightly, making the interpretation of the data difficult,
+ * hence this is not implemented currently.)
*
* <li> Secondly, @p evaluate_field_at_requested_location calls @p
* VectorTools::point_value to compute values at the specific point requested.
- * This method is valid for any FE that is supported by @p VectorTools::point_value.
- * Specifically, this method can be called by codes using adaptive mesh refinement.
+ * This method is valid for any FE that is supported by @p
+ * VectorTools::point_value. Specifically, this method can be called by codes
+ * using adaptive mesh refinement.
*
- * <li>Finally, the class offers a function @p evaluate_field that takes a
- * @p DataPostprocessor object. This method allows the deal.II
- * data postprocessor to be used to compute new quantities from the
- * solution on the fly. The values are located at the nearest quadrature
- * point to the requested point. If the mesh is refined between calls, this
- * point will change, so care must be taken when using this method in
- * code using adaptive refinement, but as the output will be meaningful (in
- * the sense that the quadrature point selected is guaranteed to remain in the
- * same vicinity, the class does not prevent the use of this method in adaptive
- * codes. The class provides warnings in the output files if the mesh has changed.
- * Note that one can reduce the error this procedure introduces by providing
- * a quadrature formula that has more points, at the expense of performing more
- * work since then the closest quadrature points is nearer to the point at which
- * the evaluation is really supposed to happen. (As a sidenote: Why not do the
- * evaluation at the requested point right away? The reason for this is that it
- * would require setting up a new quadrature point object on each cell that has
- * only a single point corresponding to the reference coordinates of the point you
- * really want; then initializing a FEValues object with it; then evaluating the
- * solution at this point; then handing the result to the DataPostprocessor object.
- * This sequence of things is expensive -- which is the reason why
- * VectorTools::point_value() is expensive. Using the same quadrature formula
- * on each cell on which we want to evaluate the solution and only having to
- * initialize a FEValue object once is a much cheaper alternative, albeit of
- * course at the expense of getting only an approximate result.)
+ * <li>Finally, the class offers a function @p evaluate_field that takes a @p
+ * DataPostprocessor object. This method allows the deal.II data postprocessor
+ * to be used to compute new quantities from the solution on the fly. The
+ * values are located at the nearest quadrature point to the requested point.
+ * If the mesh is refined between calls, this point will change, so care must
+ * be taken when using this method in code using adaptive refinement, but as
+ * the output will be meaningful (in the sense that the quadrature point
+ * selected is guaranteed to remain in the same vicinity, the class does not
+ * prevent the use of this method in adaptive codes. The class provides
+ * warnings in the output files if the mesh has changed. Note that one can
+ * reduce the error this procedure introduces by providing a quadrature
+ * formula that has more points, at the expense of performing more work since
+ * then the closest quadrature points is nearer to the point at which the
+ * evaluation is really supposed to happen. (As a sidenote: Why not do the
+ * evaluation at the requested point right away? The reason for this is that
+ * it would require setting up a new quadrature point object on each cell that
+ * has only a single point corresponding to the reference coordinates of the
+ * point you really want; then initializing a FEValues object with it; then
+ * evaluating the solution at this point; then handing the result to the
+ * DataPostprocessor object. This sequence of things is expensive -- which is
+ * the reason why VectorTools::point_value() is expensive. Using the same
+ * quadrature formula on each cell on which we want to evaluate the solution
+ * and only having to initialize a FEValue object once is a much cheaper
+ * alternative, albeit of course at the expense of getting only an approximate
+ * result.)
* </ol>
*
- * When recording a new mnemonic name, the user must supply a
- * component_mask (see @ref GlossComponentMask "this glossary entry")
- * to indicate the @ref GlossComponent "(vector) components"
- * to be extracted from the given input. If the user simply wants to extract
- * all the components, the mask need not be explicitly supplied to the @p
- * add_field_name method and the default value of the parameter is sufficient.
- * If the @p evaluate_field with a @p DataPostprocessor object is used, the
- * component_mask is interpreted as the mask of the @p DataPostprocessor
- * return vector. The size of this mask can be different to that of the FE
- * space, but must be provided when the @p add_field_name method is
- * called. One variant of the @p add_field_name method allows an unsigned int
- * input to construct a suitable mask, if all values from the @p
- * DataPostprocessor are desired.
+ * When recording a new mnemonic name, the user must supply a component_mask
+ * (see @ref GlossComponentMask "this glossary entry") to indicate the @ref
+ * GlossComponent "(vector) components" to be extracted from the given input.
+ * If the user simply wants to extract all the components, the mask need not
+ * be explicitly supplied to the @p add_field_name method and the default
+ * value of the parameter is sufficient. If the @p evaluate_field with a @p
+ * DataPostprocessor object is used, the component_mask is interpreted as the
+ * mask of the @p DataPostprocessor return vector. The size of this mask can
+ * be different to that of the FE space, but must be provided when the @p
+ * add_field_name method is called. One variant of the @p add_field_name
+ * method allows an unsigned int input to construct a suitable mask, if all
+ * values from the @p DataPostprocessor are desired.
*
- * The class automatically generates names for the data stored based on the mnemonics
- * supplied. The methods @p add_component_names and @p add_independent_names allow
- * the user to provide lists of names to use instead if desired.
+ * The class automatically generates names for the data stored based on the
+ * mnemonics supplied. The methods @p add_component_names and @p
+ * add_independent_names allow the user to provide lists of names to use
+ * instead if desired.
*
* Following is a little code snippet that shows a common usage of this class:
*
{
public:
/**
- * Provide a stripped down instance of
- * the class which does not support
- * adding points or mesh data. This may
- * be used for example for recording
- * external input or logging solver
- * performance data.
+ * Provide a stripped down instance of the class which does not support
+ * adding points or mesh data. This may be used for example for recording
+ * external input or logging solver performance data.
*/
PointValueHistory (const unsigned int n_independent_variables = 0);
/**
- * Constructor linking the class to a
- * specific @p DoFHandler. This
- * class reads specific data from the @p
- * DoFHandler and stores it internally
- * for quick access (in particular dof
- * indices of closest neighbors to
- * requested points) the class is fairly
- * intolerant to changes to the @p
- * DoFHandler if data at support points
- * is required. Mesh refinement and @p
- * DoFRenumbering methods should be
- * performed before the @p add_points
- * method is called and adaptive grid
- * refinement is only supported by some
- * methods.
+ * Constructor linking the class to a specific @p DoFHandler. This class
+ * reads specific data from the @p DoFHandler and stores it internally for
+ * quick access (in particular dof indices of closest neighbors to requested
+ * points) the class is fairly intolerant to changes to the @p DoFHandler if
+ * data at support points is required. Mesh refinement and @p DoFRenumbering
+ * methods should be performed before the @p add_points method is called and
+ * adaptive grid refinement is only supported by some methods.
*
- * The user can store extra variables
- * which do not relate to mesh location
- * by specifying the number required
- * using n_independent_variables and
- * making calls to @p
- * push_back_independent as needed. This
- * may be used for example for recording
- * external input or logging solver
- * performance data.
+ * The user can store extra variables which do not relate to mesh location
+ * by specifying the number required using n_independent_variables and
+ * making calls to @p push_back_independent as needed. This may be used for
+ * example for recording external input or logging solver performance data.
*/
PointValueHistory (const DoFHandler<dim> &dof_handler,
const unsigned int n_independent_variables = 0);
/**
- * Copy constructor. This constructor can
- * be safely called with a @p
- * PointValueHistory object that contains
- * data, but this could be expensive and
- * should be avoided.
+ * Copy constructor. This constructor can be safely called with a @p
+ * PointValueHistory object that contains data, but this could be expensive
+ * and should be avoided.
*/
PointValueHistory (const PointValueHistory &point_value_history);
/**
- * Assignment operator. This
- * assignment operator can be safely
- * called once the class is closed and
- * data added, but this is provided
- * primarily to allow a @p
- * PointValueHistory object declared in a
- * class to be reinitialized later in the
- * class. Using the assignment operator
- * when the object contains data could be
- * expensive.
+ * Assignment operator. This assignment operator can be safely called once
+ * the class is closed and data added, but this is provided primarily to
+ * allow a @p PointValueHistory object declared in a class to be
+ * reinitialized later in the class. Using the assignment operator when the
+ * object contains data could be expensive.
*/
PointValueHistory &operator=(const PointValueHistory &point_value_history);
/**
- Deconstructor.
- */
+ * Deconstructor.
+ */
~PointValueHistory ();
/**
- * Add a single point to the class. The
- * support points (one per component) in
- * the mesh that are closest to that
- * point are found and their details stored
- * for use when @p evaluate_field is
- * called. If more than one point is
- * required rather use the @p add_points
- * method since this minimizes iterations
- * over the mesh.
+ * Add a single point to the class. The support points (one per component)
+ * in the mesh that are closest to that point are found and their details
+ * stored for use when @p evaluate_field is called. If more than one point
+ * is required rather use the @p add_points method since this minimizes
+ * iterations over the mesh.
*/
void add_point(const Point <dim> &location);
/**
- * Add multiple points to the class. The
- * support points (one per component) in
- * the mesh that are closest to that
- * point is found and their details stored
- * for use when @p evaluate_field is
- * called. If more than one point is
- * required, rather call this method as it
- * is more efficient than the add_point
- * method since it minimizes iterations
- * over the mesh. The points are added to
- * the internal database in the order
- * they appear in the list and there is
- * always a one to one correspondence
- * between the requested point and the
- * added point, even if a point is
- * requested multiple times.
+ * Add multiple points to the class. The support points (one per component)
+ * in the mesh that are closest to that point is found and their details
+ * stored for use when @p evaluate_field is called. If more than one point
+ * is required, rather call this method as it is more efficient than the
+ * add_point method since it minimizes iterations over the mesh. The points
+ * are added to the internal database in the order they appear in the list
+ * and there is always a one to one correspondence between the requested
+ * point and the added point, even if a point is requested multiple times.
*/
void add_points (const std::vector <Point <dim> > &locations);
/**
- * Put another mnemonic string (and hence
- * @p VECTOR) into the class. This method
- * adds storage space for variables equal
- * to the number of true values in
- * component_mask.
- * This also adds extra entries for points
- * that are already in the class, so
- * @p add_field_name and @p add_points can
- * be called in any order.
+ * Put another mnemonic string (and hence @p VECTOR) into the class. This
+ * method adds storage space for variables equal to the number of true
+ * values in component_mask. This also adds extra entries for points that
+ * are already in the class, so @p add_field_name and @p add_points can be
+ * called in any order.
*/
void add_field_name(const std::string &vector_name,
const ComponentMask &component_mask = ComponentMask());
/**
- * Put another mnemonic string (and hence
- * @p VECTOR) into the class. This method
- * adds storage space for n_components
- * variables.
- * This also adds extra entries for points
- * that are already in the class, so
- * @p add_field_name and @p add_points can
- * be called in any order.
- * This method generates a std::vector
- * 0, ..., n_components-1 and calls the
- * previous function.
+ * Put another mnemonic string (and hence @p VECTOR) into the class. This
+ * method adds storage space for n_components variables. This also adds
+ * extra entries for points that are already in the class, so @p
+ * add_field_name and @p add_points can be called in any order. This method
+ * generates a std::vector 0, ..., n_components-1 and calls the previous
+ * function.
*/
void add_field_name(const std::string &vector_name,
const unsigned int n_components);
/**
- * Provide optional names for each component
- * of a field. These names will be used
- * instead of names generated from the
- * field name, if supplied.
+ * Provide optional names for each component of a field. These names will be
+ * used instead of names generated from the field name, if supplied.
*/
void add_component_names(const std::string &vector_name,
const std::vector <std::string> &component_names);
/**
- * Provide optional names for the
- * independent values. These names will
- * be used instead of "Indep_...", if
- * supplied.
+ * Provide optional names for the independent values. These names will be
+ * used instead of "Indep_...", if supplied.
*/
void add_independent_names(const std::vector <std::string> &independent_names);
/**
- * Extract values at the stored points
- * from the VECTOR supplied and add them
- * to the new dataset in vector_name.
- * The component mask supplied when the
- * field was added is used to select
- * components to extract.
- * If a @p DoFHandler is used, one (and only
- * one) evaluate_field method
- * must be called for each dataset (time
- * step, iteration, etc) for each
- * vector_name, otherwise a @p
- * ExcDataLostSync error can occur.
+ * Extract values at the stored points from the VECTOR supplied and add them
+ * to the new dataset in vector_name. The component mask supplied when the
+ * field was added is used to select components to extract. If a @p
+ * DoFHandler is used, one (and only one) evaluate_field method must be
+ * called for each dataset (time step, iteration, etc) for each vector_name,
+ * otherwise a @p ExcDataLostSync error can occur.
*/
template <class VECTOR>
void evaluate_field(const std::string &name,
/**
- * Compute values using a @p DataPostprocessor object
- * with the @p VECTOR supplied and add them
- * to the new dataset in vector_name.
- * The component_mask supplied when the
- * field was added is used to select
- * components to extract from the @p DataPostprocessor
- * return vector.
- * This method takes a vector of field names to
- * process and is preferred if many fields use the
- * same @p DataPostprocessor object as each cell
- * is only located once.
- * The quadrature object supplied is used for all
- * components of a vector field.
- * Although this method will not throw an exception
- * if the mesh has changed. (No internal data structures
- * are invalidated as the quadrature points are repicked
- * each time the function is called.) Nevertheless
- * the user must be aware that if the mesh changes the
- * point selected will also vary slightly, making
- * interpretation of the data more difficult.
- * If a @p DoFHandler is used, one (and only
- * one) evaluate_field method
- * must be called for each dataset (time
- * step, iteration, etc) for each
- * vector_name, otherwise a @p
- * ExcDataLostSync error can occur.
+ * Compute values using a @p DataPostprocessor object with the @p VECTOR
+ * supplied and add them to the new dataset in vector_name. The
+ * component_mask supplied when the field was added is used to select
+ * components to extract from the @p DataPostprocessor return vector. This
+ * method takes a vector of field names to process and is preferred if many
+ * fields use the same @p DataPostprocessor object as each cell is only
+ * located once. The quadrature object supplied is used for all components
+ * of a vector field. Although this method will not throw an exception if
+ * the mesh has changed. (No internal data structures are invalidated as the
+ * quadrature points are repicked each time the function is called.)
+ * Nevertheless the user must be aware that if the mesh changes the point
+ * selected will also vary slightly, making interpretation of the data more
+ * difficult. If a @p DoFHandler is used, one (and only one) evaluate_field
+ * method must be called for each dataset (time step, iteration, etc) for
+ * each vector_name, otherwise a @p ExcDataLostSync error can occur.
*/
template <class VECTOR>
void evaluate_field(const std::vector <std::string> &names,
const Quadrature<dim> &quadrature);
/**
- * Construct a std::vector <std::string>
- * containing only vector_name and
- * call the above function. The above function
- * is more efficient if multiple fields
- * use the same @p DataPostprocessor object.
+ * Construct a std::vector <std::string> containing only vector_name and
+ * call the above function. The above function is more efficient if multiple
+ * fields use the same @p DataPostprocessor object.
*/
template <class VECTOR>
void evaluate_field(const std::string &name,
/**
- * Extract values at the points actually
- * requested from the VECTOR supplied and
- * add them to the new dataset in vector_name.
- * Unlike the other evaluate_field methods
- * this method does not care if the dof_handler
- * has been modified because it uses calls to
- * @p VectorTools::point_value to extract there
- * data. Therefore, if only this method is used,
- * the class is fully compatible with
- * adaptive refinement.
- * The component_mask supplied when the
- * field was added is used to select
- * components to extract. If
- * a @p DoFHandler is used, one (and only
- * one) evaluate_field method
- * must be called for each dataset (time
- * step, iteration, etc) for each
- * vector_name, otherwise a @p
- * ExcDataLostSync error can occur.
+ * Extract values at the points actually requested from the VECTOR supplied
+ * and add them to the new dataset in vector_name. Unlike the other
+ * evaluate_field methods this method does not care if the dof_handler has
+ * been modified because it uses calls to @p VectorTools::point_value to
+ * extract there data. Therefore, if only this method is used, the class is
+ * fully compatible with adaptive refinement. The component_mask supplied
+ * when the field was added is used to select components to extract. If a @p
+ * DoFHandler is used, one (and only one) evaluate_field method must be
+ * called for each dataset (time step, iteration, etc) for each vector_name,
+ * otherwise a @p ExcDataLostSync error can occur.
*/
template <class VECTOR>
void evaluate_field_at_requested_location(const std::string &name,
/**
- * Add the key for the current dataset to
- * the dataset. Although calling this
- * method first is sensible, the order in
- * which this method, @p evaluate_field
- * and @p push_back_independent is not
- * important. It is however important
- * that all the data for a give dataset
- * is added to each dataset and that it
- * is added before a new data set is
- * started. This prevents a @p
- * ExcDataLostSync.
+ * Add the key for the current dataset to the dataset. Although calling this
+ * method first is sensible, the order in which this method, @p
+ * evaluate_field and @p push_back_independent is not important. It is
+ * however important that all the data for a give dataset is added to each
+ * dataset and that it is added before a new data set is started. This
+ * prevents a @p ExcDataLostSync.
*/
void start_new_dataset (const double key);
/**
- * If independent values have been set
- * up, this method stores these
- * values. This should only be called
- * once per dataset, and if independent
- * values are used it must be called for
- * every dataset. A @p ExcDataLostSync
- * exception can be thrown if this method
- * is not called.
+ * If independent values have been set up, this method stores these values.
+ * This should only be called once per dataset, and if independent values
+ * are used it must be called for every dataset. A @p ExcDataLostSync
+ * exception can be thrown if this method is not called.
*/
void push_back_independent (const std::vector <double> &independent_values);
/**
- * Write out a series of .gpl files named
- * base_name + "-00.gpl", base_name +
- * "-01.gpl" etc. The data file gives
- * info about where the support points
- * selected and interpreting the data.
- * If @p n_indep != 0 an additional file
- * base_name + "_indep.gpl" containing
- * key and independent data. The file
- * name agrees with the order the points
- * were added to the class.
- * The names of the data columns can
- * be supplied using the functions
- * @p add_component_names and
- * @p add_independent_names.
- * The support point information is only
- * meaningful if the dof_handler has not
- * been changed. Therefore, if adaptive
- * mesh refinement has been used the
- * support point data should not be used.
- * The optional parameter
- * postprocessor_locations is used to
- * add the postprocessor locations to the
- * output files. If this is desired, the
- * data should be obtained from a call to
- * get_postprocessor_locations while the
- * dof_handler is usable. The default
- * parameter is an empty vector of strings,
- * and will suppress postprocessor
+ * Write out a series of .gpl files named base_name + "-00.gpl", base_name +
+ * "-01.gpl" etc. The data file gives info about where the support points
+ * selected and interpreting the data. If @p n_indep != 0 an additional file
+ * base_name + "_indep.gpl" containing key and independent data. The file
+ * name agrees with the order the points were added to the class. The names
+ * of the data columns can be supplied using the functions @p
+ * add_component_names and @p add_independent_names. The support point
+ * information is only meaningful if the dof_handler has not been changed.
+ * Therefore, if adaptive mesh refinement has been used the support point
+ * data should not be used. The optional parameter postprocessor_locations
+ * is used to add the postprocessor locations to the output files. If this
+ * is desired, the data should be obtained from a call to
+ * get_postprocessor_locations while the dof_handler is usable. The default
+ * parameter is an empty vector of strings, and will suppress postprocessor
* locations output.
*/
void write_gnuplot (const std::string &base_name,
/**
- * Return a @p Vector with the indices of
- * selected points flagged with a 1. This
- * method is mainly for testing and
- * verifying that the class is working
- * correctly. By passing this vector to a
- * DataOut object, the user can verify
- * that the positions returned by @p
- * PointValueHistory< dim >::get_points
- * agree with the positions that @p
- * DataOut interprets from the @p Vector
- * returned. The code snippet below
- * demonstrates how this could be done:
+ * Return a @p Vector with the indices of selected points flagged with a 1.
+ * This method is mainly for testing and verifying that the class is working
+ * correctly. By passing this vector to a DataOut object, the user can
+ * verify that the positions returned by @p PointValueHistory< dim
+ * >::get_points agree with the positions that @p DataOut interprets from
+ * the @p Vector returned. The code snippet below demonstrates how this
+ * could be done:
* @code
* // Make a DataOut object and attach the dof_handler
* DataOut<dim> data_out;
/**
* Depreciated:
*
- * This function only exists for backward
- * compatibility as this is the interface
- * provided by previous versions of the library.
- * The function mark_support_locations replaces
- * it and reflects the fact that the locations
- * marked are actually the support points.
- *
- * @deprecated
+ * This function only exists for backward compatibility as this is the
+ * interface provided by previous versions of the library. The function
+ * mark_support_locations replaces it and reflects the fact that the
+ * locations marked are actually the support points.
+ *
+ * @deprecated
*/
Vector<double> mark_locations() DEAL_II_DEPRECATED;
/**
- * Stores the actual location of each
- * support point selected by the @p
- * add_point(s) method. This can be used
- * to compare with the point requested,
- * for example by using the @p
- * Point<dim>::distance function. For
- * convenience, location is resized to
- * the correct number of points by the
+ * Stores the actual location of each support point selected by the @p
+ * add_point(s) method. This can be used to compare with the point
+ * requested, for example by using the @p Point<dim>::distance function. For
+ * convenience, location is resized to the correct number of points by the
* method.
*/
void get_support_locations (std::vector <std::vector<Point <dim> > > &locations);
/**
* Depreciated:
*
- * This function only exists for backward
- * compatibility as this is the interface
- * provided by previous versions of the library.
- * The function get_support_locations replaces
- * it and reflects the fact that the points
+ * This function only exists for backward compatibility as this is the
+ * interface provided by previous versions of the library. The function
+ * get_support_locations replaces it and reflects the fact that the points
* returned are actually the support points.
*/
void get_points (std::vector <std::vector<Point <dim> > > &locations);
/**
- * Stores the actual location of the
- * points used by the data_postprocessor.
- * This can be used to compare with the
- * points requested, for example by using
- * the @p Point<dim>::distance function.
- * Unlike the support_locations, these
- * locations are computed every time the
- * evaluate_field method is called with a
- * postprocessor. This method uses the
- * same algorithm so can will find the
- * same points.
- * For convenience, location is resized
- * to the correct number of points by the
- * method.
+ * Stores the actual location of the points used by the data_postprocessor.
+ * This can be used to compare with the points requested, for example by
+ * using the @p Point<dim>::distance function. Unlike the support_locations,
+ * these locations are computed every time the evaluate_field method is
+ * called with a postprocessor. This method uses the same algorithm so can
+ * will find the same points. For convenience, location is resized to the
+ * correct number of points by the method.
*/
void get_postprocessor_locations (const Quadrature<dim> &quadrature,
std::vector<Point <dim> > &locations);
/**
- * Once datasets have been added to the
- * class, requests to add additional
- * points will make the data
- * interpretation unclear. The boolean @p
- * closed defines a state of the class
- * and ensures this does not
- * happen. Additional points or vectors
- * can only be added while the class is
- * not closed, and the class must be
- * closed before datasets can be added or
- * written to file. @p
- * PointValueHistory::get_points and @p
- * PointValueHistory::status do not
- * require the class to be closed. If a
- * method that requires a class to be
- * open or close is called while in the
- * wrong state a @p ExcInvalidState
+ * Once datasets have been added to the class, requests to add additional
+ * points will make the data interpretation unclear. The boolean @p closed
+ * defines a state of the class and ensures this does not happen. Additional
+ * points or vectors can only be added while the class is not closed, and
+ * the class must be closed before datasets can be added or written to file.
+ * @p PointValueHistory::get_points and @p PointValueHistory::status do not
+ * require the class to be closed. If a method that requires a class to be
+ * open or close is called while in the wrong state a @p ExcInvalidState
* exception is thrown.
*/
void close();
/**
- * Delete the lock this object has to the
- * @p DoFHandler used the last time the
- * class was created. This method should
- * not normally need to be called, but
- * can be useful to ensure that the @p
- * DoFHandler is released before it goes
- * out of scope if the @p
- * PointValueHistory class might live
- * longer than it. Once this method has
- * been called, the majority of methods
- * will throw a @p ExcInvalidState
- * exception, so if used this method
- * should be the last call to the class.
+ * Delete the lock this object has to the @p DoFHandler used the last time
+ * the class was created. This method should not normally need to be
+ * called, but can be useful to ensure that the @p DoFHandler is released
+ * before it goes out of scope if the @p PointValueHistory class might live
+ * longer than it. Once this method has been called, the majority of methods
+ * will throw a @p ExcInvalidState exception, so if used this method should
+ * be the last call to the class.
*/
void clear();
/**
- * Print useful debugging information
- * about the class, include details about
- * which support points were selected for
- * each point and sizes of the data
+ * Print useful debugging information about the class, include details about
+ * which support points were selected for each point and sizes of the data
* stored.
*/
void status(std::ostream &out);
/**
- * Check the internal data sizes to test
- * for a loss of data sync. This is often
- * used in @p Assert statements with the
- * @p ExcDataLostSync exception. If @p strict
- * is @p false this method returns
- * @p true if all sizes are within 1 of
- * each other (needed to allow data to be
- * added), with @p strict = @p true they
- * must be exactly equal.
+ * Check the internal data sizes to test for a loss of data sync. This is
+ * often used in @p Assert statements with the @p ExcDataLostSync exception.
+ * If @p strict is @p false this method returns @p true if all sizes are
+ * within 1 of each other (needed to allow data to be added), with @p strict
+ * = @p true they must be exactly equal.
*/
bool deep_check (const bool strict);
/**
- * A call has been made to @p
- * push_back_independent when no
- * independent values were requested.
+ * A call has been made to @p push_back_independent when no independent
+ * values were requested.
*/
DeclException0(ExcNoIndependent);
/**
- * This error is thrown to indicate that
- * the data sets appear to be out of
- * sync. The class requires that the
- * number of dataset keys is the same as
- * the number of independent values sets
- * and mesh linked value sets. The number
- * of each of these is allowed to differ
- * by one to allow new values to be added
- * with out restricting the order the
- * user choses to do so. Special cases
- * of no @p DoFHandler and no independent
- * values should not trigger this error.
+ * This error is thrown to indicate that the data sets appear to be out of
+ * sync. The class requires that the number of dataset keys is the same as
+ * the number of independent values sets and mesh linked value sets. The
+ * number of each of these is allowed to differ by one to allow new values
+ * to be added with out restricting the order the user choses to do so.
+ * Special cases of no @p DoFHandler and no independent values should not
+ * trigger this error.
*/
DeclException0(ExcDataLostSync);
/**
- * A method which requires access to a @p
- * DoFHandler to be meaningful has been
- * called when @p have_dof_handler is
- * false (most likely due to default
- * constructor being called). Only
- * independent variables may be logged
- * with no DoFHandler.
+ * A method which requires access to a @p DoFHandler to be meaningful has
+ * been called when @p have_dof_handler is false (most likely due to default
+ * constructor being called). Only independent variables may be logged with
+ * no DoFHandler.
*/
DeclException0(ExcDoFHandlerRequired);
/**
- * The triangulation indicated that mesh
- * has been refined in some way. This suggests
- * that the internal dof indices stored
- * are no longer meaningful.
+ * The triangulation indicated that mesh has been refined in some way. This
+ * suggests that the internal dof indices stored are no longer meaningful.
*/
DeclException0(ExcDoFHandlerChanged);
private:
/**
- * Stores keys, values on the abscissa.
- * This will often be time, but possibly
- * time step, iteration etc.
+ * Stores keys, values on the abscissa. This will often be time, but
+ * possibly time step, iteration etc.
*/
std::vector <double> dataset_key;
/**
- * Values that do not depend on grid
- * location.
+ * Values that do not depend on grid location.
*/
std::vector <std::vector <double> > independent_values;
/**
- * Saves a vector listing component
- * names associated with a independent_values.
- * This will be an empty vector
- * if the user does not supplies names.
+ * Saves a vector listing component names associated with a
+ * independent_values. This will be an empty vector if the user does not
+ * supplies names.
*/
std::vector<std::string> indep_names;
/**
- * Saves data for each mnemonic entry.
- * data_store: mnemonic ->
- * [point_0_components point_1_components
- * ... point_n-1_components][key]
- * This format facilitates scalar mnemonics
- * in a vector space, because scalar mnemonics
- * will only have one component per point.
- * Vector components are strictly
- * FE.n_components () long.
+ * Saves data for each mnemonic entry. data_store: mnemonic ->
+ * [point_0_components point_1_components ... point_n-1_components][key]
+ * This format facilitates scalar mnemonics in a vector space, because
+ * scalar mnemonics will only have one component per point. Vector
+ * components are strictly FE.n_components () long.
*/
std::map <std::string, std::vector <std::vector <double> > > data_store;
/**
- * Saves a component mask
- * for each mnemonic.
+ * Saves a component mask for each mnemonic.
*/
std::map <std::string, ComponentMask> component_mask;
/**
- * Saves a vector listing component
- * names associated with a mnemonic.
- * This will be an empty vector
- * if the user does not supplies names.
+ * Saves a vector listing component names associated with a mnemonic. This
+ * will be an empty vector if the user does not supplies names.
*/
std::map <std::string, std::vector<std::string> > component_names_map;
/**
- * Saves the location and other mesh info
- * about support points.
+ * Saves the location and other mesh info about support points.
*/
std::vector <internal::PointValueHistory::PointGeometryData <dim> >
point_geometry_data;
/**
- * Used to enforce @p closed state for some
- * methods.
+ * Used to enforce @p closed state for some methods.
*/
bool closed;
/**
- * Used to enforce @p !cleared state for
- * some methods.
+ * Used to enforce @p !cleared state for some methods.
*/
bool cleared;
/**
- * A smart pointer to the dof_handler
- * supplied to the constructor. This can be
- * released by calling @p clear().
+ * A smart pointer to the dof_handler supplied to the constructor. This can
+ * be released by calling @p clear().
*/
SmartPointer<const DoFHandler<dim>,PointValueHistory<dim> > dof_handler;
/**
- * Variable to check if the triangulation
- * has changed. If it has changed, certain
- * data is out of date (especially the
+ * Variable to check if the triangulation has changed. If it has changed,
+ * certain data is out of date (especially the
* PointGeometryData::solution_indices.
*/
bool triangulation_changed;
/**
- * A boolean to record whether the class was
- * initialized with a DoFHandler or not.
+ * A boolean to record whether the class was initialized with a DoFHandler
+ * or not.
*/
bool have_dof_handler;
boost::signals2::connection tria_listener;
/**
- * Stores the number of independent
- * variables requested.
+ * Stores the number of independent variables requested.
*/
unsigned int n_indep;
/**
- * A function that will be triggered
- * through signals whenever the
- * triangulation is modified.
+ * A function that will be triggered through signals whenever the
+ * triangulation is modified.
*
- * It is currently used to check
- * if the triangulation has changed,
- * invalidating precomputed values.
+ * It is currently used to check if the triangulation has changed,
+ * invalidating precomputed values.
*/
void tria_change_listener ();
};
DEAL_II_NAMESPACE_OPEN
/**
- * This class implements the transfer of a discrete FE function
- * (e.g. a solution vector) from one mesh to another that is obtained
- * from the first by a single refinement and/or coarsening step. During
- * interpolation the vector is reinitialized to the new size and
- * filled with the interpolated values. This class is used in the
- * step-15, step-31, and step-33 tutorial programs. A version of this
- * class that works on parallel triangulations is available as
- * parallel::distributed::SolutionTransfer.
+ * This class implements the transfer of a discrete FE function (e.g. a
+ * solution vector) from one mesh to another that is obtained from the first
+ * by a single refinement and/or coarsening step. During interpolation the
+ * vector is reinitialized to the new size and filled with the interpolated
+ * values. This class is used in the step-15, step-31, and step-33 tutorial
+ * programs. A version of this class that works on parallel triangulations is
+ * available as parallel::distributed::SolutionTransfer.
*
* <h3>Usage</h3>
*
* This class implements the algorithms in two different ways:
-
* <ul>
- * <li> If the grid will only be refined
- * (i.e. no cells are coarsened) then use @p SolutionTransfer as follows:
+ * <li> If the grid will only be refined (i.e. no cells are coarsened) then
+ * use @p SolutionTransfer as follows:
* @code
* SolutionTransfer<dim, double> soltrans(*dof_handler);
* // flag some cells for refinement, e.g.
* soltrans.refine_interpolate(solution_old, solution);
* @endcode
*
- * Although the @p refine_interpolate functions are allowed to be
- * called multiple times, e.g. for interpolating several solution
- * vectors, there is following possibility of interpolating several
- * functions simultaneously.
+ * Although the @p refine_interpolate functions are allowed to be called
+ * multiple times, e.g. for interpolating several solution vectors, there is
+ * following possibility of interpolating several functions simultaneously.
* @code
* vector<Vector<double> > solutions_old(n_vectors, Vector<double> (n));
* ...
* vector<Vector<double> > solutions(n_vectors, Vector<double> (n));
* soltrans.refine_interpolate(solutions_old, solutions);
* @endcode
- * This is used in several of the tutorial programs, for example
- * step-31.
+ * This is used in several of the tutorial programs, for example step-31.
*
- * <li> If the grid has cells that will be coarsened,
- * then use @p SolutionTransfer as follows:
+ * <li> If the grid has cells that will be coarsened, then use @p
+ * SolutionTransfer as follows:
* @code
* SolutionTransfer<dim, Vector<double> > soltrans(*dof_handler);
* // flag some cells for refinement
* soltrans.interpolate(solution, interpolated_solution);
* @endcode
*
- * Multiple calls to the function
- * <tt>interpolate (const Vector<number> &in, Vector<number> &out)</tt>
- * are NOT allowed. Interpolating several functions can be performed in one step
- * by using
- * <tt>void interpolate (const vector<Vector<number> >&all_in, vector<Vector<number> >&all_out) const</tt>,
- * and using the respective @p prepare_for_coarsening_and_refinement function
- * taking several vectors as input before actually refining and coarsening the
- * triangulation (see there).
+ * Multiple calls to the function <tt>interpolate (const Vector<number> &in,
+ * Vector<number> &out)</tt> are NOT allowed. Interpolating several functions
+ * can be performed in one step by using <tt>void interpolate (const
+ * vector<Vector<number> >&all_in, vector<Vector<number> >&all_out)
+ * const</tt>, and using the respective @p
+ * prepare_for_coarsening_and_refinement function taking several vectors as
+ * input before actually refining and coarsening the triangulation (see
+ * there).
* </ul>
*
* For deleting all stored data in @p SolutionTransfer and reinitializing it
* use the <tt>clear()</tt> function.
*
- * The template argument @p number denotes the data type of the vectors you want
- * to transfer.
+ * The template argument @p number denotes the data type of the vectors you
+ * want to transfer.
*
*
* <h3>Implementation</h3>
*
* <ul>
* <li> Solution transfer with only refinement. Assume that we have got a
- * solution vector on the current (original) grid.
- * Each entry of this vector belongs to one of the
- * DoFs of the discretization. If we now refine the grid then the calling of
- * DoFHandler::distribute_dofs() will change at least some of the
- * DoF indices. Hence we need to store the DoF indices of all active cells
- * before the refinement. A pointer for each active cell
- * is used to point to the vector of these DoF indices of that cell.
- * This is done by prepare_for_pure_refinement().
+ * solution vector on the current (original) grid. Each entry of this vector
+ * belongs to one of the DoFs of the discretization. If we now refine the grid
+ * then the calling of DoFHandler::distribute_dofs() will change at least some
+ * of the DoF indices. Hence we need to store the DoF indices of all active
+ * cells before the refinement. A pointer for each active cell is used to
+ * point to the vector of these DoF indices of that cell. This is done by
+ * prepare_for_pure_refinement().
*
- * In the function <tt>refine_interpolate(in,out)</tt> and on each cell where the
- * pointer is set (i.e. the cells that were active in the original grid)
- * we can now access the local values of the solution vector @p in
- * on that cell by using the stored DoF indices. These local values are
- * interpolated and set into the vector @p out that is at the end the
- * discrete function @p in interpolated on the refined mesh.
+ * In the function <tt>refine_interpolate(in,out)</tt> and on each cell where
+ * the pointer is set (i.e. the cells that were active in the original grid)
+ * we can now access the local values of the solution vector @p in on that
+ * cell by using the stored DoF indices. These local values are interpolated
+ * and set into the vector @p out that is at the end the discrete function @p
+ * in interpolated on the refined mesh.
*
- * The <tt>refine_interpolate(in,out)</tt> function can be called multiple times for
- * arbitrary many discrete functions (solution vectors) on the original grid.
+ * The <tt>refine_interpolate(in,out)</tt> function can be called multiple
+ * times for arbitrary many discrete functions (solution vectors) on the
+ * original grid.
*
- * <li> Solution transfer with coarsening and refinement. After
- * calling Triangulation::prepare_coarsening_and_refinement the
- * coarsen flags of either all or none of the children of a
- * (father-)cell are set. While coarsening
- * (Triangulation::execute_coarsening_and_refinement)
- * the cells that are not needed any more will be deleted from the Triangulation.
+ * <li> Solution transfer with coarsening and refinement. After calling
+ * Triangulation::prepare_coarsening_and_refinement the coarsen flags of
+ * either all or none of the children of a (father-)cell are set. While
+ * coarsening (Triangulation::execute_coarsening_and_refinement) the cells
+ * that are not needed any more will be deleted from the Triangulation.
*
* For the interpolation from the (to be coarsenend) children to their father
- * the children cells are needed. Hence this interpolation
- * and the storing of the interpolated values of each of the discrete functions
- * that we want to interpolate needs to take place before these children cells
- * are coarsened (and deleted!!). Again a pointers for the relevant cells is
- * set to point to these values (see below).
- * Additionally the DoF indices of the cells
- * that will not be coarsened need to be stored according to the solution
- * transfer while pure refinement (cf there). All this is performed by
+ * the children cells are needed. Hence this interpolation and the storing of
+ * the interpolated values of each of the discrete functions that we want to
+ * interpolate needs to take place before these children cells are coarsened
+ * (and deleted!!). Again a pointers for the relevant cells is set to point to
+ * these values (see below). Additionally the DoF indices of the cells that
+ * will not be coarsened need to be stored according to the solution transfer
+ * while pure refinement (cf there). All this is performed by
* <tt>prepare_for_coarsening_and_refinement(all_in)</tt> where the
- * <tt>vector<Vector<number> >vector all_in</tt> includes
- * all discrete functions to be interpolated onto the new grid.
+ * <tt>vector<Vector<number> >vector all_in</tt> includes all discrete
+ * functions to be interpolated onto the new grid.
*
- * As we need two different kinds of pointers (<tt>vector<unsigned int> *</tt> for the Dof
- * indices and <tt>vector<Vector<number> > *</tt> for the interpolated DoF values)
- * we use the @p Pointerstruct that includes both of these pointers and
- * the pointer for each cell points to these @p Pointerstructs.
- * On each cell only one of the two different pointers is used at one time
- * hence we could use a
- * <tt>void * pointer</tt> as <tt>vector<unsigned int> *</tt> at one time and as
- * <tt>vector<Vector<number> > *</tt> at the other but using this @p Pointerstruct
- * in between makes the use of these pointers more safe and gives better
- * possibility to expand their usage.
+ * As we need two different kinds of pointers (<tt>vector<unsigned int> *</tt>
+ * for the Dof indices and <tt>vector<Vector<number> > *</tt> for the
+ * interpolated DoF values) we use the @p Pointerstruct that includes both of
+ * these pointers and the pointer for each cell points to these @p
+ * Pointerstructs. On each cell only one of the two different pointers is used
+ * at one time hence we could use a <tt>void * pointer</tt> as
+ * <tt>vector<unsigned int> *</tt> at one time and as
+ * <tt>vector<Vector<number> > *</tt> at the other but using this @p
+ * Pointerstruct in between makes the use of these pointers more safe and
+ * gives better possibility to expand their usage.
*
- * In <tt>interpolate(all_in, all_out)</tt> the refined cells are treated according
- * to the solution transfer while pure refinement. Additionally, on each
- * cell that is coarsened (hence previously was a father cell),
- * the values of the discrete
- * functions in @p all_out are set to the stored local interpolated values
- * that are accessible due to the 'vector<Vector<number> > *' pointer in
- * @p Pointerstruct that is pointed to by the pointer of that cell.
- * It is clear that <tt>interpolate(all_in, all_out)</tt> only can be called with
- * the <tt>vector<Vector<number> > all_in</tt> that previously was the parameter
- * of the <tt>prepare_for_coarsening_and_refinement(all_in)</tt> function. Hence
- * <tt>interpolate(all_in, all_out)</tt> can (in contrast to
+ * In <tt>interpolate(all_in, all_out)</tt> the refined cells are treated
+ * according to the solution transfer while pure refinement. Additionally, on
+ * each cell that is coarsened (hence previously was a father cell), the
+ * values of the discrete functions in @p all_out are set to the stored local
+ * interpolated values that are accessible due to the 'vector<Vector<number> >
+ * *' pointer in @p Pointerstruct that is pointed to by the pointer of that
+ * cell. It is clear that <tt>interpolate(all_in, all_out)</tt> only can be
+ * called with the <tt>vector<Vector<number> > all_in</tt> that previously was
+ * the parameter of the <tt>prepare_for_coarsening_and_refinement(all_in)</tt>
+ * function. Hence <tt>interpolate(all_in, all_out)</tt> can (in contrast to
* <tt>refine_interpolate(in, out)</tt>) only be called once.
* </ul>
*
*
* <h3>Implementation in the context of hp finite elements</h3>
*
- * In the case of hp::DoFHandlers, nothing defines which of the finite elements
- * that are part of the hp::FECollection associated with the DoF handler, should
- * be considered on cells that are not active (i.e., that have children). This
- * is because degrees of freedom are only allocated for active cells and, in fact,
- * it is not allowed to set an active_fe_index on non-active cells using
- * DoFAccessor::set_active_fe_index().
+ * In the case of hp::DoFHandlers, nothing defines which of the finite
+ * elements that are part of the hp::FECollection associated with the DoF
+ * handler, should be considered on cells that are not active (i.e., that have
+ * children). This is because degrees of freedom are only allocated for active
+ * cells and, in fact, it is not allowed to set an active_fe_index on non-
+ * active cells using DoFAccessor::set_active_fe_index().
*
- * It is, thus, not entirely natural what should happen if, for example, a few cells
- * are coarsened away. This class then implements the following algorithm:
- * - If a cell is refined, then the values of the solution vector(s) are saved before
- * refinement on the to-be-refined cell and in the space associated with this
- * cell. These values are then interpolated to the finite element spaces of the
- * children post-refinement. This may lose information if, for example, the old
- * cell used a Q2 space and the children use Q1 spaces, or the information may
- * be prolonged if the mother cell used a Q1 space and the children are Q2s.
- * - If cells are to be coarsened, then the values from the child cells are
- * interpolated to the mother cell using the largest of the child cell spaces.
- * For example, if the children of a cell use Q1, Q2 and Q3 spaces, then the
- * values from the children are interpolated into a Q3 space on the mother cell.
- * After refinement, this Q3 function on the mother cell is then interpolated into
- * the space the user has selected for this cell (which may be different from
- * Q3, in this example, if the user has set the active_fe_index for a different
- * space post-refinement and before calling hp::DoFHandler::distribute_dofs()).
+ * It is, thus, not entirely natural what should happen if, for example, a few
+ * cells are coarsened away. This class then implements the following
+ * algorithm: - If a cell is refined, then the values of the solution
+ * vector(s) are saved before refinement on the to-be-refined cell and in the
+ * space associated with this cell. These values are then interpolated to the
+ * finite element spaces of the children post-refinement. This may lose
+ * information if, for example, the old cell used a Q2 space and the children
+ * use Q1 spaces, or the information may be prolonged if the mother cell used
+ * a Q1 space and the children are Q2s. - If cells are to be coarsened, then
+ * the values from the child cells are interpolated to the mother cell using
+ * the largest of the child cell spaces. For example, if the children of a
+ * cell use Q1, Q2 and Q3 spaces, then the values from the children are
+ * interpolated into a Q3 space on the mother cell. After refinement, this Q3
+ * function on the mother cell is then interpolated into the space the user
+ * has selected for this cell (which may be different from Q3, in this
+ * example, if the user has set the active_fe_index for a different space
+ * post-refinement and before calling hp::DoFHandler::distribute_dofs()).
*
* @note In the context of hp refinement, if cells are coarsened or the
* polynomial degree is lowered on some cells, then the old finite element
* transfering the solution.
*
* @ingroup numerics
- * @author Ralf Hartmann, 1999, Oliver Kayser-Herold and Wolfgang Bangerth, 2006, Wolfgang Bangerth 2014
+ * @author Ralf Hartmann, 1999, Oliver Kayser-Herold and Wolfgang Bangerth,
+ * 2006, Wolfgang Bangerth 2014
*/
template<int dim, typename VECTOR=Vector<double>, class DH=DoFHandler<dim> >
class SolutionTransfer
public:
/**
- * Constructor, takes the current DoFHandler
- * as argument.
+ * Constructor, takes the current DoFHandler as argument.
*/
SolutionTransfer(const DH &dof);
~SolutionTransfer();
/**
- * Reinit this class to the state that
- * it has
- * directly after calling the Constructor
+ * Reinit this class to the state that it has directly after calling the
+ * Constructor
*/
void clear();
/**
- * Prepares the @p SolutionTransfer for
- * pure refinement. It
- * stores the dof indices of each cell.
- * After calling this function
- * only calling the @p refine_interpolate
- * functions is allowed.
+ * Prepares the @p SolutionTransfer for pure refinement. It stores the dof
+ * indices of each cell. After calling this function only calling the @p
+ * refine_interpolate functions is allowed.
*/
void prepare_for_pure_refinement();
/**
- * Prepares the @p SolutionTransfer for
- * coarsening and refinement. It
- * stores the dof indices of each cell and
- * stores the dof values of the vectors in
- * @p all_in in each cell that'll be coarsened.
- * @p all_in includes all vectors
- * that are to be interpolated
- * onto the new (refined and/or
+ * Prepares the @p SolutionTransfer for coarsening and refinement. It stores
+ * the dof indices of each cell and stores the dof values of the vectors in
+ * @p all_in in each cell that'll be coarsened. @p all_in includes all
+ * vectors that are to be interpolated onto the new (refined and/or
* coarsenend) grid.
*/
void prepare_for_coarsening_and_refinement (const std::vector<VECTOR> &all_in);
/**
- * Same as previous function
- * but for only one discrete function
- * to be interpolated.
+ * Same as previous function but for only one discrete function to be
+ * interpolated.
*/
void prepare_for_coarsening_and_refinement (const VECTOR &in);
/**
- * This function
- * interpolates the discrete function @p in,
- * which is a vector on the grid before the
- * refinement, to the function @p out
- * which then is a vector on the refined grid.
- * It assumes the vectors having the
- * right sizes (i.e. <tt>in.size()==n_dofs_old</tt>,
+ * This function interpolates the discrete function @p in, which is a vector
+ * on the grid before the refinement, to the function @p out which then is a
+ * vector on the refined grid. It assumes the vectors having the right sizes
+ * (i.e. <tt>in.size()==n_dofs_old</tt>,
* <tt>out.size()==n_dofs_refined</tt>)
*
- * Calling this function is allowed only
- * if @p prepare_for_pure_refinement is called
- * and the refinement is
- * executed before.
- * Multiple calling of this function is
- * allowed. e.g. for interpolating several
- * functions.
+ * Calling this function is allowed only if @p prepare_for_pure_refinement
+ * is called and the refinement is executed before. Multiple calling of this
+ * function is allowed. e.g. for interpolating several functions.
*/
void refine_interpolate (const VECTOR &in,
VECTOR &out) const;
/**
- * This function
- * interpolates the discrete functions
- * that are stored in @p all_in onto
- * the refined and/or coarsenend grid.
- * It assumes the vectors in @p all_in
- * denote the same vectors
- * as in @p all_in as parameter of
- * <tt>prepare_for_refinement_and_coarsening(all_in)</tt>.
- * However, there is no way of verifying
- * this internally, so be careful here.
+ * This function interpolates the discrete functions that are stored in @p
+ * all_in onto the refined and/or coarsenend grid. It assumes the vectors in
+ * @p all_in denote the same vectors as in @p all_in as parameter of
+ * <tt>prepare_for_refinement_and_coarsening(all_in)</tt>. However, there is
+ * no way of verifying this internally, so be careful here.
*
- * Calling this function is
- * allowed only if first
- * Triangulation::prepare_coarsening_and_refinement,
- * second
- * @p SolutionTransfer::prepare_for_coarsening_and_refinement,
- * an then third
- * Triangulation::execute_coarsening_and_refinement
- * are called before. Multiple
- * calling of this function is
- * NOT allowed. Interpolating
- * several functions can be
- * performed in one step.
+ * Calling this function is allowed only if first
+ * Triangulation::prepare_coarsening_and_refinement, second @p
+ * SolutionTransfer::prepare_for_coarsening_and_refinement, an then third
+ * Triangulation::execute_coarsening_and_refinement are called before.
+ * Multiple calling of this function is NOT allowed. Interpolating several
+ * functions can be performed in one step.
*
- * The number of output vectors
- * is assumed to be the same as
- * the number of input
- * vectors. Also, the sizes of
- * the output vectors are assumed
- * to be of the right size
- * (@p n_dofs_refined). Otherwise
- * an assertion will be thrown.
+ * The number of output vectors is assumed to be the same as the number of
+ * input vectors. Also, the sizes of the output vectors are assumed to be of
+ * the right size (@p n_dofs_refined). Otherwise an assertion will be
+ * thrown.
*/
void interpolate (const std::vector<VECTOR> &all_in,
std::vector<VECTOR> &all_out) const;
/**
- * Same as the previous function.
- * It interpolates only one function.
- * It assumes the vectors having the
- * right sizes (i.e. <tt>in.size()==n_dofs_old</tt>,
- * <tt>out.size()==n_dofs_refined</tt>)
+ * Same as the previous function. It interpolates only one function. It
+ * assumes the vectors having the right sizes (i.e.
+ * <tt>in.size()==n_dofs_old</tt>, <tt>out.size()==n_dofs_refined</tt>)
*
- * Multiple calling of this function is
- * NOT allowed. Interpolating
- * several functions can be performed
- * in one step by using
- * <tt>interpolate (all_in, all_out)</tt>
+ * Multiple calling of this function is NOT allowed. Interpolating several
+ * functions can be performed in one step by using <tt>interpolate (all_in,
+ * all_out)</tt>
*/
void interpolate (const VECTOR &in,
VECTOR &out) const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
private:
/**
- * Pointer to the degree of freedom handler
- * to work with.
+ * Pointer to the degree of freedom handler to work with.
*/
SmartPointer<const DH,SolutionTransfer<dim,VECTOR,DH> > dof_handler;
/**
- * Stores the number of DoFs before the
- * refinement and/or coarsening.
+ * Stores the number of DoFs before the refinement and/or coarsening.
*/
types::global_dof_index n_dofs_old;
/**
- * Declaration of
- * @p PreparationState that
- * denotes the three possible
- * states of the
- * @p SolutionTransfer: being
- * prepared for 'pure
- * refinement', prepared for
- * 'coarsening and refinement' or
- * not prepared.
+ * Declaration of @p PreparationState that denotes the three possible states
+ * of the @p SolutionTransfer: being prepared for 'pure refinement',
+ * prepared for 'coarsening and refinement' or not prepared.
*/
enum PreparationState
{
/**
- * Is used for @p prepare_for_refining
- * (of course also for
- * @p repare_for_refining_and_coarsening)
- * and stores all dof indices
- * of the cells that'll be refined
+ * Is used for @p prepare_for_refining (of course also for @p
+ * repare_for_refining_and_coarsening) and stores all dof indices of the
+ * cells that'll be refined
*/
std::vector<std::vector<types::global_dof_index> > indices_on_cell;
/**
- * All cell data (the dof indices and
- * the dof values)
- * should be accessible from each cell.
- * As each cell has got only one
- * @p user_pointer, multiple pointers to the
- * data need to be packetized in a structure.
- * Note that in our case on each cell
- * either the
- * <tt>vector<unsigned int> indices</tt> (if the cell
- * will be refined) or the
- * <tt>vector<double> dof_values</tt> (if the
- * children of this cell will be deleted)
- * is needed, hence one @p user_pointer should
- * be sufficient, but to allow some error checks
- * and to preserve the user from making
- * user errors the @p user_pointer will be
+ * All cell data (the dof indices and the dof values) should be accessible
+ * from each cell. As each cell has got only one @p user_pointer, multiple
+ * pointers to the data need to be packetized in a structure. Note that in
+ * our case on each cell either the <tt>vector<unsigned int> indices</tt>
+ * (if the cell will be refined) or the <tt>vector<double> dof_values</tt>
+ * (if the children of this cell will be deleted) is needed, hence one @p
+ * user_pointer should be sufficient, but to allow some error checks and to
+ * preserve the user from making user errors the @p user_pointer will be
* 'multiplied' by this structure.
*/
struct Pointerstruct
};
/**
- * Map mapping from level and index of cell
- * to the @p Pointerstructs (cf. there).
- * This map makes it possible to keep all
- * the information needed to transfer the
- * solution inside this object rather than
- * using user pointers of the Triangulation
- * for this purpose.
+ * Map mapping from level and index of cell to the @p Pointerstructs (cf.
+ * there). This map makes it possible to keep all the information needed to
+ * transfer the solution inside this object rather than using user pointers
+ * of the Triangulation for this purpose.
*/
std::map<std::pair<unsigned int, unsigned int>, Pointerstruct> cell_map;
/**
- * Is used for
- * @p prepare_for_refining_and_coarsening
- * The interpolated dof values
- * of all cells that'll be coarsened
- * will be stored in this vector.
+ * Is used for @p prepare_for_refining_and_coarsening The interpolated dof
+ * values of all cells that'll be coarsened will be stored in this vector.
*/
std::vector<std::vector<Vector<typename VECTOR::value_type> > > dof_values_on_cell;
};
template <int dim, int spacedim> class Triangulation;
/**
- * This class provides an abstract interface to time dependent problems in that
- * it addresses some of the most annoying aspects of this class of problems:
- * data management. These problems frequently need large amounts of computer
- * ressources, most notably computing time, main memory and disk space.
- * Main memory reduction is often the most pressing need, methods to implement
- * it are almost always quite messy, though, quickly leading to code that
- * stores and reloads data at places scattered all over the program, and
- * which becomes unmaintainable sometimes. The present class tries to offer
- * a more structured interface, albeit simple, which emerged in my mind after
+ * This class provides an abstract interface to time dependent problems in
+ * that it addresses some of the most annoying aspects of this class of
+ * problems: data management. These problems frequently need large amounts of
+ * computer ressources, most notably computing time, main memory and disk
+ * space. Main memory reduction is often the most pressing need, methods to
+ * implement it are almost always quite messy, though, quickly leading to code
+ * that stores and reloads data at places scattered all over the program, and
+ * which becomes unmaintainable sometimes. The present class tries to offer a
+ * more structured interface, albeit simple, which emerged in my mind after
* messing with my wave equation simulation for several months.
*
* The design of this class is mostly tailored for the solution of time
- * dependent partial differential equations where the computational
- * meshes may differ between each two timesteps and where the computations
- * on each time step take a rather long time compared with the overhead
- * of this class. Since no reference to the class of problems is made within
- * this class, it is not restricted to PDEs, though, and it seems likely that
- * a solver for large ordinary matrix differential equations may successfully
- * use the same setup and therefore this class.
+ * dependent partial differential equations where the computational meshes may
+ * differ between each two timesteps and where the computations on each time
+ * step take a rather long time compared with the overhead of this class.
+ * Since no reference to the class of problems is made within this class, it
+ * is not restricted to PDEs, though, and it seems likely that a solver for
+ * large ordinary matrix differential equations may successfully use the same
+ * setup and therefore this class.
*
*
* <h3>Overview</h3>
*
- * The general structure of a time dependent problem solver using a timestepping
- * scheme is about the following: we have a collection of time step objects
- * on which we solve our problem subsequently. In order to do so, we need
- * knowledge of the data on zero or several previous timesteps (when using single
- * or multiple step methods, that is) and maybe also some data of time steps
- * ahead (for example the computational grid on these). Dependening on the
- * problem in question, a second loop over all timesteps may be done solving
- * a dual problem, where the loop may run forward (one dual problem for each
- * time step) or backward (using a global dual problem). Within one of these
- * loops or using a separate loop, error estimators may be computed and the
- * grids may be refined. Each of these loops are initiated by a call preparing
- * each timestep object for the next loop, before actually starting the loop
- * itself.
+ * The general structure of a time dependent problem solver using a
+ * timestepping scheme is about the following: we have a collection of time
+ * step objects on which we solve our problem subsequently. In order to do so,
+ * we need knowledge of the data on zero or several previous timesteps (when
+ * using single or multiple step methods, that is) and maybe also some data of
+ * time steps ahead (for example the computational grid on these). Dependening
+ * on the problem in question, a second loop over all timesteps may be done
+ * solving a dual problem, where the loop may run forward (one dual problem
+ * for each time step) or backward (using a global dual problem). Within one
+ * of these loops or using a separate loop, error estimators may be computed
+ * and the grids may be refined. Each of these loops are initiated by a call
+ * preparing each timestep object for the next loop, before actually starting
+ * the loop itself.
*
* We will denote a complete set of all these loops with the term "sweep".
* Since this library is mostly about adaptive methods, it is likely that the
* being needed for the solution of global dual problems, for example).
*
* Going from the global overview to a more local viewpoint, we note that when
- * a loop visits one timestep (e.g. to solve the primal or dual problem, or
- * to compute error information), we need information on this, one or more
+ * a loop visits one timestep (e.g. to solve the primal or dual problem, or to
+ * compute error information), we need information on this, one or more
* previous time steps and zero or more timesteps in the future. However,
- * often it is not needed to know all information from these timesteps and
- * it is often a computational requirement to delete data at the first
- * possible time when it is no more needed. Likewise, data should be reloaded
- * at the latest time possible.
+ * often it is not needed to know all information from these timesteps and it
+ * is often a computational requirement to delete data at the first possible
+ * time when it is no more needed. Likewise, data should be reloaded at the
+ * latest time possible.
*
* In order to facilitate these principles, the concept of waking up and
* letting sleep a time step object was developed. Assume we have a time
- * stepping scheme which needs to look ahead one time step and needs the
- * data of the last two time steps, the following pseudocode described
- * what the centeral loop function of this class will do when we move
- * from timestep @p n-1 to timestep @p n:
+ * stepping scheme which needs to look ahead one time step and needs the data
+ * of the last two time steps, the following pseudocode described what the
+ * centeral loop function of this class will do when we move from timestep @p
+ * n-1 to timestep @p n:
* @verbatim
* wake up timestep n+1 with signal 1
* wake up timestep n with signal 0
*
* move from n to n+1
* @endverbatim
- * The signal number here denotes the distance of the timestep being sent
- * the signal to the timestep where computations are done on. The calls to
- * the @p wake_up and @p sleep functions with signal 0 could in principle
- * be absorbed into the function doing the computation; we use these
- * redundant signals, however, in order to separate computations and data
- * management from each other, allowing to put all stuff around grid
- * management, data reload and storage into one set of functions and
- * computations into another.
+ * The signal number here denotes the distance of the timestep being sent the
+ * signal to the timestep where computations are done on. The calls to the @p
+ * wake_up and @p sleep functions with signal 0 could in principle be absorbed
+ * into the function doing the computation; we use these redundant signals,
+ * however, in order to separate computations and data management from each
+ * other, allowing to put all stuff around grid management, data reload and
+ * storage into one set of functions and computations into another.
*
- * In the example above, possible actions might be: timestep <tt>n+1</tt> rebuilds
- * the computational grid (there is a specialized class which can do this
- * for you); timestep @p n builds matrices sets solution vectors to the right
- * size, maybe using an initial guess; then it does the computations; then
- * it deletes the matrices since they are not needed by subsequent timesteps;
- * timestep @p n-1 deletes those data vectors which are only needed by one
- * timestep ahead; timestep @p n-2 deletes the remaining vectors and deletes
- * the computational grid, somewhere storing information how to rebuild it
- * eventually.
+ * In the example above, possible actions might be: timestep <tt>n+1</tt>
+ * rebuilds the computational grid (there is a specialized class which can do
+ * this for you); timestep @p n builds matrices sets solution vectors to the
+ * right size, maybe using an initial guess; then it does the computations;
+ * then it deletes the matrices since they are not needed by subsequent
+ * timesteps; timestep @p n-1 deletes those data vectors which are only needed
+ * by one timestep ahead; timestep @p n-2 deletes the remaining vectors and
+ * deletes the computational grid, somewhere storing information how to
+ * rebuild it eventually.
*
* From the given sketch above, it is clear that each time step object sees
* the following sequence of events:
* @endverbatim
* This pattern is repeated for each loop in each sweep.
*
- * For the different loops within each sweep, the numbers of timesteps
- * to look ahead (i.e. the maximum signal number to the @p wake_up function)
- * and the look-behind (i.e. the maximum signal number to the @p sleep
- * function) can be chosen separately. For example, it is usually only
- * needed to look one time step behind when computing error estimation
- * (in some cases, it may vene be possible to not look ahead or back
- * at all, in which case only signals zero will be sent), while one
- * needs a look back of at least one for a timestepping method.
+ * For the different loops within each sweep, the numbers of timesteps to look
+ * ahead (i.e. the maximum signal number to the @p wake_up function) and the
+ * look-behind (i.e. the maximum signal number to the @p sleep function) can
+ * be chosen separately. For example, it is usually only needed to look one
+ * time step behind when computing error estimation (in some cases, it may
+ * vene be possible to not look ahead or back at all, in which case only
+ * signals zero will be sent), while one needs a look back of at least one for
+ * a timestepping method.
*
- * Finally, a note on the direction of look-ahead and look-back is in
- * place: look-ahead always refers to the direction the loop is running
- * in, i.e. for loops running forward, @p wake_up is called for timestep
- * objects with a greater time value than the one previously computed on,
- * while @p sleep is called for timesteps with a lower time. If the loop
- * runs in the opposite direction, e.g. when solving a global dual
- * problem, this order is reversed.
+ * Finally, a note on the direction of look-ahead and look-back is in place:
+ * look-ahead always refers to the direction the loop is running in, i.e. for
+ * loops running forward, @p wake_up is called for timestep objects with a
+ * greater time value than the one previously computed on, while @p sleep is
+ * called for timesteps with a lower time. If the loop runs in the opposite
+ * direction, e.g. when solving a global dual problem, this order is reversed.
*
*
* <h3>Implementation</h3>
*
- * The main loop of a program using this class will usually look like
- * the following one, taken modified from an application program that
- * isn't distributed as part of the library:
+ * The main loop of a program using this class will usually look like the
+ * following one, taken modified from an application program that isn't
+ * distributed as part of the library:
* @code
* template <int dim>
* void TimeDependent_Wave<dim>::run_sweep (const unsigned int sweep_no)
* };
* @endcode
* Here, @p timestep_manager is an object of type TimeDependent_Wave(), which
- * is a class derived from TimeDependent. @p start_sweep,
- * @p solve_primal_problem, @p solve_dual_problem, @p postprocess and @p end_sweep
- * are functions inherited from this class. They all do a loop over all
- * timesteps within this object and call the respective function on each of
- * these objects. For example, here are two of the functions as they are
+ * is a class derived from TimeDependent. @p start_sweep, @p
+ * solve_primal_problem, @p solve_dual_problem, @p postprocess and @p
+ * end_sweep are functions inherited from this class. They all do a loop over
+ * all timesteps within this object and call the respective function on each
+ * of these objects. For example, here are two of the functions as they are
* implemented by the library:
* @code
* void TimeDependent::start_sweep (const unsigned int s)
* forward);
* };
* @endcode
- * The latter function shows rather clear how most of the loops are
- * invoked (@p solve_primal_problem, @p solve_dual_problem, @p postprocess,
- * @p refine_grids and @p write_statistics all have this form, where the
- * latter two give functions of the derived timestep class, rather than
- * from the base class). The function TimeStepBase::init_for_primal_problem
- * and the respective ones for the other operations defined by that class
- * are only used to store the type of operation which the loop presently
- * performed will do.
+ * The latter function shows rather clear how most of the loops are invoked
+ * (@p solve_primal_problem, @p solve_dual_problem, @p postprocess, @p
+ * refine_grids and @p write_statistics all have this form, where the latter
+ * two give functions of the derived timestep class, rather than from the base
+ * class). The function TimeStepBase::init_for_primal_problem and the
+ * respective ones for the other operations defined by that class are only
+ * used to store the type of operation which the loop presently performed will
+ * do.
*
- * As can be seen, most of the work is done by the @p do_loop function of
- * this class, which takes the addresses of two functions which are used
- * to initialize all timestep objects for the loop and to actually perform
- * some action. The next parameter gives some information on the look-ahead
- * and look-back and the last one denotes in which direction the loop is
- * to be run.
+ * As can be seen, most of the work is done by the @p do_loop function of this
+ * class, which takes the addresses of two functions which are used to
+ * initialize all timestep objects for the loop and to actually perform some
+ * action. The next parameter gives some information on the look-ahead and
+ * look-back and the last one denotes in which direction the loop is to be
+ * run.
*
- * Using function pointers through the @p mem_fun functions provided by
- * the <tt>C++</tt> standard library, it is possible to do neat tricks, like
- * the following, also taken from the wave program, in this case from
- * the function @p refine_grids:
+ * Using function pointers through the @p mem_fun functions provided by the
+ * <tt>C++</tt> standard library, it is possible to do neat tricks, like the
+ * following, also taken from the wave program, in this case from the function
+ * @p refine_grids:
* @code
* ...
* compute the thresholds for refinement
* TimeDependent::TimeSteppingData (0,1),
* TimeDependent::forward);
* @endcode
- * TimeStepBase_Wave::refine_grid is a function taking an argument, unlike
- * all the other functions used above within the loops. However, in this special
+ * TimeStepBase_Wave::refine_grid is a function taking an argument, unlike all
+ * the other functions used above within the loops. However, in this special
* case the parameter was the same for all timesteps and known before the loop
* was started, so we fixed it and made a function object which to the outside
* world does not take parameters.
*
* Since it is the central function of this class, we finally present a
- * stripped down version of the @p do_loop method, which is shown in order
- * to provide a better understanding of the internals of this class. For
- * brevity we have omitted the parts that deal with backward running loops
- * as well as the checks whether wake-up and sleep operations act on timesteps
- * outside <tt>0..n_timesteps-1</tt>.
+ * stripped down version of the @p do_loop method, which is shown in order to
+ * provide a better understanding of the internals of this class. For brevity
+ * we have omitted the parts that deal with backward running loops as well as
+ * the checks whether wake-up and sleep operations act on timesteps outside
+ * <tt>0..n_timesteps-1</tt>.
* @code
* template <typename InitFunctionObject, typename LoopFunctionObject>
* void TimeDependent::do_loop (InitFunctionObject init_function,
{
public:
/**
- * Structure holding the two basic
- * entities that control a loop over
- * all time steps: how many time steps
- * ahead of the present one we shall
- * start waking up timestep objects
- * and how many timesteps behind
- * we shall call their @p sleep
- * method.
+ * Structure holding the two basic entities that control a loop over all
+ * time steps: how many time steps ahead of the present one we shall start
+ * waking up timestep objects and how many timesteps behind we shall call
+ * their @p sleep method.
*/
struct TimeSteppingData
{
/**
- * Constructor; see the different
- * fields for a description of the
- * meaning of the parameters.
+ * Constructor; see the different fields for a description of the meaning
+ * of the parameters.
*/
TimeSteppingData (const unsigned int look_ahead,
const unsigned int look_back);
/**
- * This denotes the number of timesteps
- * the timestepping algorithm needs to
- * look ahead. Usually, this number
- * will be zero, since algorithms
- * looking ahead can't act as
- * timestepping schemes since they
- * can't compute their data from knowledge
- * of the past only and are therefore
+ * This denotes the number of timesteps the timestepping algorithm needs
+ * to look ahead. Usually, this number will be zero, since algorithms
+ * looking ahead can't act as timestepping schemes since they can't
+ * compute their data from knowledge of the past only and are therefore
* global in time.
*
- * However, it may be necessary to look
- * ahead in other circumstances, when
- * not wanting to access the data of the
- * next time step(s), but for example
- * to know the next grid, the solution
- * of a dual problem on the next
- * time level, etc.
+ * However, it may be necessary to look ahead in other circumstances, when
+ * not wanting to access the data of the next time step(s), but for
+ * example to know the next grid, the solution of a dual problem on the
+ * next time level, etc.
*
- * Note that for a dual problem walking
- * back in time, "looking ahead" means
- * looking towards smaller time values.
+ * Note that for a dual problem walking back in time, "looking ahead"
+ * means looking towards smaller time values.
*
- * The value of this number determines,
- * how many time steps ahead the
- * time step manager start to call
- * the @p wake_up function for each
- * time step.
+ * The value of this number determines, how many time steps ahead the time
+ * step manager start to call the @p wake_up function for each time step.
*/
const unsigned int look_ahead;
/**
- * This is the opposite variable to the
- * above one. It denotes the number of
- * time steps behind the present one
- * for which we need to keep all data
- * in order to do the computations on
- * the present time level.
+ * This is the opposite variable to the above one. It denotes the number
+ * of time steps behind the present one for which we need to keep all data
+ * in order to do the computations on the present time level.
*
- * For one step schemes (e.g. the
- * Euler schemes, or the Crank-Nicolson
+ * For one step schemes (e.g. the Euler schemes, or the Crank-Nicolson
* scheme), this value will be one.
*
- * The value of this number
- * determines, how many time
- * steps after having done
- * computations on a tim level
- * the time step manager will
- * call the @p sleep function for
- * each time step.
+ * The value of this number determines, how many time steps after having
+ * done computations on a tim level the time step manager will call the @p
+ * sleep function for each time step.
*/
const unsigned int look_back;
};
/**
- * Enum offering the different directions
- * in which a loop executed by
- * @p do_loop may be run.
+ * Enum offering the different directions in which a loop executed by @p
+ * do_loop may be run.
*/
enum Direction
{
/**
- * Destructor. This will delete the
- * objects pointed to by the pointers
- * given to the <tt>insert_*</tt> and
- * @p add_timestep functions, i.e.
- * it will delete the objects doing
- * the computations on each time step.
+ * Destructor. This will delete the objects pointed to by the pointers given
+ * to the <tt>insert_*</tt> and @p add_timestep functions, i.e. it will
+ * delete the objects doing the computations on each time step.
*/
virtual ~TimeDependent ();
/**
- * Add a timestep at any position. The
- * position is a pointer to an existing
- * time step object, or a null pointer
- * denoting the end of the timestep
- * sequence. If @p position is non-null,
- * the new time step will be inserted
+ * Add a timestep at any position. The position is a pointer to an existing
+ * time step object, or a null pointer denoting the end of the timestep
+ * sequence. If @p position is non-null, the new time step will be inserted
* before the respective element.
*
- * Note that by giving an object
- * to this function, the
- * TimeDependent object assumes
- * ownership of the object; it will
- * therefore also take care of
+ * Note that by giving an object to this function, the TimeDependent object
+ * assumes ownership of the object; it will therefore also take care of
* deletion of the objects its manages.
*
- * There is another function,
- * @p add_timestep, which inserts a
- * time step at the end of the list.
+ * There is another function, @p add_timestep, which inserts a time step at
+ * the end of the list.
*
- * Note that this function does not
- * change the timestep numbers stored
- * within the other timestep objects,
- * nor does it set the timestep number
- * of this new timestep. This is only
- * done upon calling the @p start_sweep
- * function. In not changing the timestep
- * numbers, it is simpler to operate
- * on a space-time triangulation since
- * one can always use the timestep numbers
- * that were used in the previous sweep.
+ * Note that this function does not change the timestep numbers stored
+ * within the other timestep objects, nor does it set the timestep number of
+ * this new timestep. This is only done upon calling the @p start_sweep
+ * function. In not changing the timestep numbers, it is simpler to operate
+ * on a space-time triangulation since one can always use the timestep
+ * numbers that were used in the previous sweep.
*/
void insert_timestep (const TimeStepBase *position,
TimeStepBase *new_timestep);
/**
- * Just like @p insert_timestep, but
- * insert at the end.
+ * Just like @p insert_timestep, but insert at the end.
*
- * This mechanism usually will result
- * in a set-up loop like this
+ * This mechanism usually will result in a set-up loop like this
* @code
* for (i=0; i<N; ++i)
* manager.add_timestep(new MyTimeStep());
void add_timestep (TimeStepBase *new_timestep);
/**
- * Delete a timestep. This is only
- * necessary to call, if you want to
- * delete it between two sweeps; at
- * the end of the lifetime of this object,
- * care is taken automatically of
- * deletion of the time step objects.
- * Deletion of the object by the
- * destructor is done through this
- * function also.
+ * Delete a timestep. This is only necessary to call, if you want to delete
+ * it between two sweeps; at the end of the lifetime of this object, care is
+ * taken automatically of deletion of the time step objects. Deletion of the
+ * object by the destructor is done through this function also.
*
- * Note that this function does
- * not change the timestep
- * numbers stored within the
- * other timestep objects. This
- * is only done upon calling the
- * @p start_sweep function. In not
- * changing the timestep numbers,
- * it is simpler to operate on a
- * space-time triangulation since
- * one can always use the
- * timestep numbers that were
- * used in the previous sweep.
+ * Note that this function does not change the timestep numbers stored
+ * within the other timestep objects. This is only done upon calling the @p
+ * start_sweep function. In not changing the timestep numbers, it is simpler
+ * to operate on a space-time triangulation since one can always use the
+ * timestep numbers that were used in the previous sweep.
*/
void delete_timestep (const unsigned int position);
/**
- * Solve the primal problem; uses the
- * functions @p init_for_primal_problem
- * and @p solve_primal_problem of the
- * TimeStepBase class through the
- * @p do_loop function of this class.
+ * Solve the primal problem; uses the functions @p init_for_primal_problem
+ * and @p solve_primal_problem of the TimeStepBase class through the @p
+ * do_loop function of this class.
*
- * Look ahead and look back are
- * determined by the @p timestepping_data_primal
- * object given to the constructor.
+ * Look ahead and look back are determined by the @p
+ * timestepping_data_primal object given to the constructor.
*/
void solve_primal_problem ();
/**
- * Solve the dual problem; uses the
- * functions @p init_for_dual_problem
- * and @p solve_dual_problem of the
- * TimeStepBase class through the
- * @p do_loop function of this class.
+ * Solve the dual problem; uses the functions @p init_for_dual_problem and
+ * @p solve_dual_problem of the TimeStepBase class through the @p do_loop
+ * function of this class.
*
- * Look ahead and look back are
- * determined by the @p timestepping_data_dual
+ * Look ahead and look back are determined by the @p timestepping_data_dual
* object given to the constructor.
*/
void solve_dual_problem ();
/**
- * Do a postprocessing round; uses the
- * functions @p init_for_postprocessing
- * and @p postprocess of the
- * TimeStepBase class through the
- * @p do_loop function of this class.
+ * Do a postprocessing round; uses the functions @p init_for_postprocessing
+ * and @p postprocess of the TimeStepBase class through the @p do_loop
+ * function of this class.
*
- * Look ahead and look back are
- * determined by the @p timestepping_data_postprocess
- * object given to the constructor.
+ * Look ahead and look back are determined by the @p
+ * timestepping_data_postprocess object given to the constructor.
*/
void postprocess ();
/**
- * Do a loop over all timesteps, call the
- * @p init_function at the beginning and
- * the @p loop_function of each time step.
- * The @p timestepping_data determine how
- * many timesteps in front and behind
- * the present one the @p wake_up and
- * @p sleep functions are called.
+ * Do a loop over all timesteps, call the @p init_function at the beginning
+ * and the @p loop_function of each time step. The @p timestepping_data
+ * determine how many timesteps in front and behind the present one the @p
+ * wake_up and @p sleep functions are called.
*
- * To see how this function work, note that
- * the function @p solve_primal_problem only
- * consists of a call to
- * <tt>do_loop (mem_fun(&TimeStepBase::init_for_primal_problem),
- * mem_fun(&TimeStepBase::solve_primal_problem),
- * timestepping_data_primal, forward);</tt>.
+ * To see how this function work, note that the function @p
+ * solve_primal_problem only consists of a call to <tt>do_loop
+ * (mem_fun(&TimeStepBase::init_for_primal_problem),
+ * mem_fun(&TimeStepBase::solve_primal_problem), timestepping_data_primal,
+ * forward);</tt>.
*
- * Note also, that the given class from which
- * the two functions are taken needs not
- * necessarily be TimeStepBase, but it
- * could also be a derived class, that is
- * @p static_castable from a TimeStepBase.
- * The function may be a virtual function
- * (even a pure one) of that class, which
- * should help if the actual class where it
- * is implemented is one which is derived
- * through virtual base classes and thus
- * unreachable by @p static_cast from the
- * TimeStepBase class.
+ * Note also, that the given class from which the two functions are taken
+ * needs not necessarily be TimeStepBase, but it could also be a derived
+ * class, that is @p static_castable from a TimeStepBase. The function may
+ * be a virtual function (even a pure one) of that class, which should help
+ * if the actual class where it is implemented is one which is derived
+ * through virtual base classes and thus unreachable by @p static_cast from
+ * the TimeStepBase class.
*
- * Instead of using the above form, you can
- * equally well use
- * <tt>bind2nd(mem_fun1(&X::unary_function), arg)</tt>
- * which lets the @p do_loop
- * function call the given function with
- * the specified parameter. Note that you
- * need to bind the second parameter since
- * the first one implicitly contains
- * the object which the function is to
- * be called for.
+ * Instead of using the above form, you can equally well use
+ * <tt>bind2nd(mem_fun1(&X::unary_function), arg)</tt> which lets the @p
+ * do_loop function call the given function with the specified parameter.
+ * Note that you need to bind the second parameter since the first one
+ * implicitly contains the object which the function is to be called for.
*/
template <typename InitFunctionObject, typename LoopFunctionObject>
void do_loop (InitFunctionObject init_function,
/**
- * Initialize the objects for the next
- * sweep. This function specifically does
- * the following: assign each time
- * level the number it presently has
- * within the array (which may change,
- * if time levels are inserted or
- * deleted) and transmit the number of
- * the present sweep to these objects.
+ * Initialize the objects for the next sweep. This function specifically
+ * does the following: assign each time level the number it presently has
+ * within the array (which may change, if time levels are inserted or
+ * deleted) and transmit the number of the present sweep to these objects.
*
- * It also calls the @p start_sweep
- * function of each time step object,
- * after the numbers above are set.
+ * It also calls the @p start_sweep function of each time step object, after
+ * the numbers above are set.
*
- * This function is virtual, so you
- * may overload it. You should, however
- * not forget to call this function as
- * well from your overwritten version,
- * at best at the beginning of your
- * function since this is some kind of
- * "constructor-like" function, which
- * should be called bottom-up.
+ * This function is virtual, so you may overload it. You should, however not
+ * forget to call this function as well from your overwritten version, at
+ * best at the beginning of your function since this is some kind of
+ * "constructor-like" function, which should be called bottom-up.
*
- * The default implementation of this
- * function calls @p start_sweep on all
+ * The default implementation of this function calls @p start_sweep on all
* time step objects.
*/
virtual void start_sweep (const unsigned int sweep_no);
/**
- * Analogon to the above
- * function, calling @p end_sweep
- * of each time step object. The
- * same applies with respect to
- * the @p virtualness of this
- * function as for the previous
- * one.
+ * Analogon to the above function, calling @p end_sweep of each time step
+ * object. The same applies with respect to the @p virtualness of this
+ * function as for the previous one.
*
- * @note This function does not
- * guarantee that @p end_sweep is
- * called for successive time
- * steps successively, rather the order of
- * time step objects for which the
- * function is called is
- * arbitrary. You should
- * therefore not assume that that
- * function has been called for
- * previous time steps
- * already. If in multithread
- * mode, the @p end_sweep function
- * of several time steps may be
- * called at once, so you should
- * use synchronization
- * mechanisms if your program
- * requires so.
+ * @note This function does not guarantee that @p end_sweep is called for
+ * successive time steps successively, rather the order of time step objects
+ * for which the function is called is arbitrary. You should therefore not
+ * assume that that function has been called for previous time steps
+ * already. If in multithread mode, the @p end_sweep function of several
+ * time steps may be called at once, so you should use synchronization
+ * mechanisms if your program requires so.
*/
virtual void end_sweep ();
/**
- * @deprecated Use the function without an argument.
- * @arg n_threads This argument is ignored.
+ * @deprecated Use the function without an argument. @arg n_threads This
+ * argument is ignored.
*/
virtual void end_sweep (const unsigned int n_threads) DEAL_II_DEPRECATED;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*/
std::size_t memory_consumption () const;
protected:
/**
- * Vector holding pointers to the time
- * level objects. This is the main data
- * this object operates on. Note that
- * this object takes possession of the
- * objects pointed to by the pointers
- * in this collection.
+ * Vector holding pointers to the time level objects. This is the main data
+ * this object operates on. Note that this object takes possession of the
+ * objects pointed to by the pointers in this collection.
*/
std::vector<SmartPointer<TimeStepBase,TimeDependent> > timesteps;
/**
- * Number of the present sweep. This is
- * reset by the @p start_sweep function
+ * Number of the present sweep. This is reset by the @p start_sweep function
* called at the outset of each sweep.
*/
unsigned int sweep_no;
/**
- * Some flags telling the
- * @p solve_primal_problem function what to
- * do. See the documentation of this struct
- * for more information.
+ * Some flags telling the @p solve_primal_problem function what to do. See
+ * the documentation of this struct for more information.
*/
const TimeSteppingData timestepping_data_primal;
/**
- * Some flags telling the
- * @p solve_dual_problem function what to
- * do. See the documentation of this struct
- * for more information.
+ * Some flags telling the @p solve_dual_problem function what to do. See the
+ * documentation of this struct for more information.
*/
const TimeSteppingData timestepping_data_dual;
/**
- * Some flags telling the
- * @p postprocess function what to
- * do. See the documentation of this struct
- * for more information.
+ * Some flags telling the @p postprocess function what to do. See the
+ * documentation of this struct for more information.
*/
const TimeSteppingData timestepping_data_postprocess;
private:
/**
- * Do the work of <tt>end_sweep()</tt>
- * for some timesteps only. This
- * is useful in multithread mode.
+ * Do the work of <tt>end_sweep()</tt> for some timesteps only. This is
+ * useful in multithread mode.
*/
void end_sweep (const unsigned int begin_timestep,
const unsigned int end_timestep);
/**
* Base class for a time step in time dependent problems. This class provides
* barely more than the basic framework, defining the necessary virtual
- * functions (namely @p sleep and @p wake_up), the interface to previous
- * and following grids, and some functions to be called before a new loop
- * over all time steps is started.
+ * functions (namely @p sleep and @p wake_up), the interface to previous and
+ * following grids, and some functions to be called before a new loop over all
+ * time steps is started.
*
* @author Wolfgang Bangerth, 1999
*/
{
public:
/**
- * Enum denoting the type of problem
- * which will have to be solved next.
+ * Enum denoting the type of problem which will have to be solved next.
*/
enum SolutionState
{
};
/**
- * Constructor. Does nothing here apart
- * from setting the time.
+ * Constructor. Does nothing here apart from setting the time.
*/
TimeStepBase (const double time);
/**
- * Destructor. At present, this does
- * nothing.
+ * Destructor. At present, this does nothing.
*/
virtual ~TimeStepBase ();
/**
- * Reconstruct all the data that is
- * needed for this time level to work.
- * This function serves to reget all
- * the variables and data structures
- * to work again after they have been
- * send to sleep some time before, or
- * at the first time we visit this time
- * level. In particular, it is used
- * to reconstruct the triangulation,
- * degree of freedom handlers, to reload
- * data vectors in case they have been
- * stored to disk, etc.
+ * Reconstruct all the data that is needed for this time level to work. This
+ * function serves to reget all the variables and data structures to work
+ * again after they have been send to sleep some time before, or at the
+ * first time we visit this time level. In particular, it is used to
+ * reconstruct the triangulation, degree of freedom handlers, to reload data
+ * vectors in case they have been stored to disk, etc.
*
- * The actual implementation of
- * this function does nothing.
+ * The actual implementation of this function does nothing.
*
- * Since this is an important task, you
- * should call this function from your
- * own function, should you choose to
- * overload it in your own class (which
- * likely is the case), preferably at
- * the beginning so that your function
- * can take effect of the triangulation
- * already existing.
+ * Since this is an important task, you should call this function from your
+ * own function, should you choose to overload it in your own class (which
+ * likely is the case), preferably at the beginning so that your function
+ * can take effect of the triangulation already existing.
*/
virtual void wake_up (const unsigned int);
/**
- * This is the opposite function
- * to @p wake_up. It is used to
- * delete data or save it to disk
- * after they are no more needed
- * for the present sweep. Typical
- * kinds of data for this are
- * data vectors, degree of
- * freedom handlers,
- * triangulation objects,
- * etc. which occupy large
- * amounts of memory and may
- * therefore be externalized.
+ * This is the opposite function to @p wake_up. It is used to delete data or
+ * save it to disk after they are no more needed for the present sweep.
+ * Typical kinds of data for this are data vectors, degree of freedom
+ * handlers, triangulation objects, etc. which occupy large amounts of
+ * memory and may therefore be externalized.
*
- * By default, this function does
- * nothing.
+ * By default, this function does nothing.
*/
virtual void sleep (const unsigned int);
/**
- * This function is called each time
- * before a new sweep is started. You
- * may want to set up some fields needed
- * in the course of the computations,
- * and so on. You should take good care,
- * however, not to install large objects,
- * which should be deferred until the
- * @p wake_up function is called.
+ * This function is called each time before a new sweep is started. You may
+ * want to set up some fields needed in the course of the computations, and
+ * so on. You should take good care, however, not to install large objects,
+ * which should be deferred until the @p wake_up function is called.
*
- * A typical action of this function
- * would be sorting out names of
- * temporary files needed in the
- * process of solving, etc.
+ * A typical action of this function would be sorting out names of temporary
+ * files needed in the process of solving, etc.
*
- * At the time this function is called,
- * the values of @p timestep_no, @p sweep_no
- * and the pointer to the previous and
- * next time step object already have
- * their correct value.
+ * At the time this function is called, the values of @p timestep_no, @p
+ * sweep_no and the pointer to the previous and next time step object
+ * already have their correct value.
*
- * The default implementation of this
- * function does nothing.
+ * The default implementation of this function does nothing.
*/
virtual void start_sweep ();
/**
- * This is the analogon to the above
- * function, but it is called at the
- * end of a sweep. You will usually want
- * to do clean-ups in this function,
- * such as deleting temporary files
- * and the like.
+ * This is the analogon to the above function, but it is called at the end
+ * of a sweep. You will usually want to do clean-ups in this function, such
+ * as deleting temporary files and the like.
*/
virtual void end_sweep ();
/**
- * Before the primal problem is
- * solved on each time level, this
- * function is called (i.e. before the
- * solution takes place on the first
- * time level). By default, this function
- * sets the @p next_action variable of
- * this class. You may overload this
- * function, but you should call this
- * function within your own one.
+ * Before the primal problem is solved on each time level, this function is
+ * called (i.e. before the solution takes place on the first time level). By
+ * default, this function sets the @p next_action variable of this class.
+ * You may overload this function, but you should call this function within
+ * your own one.
*/
virtual void init_for_primal_problem ();
/**
- * Same as above, but called before
- * a round of dual problem solves.
+ * Same as above, but called before a round of dual problem solves.
*/
virtual void init_for_dual_problem ();
/**
- * Same as above, but called before
- * a round of postprocessing steps.
+ * Same as above, but called before a round of postprocessing steps.
*/
virtual void init_for_postprocessing ();
/**
- * This function is called by the
- * manager object when solving the
- * primal problem on this time level
- * is needed. It is called after
- * the @p wake_up function was
- * called and before the @p sleep
- * function will be called. There
- * is no default implementation for
- * obvious reasons, so you have
- * to overload this function.
+ * This function is called by the manager object when solving the primal
+ * problem on this time level is needed. It is called after the @p wake_up
+ * function was called and before the @p sleep function will be called.
+ * There is no default implementation for obvious reasons, so you have to
+ * overload this function.
*/
virtual void solve_primal_problem () = 0;
/**
- * This function is called by the
- * manager object when solving the
- * dual problem on this time level
- * is needed. It is called after
- * the @p wake_up function was
- * called and before the @p sleep
- * function will be called. There
- * is a default implementation
- * doing plain nothing since some
- * problems may not need solving a
- * dual problem. However, it
- * will abort the program when
- * being called anyway, since then you
- * should really overload the function.
+ * This function is called by the manager object when solving the dual
+ * problem on this time level is needed. It is called after the @p wake_up
+ * function was called and before the @p sleep function will be called.
+ * There is a default implementation doing plain nothing since some problems
+ * may not need solving a dual problem. However, it will abort the program
+ * when being called anyway, since then you should really overload the
+ * function.
*/
virtual void solve_dual_problem ();
/**
- * This function is called by the
- * manager object when postprocessing
- * this time level
- * is needed. It is called after
- * the @p wake_up function was
- * called and before the @p sleep
- * function will be called. There
- * is a default implementation
- * doing plain nothing since some
- * problems may not need doing a
- * postprocess step, e.g. if everything
- * was already done when solving the
- * primal problem. However, it
- * will abort the program when
- * being called anyway, since then you
- * should really overload the function.
+ * This function is called by the manager object when postprocessing this
+ * time level is needed. It is called after the @p wake_up function was
+ * called and before the @p sleep function will be called. There is a
+ * default implementation doing plain nothing since some problems may not
+ * need doing a postprocess step, e.g. if everything was already done when
+ * solving the primal problem. However, it will abort the program when being
+ * called anyway, since then you should really overload the function.
*/
virtual void postprocess_timestep ();
/**
- * Return the time value of this time
- * step.
+ * Return the time value of this time step.
*/
double get_time () const;
/**
- * Return the number of this time
- * step. Note that this number may vary
- * between different sweeps, if timesteps
- * are added or deleted.
+ * Return the number of this time step. Note that this number may vary
+ * between different sweeps, if timesteps are added or deleted.
*/
unsigned int get_timestep_no () const;
/**
- * Compute the time difference to the
- * last time step. If this timestep is
- * the first one, this function will
- * result in an exception. Though this
- * behaviour seems a bit drastic, it
- * is appropriate in most cases since
- * if there is no previous time step
- * you will need special treatment
- * anyway and this way no invalid
- * value is returned which could lead
- * to wrong but unnoticed results of
- * your computation. (The only sensible
- * value to return in that case would
- * not be zero, since valid computation
- * can be done with that, but would
- * be a denormalized value such as @p NaN.
- * However, there is not much difference
- * in finding that the results of a
- * computation are all denormalized values
- * or in getting an exception; in the
- * latter case you at least get the exact
- * place where your problem lies.)
+ * Compute the time difference to the last time step. If this timestep is
+ * the first one, this function will result in an exception. Though this
+ * behaviour seems a bit drastic, it is appropriate in most cases since if
+ * there is no previous time step you will need special treatment anyway and
+ * this way no invalid value is returned which could lead to wrong but
+ * unnoticed results of your computation. (The only sensible value to return
+ * in that case would not be zero, since valid computation can be done with
+ * that, but would be a denormalized value such as @p NaN. However, there is
+ * not much difference in finding that the results of a computation are all
+ * denormalized values or in getting an exception; in the latter case you at
+ * least get the exact place where your problem lies.)
*/
double get_backward_timestep () const;
/**
- * Return the time difference to the next
- * time step. With regard to the case
- * that there is no next time step,
- * the same applies as for the function
+ * Return the time difference to the next time step. With regard to the case
+ * that there is no next time step, the same applies as for the function
* above.
*/
double get_forward_timestep () const;
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*
- * You will want to overload
- * this function in derived
- * classes to compute the
- * amount memory used by the
- * derived class, and add the
- * result of this function to
- * your result.
+ * You will want to overload this function in derived classes to compute the
+ * amount memory used by the derived class, and add the result of this
+ * function to your result.
*/
virtual std::size_t memory_consumption () const;
protected:
/**
- * Pointer to the previous time step object
- * in the list.
+ * Pointer to the previous time step object in the list.
*/
const TimeStepBase *previous_timestep;
/**
- * Pointer to the next time step object
- * in the list.
+ * Pointer to the next time step object in the list.
*/
const TimeStepBase *next_timestep;
/**
- * Number of the sweep we are presently
- * in. This number is reset by the time
- * level manager before a sweep is
- * started.
+ * Number of the sweep we are presently in. This number is reset by the time
+ * level manager before a sweep is started.
*/
unsigned int sweep_no;
/**
- * Number of the time step, counted from
- * zero onwards. This number is reset at
- * the start of each sweep by the time
- * level manager, since some time steps
- * may have been inserted or deleted
- * after the previous sweep.
+ * Number of the time step, counted from zero onwards. This number is reset
+ * at the start of each sweep by the time level manager, since some time
+ * steps may have been inserted or deleted after the previous sweep.
*/
unsigned int timestep_no;
const double time;
/**
- * Variable storing whether the
- * solution of a primal or a dual
- * problem is actual, or any of
- * the other actions
- * specified. This variable is
- * set by the <tt>init_for_*</tt>
- * functions.
+ * Variable storing whether the solution of a primal or a dual problem is
+ * actual, or any of the other actions specified. This variable is set by
+ * the <tt>init_for_*</tt> functions.
*/
unsigned int next_action;
private:
/**
- * Reset the pointer to the previous time
- * step; shall only be called by the
+ * Reset the pointer to the previous time step; shall only be called by the
* time level manager object.
*
- * This function is called at the set-up
- * of the manager object and whenever
+ * This function is called at the set-up of the manager object and whenever
* a timestep is inserted or deleted.
*/
void set_previous_timestep (const TimeStepBase *previous);
/**
- * Reset the pointer to the next time
- * step; shall only be called by the
- * time level manager object.
+ * Reset the pointer to the next time step; shall only be called by the time
+ * level manager object.
*
- * This function is called at the set-up
- * of the manager object and whenever
+ * This function is called at the set-up of the manager object and whenever
* a timestep is inserted or deleted.
*/
void set_next_timestep (const TimeStepBase *next);
/**
- * Set the number this time step
- * has in the list of timesteps.
- * This function is called by the
- * time step management object at
- * the beginning of each sweep, to
- * update information which may have
- * changed due to addition or deleltion
- * of time levels.
+ * Set the number this time step has in the list of timesteps. This function
+ * is called by the time step management object at the beginning of each
+ * sweep, to update information which may have changed due to addition or
+ * deleltion of time levels.
*/
void set_timestep_no (const unsigned int step_no);
/**
- * Set the number of the sweep we are
- * presently in. This function is
- * called by the time level management
- * object at start-up time of each
- * sweep.
+ * Set the number of the sweep we are presently in. This function is called
+ * by the time level management object at start-up time of each sweep.
*/
void set_sweep_no (const unsigned int sweep_no);
/**
- * Copy constructor. I can see no reason
- * why someone might want to use it, so
- * I don't provide it. Since this class
- * has pointer members, making it private
- * prevents the compiler to provide it's
- * own, incorrect one if anyone chose to
- * copy such an object.
+ * Copy constructor. I can see no reason why someone might want to use it,
+ * so I don't provide it. Since this class has pointer members, making it
+ * private prevents the compiler to provide it's own, incorrect one if
+ * anyone chose to copy such an object.
*/
TimeStepBase (const TimeStepBase &);
/**
- * Copy operator. I can see no reason
- * why someone might want to use it, so
- * I don't provide it. Since this class
- * has pointer members, making it private
- * prevents the compiler to provide it's
- * own, incorrect one if anyone chose to
- * copy such an object.
+ * Copy operator. I can see no reason why someone might want to use it, so I
+ * don't provide it. Since this class has pointer members, making it private
+ * prevents the compiler to provide it's own, incorrect one if anyone chose
+ * to copy such an object.
*/
TimeStepBase &operator = (const TimeStepBase &);
/**
- * Namespace in which some classes are declared that encapsulate flags
- * for the TimeStepBase_Tria() class. These used to be local data
- * types of that class, but some compilers choked on some aspects, so
- * we put them into a namespace of their own.
+ * Namespace in which some classes are declared that encapsulate flags for the
+ * TimeStepBase_Tria() class. These used to be local data types of that class,
+ * but some compilers choked on some aspects, so we put them into a namespace
+ * of their own.
*
* @author Wolfgang Bangerth, 2001
*/
namespace TimeStepBase_Tria_Flags
{
/**
- * This structure is used to tell the TimeStepBase_Tria() class how grids should
- * be handled. It has flags defining the moments where grids shall be
+ * This structure is used to tell the TimeStepBase_Tria() class how grids
+ * should be handled. It has flags defining the moments where grids shall be
* re-made and when they may be deleted. Also, one variable states whether
* grids should be kept in memory or should be deleted between to uses to
* save memory.
struct Flags
{
/**
- * Default constructor; yields
- * an exception, so is not
- * really usable.
+ * Default constructor; yields an exception, so is not really usable.
*/
Flags ();
/**
- * Constructor; see the different
- * fields for a description of the
- * meaning of the parameters.
+ * Constructor; see the different fields for a description of the meaning
+ * of the parameters.
*/
Flags (const bool delete_and_rebuild_tria,
const unsigned int wakeup_level_to_build_grid,
const unsigned int sleep_level_to_delete_grid);
/**
- * This flag determines whether
- * the @p sleep and
- * @p wake_up functions shall
- * delete and rebuild the
- * triangulation. While for
- * small problems, this is not
- * necessary, for large
- * problems it is indispensable
- * to save memory. The reason
- * for this is that there may
- * be several hundred time
- * levels in memory, each with
- * its own triangulation, which
- * may require large amounts if
- * there are many cells on
- * each. Having a total of
- * 100.000.000 cells on all
- * time levels taken together
- * is not uncommon, which makes
- * this flag understandable.
+ * This flag determines whether the @p sleep and @p wake_up functions
+ * shall delete and rebuild the triangulation. While for small problems,
+ * this is not necessary, for large problems it is indispensable to save
+ * memory. The reason for this is that there may be several hundred time
+ * levels in memory, each with its own triangulation, which may require
+ * large amounts if there are many cells on each. Having a total of
+ * 100.000.000 cells on all time levels taken together is not uncommon,
+ * which makes this flag understandable.
*/
const bool delete_and_rebuild_tria;
/**
- * This number denotes the
- * parameter to the @p wake_up
- * function at which it shall
- * rebuild the grid. Obviously,
- * it shall be less than or
- * equal to the @p look_ahead
- * number passed to the time
- * step management object; if
- * it is equal, then the grid
- * is rebuilt the first time
- * the @p wake_up function is
- * called. If
- * @p delete_and_rebuild_tria
- * is @p false, this number
- * has no meaning.
+ * This number denotes the parameter to the @p wake_up function at which
+ * it shall rebuild the grid. Obviously, it shall be less than or equal to
+ * the @p look_ahead number passed to the time step management object; if
+ * it is equal, then the grid is rebuilt the first time the @p wake_up
+ * function is called. If @p delete_and_rebuild_tria is @p false, this
+ * number has no meaning.
*/
const unsigned int wakeup_level_to_build_grid;
/**
- * This is the opposite flag to
- * the one above: it determines
- * at which call to * @p sleep
- * the grid shall be deleted.
+ * This is the opposite flag to the one above: it determines at which call
+ * to * @p sleep the grid shall be deleted.
*/
const unsigned int sleep_level_to_delete_grid;
/**
- * This structure is used to tell the TimeStepBase_Tria() class how grids should
- * be refined. Before we explain all the different variables, fist some terminology:
+ * This structure is used to tell the TimeStepBase_Tria() class how grids
+ * should be refined. Before we explain all the different variables, fist
+ * some terminology:
* <ul>
* <li> Correction: after having flagged some cells of the triangulation for
- * following some given criterion, we may want to change the number of flagged
- * cells on this grid according to another criterion that the number of cells
- * may be only a certain fraction more or less then the number of cells on
- * the previous grid. This change of refinement flags will be called
- * "correction" in the sequel.
- * <li> Adaption: in order to make the change between one grid and the next not
- * to large, we may want to flag some additional cells on one of the two
- * grids such that there are not too grave differences. This process will
- * be called "adaption".
+ * following some given criterion, we may want to change the number of
+ * flagged cells on this grid according to another criterion that the number
+ * of cells may be only a certain fraction more or less then the number of
+ * cells on the previous grid. This change of refinement flags will be
+ * called "correction" in the sequel.
+ * <li> Adaption: in order to make the change between one grid and the next
+ * not to large, we may want to flag some additional cells on one of the two
+ * grids such that there are not too grave differences. This process will be
+ * called "adaption".
* </ul>
*
*
* <h3>Description of flags</h3>
*
* <ul>
- * <li> @p max_refinement_level: Cut the refinement of cells at a given level.
- * This flag does not influence the flagging of cells, so not more cells
- * on the coarser levels are flagged than usual. Rather, the flags are all
- * set, but when it comes to the actual refinement, the maximum refinement
- * level is truncated.
+ * <li> @p max_refinement_level: Cut the refinement of cells at a given
+ * level. This flag does not influence the flagging of cells, so not more
+ * cells on the coarser levels are flagged than usual. Rather, the flags are
+ * all set, but when it comes to the actual refinement, the maximum
+ * refinement level is truncated.
*
- * This option is only really useful when you want to compare global
- * refinement with adaptive refinement when you don't want the latter
- * to refine more than the global refinement.
+ * This option is only really useful when you want to compare global
+ * refinement with adaptive refinement when you don't want the latter to
+ * refine more than the global refinement.
*
- * <li> @p first_sweep_with_correction: When using cell number correction
- * as defined above, it may be worth while to start with this only in
- * later sweeps, not already in the first one. If this variable is
- * zero, then start with the first sweep, else with a higher one. The
- * rationale for only starting later is that we do not want to block the
- * development of grids at the beginning and only impose restrictions in
- * the sweeps where we start to be interested in the actual results of
- * the computations.
+ * <li> @p first_sweep_with_correction: When using cell number correction as
+ * defined above, it may be worth while to start with this only in later
+ * sweeps, not already in the first one. If this variable is zero, then
+ * start with the first sweep, else with a higher one. The rationale for
+ * only starting later is that we do not want to block the development of
+ * grids at the beginning and only impose restrictions in the sweeps where
+ * we start to be interested in the actual results of the computations.
*
- * <li> @p min_cells_for_correction: If we want a more free process of
- * grid development, we may want to impose less rules for grids with few
- * cells also. This variable sets a lower bound for the cell number of
- * grids where corrections are to be performed.
+ * <li> @p min_cells_for_correction: If we want a more free process of grid
+ * development, we may want to impose less rules for grids with few cells
+ * also. This variable sets a lower bound for the cell number of grids where
+ * corrections are to be performed.
*
* <li> @p cell_number_corridor_top: Fraction of the number of cells by
- * which the number of cells of one grid may be higher than that on the
- * previous grid. Common values are 10 per cent (i.e. 0.1). The naming
- * of the variable results from the goal to define a target corridor
- * for the number of cells after refinement has taken place.
+ * which the number of cells of one grid may be higher than that on the
+ * previous grid. Common values are 10 per cent (i.e. 0.1). The naming of
+ * the variable results from the goal to define a target corridor for the
+ * number of cells after refinement has taken place.
*
* <li> @p cell_number_corridor_bottom: Fraction of the number of cells by
- * which the number of cells of one grid may be lower than that on the
- * previous grid. Common values are 5 per cent (i.e. 0.05). Usually this
- * number will be smaller than @p cell_number_corridor_top since an
- * increase of the number of cells is not harmful (though it increases
- * the numerical amount of work needed to solve the problem) while a
- * sharp decrease may reduce the accuracy of the final result even if
- * the time steps computed before the decrease were computed to high
- * accuracy.
+ * which the number of cells of one grid may be lower than that on the
+ * previous grid. Common values are 5 per cent (i.e. 0.05). Usually this
+ * number will be smaller than @p cell_number_corridor_top since an increase
+ * of the number of cells is not harmful (though it increases the numerical
+ * amount of work needed to solve the problem) while a sharp decrease may
+ * reduce the accuracy of the final result even if the time steps computed
+ * before the decrease were computed to high accuracy.
*
- * Note however, that if you compute the dual problem as well, then the time
- * direction is reversed, so the two values defining the cell number
- * corridor should be about equal.
+ * Note however, that if you compute the dual problem as well, then the time
+ * direction is reversed, so the two values defining the cell number
+ * corridor should be about equal.
*
- * <li> @p correction_relaxations: This is a list of pairs of number with the
- * following meaning: just as for @p min_cells_for_correction, it may be
- * worth while to reduce the requirements upon grids if the have few cells.
- * The present variable stores a list of cell numbers along with some values
- * which tell us that the cell number corridor should be enlarged by a
- * certain factor. For example, if this list was <tt>((100 5) (200 3) (500 2))</tt>,
- * this would mean that for grids with a cell number below 100, the
- * <tt>cell_number_corridor_*</tt> variables are to be multiplied by 5 before they
- * are applied, for cell numbers below 200 they are to be multiplied by 3,
- * and so on.
+ * <li> @p correction_relaxations: This is a list of pairs of number with
+ * the following meaning: just as for @p min_cells_for_correction, it may be
+ * worth while to reduce the requirements upon grids if the have few cells.
+ * The present variable stores a list of cell numbers along with some values
+ * which tell us that the cell number corridor should be enlarged by a
+ * certain factor. For example, if this list was <tt>((100 5) (200 3) (500
+ * 2))</tt>, this would mean that for grids with a cell number below 100,
+ * the <tt>cell_number_corridor_*</tt> variables are to be multiplied by 5
+ * before they are applied, for cell numbers below 200 they are to be
+ * multiplied by 3, and so on.
*
- * @p correction_relaxations is actually a vector of such list. Each entry
- * in this vector denotes the relaxation rules for one sweep. The last
- * entry defines the relaxation rules for all following sweeps. This
- * scheme is adopted to allow for stricter corrections in later sweeps
- * while the relaxations may be more generous in the first sweeps.
+ * @p correction_relaxations is actually a vector of such list. Each entry
+ * in this vector denotes the relaxation rules for one sweep. The last entry
+ * defines the relaxation rules for all following sweeps. This scheme is
+ * adopted to allow for stricter corrections in later sweeps while the
+ * relaxations may be more generous in the first sweeps.
*
- * There is a static variable @p default_correction_relaxations which you
- * can use as a default value. It is an empty list and thus defines no
- * relaxations.
+ * There is a static variable @p default_correction_relaxations which you
+ * can use as a default value. It is an empty list and thus defines no
+ * relaxations.
*
* <li> @p cell_number_correction_steps: Usually, if you want the number of
- * cells to be corrected, the target corridor for the cell number is computed
- * and some additional cells are flagged or flags are removed. But since
- * the cell number resulting after flagging and deflagging can not be
- * easily computed, it will usually not be within the corridor. We therefore
- * need to iteratively get to our goal. Usually, three or four iterations are
- * needed, but using this variable, you can reduce the allowed number of
- * iterations; breaking the loop after two iterations yields good results
- * regularly. Setting the variable to zero will result in no correction
- * steps at all.
+ * cells to be corrected, the target corridor for the cell number is
+ * computed and some additional cells are flagged or flags are removed. But
+ * since the cell number resulting after flagging and deflagging can not be
+ * easily computed, it will usually not be within the corridor. We therefore
+ * need to iteratively get to our goal. Usually, three or four iterations
+ * are needed, but using this variable, you can reduce the allowed number of
+ * iterations; breaking the loop after two iterations yields good results
+ * regularly. Setting the variable to zero will result in no correction
+ * steps at all.
*
* <li> @p mirror_flags_to_previous_grid: If a cell on the present grid is
- * flagged for refinement, also flag the corresponding cell on the previous
- * grid. This is useful if, for example, error indicators are computed for
- * space-time cells, but are stored for the second grid only. Now, since the
- * first grid has the same contributions to the indicators as the second, it
- * may be useful to flag both if necessary. This is done if the present
- * variable is set.
+ * flagged for refinement, also flag the corresponding cell on the previous
+ * grid. This is useful if, for example, error indicators are computed for
+ * space-time cells, but are stored for the second grid only. Now, since the
+ * first grid has the same contributions to the indicators as the second, it
+ * may be useful to flag both if necessary. This is done if the present
+ * variable is set.
*
- * <li> @p adapt_grids: adapt the present grid to the previous one in the sense
- * defined above. What is actually done here is the following: if going from
- * the previous to the present grid would result in double refinement or
- * double coarsening of some cells, then we try to flag these cells for
- * refinement or coarsening such as to avoid the double step. Obviously, more
- * than double refinement of coarsening is also caught.
+ * <li> @p adapt_grids: adapt the present grid to the previous one in the
+ * sense defined above. What is actually done here is the following: if
+ * going from the previous to the present grid would result in double
+ * refinement or double coarsening of some cells, then we try to flag these
+ * cells for refinement or coarsening such as to avoid the double step.
+ * Obviously, more than double refinement of coarsening is also caught.
*
- * Grid adaption can try to avoid such changes between two grids, but it can
- * never promise that they don't occur. This is because the next grid may
- * change the present one, but then again there may be jumps in refinement
- * level between the present and the previous one; this could only be avoided
- * by looping iteratively through all grids, back and forth, until nothing
- * changes anymore, which is obviously impossible if there are many time steps
- * with very large grids.
+ * Grid adaption can try to avoid such changes between two grids, but it can
+ * never promise that they don't occur. This is because the next grid may
+ * change the present one, but then again there may be jumps in refinement
+ * level between the present and the previous one; this could only be
+ * avoided by looping iteratively through all grids, back and forth, until
+ * nothing changes anymore, which is obviously impossible if there are many
+ * time steps with very large grids.
* </ul>
*/
template <int dim>
struct RefinementFlags
{
/**
- * Typedef of a data type
- * describing some relaxations
- * of the correction process.
- * See the general description
- * of this class for more
+ * Typedef of a data type describing some relaxations of the correction
+ * process. See the general description of this class for more
* information.
*/
typedef std::vector<std::vector<std::pair<unsigned int, double> > > CorrectionRelaxations;
/**
- * Default values for the relaxations:
- * no relaxations.
+ * Default values for the relaxations: no relaxations.
*/
static CorrectionRelaxations default_correction_relaxations;
/**
- * Constructor. The default
- * values are chosen such that
- * almost no restriction on the
- * mesh refinement is imposed.
+ * Constructor. The default values are chosen such that almost no
+ * restriction on the mesh refinement is imposed.
*/
RefinementFlags (const unsigned int max_refinement_level = 0,
const unsigned int first_sweep_with_correction = 0,
const bool adapt_grids = false);
/**
- * Maximum level of a cell in
- * the triangulation of a time
- * level. If it is set to zero,
- * then no limit is imposed on
- * the number of refinements a
- * coarse grid cell may
- * undergo. Usually, this field
- * is used, if for some reason
- * you want to limit refinement
- * in an adaptive process, for
- * example to avoid overly
- * large numbers of cells or to
- * compare with grids which
- * have a certain number of
- * refinements.
+ * Maximum level of a cell in the triangulation of a time level. If it is
+ * set to zero, then no limit is imposed on the number of refinements a
+ * coarse grid cell may undergo. Usually, this field is used, if for some
+ * reason you want to limit refinement in an adaptive process, for example
+ * to avoid overly large numbers of cells or to compare with grids which
+ * have a certain number of refinements.
*/
const unsigned int max_refinement_level;
/**
- * First sweep to perform cell
- * number correction steps on;
- * for sweeps before, cells are
- * only flagged and no
- * number-correction to
- * previous grids is performed.
+ * First sweep to perform cell number correction steps on; for sweeps
+ * before, cells are only flagged and no number-correction to previous
+ * grids is performed.
*/
const unsigned int first_sweep_with_correction;
/**
- * Apply cell number correction
- * with the previous time level
- * only if there are more than
- * this number of cells.
+ * Apply cell number correction with the previous time level only if there
+ * are more than this number of cells.
*/
const unsigned int min_cells_for_correction;
/**
- * Fraction by which the number
- * of cells on a time level may
- * differ from the number on
- * the previous time level
- * (first: top deviation,
- * second: bottom deviation).
+ * Fraction by which the number of cells on a time level may differ from
+ * the number on the previous time level (first: top deviation, second:
+ * bottom deviation).
*/
const double cell_number_corridor_top;
const double cell_number_corridor_bottom;
/**
- * List of relaxations to the
- * correction step.
+ * List of relaxations to the correction step.
*/
const std::vector<std::vector<std::pair<unsigned int,double> > > correction_relaxations;
/**
- * Number of iterations to be
- * performed to adjust the
- * number of cells on a time
- * level to those on the
- * previous one. Zero means: do
- * no such iteration.
+ * Number of iterations to be performed to adjust the number of cells on a
+ * time level to those on the previous one. Zero means: do no such
+ * iteration.
*/
const unsigned int cell_number_correction_steps;
/**
- * Flag all cells which are
- * flagged on this timestep for
- * refinement on the previous
- * one also. This is useful in
- * case the error indicator was
- * computed by integration over
- * time-space cells, but are
- * now associated to a grid on
- * a discrete time level. Since
- * the error contribution comes
- * from both grids, however, it
- * is appropriate to refine
- * both grids.
+ * Flag all cells which are flagged on this timestep for refinement on the
+ * previous one also. This is useful in case the error indicator was
+ * computed by integration over time-space cells, but are now associated
+ * to a grid on a discrete time level. Since the error contribution comes
+ * from both grids, however, it is appropriate to refine both grids.
*
- * Since the previous grid does
- * not mirror the flags to the
- * one before it, this does not
- * lead to an almost infinite
- * growth of cell numbers. You
- * should use this flag with
- * cell number correction
- * switched on only, however.
+ * Since the previous grid does not mirror the flags to the one before it,
+ * this does not lead to an almost infinite growth of cell numbers. You
+ * should use this flag with cell number correction switched on only,
+ * however.
*
- * Mirroring is done after cell
- * number correction is done,
- * but before grid adaption, so
- * the cell number on this grid
- * is not noticeably influenced
- * by the cells flagged
- * additionally on the previous
- * grid.
+ * Mirroring is done after cell number correction is done, but before grid
+ * adaption, so the cell number on this grid is not noticeably influenced
+ * by the cells flagged additionally on the previous grid.
*/
const bool mirror_flags_to_previous_grid;
/**
- * Adapt this grid to the
- * previous one.
+ * Adapt this grid to the previous one.
*/
const bool adapt_grids;
/**
* Structure given to the actual refinement function, telling it which
* thresholds to take for coarsening and refinement. The actual refinement
- * criteria are loaded by calling the virtual function
- * @p get_tria_refinement_criteria.
+ * criteria are loaded by calling the virtual function @p
+ * get_tria_refinement_criteria.
*/
template <int dim>
struct RefinementData
const double coarsening_threshold=0);
/**
- * Threshold for refinement:
- * cells having a larger value
- * will be refined (at least in
- * the first round; subsequent
- * steps of the refinement
- * process may flag other cells
- * as well or remove the flag
- * from cells with a criterion
- * higher than this threshold).
+ * Threshold for refinement: cells having a larger value will be refined
+ * (at least in the first round; subsequent steps of the refinement
+ * process may flag other cells as well or remove the flag from cells with
+ * a criterion higher than this threshold).
*/
const double refinement_threshold;
/**
- * Same threshold for
- * coarsening: cells with a
- * smaller threshold will be
+ * Same threshold for coarsening: cells with a smaller threshold will be
* coarsened if possible.
*/
const double coarsening_threshold;
/**
- * Specialisation of TimeStepBase which addresses some aspects of grid handling.
- * In particular, this class is thought to make handling of grids available that
- * are adaptively refined on each time step separately or with a loose coupling
- * between time steps. It also takes care of deleting and rebuilding grids when
- * memory resources are a point, through the @p sleep and @p wake_up functions
- * declared in the base class.
+ * Specialisation of TimeStepBase which addresses some aspects of grid
+ * handling. In particular, this class is thought to make handling of grids
+ * available that are adaptively refined on each time step separately or with
+ * a loose coupling between time steps. It also takes care of deleting and
+ * rebuilding grids when memory resources are a point, through the @p sleep
+ * and @p wake_up functions declared in the base class.
*
- * In addition to that, it offers functions which do some rather hairy refinement
- * rules for time dependent problems, trying to avoid too much change in the grids
- * between subsequent time levels, while also trying to retain the freedom of
- * refining each grid separately. There are lots of flags and numbers controlling
- * this function, which might drastically change the behaviour of the function -- see
- * the description of the flags for further information.
+ * In addition to that, it offers functions which do some rather hairy
+ * refinement rules for time dependent problems, trying to avoid too much
+ * change in the grids between subsequent time levels, while also trying to
+ * retain the freedom of refining each grid separately. There are lots of
+ * flags and numbers controlling this function, which might drastically change
+ * the behaviour of the function -- see the description of the flags for
+ * further information.
*
- * @author Wolfgang Bangerth, 1999; large parts taken from the wave program, by Wolfgang Bangerth 1998
+ * @author Wolfgang Bangerth, 1999; large parts taken from the wave program,
+ * by Wolfgang Bangerth 1998
*/
template <int dim>
class TimeStepBase_Tria : public TimeStepBase
{
public:
/**
- * Typedef the data types of the
- * TimeStepBase_Tria_Flags()
- * namespace into local scope.
+ * Typedef the data types of the TimeStepBase_Tria_Flags() namespace into
+ * local scope.
*/
typedef typename TimeStepBase_Tria_Flags::Flags<dim> Flags;
typedef typename TimeStepBase_Tria_Flags::RefinementFlags<dim> RefinementFlags;
/**
- * Extension of the enum in the base
- * class denoting the next action to be
+ * Extension of the enum in the base class denoting the next action to be
* done.
*/
enum SolutionState
/**
- * Default constructor. Does nothing but
- * throws an exception. We need to have
- * such a constructor in order to satisfy
- * the needs of derived classes, which
- * take this class as a virtual base class
- * and don't need to call this constructor
- * of they are not terminal classes. The
- * compiler would like to know a
- * constructor to call anyway since it
- * can't know that the class is not
- * terminal.
+ * Default constructor. Does nothing but throws an exception. We need to
+ * have such a constructor in order to satisfy the needs of derived classes,
+ * which take this class as a virtual base class and don't need to call this
+ * constructor of they are not terminal classes. The compiler would like to
+ * know a constructor to call anyway since it can't know that the class is
+ * not terminal.
*/
TimeStepBase_Tria ();
/**
- * Constructor. Takes a coarse
- * grid from which the grids on this
- * time level will be derived and
- * some flags steering the behaviour
- * of this object.
+ * Constructor. Takes a coarse grid from which the grids on this time level
+ * will be derived and some flags steering the behaviour of this object.
*
- * The ownership of the coarse grid
- * stays with the creator of this
- * object. However, it is locked
- * from destruction to guarantee
- * the lifetime of the coarse grid
- * is longer than it is needed by
- * this object.
+ * The ownership of the coarse grid stays with the creator of this object.
+ * However, it is locked from destruction to guarantee the lifetime of the
+ * coarse grid is longer than it is needed by this object.
*
- * You need to give the general flags
- * structure to this function since it
- * is needed anyway; the refinement
- * flags can be omitted if you do
- * not intend to call the refinement
- * function of this class.
+ * You need to give the general flags structure to this function since it is
+ * needed anyway; the refinement flags can be omitted if you do not intend
+ * to call the refinement function of this class.
*/
TimeStepBase_Tria (const double time,
const Triangulation<dim, dim> &coarse_grid,
const RefinementFlags &refinement_flags = RefinementFlags());
/**
- * Destructor. At present, this does
- * not more than releasing the lock on
- * the coarse grid triangulation given
- * to the constructor.
+ * Destructor. At present, this does not more than releasing the lock on the
+ * coarse grid triangulation given to the constructor.
*/
virtual ~TimeStepBase_Tria ();
/**
- * Reconstruct all the data that is
- * needed for this time level to work.
- * This function serves to reget all
- * the variables and data structures
- * to work again after they have been
- * send to sleep some time before, or
- * at the first time we visit this time
- * level. In particular, it is used
- * to reconstruct the triangulation,
- * degree of freedom handlers, to reload
- * data vectors in case they have been
- * stored to disk, etc. By default,
- * this function rebuilds the triangulation
- * if the respective flag has been set to
- * destroy it in the @p sleep function.
- * It does so also the first time we
- * hit this function and @p wakeup_level
- * equals <tt>flags.wakeup_level_to_build_grid</tt>,
- * independently of the value of the
- * mentioned flag. (Actually, it does so
- * whenever the triangulation pointer
- * equals the Null pointer and the
- * value of @p wakeup_level is right.)
+ * Reconstruct all the data that is needed for this time level to work. This
+ * function serves to reget all the variables and data structures to work
+ * again after they have been send to sleep some time before, or at the
+ * first time we visit this time level. In particular, it is used to
+ * reconstruct the triangulation, degree of freedom handlers, to reload data
+ * vectors in case they have been stored to disk, etc. By default, this
+ * function rebuilds the triangulation if the respective flag has been set
+ * to destroy it in the @p sleep function. It does so also the first time we
+ * hit this function and @p wakeup_level equals
+ * <tt>flags.wakeup_level_to_build_grid</tt>, independently of the value of
+ * the mentioned flag. (Actually, it does so whenever the triangulation
+ * pointer equals the Null pointer and the value of @p wakeup_level is
+ * right.)
*
- * Since this is an important task, you
- * should call this function from your
- * own function, should you choose to
- * overload it in your own class (which
- * likely is the case), preferably at
- * the beginning so that your function
- * can take effect of the triangulation
- * already existing.
+ * Since this is an important task, you should call this function from your
+ * own function, should you choose to overload it in your own class (which
+ * likely is the case), preferably at the beginning so that your function
+ * can take effect of the triangulation already existing.
*/
virtual void wake_up (const unsigned int wakeup_level);
/**
- * This is the opposite function
- * to @p wake_up. It is used to
- * delete data or save it to disk
- * after they are no more needed
- * for the present sweep. Typical
- * kinds of data for this are
- * data vectors, degree of
- * freedom handlers,
- * triangulation objects,
- * etc. which occupy large
- * amounts of memory and may
- * therefore be externalized.
+ * This is the opposite function to @p wake_up. It is used to delete data or
+ * save it to disk after they are no more needed for the present sweep.
+ * Typical kinds of data for this are data vectors, degree of freedom
+ * handlers, triangulation objects, etc. which occupy large amounts of
+ * memory and may therefore be externalized.
*
- * By default, if the user specified so
- * in the flags for this object, the
- * triangulation is deleted and the
- * refinement history saved such that
- * the respective @p wake_up function can
- * rebuild it. You should therefore call
- * this function from your overloaded
- * version, preferably at the end so
- * that your function can use the
- * triangulation as long as ou need it.
+ * By default, if the user specified so in the flags for this object, the
+ * triangulation is deleted and the refinement history saved such that the
+ * respective @p wake_up function can rebuild it. You should therefore call
+ * this function from your overloaded version, preferably at the end so that
+ * your function can use the triangulation as long as ou need it.
*/
virtual void sleep (const unsigned int);
/**
- * Do the refinement according to the
- * flags passed to the constructor of this
- * object and the data passed to this
- * function. For a description of the
- * working of this function refer to the
- * general documentation of this class.
+ * Do the refinement according to the flags passed to the constructor of
+ * this object and the data passed to this function. For a description of
+ * the working of this function refer to the general documentation of this
+ * class.
*
- * In fact, this function does not
- * actually refine or coarsen the
- * triangulation, but only sets the
- * respective flags. This is done because
- * usually you will not need the grid
- * immediately afterwards but only
- * in the next sweep, so it suffices
- * to store the flags and rebuild it
- * the next time we need it. Also, it
- * may be that the next time step
- * would like to add or delete some
- * flags, so we have to wait anyway
- * with the use of this grid.
+ * In fact, this function does not actually refine or coarsen the
+ * triangulation, but only sets the respective flags. This is done because
+ * usually you will not need the grid immediately afterwards but only in the
+ * next sweep, so it suffices to store the flags and rebuild it the next
+ * time we need it. Also, it may be that the next time step would like to
+ * add or delete some flags, so we have to wait anyway with the use of this
+ * grid.
*/
void refine_grid (const RefinementData data);
/**
- * Respective init function for the
- * refinement loop; does nothing in
- * the default implementation, apart from
- * setting @p next_action to
- * @p grid_refinement but can
- * be overloaded.
+ * Respective init function for the refinement loop; does nothing in the
+ * default implementation, apart from setting @p next_action to @p
+ * grid_refinement but can be overloaded.
*/
virtual void init_for_refinement ();
/**
- * Virtual function that should fill
- * the vector with the refinement
- * criteria for the present triangulation.
- * It is used within the @p refine_grid
- * function to get the criteria for
- * the present time step, since they
- * can't be passed through its
- * argument when using the loop of
- * the time step management object.
+ * Virtual function that should fill the vector with the refinement criteria
+ * for the present triangulation. It is used within the @p refine_grid
+ * function to get the criteria for the present time step, since they can't
+ * be passed through its argument when using the loop of the time step
+ * management object.
*/
virtual void get_tria_refinement_criteria (Vector<float> &criteria) const = 0;
/**
- * The refinement
- * flags of the triangulation are stored
- * in a local variable thus allowing
- * a restoration. The coarsening flags
- * are also stored.
+ * The refinement flags of the triangulation are stored in a local variable
+ * thus allowing a restoration. The coarsening flags are also stored.
*/
void save_refine_flags ();
/**
- * Determine an estimate for the
- * memory consumption (in bytes)
- * of this object.
+ * Determine an estimate for the memory consumption (in bytes) of this
+ * object.
*
- * You will want to overload
- * this function in derived
- * classes to compute the
- * amount memory used by the
- * derived class, and add the
- * result of this function to
- * your result.
+ * You will want to overload this function in derived classes to compute the
+ * amount memory used by the derived class, and add the result of this
+ * function to your result.
*/
virtual std::size_t memory_consumption () const;
protected:
/**
- * Triangulation used at this
- * time level. Since this is
- * something that every time
- * stepping scheme needs to have,
- * we can safely put it into the
- * base class. Note that the
- * triangulation is frequently
- * deleted and rebuilt by the
- * functions @p sleep and
- * @p wake_up to save memory, if
- * such a behaviour is specified
- * in the @p flags structure.
+ * Triangulation used at this time level. Since this is something that every
+ * time stepping scheme needs to have, we can safely put it into the base
+ * class. Note that the triangulation is frequently deleted and rebuilt by
+ * the functions @p sleep and @p wake_up to save memory, if such a behaviour
+ * is specified in the @p flags structure.
*/
SmartPointer<Triangulation<dim, dim>,TimeStepBase_Tria<dim> > tria;
/**
- * Pointer to a grid which is to
- * be used as the coarse grid for
- * this time level. This pointer
- * is set through the
- * constructor; ownership remains
- * with the owner of this
- * management object.
+ * Pointer to a grid which is to be used as the coarse grid for this time
+ * level. This pointer is set through the constructor; ownership remains
+ * with the owner of this management object.
*/
SmartPointer<const Triangulation<dim, dim>,TimeStepBase_Tria<dim> > coarse_grid;
/**
- * Some flags about how this time level
- * shall behave. See the documentation
- * of this struct to find out more about
- * that.
+ * Some flags about how this time level shall behave. See the documentation
+ * of this struct to find out more about that.
*/
const Flags flags;
/**
- * Flags controlling the refinement
- * process; see the documentation of the
- * respective structure for more
- * information.
+ * Flags controlling the refinement process; see the documentation of the
+ * respective structure for more information.
*/
const RefinementFlags refinement_flags;
private:
/**
- * Vectors holding the refinement and
- * coarsening flags of the different
- * sweeps on this time level. The
- * vectors therefore hold the history
- * of the grid.
+ * Vectors holding the refinement and coarsening flags of the different
+ * sweeps on this time level. The vectors therefore hold the history of the
+ * grid.
*/
std::vector<std::vector<bool> > refine_flags;
std::vector<std::vector<bool> > coarsen_flags;
/**
- * Restore the grid according to the saved
- * data. For this, the coarse grid is
- * copied and the grid is stepwise
- * rebuilt using the saved flags.
+ * Restore the grid according to the saved data. For this, the coarse grid
+ * is copied and the grid is stepwise rebuilt using the saved flags.
*/
void restore_grid ();
};
* revolves around the question what the normal vector is. Consider the
* following situation:
*
- * <p ALIGN="center">
- * @image html no_normal_flux_1.png
- * </p>
+ * <p ALIGN="center"> @image html no_normal_flux_1.png </p>
*
* Here, we have two cells that use a bilinear mapping (i.e. MappingQ1).
* Consequently, for each of the cells, the normal vector is perpendicular
*
* Unfortunately, this is not quite enough. Consider the situation here:
*
- * <p ALIGN="center">
- * @image html no_normal_flux_2.png
- * </p>
+ * <p ALIGN="center"> @image html no_normal_flux_2.png </p>
*
* If again the top and right edges approximate a curved boundary, and the
* left boundary a separate boundary (for example straight) so that the
* we have considered above, is discretized with the following mesh, then we
* get into trouble:
*
- * <p ALIGN="center">
- * @image html no_normal_flux_3.png
- * </p>
+ * <p ALIGN="center"> @image html no_normal_flux_3.png </p>
*
* Here, the algorithm assumes that the boundary does not have a corner at
* the point where faces $F1$ and $F2$ join because at that point there are
* The situation is more complicated in 3d. Consider the following case
* where we want to compute the constraints at the marked vertex:
*
- * <p ALIGN="center">
- * @image html no_normal_flux_4.png
- * </p>
+ * <p ALIGN="center"> @image html no_normal_flux_4.png </p>
*
* Here, we get four different normal vectors, one from each of the four
* faces that meet at the vertex. Even though they may form a complete set
* on a circle and on a sphere to which the constraints computed by this
* function have been applied:
*
- * <p ALIGN="center">
- * @image html no_normal_flux_5.png
- * @image html no_normal_flux_6.png
- * </p>
+ * <p ALIGN="center"> @image html no_normal_flux_5.png @image html
+ * no_normal_flux_6.png </p>
*
* The vectors fields are not physically reasonable but the tangentiality
* constraint is clearly enforced. The fact that the vector fields are zero
* @param[in] fe_function A vector with nodal values representing the
* numerical approximation $u_h$. This vector needs to correspond to the
* finite element space represented by @p dof.
- * @param[in] exact_solution The exact solution that is used to compute
- * the error.
+ * @param[in] exact_solution The exact solution that is used to compute the
+ * error.
* @param[out] difference The vector of values $d_K$ computed as above.
* @param[in] q The quadrature formula used to approximate the integral
* shown above. Note that some quadrature formulas are more useful than
namespace internal
{
/**
- * Interpolate zero boundary values. We don't need to worry about a mapping
- * here because the function we evaluate for the DoFs is zero in the mapped
- * locations as well as in the original, unmapped locations
+ * Interpolate zero boundary values. We don't need to worry about a
+ * mapping here because the function we evaluate for the DoFs is zero in
+ * the mapped locations as well as in the original, unmapped locations
*/
template <class DH>
void
/**
- * Return whether the boundary values try to constrain a degree of
- * freedom that is already constrained to something else
+ * Return whether the boundary values try to constrain a degree of freedom
+ * that is already constrained to something else
*/
bool constraints_and_b_v_are_compatible (const ConstraintMatrix &constraints,
std::map<types::global_dof_index,double> &boundary_values)
namespace internal
{
/**
- * A structure that stores the dim DoF
- * indices that correspond to a
- * vector-valued quantity at a single
- * support point.
+ * A structure that stores the dim DoF indices that correspond to a
+ * vector-valued quantity at a single support point.
*/
template <int dim>
struct VectorDoFTuple
/**
- * Add the constraint
- * $\vec n \cdot \vec u = inhom$
- * to the list of constraints.
+ * Add the constraint $\vec n \cdot \vec u = inhom$ to the list of
+ * constraints.
*
- * Here, $\vec u$ is represented
- * by the set of given DoF
- * indices, and $\vec n$ by the
- * vector specified as the second
- * argument.
+ * Here, $\vec u$ is represented by the set of given DoF indices, and
+ * $\vec n$ by the vector specified as the second argument.
*
- * The function does not add constraints
- * if a degree of freedom is already
+ * The function does not add constraints if a degree of freedom is already
* constrained in the constraints object.
*/
template <int dim>
/**
- * Add the constraint $(\vec u-\vec u_\Gamma) \|
- * \vec t$ to the list of
- * constraints. In 2d, this is a
- * single constraint, in 3d these
- * are two constraints
+ * Add the constraint $(\vec u-\vec u_\Gamma) \| \vec t$ to the list of
+ * constraints. In 2d, this is a single constraint, in 3d these are two
+ * constraints
*
- * Here, $\vec u$ is represented
- * by the set of given DoF
- * indices, and $\vec t$ by the
- * vector specified as the second
- * argument.
+ * Here, $\vec u$ is represented by the set of given DoF indices, and
+ * $\vec t$ by the vector specified as the second argument.
*
- * The function does not add constraints
- * if a degree of freedom is already
+ * The function does not add constraints if a degree of freedom is already
* constrained in the constraints object.
*/
template <int dim>
/**
- * Given a vector, compute a set
- * of dim-1 vectors that are
- * orthogonal to the first one
- * and mutually orthonormal as
- * well.
+ * Given a vector, compute a set of dim-1 vectors that are orthogonal to
+ * the first one and mutually orthonormal as well.
*/
template <int dim>
void
namespace OpenCASCADE
{
/**
- * A Boundary object based on OpenCASCADE TopoDS_Shape where where
- * new points are first computed by averaging the surrounding points
- * in the same way as FlatManifold does, and are then projected in the
- * normal direction using OpenCASCADE utilities.
+ * A Boundary object based on OpenCASCADE TopoDS_Shape where where new
+ * points are first computed by averaging the surrounding points in the same
+ * way as FlatManifold does, and are then projected in the normal direction
+ * using OpenCASCADE utilities.
*
- * This class makes no assumptions on the shape you pass to it, and
- * the topological dimension of the Manifold is inferred from the
- * TopoDS_Shape itself. In debug mode there is a sanity check to
- * make sure that the surrounding points (the ones used in
- * project_to_manifold()) actually live on the Manifold, i.e.,
- * calling OpenCASCADE::closest_point() on those points leaves them
- * untouched. If this is not the case, an ExcPointNotOnManifold is
- * thrown.
+ * This class makes no assumptions on the shape you pass to it, and the
+ * topological dimension of the Manifold is inferred from the TopoDS_Shape
+ * itself. In debug mode there is a sanity check to make sure that the
+ * surrounding points (the ones used in project_to_manifold()) actually live
+ * on the Manifold, i.e., calling OpenCASCADE::closest_point() on those
+ * points leaves them untouched. If this is not the case, an
+ * ExcPointNotOnManifold is thrown.
*
- * This could happen, for example, if you are trying to use a shape
- * of type TopoDS_Edge when projecting on a face. In this case, the
- * vertices of the face would be collapsed to the edge, and your
- * surrounding points would not be lying on the given shape, raising
- * an exception.
+ * This could happen, for example, if you are trying to use a shape of type
+ * TopoDS_Edge when projecting on a face. In this case, the vertices of the
+ * face would be collapsed to the edge, and your surrounding points would
+ * not be lying on the given shape, raising an exception.
*
* @author Luca Heltai, Andrea Mola, 2011--2014.
*/
public:
/**
- * The standard constructor takes a generic TopoDS_Shape @p sh,
- * and a tolerance used to compute distances internally.
+ * The standard constructor takes a generic TopoDS_Shape @p sh, and a
+ * tolerance used to compute distances internally.
*
- * The TopoDS_Shape can be arbitrary, i.e., a collection of
- * shapes, faces, edges or a single face or edge.
+ * The TopoDS_Shape can be arbitrary, i.e., a collection of shapes, faces,
+ * edges or a single face or edge.
*/
NormalProjectionBoundary(const TopoDS_Shape &sh,
const double tolerance=1e-7);
/**
- * Perform the actual projection onto the manifold. This function,
- * in debug mode, checks that each of the @p surrounding_points is
- * within tolerance from the given TopoDS_Shape. If this is not
- * the case, an exception is thrown.
+ * Perform the actual projection onto the manifold. This function, in
+ * debug mode, checks that each of the @p surrounding_points is within
+ * tolerance from the given TopoDS_Shape. If this is not the case, an
+ * exception is thrown.
*
- * The projected point is computed using OpenCASCADE normal
- * projection algorithms.
+ * The projected point is computed using OpenCASCADE normal projection
+ * algorithms.
*/
virtual Point<spacedim>
project_to_manifold (const std::vector<Point<spacedim> > &surrounding_points,
private:
/**
- * The topological shape which is used internally to project
- * points. You can construct such a shape by calling the
- * OpenCASCADE::read_IGES() function, which will create a
- * TopoDS_Shape with the geometry contained in the IGES file.
+ * The topological shape which is used internally to project points. You
+ * can construct such a shape by calling the OpenCASCADE::read_IGES()
+ * function, which will create a TopoDS_Shape with the geometry contained
+ * in the IGES file.
*/
const TopoDS_Shape sh;
};
/**
- * A Boundary object based on OpenCASCADE TopoDS_Shape where new
- * points are first computed by averaging the surrounding points in
- * the same way as FlatManifold does, and then projecting them onto
- * the manifold along the direction specified at construction time
- * using OpenCASCADE utilities.
+ * A Boundary object based on OpenCASCADE TopoDS_Shape where new points are
+ * first computed by averaging the surrounding points in the same way as
+ * FlatManifold does, and then projecting them onto the manifold along the
+ * direction specified at construction time using OpenCASCADE utilities.
*
- * This class makes no assumptions on the shape you pass to it, and
- * the topological dimension of the Manifold is inferred from the
- * TopoDS_Shape itself. In debug mode there is a sanity check to
- * make sure that the surrounding points (the ones used in
- * project_to_manifold()) actually live on the Manifold, i.e.,
- * calling OpenCASCADE::closest_point() on those points leaves them
- * untouched. If this is not the case, an ExcPointNotOnManifold is
- * thrown.
+ * This class makes no assumptions on the shape you pass to it, and the
+ * topological dimension of the Manifold is inferred from the TopoDS_Shape
+ * itself. In debug mode there is a sanity check to make sure that the
+ * surrounding points (the ones used in project_to_manifold()) actually live
+ * on the Manifold, i.e., calling OpenCASCADE::closest_point() on those
+ * points leaves them untouched. If this is not the case, an
+ * ExcPointNotOnManifold is thrown.
*
- * Notice that this type of Boundary descriptor may fail to give
- * results if the triangulation to be refined is close to the
- * boundary of the given TopoDS_Shape, or when the direction you use
- * at construction time does not intersect the shape. An exception
- * is thrown when this happens.
+ * Notice that this type of Boundary descriptor may fail to give results if
+ * the triangulation to be refined is close to the boundary of the given
+ * TopoDS_Shape, or when the direction you use at construction time does not
+ * intersect the shape. An exception is thrown when this happens.
*
* @author Luca Heltai, Andrea Mola, 2011--2014.
*/
const double tolerance=1e-7);
/**
- * Perform the actual projection onto the manifold. This function,
- * in debug mode, checks that each of the @p surrounding_points is
- * within tolerance from the given TopoDS_Shape. If this is not
- * the case, an exception is thrown.
+ * Perform the actual projection onto the manifold. This function, in
+ * debug mode, checks that each of the @p surrounding_points is within
+ * tolerance from the given TopoDS_Shape. If this is not the case, an
+ * exception is thrown.
*
* The projected point is computed using OpenCASCADE directional
* projection algorithms.
private:
/**
- * The topological shape which is used internally to project
- * points. You can construct such a shape by calling the
- * OpenCASCADE::read_IGES() function, which will create a
- * TopoDS_Shape with the geometry contained in the IGES file.
+ * The topological shape which is used internally to project points. You
+ * can construct such a shape by calling the OpenCASCADE::read_IGES()
+ * function, which will create a TopoDS_Shape with the geometry contained
+ * in the IGES file.
*/
const TopoDS_Shape sh;
/**
- * A Boundary object based on OpenCASCADE TopoDS_Shape where new
- * points are first computed by averaging the surrounding points in
- * the same way as FlatManifold does, and then projecting them using
- * OpenCASCADE utilities onto the manifold along a direction which
- * is an estimation of the surrounding points (hence mesh cell)
- * normal.
+ * A Boundary object based on OpenCASCADE TopoDS_Shape where new points are
+ * first computed by averaging the surrounding points in the same way as
+ * FlatManifold does, and then projecting them using OpenCASCADE utilities
+ * onto the manifold along a direction which is an estimation of the
+ * surrounding points (hence mesh cell) normal.
*
- * The direction normal to the mesh is particularly useful because
- * it is the direction in which the mesh is missing nodes. For
- * instance, during the refinement of a cell a new node is initially
- * created around the baricenter of the cell. This location somehow
- * ensures a uniform distance from the nodes of the old cell.
- * Projecting such cell baricenter onto the CAD surface in the direction
- * normal to the original cell will then retain uniform distance from
- * the points of the original cell. Of course, at the stage of mesh
- * generation, no dof handler nor finite element are defined, and
- * such direction has to be estimated.
- * For the case in which 8 surrounding points are present, 4 different
- * triangles are identified with the points assigned, and the normals
- * of such triangles are averaged to obtain the approximation of
- * the normal to the cell.
+ * The direction normal to the mesh is particularly useful because it is the
+ * direction in which the mesh is missing nodes. For instance, during the
+ * refinement of a cell a new node is initially created around the
+ * baricenter of the cell. This location somehow ensures a uniform distance
+ * from the nodes of the old cell. Projecting such cell baricenter onto the
+ * CAD surface in the direction normal to the original cell will then retain
+ * uniform distance from the points of the original cell. Of course, at the
+ * stage of mesh generation, no dof handler nor finite element are defined,
+ * and such direction has to be estimated. For the case in which 8
+ * surrounding points are present, 4 different triangles are identified with
+ * the points assigned, and the normals of such triangles are averaged to
+ * obtain the approximation of the normal to the cell.
*
- * The case in which 2 surrounding points are present (i.e.:a cell
- * edge is being refined) is of course more tricky. The average of
- * the CAD surface normals at the 2 surrounding points is first
- * computed, and then projected onto the plane normal to the
- * segment linking the surrounding points. This again is an attempt
- * to have the new point with equal distance with respect to the
- * surrounding points
+ * The case in which 2 surrounding points are present (i.e.:a cell edge is
+ * being refined) is of course more tricky. The average of the CAD surface
+ * normals at the 2 surrounding points is first computed, and then projected
+ * onto the plane normal to the segment linking the surrounding points. This
+ * again is an attempt to have the new point with equal distance with
+ * respect to the surrounding points
*
- * This class only operates with CAD faces and makes the assumption
- * that the shape you pass to it contains at least one face. If that
- * is not the case, an Exception is thrown. In debug mode there is a
- * sanity check to make sure that the surrounding points (the ones
- * used in project_to_manifold()) actually live on the Manifold,
- * i.e., calling OpenCASCADE::closest_point() on those points leaves
- * them untouched. If this is not the case, an ExcPointNotOnManifold
- * is thrown.
+ * This class only operates with CAD faces and makes the assumption that the
+ * shape you pass to it contains at least one face. If that is not the case,
+ * an Exception is thrown. In debug mode there is a sanity check to make
+ * sure that the surrounding points (the ones used in project_to_manifold())
+ * actually live on the Manifold, i.e., calling OpenCASCADE::closest_point()
+ * on those points leaves them untouched. If this is not the case, an
+ * ExcPointNotOnManifold is thrown.
*
*
- * Notice that this type of Boundary descriptor may fail to give
- * results if the triangulation to be refined is close to the
- * boundary of the given TopoDS_Shape, or when the normal direction
- * estimated from the surrounding points does not intersect the
- * shape. An exception is thrown when this happens.
+ * Notice that this type of Boundary descriptor may fail to give results if
+ * the triangulation to be refined is close to the boundary of the given
+ * TopoDS_Shape, or when the normal direction estimated from the surrounding
+ * points does not intersect the shape. An exception is thrown when this
+ * happens.
*
* @author Luca Heltai, Andrea Mola, 2011--2014.
*/
public:
/**
* Construct a Boundary object which will project points on the
- * TopoDS_Shape @p sh, along a direction which is approximately
- * normal to the mesh cell.
+ * TopoDS_Shape @p sh, along a direction which is approximately normal to
+ * the mesh cell.
*/
NormalToMeshProjectionBoundary(const TopoDS_Shape &sh,
const double tolerance=1e-7);
/**
- * Perform the actual projection onto the manifold. This function,
- * in debug mode, checks that each of the @p surrounding_points is
- * within tolerance from the given TopoDS_Shape. If this is not
- * the case, an exception is thrown.
+ * Perform the actual projection onto the manifold. This function, in
+ * debug mode, checks that each of the @p surrounding_points is within
+ * tolerance from the given TopoDS_Shape. If this is not the case, an
+ * exception is thrown.
*/
virtual Point<spacedim>
project_to_manifold (const std::vector<Point<spacedim> > &surrounding_points,
private:
/**
- * The topological shape which is used internally to project
- * points. You can construct such a shape by calling the
- * OpenCASCADE::read_IGES() function, which will create a
- * TopoDS_Shape with the geometry contained in the IGES file.
+ * The topological shape which is used internally to project points. You
+ * can construct such a shape by calling the OpenCASCADE::read_IGES()
+ * function, which will create a TopoDS_Shape with the geometry contained
+ * in the IGES file.
*/
const TopoDS_Shape sh;
};
/**
- * A Boundary object based on OpenCASCADE TopoDS_Shape objects which
- * have topological dimension equal to one (TopoDS_Edge or
- * TopoDS_Wire) where new points are located at the arclength
- * average of the surrounding points. If the given TopoDS_Shape can
- * be casted to a periodic (closed) curve, then this information is
- * used internally to set the periodicity of the base ChartManifold
- * class.
+ * A Boundary object based on OpenCASCADE TopoDS_Shape objects which have
+ * topological dimension equal to one (TopoDS_Edge or TopoDS_Wire) where new
+ * points are located at the arclength average of the surrounding points. If
+ * the given TopoDS_Shape can be casted to a periodic (closed) curve, then
+ * this information is used internally to set the periodicity of the base
+ * ChartManifold class.
*
- * This class can only work on TopoDS_Edge or TopoDS_Wire objects,
- * and it only makes sense when spacedim is three. If you use an
- * object of topological dimension different from one, an exception
- * is throw.
+ * This class can only work on TopoDS_Edge or TopoDS_Wire objects, and it
+ * only makes sense when spacedim is three. If you use an object of
+ * topological dimension different from one, an exception is throw.
*
- * In debug mode there is an additional sanity check to make sure
- * that the surrounding points actually live on the Manifold, i.e.,
- * calling OpenCASCADE::closest_point() on those points leaves them
- * untouched. If this is not the case, an ExcPointNotOnManifold is
- * thrown.
+ * In debug mode there is an additional sanity check to make sure that the
+ * surrounding points actually live on the Manifold, i.e., calling
+ * OpenCASCADE::closest_point() on those points leaves them untouched. If
+ * this is not the case, an ExcPointNotOnManifold is thrown.
*
* @author Luca Heltai, Andrea Mola, 2011--2014.
*/
const double tolerance=1e-7);
/**
- * Given a point on real space, find its arclength
- * parameter. Throws an error in debug mode, if the point is not
- * on the TopoDS_Edge given at construction time.
+ * Given a point on real space, find its arclength parameter. Throws an
+ * error in debug mode, if the point is not on the TopoDS_Edge given at
+ * construction time.
*/
virtual Point<1>
pull_back(const Point<spacedim> &space_point) const;
private:
/**
- * A Curve adaptor. This is the one which is used in the
- * computations, and it points to the right one above.
+ * A Curve adaptor. This is the one which is used in the computations, and
+ * it points to the right one above.
*/
Handle_Adaptor3d_HCurve curve;
const double tolerance;
/**
- * The total length of the curve. This is also used as a period if
- * the edge is periodic.
+ * The total length of the curve. This is also used as a period if the
+ * edge is periodic.
*/
const double length;
};
DEAL_II_NAMESPACE_OPEN
/**
- * We collect in this namespace all utilities which operate on
- * OpenCASCADE entities. OpenCASCADE splits every object into a
- * topological description and a geometrical entity. The basic
- * topological description is a TopoDS_Shape. TopoDS_Shapes are light
- * objects, and can be copied around. The closest deal.II analog is a
- * TriaIterator.
+ * We collect in this namespace all utilities which operate on OpenCASCADE
+ * entities. OpenCASCADE splits every object into a topological description
+ * and a geometrical entity. The basic topological description is a
+ * TopoDS_Shape. TopoDS_Shapes are light objects, and can be copied around.
+ * The closest deal.II analog is a TriaIterator.
*
- * The OpenCASCADE topology is designed with reference to the STEP
- * standard ISO-10303-42. The structure is an oriented one-way graph,
- * where parents refer to their children, and there are no back
- * references. Abstract structure is implemented as C++ classes from
- * the TopoDS package. A TopoDS_Shape is manipulated by value and
- * contains 3 fields: location, orientation and a myTShape handle (of
- * the TopoDS_TShape type). According to OpenCASCADE documentation,
- * myTShape and Location are used to share data between various shapes
- * to save memory. For example, an edge belonging to two faces has
- * equal Locations and myTShape fields but different Orientations
- * (Forward in context of one face and Reversed in one of the other).
+ * The OpenCASCADE topology is designed with reference to the STEP standard
+ * ISO-10303-42. The structure is an oriented one-way graph, where parents
+ * refer to their children, and there are no back references. Abstract
+ * structure is implemented as C++ classes from the TopoDS package. A
+ * TopoDS_Shape is manipulated by value and contains 3 fields: location,
+ * orientation and a myTShape handle (of the TopoDS_TShape type). According to
+ * OpenCASCADE documentation, myTShape and Location are used to share data
+ * between various shapes to save memory. For example, an edge belonging to
+ * two faces has equal Locations and myTShape fields but different
+ * Orientations (Forward in context of one face and Reversed in one of the
+ * other).
*
- * Valid shapes include collection of other shapes, solids, faces,
- * edges, vertices, etc.
+ * Valid shapes include collection of other shapes, solids, faces, edges,
+ * vertices, etc.
*
- * Once a topological description is available, if a concrete
- * geometrical object can be created, the BRep classes allow one to
- * extract the actual geometrical information from a shape.
+ * Once a topological description is available, if a concrete geometrical
+ * object can be created, the BRep classes allow one to extract the actual
+ * geometrical information from a shape.
*
- * This is done by inheriting abstract topology classes from the
- * TopoDS package by those implementing a boundary representation
- * model (from the BRep package). Only 3 types of topological objects
- * have geometric representations – vertex, edge, and face.
+ * This is done by inheriting abstract topology classes from the TopoDS
+ * package by those implementing a boundary representation model (from the
+ * BRep package). Only 3 types of topological objects have geometric
+ * representations – vertex, edge, and face.
*
- * Every TopoDS_Shape can be queried to figure out what type of shape
- * it is, and actual geometrical objects, like surfaces, curves or
- * points, can be extracted using BRepTools.
+ * Every TopoDS_Shape can be queried to figure out what type of shape it is,
+ * and actual geometrical objects, like surfaces, curves or points, can be
+ * extracted using BRepTools.
*
- * In this namespace we provide readers and writers that read standard
- * CAD files, and return a TopoDS_Shape, or that write a CAD file,
- * given a TopoDS_Shape. Most of the functions in the OpenCASCADE
- * namespace deal with TopoDS_Shapes of one type or another, and
- * provide interfaces to common deal.II objects, like Triangulation,
- * Manifold, and so on.
+ * In this namespace we provide readers and writers that read standard CAD
+ * files, and return a TopoDS_Shape, or that write a CAD file, given a
+ * TopoDS_Shape. Most of the functions in the OpenCASCADE namespace deal with
+ * TopoDS_Shapes of one type or another, and provide interfaces to common
+ * deal.II objects, like Triangulation, Manifold, and so on.
*
- * Notice that these tools are only useful when spacedim is equal to
- * three, since OpenCASCADE only operates in three-dimensional mode.
+ * Notice that these tools are only useful when spacedim is equal to three,
+ * since OpenCASCADE only operates in three-dimensional mode.
*
* @author Luca Heltai, Andrea Mola, 2011--2014.
*/
namespace OpenCASCADE
{
/**
- * Count the subobjects of a shape. This function is useful to
- * gather information about the TopoDS_Shape passed as argument. It
- * returns the number of faces, edges and vertices (the only
- * topological entities associated with actual geometries) which are
- * contained in the given shape.
+ * Count the subobjects of a shape. This function is useful to gather
+ * information about the TopoDS_Shape passed as argument. It returns the
+ * number of faces, edges and vertices (the only topological entities
+ * associated with actual geometries) which are contained in the given
+ * shape.
*/
std_cxx11::tuple<unsigned int, unsigned int, unsigned int>
count_elements(const TopoDS_Shape &shape);
/**
- * Read IGES files and translate their content into openCascade
- * topological entities. The option scale_factor is used to
- * compensate for different units being used in the IGES files and
- * in the target application. The standard unit for IGES files is
- * millimiters. The return object is a TopoDS_Shape which contains
- * all objects from the file.
+ * Read IGES files and translate their content into openCascade topological
+ * entities. The option scale_factor is used to compensate for different
+ * units being used in the IGES files and in the target application. The
+ * standard unit for IGES files is millimiters. The return object is a
+ * TopoDS_Shape which contains all objects from the file.
*/
TopoDS_Shape read_IGES(const std::string &filename,
const double scale_factor=1e-3);
/**
- * Write the given topological shape into an IGES file.
- */
+ * Write the given topological shape into an IGES file.
+ */
void write_IGES(const TopoDS_Shape &shape,
const std::string &filename);
/**
- * Read STEP files and translate their content into openCascade
- * topological entities. The option scale_factor is used to
- * compensate for different units being used in the STEP files and
- * in the target application. The standard unit for STEP files is
- * millimiters. The return object is a TopoDS_Shape which contains
- * all objects from the file.
+ * Read STEP files and translate their content into openCascade topological
+ * entities. The option scale_factor is used to compensate for different
+ * units being used in the STEP files and in the target application. The
+ * standard unit for STEP files is millimiters. The return object is a
+ * TopoDS_Shape which contains all objects from the file.
*/
TopoDS_Shape read_STEP(const std::string &filename,
const double scale_factor=1e-3);
/**
- * Write the given topological shape into an STEP file.
- */
+ * Write the given topological shape into an STEP file.
+ */
void write_STEP(const TopoDS_Shape &shape,
const std::string &filename);
/**
- * This function returns the tolerance associated with the shape.
- * Each CAD geometrical object is defined along with a tolerance,
- * which indicates possible inaccuracy of its placement. For
- * instance, the tolerance of a vertex indicates that it can be
- * located in any point contained in a sphere centered in the
- * nominal position and having radius tol. While carrying out an
- * operation such as projecting a point onto a surface (which will
- * in turn have its tolerance) we must keep in mind that the
- * precision of the projection will be limited by the tolerance
- * with which the surface is built. The tolerance is computed
- * taking the maximum tolerance among the subshapes composing the
- * shape.
- */
+ * This function returns the tolerance associated with the shape. Each CAD
+ * geometrical object is defined along with a tolerance, which indicates
+ * possible inaccuracy of its placement. For instance, the tolerance of a
+ * vertex indicates that it can be located in any point contained in a
+ * sphere centered in the nominal position and having radius tol. While
+ * carrying out an operation such as projecting a point onto a surface
+ * (which will in turn have its tolerance) we must keep in mind that the
+ * precision of the projection will be limited by the tolerance with which
+ * the surface is built. The tolerance is computed taking the maximum
+ * tolerance among the subshapes composing the shape.
+ */
double get_shape_tolerance(const TopoDS_Shape &shape);
/**
- * Perform the intersection of the given topological shape with the
- * plane $c_x x + c_y y + c_z z +c = 0$. The returned topological
- * shape will contain as few bsplines as possible. An exception is
- * thrown if the intersection produces an empty shape.
+ * Perform the intersection of the given topological shape with the plane
+ * $c_x x + c_y y + c_z z +c = 0$. The returned topological shape will
+ * contain as few bsplines as possible. An exception is thrown if the
+ * intersection produces an empty shape.
*/
TopoDS_Shape intersect_plane(const TopoDS_Shape &in_shape,
const double c_x,
const double tolerance=1e-7);
/**
- * Try to join all edges contained in the given TopoDS_Shape into a
- * single TopoDS_Edge, containing as few BSPlines as possible. If
- * the input shape contains faces, they will be ignored by this
- * function. If the contained edges cannot be joined into a single
- * one, i.e., they form disconnected curves, an exception will be
- * thrown.
+ * Try to join all edges contained in the given TopoDS_Shape into a single
+ * TopoDS_Edge, containing as few BSPlines as possible. If the input shape
+ * contains faces, they will be ignored by this function. If the contained
+ * edges cannot be joined into a single one, i.e., they form disconnected
+ * curves, an exception will be thrown.
*/
TopoDS_Edge join_edges(const TopoDS_Shape &in_shape,
const double tolerance=1e-7);
/**
- * Creates a 3D smooth BSpline curve passing through the points in
- * the assigned vector, and store it in the returned TopoDS_Shape
- * (which is of type TopoDS_Edge). The points are reordered
- * internally according to their scalar product with the direction,
- * if direction is different from zero, otherwise they are used as
- * passed. Notice that this function changes the input points if
- * required by the algorithm.
+ * Creates a 3D smooth BSpline curve passing through the points in the
+ * assigned vector, and store it in the returned TopoDS_Shape (which is of
+ * type TopoDS_Edge). The points are reordered internally according to their
+ * scalar product with the direction, if direction is different from zero,
+ * otherwise they are used as passed. Notice that this function changes the
+ * input points if required by the algorithm.
*
- * This class is used to interpolate a BsplineCurve passing through
- * an array of points, with a C2 Continuity. If the optional
- * parameter @p closed is set to true, then the curve will be C2 at
- * all points except the first (where only C1 continuity will be
- * given), and it will be a closed curve.
+ * This class is used to interpolate a BsplineCurve passing through an array
+ * of points, with a C2 Continuity. If the optional parameter @p closed is
+ * set to true, then the curve will be C2 at all points except the first
+ * (where only C1 continuity will be given), and it will be a closed curve.
*
- * The curve is garanteed to be at distance @p tolerance from the
- * input points. If the algorithm fails in generating such a curve,
- * an exception is thrown.
+ * The curve is garanteed to be at distance @p tolerance from the input
+ * points. If the algorithm fails in generating such a curve, an exception
+ * is thrown.
*/
TopoDS_Edge interpolation_curve(std::vector<Point<3> > &curve_points,
const Tensor<1,3> &direction=Tensor<1,3>(),
const double tolerance=1e-7);
/**
- * Extract all subshapes from a TopoDS_Shape, and store the results
- * into standard containers. If the shape does not contain a certain
- * type of shape, the respective container will be empty.
+ * Extract all subshapes from a TopoDS_Shape, and store the results into
+ * standard containers. If the shape does not contain a certain type of
+ * shape, the respective container will be empty.
*/
void extract_geometrical_shapes(const TopoDS_Shape &shape,
std::vector<TopoDS_Face> &faces,
std::vector<TopoDS_Vertex> &vertices);
/**
- * Create a triangulation from a single face. This class extract the
- * first u and v parameter of the parametric surface making up this
- * face, and creates a Triangulation<2,3> containing a single coarse
- * cell reflecting this face. If the surface is not a trimmed
- * surface, the vertices of this cell will coincide with the
- * TopoDS_Vertex vertices of the original TopoDS_Face. This,
- * however, is often not the case, and the user should be careful on
- * how this mesh is used.
+ * Create a triangulation from a single face. This class extract the first u
+ * and v parameter of the parametric surface making up this face, and
+ * creates a Triangulation<2,3> containing a single coarse cell reflecting
+ * this face. If the surface is not a trimmed surface, the vertices of this
+ * cell will coincide with the TopoDS_Vertex vertices of the original
+ * TopoDS_Face. This, however, is often not the case, and the user should be
+ * careful on how this mesh is used.
*/
void create_triangulation(const TopoDS_Face &face,
Triangulation<2,3> &tria);
/**
- * Extract all compound shapes from a TopoDS_Shape, and store the
- * results into standard containers. If the shape does not contain a
- * certain type of compound, the respective container will be empty.
+ * Extract all compound shapes from a TopoDS_Shape, and store the results
+ * into standard containers. If the shape does not contain a certain type of
+ * compound, the respective container will be empty.
*/
void extract_compound_shapes(const TopoDS_Shape &shape,
std::vector<TopoDS_Compound> &compounds,
/**
* Project the point @p origin on the topological shape given by @p
- * in_shape, and returns the projected point, the subshape which
- * contains the point and the parametric u and v coordinates of the
- * point within the resulting shape. If the shape is not elementary,
- * all its subshapes are iterated, faces first, then edges, and the
- * returned shape is the closest one to the point @p origin. If the
- * returned shape is an edge, then only the u coordinate is filled
- * with sensible information, and the v coordinate is set to zero.
+ * in_shape, and returns the projected point, the subshape which contains
+ * the point and the parametric u and v coordinates of the point within the
+ * resulting shape. If the shape is not elementary, all its subshapes are
+ * iterated, faces first, then edges, and the returned shape is the closest
+ * one to the point @p origin. If the returned shape is an edge, then only
+ * the u coordinate is filled with sensible information, and the v
+ * coordinate is set to zero.
*
- * This function returns a tuple containing the projected point, the
- * shape, the u coordinate and the v coordinate (which is different
- * from zero only if the resulting shape is a face).
+ * This function returns a tuple containing the projected point, the shape,
+ * the u coordinate and the v coordinate (which is different from zero only
+ * if the resulting shape is a face).
*/
std_cxx11::tuple<Point<3>, TopoDS_Shape, double, double>
project_point_and_pull_back(const TopoDS_Shape &in_shape,
const double tolerance=1e-7);
/**
- * Return the projection of the point @p origin on the topological
- * shape given by @p in_shape. If the shape is not elementary, all
- * its subshapes are iterated, faces first, then edges, and the
- * returned point is the closest one to the @p in_shape, regardless
- * of its type.
+ * Return the projection of the point @p origin on the topological shape
+ * given by @p in_shape. If the shape is not elementary, all its subshapes
+ * are iterated, faces first, then edges, and the returned point is the
+ * closest one to the @p in_shape, regardless of its type.
*/
Point<3> closest_point(const TopoDS_Shape &in_shape,
const Point<3> &origin,
const double tolerance=1e-7);
/**
- * Given an elementary shape @p in_shape and the reference
- * coordinates within the shape, returns the corresponding point in
- * real space. If the shape is a TopoDS_Edge, the @p v coordinate is
- * ignored. Only edges or faces, as returned by the function
- * project_point_and_pull_back(), can be used as input to this
- * function. If this is not the case, an Exception is thrown.
+ * Given an elementary shape @p in_shape and the reference coordinates
+ * within the shape, returns the corresponding point in real space. If the
+ * shape is a TopoDS_Edge, the @p v coordinate is ignored. Only edges or
+ * faces, as returned by the function project_point_and_pull_back(), can be
+ * used as input to this function. If this is not the case, an Exception is
+ * thrown.
*/
Point<3> push_forward(const TopoDS_Shape &in_shape,
const double u,
/**
- * Given a TopoDS_Face @p face and the reference coordinates within
- * this face, returns the corresponding point in real space, the
- * normal to the surface at that point and the mean curvature as a
- * tuple.
+ * Given a TopoDS_Face @p face and the reference coordinates within this
+ * face, returns the corresponding point in real space, the normal to the
+ * surface at that point and the mean curvature as a tuple.
*/
std_cxx11::tuple<Point<3>, Point<3>, double >
push_forward_and_differential_forms(const TopoDS_Face &face,
/**
- * Get the closest point to the given topological shape, together
- * with the normal and the mean curvature at that point. If the
- * shape is not elementary, all its sub-faces (only the faces) are
- * iterated, faces first, and only the closest point is
- * returned. This function will throw an exception if the @p
- * in_shape does not contain at least one face.
+ * Get the closest point to the given topological shape, together with the
+ * normal and the mean curvature at that point. If the shape is not
+ * elementary, all its sub-faces (only the faces) are iterated, faces first,
+ * and only the closest point is returned. This function will throw an
+ * exception if the @p in_shape does not contain at least one face.
*/
std_cxx11::tuple<Point<3>, Point<3>, double>
closest_point_and_differential_forms(const TopoDS_Shape &in_shape,
/**
- * Intersect a line passing through the given @p origin point along
- * @p direction and the given topological shape. If there is more than
- * one intersection, it will return the closest one.
+ * Intersect a line passing through the given @p origin point along @p
+ * direction and the given topological shape. If there is more than one
+ * intersection, it will return the closest one.
*
* The optional @p tolerance parameter is used to compute distances.
*/
/**
- * Sort two points according to their scalar product with
- * direction. If the norm of the direction is zero, then use
- * lexicographical ordering. The optional parameter is used as a
- * relative tolerance when comparing objects.
+ * Sort two points according to their scalar product with direction. If the
+ * norm of the direction is zero, then use lexicographical ordering. The
+ * optional parameter is used as a relative tolerance when comparing
+ * objects.
*/
bool point_compare(const Point<3> &p1, const Point<3> &p2,
const Tensor<1,3> &direction=Tensor<1,3>(),
/**
- * Exception thrown when the point specified as argument does not
- * lie between @p tolerance from the given TopoDS_Shape.
+ * Exception thrown when the point specified as argument does not lie
+ * between @p tolerance from the given TopoDS_Shape.
*/
DeclException1 (ExcPointNotOnManifold,
Point<3>,
<<"The point [ "<<arg1<<" ] is not on the manifold.");
/**
- * Exception thrown when the point specified as argument cannot be
- * projected to the manifold.
+ * Exception thrown when the point specified as argument cannot be projected
+ * to the manifold.
*/
DeclException1 (ExcProjectionFailed,
Point<3>,
<< " ] failed.");
/**
- * Thrown when internal OpenCASCADE utilities fail to return the OK
- * status.
+ * Thrown when internal OpenCASCADE utilities fail to return the OK status.
*/
DeclException1 (ExcOCCError,
IFSelect_ReturnStatus,