DataCoupler.hpp

Go to the documentation of this file.

/**
 * \class moab::DataCoupler
 *
 * \brief This class couples data between meshes.
 *
 * The coupler interpolates solution data at a set of points. Data being interpolated resides on a
 * "source" mesh, in a tag or in vertex coords. Applications calling this coupler send in entities,
 * and receive back data interpolated at those points. Entities in the source mesh containing those
 * points do not have to reside on the same processor.
 *
 * To use, an application should:
 * - instantiate this DataCoupler by calling the constructor collectively on all processors in the
 * communicator
 * - call locate_points, which locates the points to be interpolated and (optionally) caches the
 * results in this class and SpatialLocator
 * - call interpolate, which does the interpolation
 *
 * Multiple interpolations (of multiple tags, or element-average vs. true interpolation) can be done
 * after locating the points.
 *
 * SpatialLocator is used for the spatial location portion of this work.
 *
 * This class is a next-generation implementation of Coupler.
 */
#ifndef DATACOUPLER_HPP
#define DATACOUPLER_HPP
 
#include "moab/Range.hpp"
#include "moab/Interface.hpp"
 
#include <sstream>
 
namespace moab
{
 
class ParallelComm;
class SpatialLocator;
 
class DataCoupler
{
 public:
 enum Method
 {
 CONSTANT,
 LINEAR_FE,
 QUADRATIC_FE,
 SPECTRAL
 };
 
 enum IntegType
 {
 VOLUME
 };
 
 /* Constructor
 * Constructor, which also optionally initializes the coupler
 * \param source_ents Elements in the source mesh
 * \param coupler_id Id of this coupler, should be the same over all procs
 * \param pc ParallelComm object to be used with this coupler, representing the union
 * of processors containing source and target meshes
 * \param init_locator If true, initializes a spatial locator inside the constructor
 * \param dim Dimension of entities to be coupled; if -1, get from source_elems
 */
 DataCoupler( Interface* impl,
 Range& source_ents,
 int coupler_id,
 ParallelComm* pc = NULL,
 bool init_locator = true,
 int dim = -1 );
 
 /* Destructor
 */
 virtual ~DataCoupler();
 
 /* \brief Locate points on the source mesh
 * This is a pass-through function to SpatialLocator::locate_points
 * \param xyz Point locations (interleaved) being located
 * \param num_points Number of points in xyz
 * \param rel_iter_tol Relative tolerance for non-linear iteration
 * \param abs_iter_tol Relative tolerance for non-linear iteration, usually 10^-10 or so
 * \param inside_tol Tolerance of is_inside evaluation, usually 10^-6 or so
 * \param loc_results Tuple list containing the results; two types of results are possible,
 * controlled by value of store_local parameter:
 * store_local = true: each tuple T[j] consists of (p, i), p = proc with src element
 * containing point j (or 0 if serial), i = index in stored list (in SpatialLocator) on src proc
 * store_local = false: each tuple T[j] consists of (p, ht, hs, pr[3]), where ht = target
 * mesh entity handle, hs = source mesh entity containing point (0 if not found), pr =
 * parameters in hs \param store_local If true, stores the located points on SpatialLocator
 */
 ErrorCode locate_points( double* xyz,
 int num_points,
 const double rel_iter_tol = 1.0e-10,
 const double abs_iter_tol = 1.0e-10,
 const double inside_tol = 1.0e-6 );
 
 /* \brief Locate points on the source mesh
 * This is a pass-through function to SpatialLocator::locate_points
 * \param ents Target entities being located
 * \param rel_iter_tol Relative tolerance for non-linear iteration
 * \param abs_iter_tol Relative tolerance for non-linear iteration, usually 10^-10 or so
 * \param inside_tol Tolerance of is_inside evaluation, usually 10^-6 or so
 * \param loc_results Tuple list containing the results; two types of results are possible,
 * controlled by value of store_local parameter:
 * store_local = true: each tuple T[j] consists of (p, i), p = proc with src element
 * containing point j (or 0 if serial), i = index in stored list (in SpatialLocator) on src proc
 * store_local = false: each tuple T[j] consists of (p, ht, hs, pr[3]), where ht = target
 * mesh entity handle, hs = source mesh entity containing point (0 if not found), pr =
 * parameters in hs \param store_local If true, stores the located points on SpatialLocator
 */
 ErrorCode locate_points( Range& ents,
 const double rel_iter_tol = 1.0e-10,
 const double abs_iter_tol = 1.0e-10,
 const double inside_tol = 1.0e-6 );
 
 /* \brief Interpolate data from the source mesh onto points
 * All entities/points or, if tuple_list is input, only those points
 * are interpolated from the source mesh. Application should
 * allocate enough memory in interp_vals to hold interpolation results.
 *
 * If normalization is requested, technique used depends on the coupling
 * method.
 *
 * \param method Interpolation/normalization method
 * \param tag Tag on source mesh holding data to be interpolated
 * \param interp_vals Memory holding interpolated data; if NULL, data is written to same tag on
 * target ents \param point_indices If non-NULL, a set of indices of points input to
 * locate_points at which to interpolate; if NULL, interpolates at all points
 * input to locate_points
 * \param normalize If true, normalization is done according to method
 */
 ErrorCode interpolate( /*DataCoupler::Method*/ int method,
 Tag tag,
 double* interp_vals = NULL,
 std::vector< int >* point_indices = NULL,
 bool normalize = true );
 
