* weighting function on the old Triangulation and connect it to the new one.
*
* @note A hp::FECollection needs to be attached to your DoFHandler object via
- * DoFHandler::distribute_dofs() <em>once before</em> the
+ * DoFHandler::distribute_dofs() <em>before</em> the
* Triangulation::Signals::weight signal will be triggered. Otherwise,
* your DoFHandler does not know many degrees of freedom your cells have. In
* other words, you need to call DoFHandler::distribute_dofs() once before you
private:
/**
- * A connection to the corresponding weight signal of the Triangulation
+ * A connection to the corresponding `weight` signal of the Triangulation
* which is attached to the DoFHandler.
*/
boost::signals2::connection connection;
/**
- * A callback function that will be connected to the weight signal of
+ * A callback function that will be connected to the `weight` signal of
* the @p triangulation, to which the @p dof_handler is attached. Ultimately
* returns the weight for each cell, determined by the @p weighting_function
* provided as a parameter. Returns zero if @p dof_handler has not been
* @note This function by default partitions the mesh in such a way that
* the number of cells on all processors is roughly equal. If you want
* to set weights for partitioning, e.g. because some cells are more
- * expensive to compute than others, you can use the signal weight
+ * expensive to compute than others, you can use the signal `weight`
* as documented in the dealii::Triangulation class. This function will
* check whether a function is connected to the signal and if so use it.
* If you prefer to repartition the mesh yourself at user-defined
* flag to the constructor, which ensures that calling the current
* function only refines and coarsens the triangulation, but doesn't
* partition it. You can then call the repartition() function manually.
- * The usage of the weight signal is identical in both cases, if a
+ * The usage of the `weight` signal is identical in both cases, if a
* function is connected to the signal it will be used to balance the
* calculated weights, otherwise the number of cells is balanced.
*/
* the same way as execute_coarsening_and_refinement() with respect to
* dealing with data movement (SolutionTransfer, etc.).
*
- * @note If no function is connected to the weight signal described
+ * @note If no function is connected to the `weight` signal described
* in the dealii::Triangulation class, this function will balance the
* number of cells on each processor. If one or more functions are
* connected, it will calculate the sum of the weights and balance the
* single-partition case without packages installed, and only requires them
* installed when multiple partitions are required.
*
- * @note If the @p weight signal has been attached to the @p triangulation,
+ * @note If the `weight` signal has been attached to the @p triangulation,
* then this will be used and passed to the partitioner.
*/
template <int dim, int spacedim>
* case like this, partitioning algorithm may sometimes make bad decisions and
* you may want to build your own connectivity graph.
*
- * @note If the @p weight signal has been attached to the @p triangulation,
+ * @note If the `weight` signal has been attached to the @p triangulation,
* then this will be used and passed to the partitioner.
*/
template <int dim, int spacedim>
};
/**
- * A structure used to accumulate the results of the weight signal slot
+ * A structure used to accumulate the results of the `weight` signal slot
* functions below. It takes an iterator range and returns the sum of
* values.
*/
/**
* This signal is triggered for each cell during every automatic or manual
- * repartitioning. This signal will only be triggered if functions
- * are connected to it. It is intended to allow a weighted repartitioning
+ * repartitioning. It is intended to allow a weighted repartitioning
* of the domain to balance the computational load across processes in a
* different way than balancing the number of cells. Any connected
* function is expected to take an iterator to a cell, and a CellStatus
* refinement. If this cell is going to be coarsened, the signal is called
* for the parent cell and you need to provide the weight of the future
* parent cell. If this cell is going to be refined, the function is called
- * on all children and you should ideally return the same weight for all
- * children.
+ * on all children while `cell_iterator` refers to their parent cell. In
+ * this case, you need to pick a weight for each individual child based on
+ * information given by the parent cell.
*
* If several functions are connected to this signal, their return values
- * will be summed to calculate the final weight via `CellWeightSum`.
+ * will be summed to calculate the final weight of a cell. This allows
+ * different parts of a larger code base to have their own functions
+ * computing the weight of a cell; for example in a code that does both
+ * finite element and particle computations on each cell, the code could
+ * separate the computation of a cell's weight into two functions, each
+ * implemented in their respective files, that provide the finite
+ * element-based and the particle-based weights.
*
- * This function is used in step-68 and implicitely in step-75 using the
+ * This function is used in step-68 and implicitly in step-75 using the
* parallel::CellWeights class.
*/
boost::signals2::signal<unsigned int(const cell_iterator &,
/**
* @copydoc weight
*
- * As a reference a value of 1000 is added for every cell to the total
+ * As a reference, a value of 1000 is added for every cell to the total
* weight. This means a signal return value of 1000 (resulting in a weight
* of 2000) means that it is twice as expensive for a process to handle this
* particular cell.
*
- * @deprecated Use the weight signal instead which omits the base weight.
+ * @deprecated Use the `weight` signal instead which omits the base weight.
* You can invoke the old behavior by connecting a function to the signal
- * that returns the base weight like this:
+ * that returns the base weight as follows. This function should be added
+ * <em>in addition</em> to the one that actually computes the weight.
* @code{.cc}
* triangulation.signals.weight.connect(
* [](const typename Triangulation<dim>::cell_iterator &,
projects / dealii.git / commitdiff