// ------------------------------------------------------------------------ // // SPDX-License-Identifier: LGPL-2.1-or-later // Copyright (C) 2019 - 2024 by the deal.II authors // // This file is part of the deal.II library. // // Part of the source code is dual licensed under Apache-2.0 WITH // LLVM-exception OR LGPL-2.1-or-later. Detailed license information // governing the source code and code contributions can be found in // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II. // // ------------------------------------------------------------------------ #ifndef dealii_distributed_cell_data_transfer_h #define dealii_distributed_cell_data_transfer_h #include #include #include #include #include #include DEAL_II_NAMESPACE_OPEN namespace parallel { namespace distributed { /** * Transfer data that is associated with each active cell (like error * indicators) while refining and/or coarsening a distributed triangulation * and handle the necessary communication. * * This class therefore does for cell-related information what * parallel::distributed::SolutionTransfer does for the values of degrees of * freedom defined on a parallel::distributed::Triangulation. * * This class has been designed to operate on any kind of datatype that is * serializable. A non-distributed container (like Vector or `std::vector`) * has to be provided, which holds the cell-wise data in the same order as * active cells are traversed. In other words, each entry corresponds to the * cell with the same index CellAccessor::active_cell_index(), and the * container has to be of size Triangulation::n_active_cells(). * *

Transferring cell-wise data

* * The following code snippet demonstrates how to transfer cell-related data * across refinement/coarsening of the registered triangulation. * * @code * // prepare the triangulation, * triangulation.prepare_coarsening_and_refinement(); * * // prepare the CellDataTransfer object for coarsening and refinement * // and give the cell data vector that we intend to unpack later, * Vector data_to_transfer(triangulation.n_active_cells()); * //[fill data_to_transfer with cell-wise values...] * * parallel::distributed::CellDataTransfer> * cell_data_trans(triangulation); * cell_data_trans.prepare_for_coarsening_and_refinement(data_to_transfer); * * // actually execute the refinement, * triangulation.execute_coarsening_and_refinement(); * * // unpack transferred data, * Vector transferred_data(triangulation.n_active_cells()); * cell_data_trans.unpack(transferred_data); * * @endcode * * *

Use for serialization

* * This class can be used to serialize and later deserialize a distributed * mesh with attached data to separate files. * * For serialization, the following code snippet saves not only the * triangulation itself, but also the cell-wise data attached: * @code * Vector data_to_transfer(triangulation.n_active_cells()); * //[fill data_to_transfer with cell-wise values...] * * parallel::distributed::CellDataTransfer> * cell_data_trans(triangulation); * cell_data_trans.prepare_for_serialization(data_to_transfer); * * triangulation.save(filename); * @endcode * * Later, during deserialization, both triangulation and data can be * restored as follows: * @code * //[create coarse mesh...] * triangulation.load(filename); * * parallel::distributed::CellDataTransfer> * cell_data_trans(triangulation); * Vector transferred_data(triangulation.n_active_cells()); * cell_data_trans.deserialize(transferred_data); * @endcode * * @note If you use more than one object to transfer data via the * parallel::distributed::Triangulation::register_data_attach() and * parallel::distributed::Triangulation::notify_ready_for_unpack() interface * with the aim of serialization, the calls to the corresponding * prepare_for_serialization() and deserialize() functions need to happen in * the same order, respectively. Classes relying on this interface are e.g. * parallel::distributed::CellDataTransfer, * parallel::distributed::SolutionTransfer, and Particles::ParticleHandler. * * @note See the documentation of parallel::distributed::SolutionTransfer for * matching code snippets for both transfer and serialization. * * @ingroup distributed */ template > class CellDataTransfer { private: /** * An alias that defines the data type of provided container template. */ using value_type = typename VectorType::value_type; public: /** * Constructor. * * @param[in] triangulation The triangulation on which all operations will * happen. At the time when this constructor is called, the refinement * in question has not happened yet. * @param[in] transfer_variable_size_data Specify whether your VectorType * container stores values that differ in size. A varying amount of data * may be packed per cell, if for example the underlying ValueType of * the VectorType container is a container itself. * @param[in] refinement_strategy %Function deciding how data will be * stored on refined cells from its parent cell. * @param[in] coarsening_strategy %Function deciding which data to store * on a cell whose children will get coarsened into. */ CellDataTransfer( const parallel::distributed::Triangulation &triangulation, const bool transfer_variable_size_data = false, const std::function( const typename dealii::Triangulation::cell_iterator &parent, const value_type parent_value)> refinement_strategy = &dealii::AdaptationStrategies::Refinement:: preserve, const std::function::cell_iterator &parent, const std::vector &children_values)> coarsening_strategy = &dealii::AdaptationStrategies::Coarsening:: check_equality); /** * Prepare the current object for coarsening and refinement. * * It registers the data transfer of @p in on the underlying triangulation. * @p in includes data to be interpolated onto the new (refined and/or * coarsened) grid. See documentation of this class for more information * on how to use this functionality. * * This function can be called only once for the specified container * until data transfer has been completed. If multiple vectors shall be * transferred via this class, use the function below. */ void prepare_for_coarsening_and_refinement(const VectorType &in); /** * Same as the function above, only for a list of vectors. */ void prepare_for_coarsening_and_refinement( const std::vector &all_in); /** * Prepare the serialization of the given vector. * * The serialization is done by Triangulation::save(). See documentation * of this class for more information on how to use this functionality. * * This function can be called only once for the specified container * until data transfer has been completed. If multiple vectors shall be * transferred via this class, use the function below. */ void prepare_for_serialization(const VectorType &in); /** * Same as the function above, only for a list of vectors. */ void prepare_for_serialization(const std::vector &all_in); /** * Unpack the information previously stored in this object before * the mesh was refined or coarsened onto the current set of cells. */ void unpack(VectorType &out); /** * Same as the function above, only for a list of vectors. */ void unpack(std::vector &all_out); /** * Execute the deserialization of the stored information. * This needs to be done after calling Triangulation::load(). */ void deserialize(VectorType &out); /** * Same as the function above, only for a list of vectors. */ void deserialize(std::vector &all_out); private: /** * Pointer to the triangulation to work with. */ ObserverPointer, CellDataTransfer> triangulation; /** * Specifies if size of data to transfer varies from cell to cell. */ const bool transfer_variable_size_data; /** * %Function deciding how data will be stored on refined cells from its * parent cell. */ const std::function( const typename Triangulation::cell_iterator &parent, const value_type parent_value)> refinement_strategy; /** * %Function deciding on how to process data from children to be stored on * the parent cell. */ const std::function::cell_iterator &parent, const std::vector &children_values)> coarsening_strategy; /** * A vector that stores pointers to all the vectors we are supposed to * copy over from the old to the new mesh. */ std::vector input_vectors; /** * The handle that triangulation has assigned to this object * with which we can access our memory offset and our pack function. */ unsigned int handle; /** * Registers the pack_callback() function to the triangulation * and stores the returning handle. */ void register_data_attach(); /** * A callback function used to pack the data on the current mesh into * objects that can later be retrieved after refinement, coarsening and * repartitioning. */ std::vector pack_callback(const typename parallel::distributed:: Triangulation::cell_iterator &cell, const CellStatus status); /** * 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 parallel::distributed::Triangulation:: cell_iterator &cell, const CellStatus status, const boost::iterator_range::const_iterator> &data_range, std::vector &all_out); }; } // namespace distributed } // namespace parallel DEAL_II_NAMESPACE_CLOSE #endif /* dealii_distributed_cell_data_transfer_h */