 /* \brief Interpolate data from the source mesh onto points
 * All entities/points or, if tuple_list is input, only those points
 * are interpolated from the source mesh. Application should
 * allocate enough memory in interp_vals to hold interpolation results.
 *
 * If normalization is requested, technique used depends on the coupling
 * method.
 *
 * \param method Interpolation/normalization method
 * \param tag_name Tag name on source mesh holding data to be interpolated
 * \param interp_vals Memory holding interpolated data; if NULL, data is written to same tag on
 * target ents \param point_indices If non-NULL, a set of indices of points input to
 * locate_points at which to interpolate; if NULL, interpolates at all points
 * input to locate_points
 * \param normalize If true, normalization is done according to method
 */
 ErrorCode interpolate( /*DataCoupler::Method*/ int method,
 const std::string& tag_name,
 double* interp_vals = NULL,
 std::vector< int >* point_indices = NULL,
 bool normalize = true );
 
 /* \brief Interpolate data from multiple tags
 * All entities/points or, if tuple_list is input, only those points
 * are interpolated from the source mesh. Application should
 * allocate enough memory in interp_vals to hold interpolation results.
 *
 * In this variant, multiple tags, possibly with multiple interpolation
 * methods, are specified. Sum of values in points_per_method should be
 * the number of points in tl or, if NULL, targetPts.
 *
 * If normalization is requested, technique used depends on the coupling
 * method.
 *
 * \param methods Vector of Interpolation/normalization methods
 * \param tag_names Names of tag being interpolated for each method
 * \param points_per_method Number of points for each method
 * \param num_methods Length of vectors in previous 3 arguments
 * \param interp_vals Memory holding interpolated data; if NULL, data is written to same tag on
 * target ents \param point_indices If non-NULL, a set of indices of points input to
 * locate_points at which to interpolate; if NULL, interpolates at all points
 * input to locate_points
 * \param normalize If true, normalization is done according to method
 */
 ErrorCode interpolate( /*DataCoupler::Method*/ int* methods,
 const std::string* tag_names,
 int* points_per_method,
 int num_methods,
 double* interp_vals = NULL,
 std::vector< int >* point_indices = NULL,
 bool normalize = true );
 
 /* \brief Interpolate data from multiple tags
 * All entities/points or, if tuple_list is input, only those points
 * are interpolated from the source mesh. Application should
 * allocate enough memory in interp_vals to hold interpolation results.
 *
 * In this variant, multiple tags, possibly with multiple interpolation
 * methods, are specified. Sum of values in points_per_method should be
 * the number of points in tl or, if NULL, targetPts.
 *
 * If normalization is requested, technique used depends on the coupling
 * method.
 *
 * \param methods Vector of Interpolation/normalization methods
 * \param tag_names Names of tag being interpolated for each method
 * \param points_per_method Number of points for each method
 * \param num_methods Length of vectors in previous 3 arguments
 * \param interp_vals Memory holding interpolated data; if NULL, data is written to same tag on
 * target ents \param point_indices If non-NULL, a set of indices of points input to
 * locate_points at which to interpolate; if NULL, interpolates at all points
 * input to locate_points
 * \param normalize If true, normalization is done according to method
 */
 ErrorCode interpolate( /*DataCoupler::Method*/ int* methods,
 Tag* tag_names,
 int* points_per_method,
 int num_methods,
 double* interp_vals = NULL,
 std::vector< int >* point_indices = NULL,
 bool normalize = true );
 
 /* Get functions */
 inline SpatialLocator* spatial_locator()
 {
 return myLocator;
 }
 inline int my_id() const
 {
 return myId;
 }
 inline const Range& target_ents() const
 {
 return targetEnts;
 }
 inline Range& target_ents()
 {
 return targetEnts;
 }
 inline int get_dim() const
 {
 return myDim;
 }
 
 private:
 /* \brief MOAB instance
 */
 Interface* mbImpl;
 
 /* \brief ParallelComm object for this coupler
 */
 ParallelComm* myPcomm;
 
 /* \brief SpatialLocator for local mesh
 */
 SpatialLocator* myLocator;
 
 /* \brief Id of this coupler
 */
 int myId;
 
 /* \brief Range of target entities
 */
 Range targetEnts;
 
 // Entity dimension
 int myDim;
};
 
inline ErrorCode DataCoupler::interpolate( /*DataCoupler::Method*/ int method,
 Tag tag,
 double* interp_vals,
 std::vector< int >* point_indices,
 bool normalize )
{
 // No point indices input,
 int num_pts = ( point_indices ? point_indices->size() : targetEnts.size() );
 return interpolate( &method, &tag, &num_pts, 1, interp_vals, point_indices, normalize );
}
 
} // namespace moab
 
#endif