Mesh Oriented datABase  (version 5.4.1)
Array-based unstructured mesh datastructure
DataCoupler.hpp
Go to the documentation of this file.
00001 /**
00002  * \class moab::DataCoupler
00003  *
00004  * \brief This class couples data between meshes.
00005  *
00006  * The coupler interpolates solution data at a set of points.  Data being interpolated resides on a
00007  * "source" mesh, in a tag or in vertex coords.  Applications calling this coupler send in entities,
00008  * and receive back data interpolated at those points.  Entities in the source mesh containing those
00009  * points do not have to reside on the same processor.
00010  *
00011  * To use, an application should:
00012  * - instantiate this DataCoupler by calling the constructor collectively on all processors in the
00013  * communicator
00014  * - call locate_points, which locates the points to be interpolated and (optionally) caches the
00015  * results in this class and SpatialLocator
00016  * - call interpolate, which does the interpolation
00017  *
00018  * Multiple interpolations (of multiple tags, or element-average vs. true interpolation) can be done
00019  * after locating the points.
00020  *
00021  * SpatialLocator is used for the spatial location portion of this work.
00022  *
00023  * This class is a next-generation implementation of Coupler.
00024  */
00025 #ifndef DATACOUPLER_HPP
00026 #define DATACOUPLER_HPP
00027 
00028 #include "moab/Range.hpp"
00029 #include "moab/Interface.hpp"
00030 
00031 #include <sstream>
00032 
00033 namespace moab
00034 {
00035 
00036 class ParallelComm;
00037 class SpatialLocator;
00038 
00039 class DataCoupler
00040 {
00041   public:
00042     enum Method
00043     {
00044         CONSTANT,
00045         LINEAR_FE,
00046         QUADRATIC_FE,
00047         SPECTRAL
00048     };
00049 
00050     enum IntegType
00051     {
00052         VOLUME
00053     };
00054 
00055     /* Constructor
00056      * Constructor, which also optionally initializes the coupler
00057      * \param source_ents Elements in the source mesh
00058      * \param coupler_id Id of this coupler, should be the same over all procs
00059      * \param pc ParallelComm object to be used with this coupler, representing the union
00060      *    of processors containing source and target meshes
00061      * \param init_locator If true, initializes a spatial locator inside the constructor
00062      * \param dim Dimension of entities to be coupled; if -1, get from source_elems
00063      */
00064     DataCoupler( Interface* impl,
00065                  Range& source_ents,
00066                  int coupler_id,
00067                  ParallelComm* pc  = NULL,
00068                  bool init_locator = true,
00069                  int dim           = -1 );
00070 
00071     /* Destructor
00072      */
00073     virtual ~DataCoupler();
00074 
00075     /* \brief Locate points on the source mesh
00076      * This is a pass-through function to SpatialLocator::locate_points
00077      * \param xyz Point locations (interleaved) being located
00078      * \param num_points Number of points in xyz
00079      * \param rel_iter_tol Relative tolerance for non-linear iteration
00080      * \param abs_iter_tol Relative tolerance for non-linear iteration, usually 10^-10 or so
00081      * \param inside_tol Tolerance of is_inside evaluation, usually 10^-6 or so
00082      * \param loc_results Tuple list containing the results; two types of results are possible,
00083      *      controlled by value of store_local parameter:
00084      *      store_local = true: each tuple T[j] consists of (p, i), p = proc with src element
00085      * containing point j (or 0 if serial), i = index in stored list (in SpatialLocator) on src proc
00086      *      store_local = false: each tuple T[j] consists of (p, ht, hs, pr[3]), where ht = target
00087      * mesh entity handle, hs = source mesh entity containing point (0 if not found), pr =
00088      * parameters in hs \param store_local If true, stores the located points on SpatialLocator
00089      */
00090     ErrorCode locate_points( double* xyz,
00091                              int num_points,
00092                              const double rel_iter_tol = 1.0e-10,
00093                              const double abs_iter_tol = 1.0e-10,
00094                              const double inside_tol   = 1.0e-6 );
00095 
00096     /* \brief Locate points on the source mesh
00097      * This is a pass-through function to SpatialLocator::locate_points
00098      * \param ents Target entities being located
00099      * \param rel_iter_tol Relative tolerance for non-linear iteration
00100      * \param abs_iter_tol Relative tolerance for non-linear iteration, usually 10^-10 or so
00101      * \param inside_tol Tolerance of is_inside evaluation, usually 10^-6 or so
00102      * \param loc_results Tuple list containing the results; two types of results are possible,
00103      *      controlled by value of store_local parameter:
00104      *      store_local = true: each tuple T[j] consists of (p, i), p = proc with src element
00105      * containing point j (or 0 if serial), i = index in stored list (in SpatialLocator) on src proc
00106      *      store_local = false: each tuple T[j] consists of (p, ht, hs, pr[3]), where ht = target
00107      * mesh entity handle, hs = source mesh entity containing point (0 if not found), pr =
00108      * parameters in hs \param store_local If true, stores the located points on SpatialLocator
00109      */
00110     ErrorCode locate_points( Range& ents,
00111                              const double rel_iter_tol = 1.0e-10,
00112                              const double abs_iter_tol = 1.0e-10,
00113                              const double inside_tol   = 1.0e-6 );
00114 
00115     /* \brief Interpolate data from the source mesh onto points
00116      * All entities/points or, if tuple_list is input, only those points
00117      * are interpolated from the source mesh.  Application should
00118      * allocate enough memory in interp_vals to hold interpolation results.
00119      *
00120      * If normalization is requested, technique used depends on the coupling
00121      * method.
00122      *
00123      * \param method Interpolation/normalization method
00124      * \param tag Tag on source mesh holding data to be interpolated
00125      * \param interp_vals Memory holding interpolated data; if NULL, data is written to same tag on
00126      * target ents \param point_indices If non-NULL, a set of indices of points input to
00127      *        locate_points at which to interpolate; if NULL, interpolates at all points
00128      *        input to locate_points
00129      * \param normalize If true, normalization is done according to method
00130      */
00131     ErrorCode interpolate( /*DataCoupler::Method*/ int method,
00132                            Tag tag,
00133                            double* interp_vals               = NULL,
00134                            std::vector< int >* point_indices = NULL,
00135                            bool normalize                    = true );
00136 
00137     /* \brief Interpolate data from the source mesh onto points
00138      * All entities/points or, if tuple_list is input, only those points
00139      * are interpolated from the source mesh.  Application should
00140      * allocate enough memory in interp_vals to hold interpolation results.
00141      *
00142      * If normalization is requested, technique used depends on the coupling
00143      * method.
00144      *
00145      * \param method Interpolation/normalization method
00146      * \param tag_name Tag name on source mesh holding data to be interpolated
00147      * \param interp_vals Memory holding interpolated data; if NULL, data is written to same tag on
00148      * target ents \param point_indices If non-NULL, a set of indices of points input to
00149      *        locate_points at which to interpolate; if NULL, interpolates at all points
00150      *        input to locate_points
00151      * \param normalize If true, normalization is done according to method
00152      */
00153     ErrorCode interpolate( /*DataCoupler::Method*/ int method,
00154                            const std::string& tag_name,
00155                            double* interp_vals               = NULL,
00156                            std::vector< int >* point_indices = NULL,
00157                            bool normalize                    = true );
00158 
00159     /* \brief Interpolate data from multiple tags
00160      * All entities/points or, if tuple_list is input, only those points
00161      * are interpolated from the source mesh.  Application should
00162      * allocate enough memory in interp_vals to hold interpolation results.
00163      *
00164      * In this variant, multiple tags, possibly with multiple interpolation
00165      * methods, are specified.  Sum of values in points_per_method should be
00166      * the number of points in tl or, if NULL, targetPts.
00167      *
00168      * If normalization is requested, technique used depends on the coupling
00169      * method.
00170      *
00171      * \param methods Vector of Interpolation/normalization methods
00172      * \param tag_names Names of tag being interpolated for each method
00173      * \param points_per_method Number of points for each method
00174      * \param num_methods Length of vectors in previous 3 arguments
00175      * \param interp_vals Memory holding interpolated data; if NULL, data is written to same tag on
00176      * target ents \param point_indices If non-NULL, a set of indices of points input to
00177      *        locate_points at which to interpolate; if NULL, interpolates at all points
00178      *        input to locate_points
00179      * \param normalize If true, normalization is done according to method
00180      */
00181     ErrorCode interpolate( /*DataCoupler::Method*/ int* methods,
00182                            const std::string* tag_names,
00183                            int* points_per_method,
00184                            int num_methods,
00185                            double* interp_vals               = NULL,
00186                            std::vector< int >* point_indices = NULL,
00187                            bool normalize                    = true );
00188 
00189     /* \brief Interpolate data from multiple tags
00190      * All entities/points or, if tuple_list is input, only those points
00191      * are interpolated from the source mesh.  Application should
00192      * allocate enough memory in interp_vals to hold interpolation results.
00193      *
00194      * In this variant, multiple tags, possibly with multiple interpolation
00195      * methods, are specified.  Sum of values in points_per_method should be
00196      * the number of points in tl or, if NULL, targetPts.
00197      *
00198      * If normalization is requested, technique used depends on the coupling
00199      * method.
00200      *
00201      * \param methods Vector of Interpolation/normalization methods
00202      * \param tag_names Names of tag being interpolated for each method
00203      * \param points_per_method Number of points for each method
00204      * \param num_methods Length of vectors in previous 3 arguments
00205      * \param interp_vals Memory holding interpolated data; if NULL, data is written to same tag on
00206      * target ents \param point_indices If non-NULL, a set of indices of points input to
00207      *        locate_points at which to interpolate; if NULL, interpolates at all points
00208      *        input to locate_points
00209      * \param normalize If true, normalization is done according to method
00210      */
00211     ErrorCode interpolate( /*DataCoupler::Method*/ int* methods,
00212                            Tag* tag_names,
00213                            int* points_per_method,
00214                            int num_methods,
00215                            double* interp_vals               = NULL,
00216                            std::vector< int >* point_indices = NULL,
00217                            bool normalize                    = true );
00218 
00219     /* Get functions */
00220     inline SpatialLocator* spatial_locator()
00221     {
00222         return myLocator;
00223     }
00224     inline int my_id() const
00225     {
00226         return myId;
00227     }
00228     inline const Range& target_ents() const
00229     {
00230         return targetEnts;
00231     }
00232     inline Range& target_ents()
00233     {
00234         return targetEnts;
00235     }
00236     inline int get_dim() const
00237     {
00238         return myDim;
00239     }
00240 
00241   private:
00242     /* \brief MOAB instance
00243      */
00244     Interface* mbImpl;
00245 
00246     /* \brief ParallelComm object for this coupler
00247      */
00248     ParallelComm* myPcomm;
00249 
00250     /* \brief SpatialLocator for local mesh
00251      */
00252     SpatialLocator* myLocator;
00253 
00254     /* \brief Id of this coupler
00255      */
00256     int myId;
00257 
00258     /* \brief Range of target entities
00259      */
00260     Range targetEnts;
00261 
00262     // Entity dimension
00263     int myDim;
00264 };
00265 
00266 inline ErrorCode DataCoupler::interpolate( /*DataCoupler::Method*/ int method,
00267                                            Tag tag,
00268                                            double* interp_vals,
00269                                            std::vector< int >* point_indices,
00270                                            bool normalize )
00271 {
00272     // No point indices input,
00273     int num_pts = ( point_indices ? point_indices->size() : targetEnts.size() );
00274     return interpolate( &method, &tag, &num_pts, 1, interp_vals, point_indices, normalize );
00275 }
00276 
00277 }  // namespace moab
00278 
00279 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines