XdmfMap.hpp 13.7 KB
Newer Older
Kenneth Leiter's avatar
Kenneth Leiter committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
/*****************************************************************************/
/*                                    XDMF                                   */
/*                       eXtensible Data Model and Format                    */
/*                                                                           */
/*  Id : XdmfMap.hpp                                                         */
/*                                                                           */
/*  Author:                                                                  */
/*     Kenneth Leiter                                                        */
/*     kenneth.leiter@arl.army.mil                                           */
/*     US Army Research Laboratory                                           */
/*     Aberdeen Proving Ground, MD                                           */
/*                                                                           */
/*     Copyright @ 2011 US Army Research Laboratory                          */
/*     All Rights Reserved                                                   */
/*     See Copyright.txt for details                                         */
/*                                                                           */
/*     This software is distributed WITHOUT ANY WARRANTY; without            */
/*     even the implied warranty of MERCHANTABILITY or FITNESS               */
/*     FOR A PARTICULAR PURPOSE.  See the above copyright notice             */
/*     for more information.                                                 */
/*                                                                           */
/*****************************************************************************/

24 25 26
#ifndef XDMFMAP_HPP_
#define XDMFMAP_HPP_

27 28 29 30 31 32
// C Compatible Includes
#include "Xdmf.hpp"
#include "XdmfItem.hpp"

#ifdef __cplusplus

33
// Forward Declarations
34
class XdmfArray;
35
class XdmfAttribute;
36
class XdmfHeavyDataController;
37 38 39

// Includes

40 41
#include <set>

42
/**
43 44
 * @brief Boundary communicator map for partitioned spatial
 * collections.
45
 *
46 47 48
 * Provides mechanism for mapping nodes across partition
 * boundaries. Each partitioned grid contains its own map, mapping its
 * own nodes to all other nodes in the global system.
49 50 51
 *
 * There are two methods for constructing XdmfMaps:
 *
52 53 54
 * Calling New() with no parameters will construct an empty map. The
 * map can be filled manually with subsequent insert commands.
 *
55
 * Calling New(const std::vector<shared_ptr<XdmfAttribute> > &
56 57 58 59
 * globalNodeIds) will construct XdmfMaps for each grid in an entire
 * global system. Each entry in the vector contains the globalNodeIds
 * for that partition. The constructor accepts global node ids for
 * each partition to construct the proper XdmfMaps.
60
 */
61
class XDMF_EXPORT XdmfMap : public XdmfItem {
62

63
public:
64

65 66 67 68
  typedef int node_id;
  typedef int task_id;
  typedef std::map<node_id, std::set<node_id> > node_id_map;

69 70 71
  /**
   * Create a new XdmfMap.
   *
72 73 74 75
   * Example of use:
   *
   * C++
   *
76
   * @dontinclude ExampleXdmfMap.cpp
77 78
   * @skipline //#initialization
   * @until //#initialization
79 80 81
   *
   * Python
   *
82
   * @dontinclude XdmfExampleMap.py
83 84
   * @skipline #//initialization
   * @until #//initialization
85
   *
86
   * @return    Constructed XdmfMap.
87
   */
88
  static shared_ptr<XdmfMap> New();
89 90

  /**
91 92 93
   * Create XdmfMaps for each grid in a domain decomposed mesh. Each
   * entry in the globalNodeIds vector contains the global node ids
   * for that partition.
94
   *
95 96 97 98
   * Example of use:
   *
   * C++
   *
99
   * @dontinclude ExampleXdmfMap.cpp
100 101
   * @skipline //#initializationnode
   * @until //#initializationnode
102 103 104
   *
   * Python
   *
105
   * @dontinclude XdmfExampleMap.py
106 107
   * @skipline #//initializationnode
   * @until #//initializationnode
108
   *
109
   * @param     globalNodeIds   A vector of attributes containing globalNodeId
110
   *                            values for each partition to be mapped.
111
   *
112 113 114
   * @return                    Constructed XdmfMaps for each partition. The
   *                            size of the vector will be the same as the
   *                            globalNodeIds vector.
115
   */
116 117
  static std::vector<shared_ptr<XdmfMap> >
  New(const std::vector<shared_ptr<XdmfAttribute> > & globalNodeIds);
118 119 120

  virtual ~XdmfMap();

121
  LOKI_DEFINE_VISITABLE(XdmfMap, XdmfItem)
122 123 124 125 126
  static const std::string ItemTag;

  std::map<std::string, std::string> getItemProperties() const;

  /**
127 128
   * Get stored boundary communicator map.
   *
129 130 131 132
   * Example of use:
   *
   * C++
   *
133
   * @dontinclude ExampleXdmfMap.cpp
134 135 136 137
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getMap
   * @until //#getMap
138 139 140
   *
   * Python
   *
141
   * @dontinclude XdmfExampleMap.py
142 143 144 145
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getMap
   * @until #//getMap
146
   *
147
   * @return    Stored boundary communicator map.
148 149 150
   */
  std::map<task_id, node_id_map> getMap() const;

151 152 153
  /**
   * Get name of boundary communicator map.
   *
154 155 156 157
   * Example of use:
   *
   * C++
   *
158
   * @dontinclude ExampleXdmfMap.cpp
159 160 161 162 163 164
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#setName
   * @until //#setName
   * @skipline //#getName
   * @until //#getName
165 166 167
   *
   * Python
   *
168
   * @dontinclude XdmfExampleMap.py
169 170 171 172 173 174
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//setName
   * @until #//setName
   * @skipline #//getName
   * @until #//getName
175
   *
176
   * @return    Name of boundary communicator map.
177 178 179
   */
  std::string getName() const;

180 181
  /**
   * Given a remote task id return a map of local node ids to remote
182
   * node ids
183
   *
184 185 186 187
   * Example of use:
   *
   * C++
   *
188
   * @dontinclude ExampleXdmfMap.cpp
189 190 191 192
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#getRemoteNodeIds
   * @until //#getRemoteNodeIds
193 194 195
   *
   * Python
   *
196
   * @dontinclude XdmfExampleMap.py
197 198 199 200
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//getRemoteNodeIds
   * @until #//getRemoteNodeIds
201
   *
202
   * @param     remoteTaskId    Task id to retrieve mapping for.
203
   *
204 205
   * @return                    A map of local node ids to a vector of
   *                            remote node ids on remoteTaskId.
206
   */
207
  node_id_map getRemoteNodeIds(const task_id remoteTaskId);
208 209 210 211 212

  std::string getItemTag() const;

  using XdmfItem::insert;

213 214 215
  /**
   * Insert a new entry in map.
   *
216 217 218 219
   * Example of use:
   *
   * C++
   *
220
   * @dontinclude ExampleXdmfMap.cpp
221 222 223 224
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#inserttuple
   * @until //#inserttuple
225 226 227
   *
   * Python
   *
228
   * @dontinclude XdmfExampleMap.py
229 230 231 232
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//inserttuple
   * @until #//inserttuple
233
   *
234 235 236 237 238
   * @param     remoteTaskId            task id where the remoteLoalNodeId is
   *                                    located.
   * @param     localNodeId             The node id of the node being mapped.
   * @param     remoteLocalNodeId       A node id on the remoteTaskId that the
   *                                    localNodeId is mapped to.
239
   */
240
  void insert(const task_id  remoteTaskId,
241 242
              const node_id  localNodeId,
              const node_id  remoteLocalNodeId);
243 244

  /**
245 246
   * Returns whether the map is initialized (contains values in
   * memory).
247
   *
248 249 250 251
   * Example of use:
   *
   * C++
   *
252
   * @dontinclude ExampleXdmfMap.cpp
253 254 255 256
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#isInitialized
   * @until //#isInitialized
257 258 259
   *
   * Python
   *
260
   * @dontinclude XdmfExampleMap.py
261 262 263 264
   * @skipline //#initialization
   * @until //#initialization
   * @skipline #//isInitialized
   * @until #//isInitialized
265
   *
266
   * @return    bool true if map contains values in memory.
267 268 269 270 271
   */
  bool isInitialized() const;

  /**
   * Read data from disk into memory.
272 273 274 275 276
   *
   * Example of use:
   *
   * C++
   *
277
   * @dontinclude ExampleXdmfMap.cpp
278 279 280 281
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#isInitialized
   * @until //#isInitialized
282 283 284
   *
   * Python
   *
285
   * @dontinclude XdmfExampleMap.py
286 287 288 289
   * @skipline //#initialization
   * @until //#initialization
   * @skipline #//isInitialized
   * @until #//isInitialized
290 291 292 293
   */
  void read();

  /**
294
   * Release all data held in memory. The heavy data remain attached.
295 296 297 298 299
   *
   * Example of use:
   *
   * C++
   *
300
   * @dontinclude ExampleXdmfMap.cpp
301 302 303 304
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#release
   * @until //#release
305 306 307
   *
   * Python
   *
308
   * @dontinclude XdmfExampleMap.py
309 310 311 312
   * @skipline //#initialization
   * @until //#initialization
   * @skipline #//release
   * @until #//release
313 314 315 316 317 318
   */
  void release();

  /**
   * Set the heavy data controllers for this map.
   *
319 320 321 322
   * Example of use:
   *
   * C++
   *
323
   * @dontinclude ExampleXdmfMap.cpp
324 325 326 327
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#setHeavyDataController
   * @until //#setHeavyDataController
328 329 330
   *
   * Python
   *
331
   * @dontinclude XdmfExampleMap.py
332 333 334 335
   * @skipline //#initialization
   * @until //#initialization
   * @skipline #//setHeavyDataController
   * @until #//setHeavyDataController
336
   *
337 338 339 340 341 342
   * @param     remoteTaskIdsControllers        A vector of XdmfHeavyDataControllers 
   *                                            to the remote task ids dataset.
   * @param     localNodeIdsControllers         A vector of XdmfHeavyDataControllers
   *                                            to the local node ids dataset.
   * @param     remoteLocalNodeIdsControllers   A vector of XdmfHeavyDataControllers
   *                                            to the remote local node ids dataset.
343 344
   */
  void
345 346 347
  setHeavyDataControllers(std::vector<shared_ptr<XdmfHeavyDataController> > remoteTaskIdsControllers,
                          std::vector<shared_ptr<XdmfHeavyDataController> > localNodeIdsControllers,
                          std::vector<shared_ptr<XdmfHeavyDataController> > remoteLocalNodeIdsControllers);
348

349 350 351
  /**
   * Set the boundary communicator map.
   *
352 353 354 355
   * Example of use:
   *
   * C++
   *
356
   * @dontinclude ExampleXdmfMap.cpp
357 358 359 360
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#setMap
   * @until //#setMap
361 362 363
   *
   * Python
   *
364
   * @dontinclude XdmfExampleMap.py
365 366 367 368
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//setMap
   * @until #//setMap
369
   *
370
   * @param     map     The boundary communicator map to store.
371 372 373
   */
  void setMap(std::map<task_id, node_id_map> map);

374 375 376
  /**
   * Set the name of the boundary communicator map.
   *
377 378 379 380
   * Example of use:
   *
   * C++
   *
381
   * @dontinclude ExampleXdmfMap.cpp
382 383 384 385
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#setName
   * @until //#setName
386 387 388
   *
   * Python
   *
389
   * @dontinclude XdmfExampleMap.py
390 391 392 393
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//setName
   * @until #//setName
394
   *
395
   * @param     name    The name of the boundary communicator map to set.
396 397 398
   */
  void setName(const std::string & name);

399
  void traverse(const shared_ptr<XdmfBaseVisitor> visitor);
400

401 402
  XdmfMap(XdmfMap & map);

403
protected:
404 405 406 407 408

  XdmfMap();

  virtual void
  populateItem(const std::map<std::string, std::string> & itemProperties,
409
               const std::vector<shared_ptr<XdmfItem> > & childItems,
410 411
               const XdmfCoreReader * const reader);

412
private:
413 414 415 416

  XdmfMap(const XdmfMap & map);  // Not implemented.
  void operator=(const XdmfMap & map);  // Not implemented.

417
  std::vector<shared_ptr<XdmfHeavyDataController> > mLocalNodeIdsControllers;
418 419
  // remoteTaskId | localNodeId | remoteLocalNodeId
  std::map<task_id, node_id_map > mMap;
420
  std::string mName;
421 422
  std::vector<shared_ptr<XdmfHeavyDataController> > mRemoteLocalNodeIdsControllers;
  std::vector<shared_ptr<XdmfHeavyDataController> > mRemoteTaskIdsControllers;
423 424 425

};

426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480
#endif

#ifdef __cplusplus
extern "C" {
#endif

// C wrappers go here

struct XDMFMAP; // Simply as a typedef to ensure correct typing
typedef struct XDMFMAP XDMFMAP;

XDMF_EXPORT XDMFMAP * XdmfMapNew();

XDMF_EXPORT XDMFMAP ** XdmfMapNewFromIdVector(int ** globalNodeIds, int * numIdsOnNode, int numIds);

XDMF_EXPORT char * XdmfMapGetName(XDMFMAP * map);

XDMF_EXPORT void XdmfMapInsert(XDMFMAP * map, int remoteTaskId, int localNodeId, int remoteLocalNodeId);

XDMF_EXPORT int XdmfMapIsInitialized(XDMFMAP * map);

XDMF_EXPORT void XdmfMapRead(XDMFMAP * map, int * status);

XDMF_EXPORT void XdmfMapRelease(XDMFMAP * map);

XDMF_EXPORT int * XdmfMapRetrieveLocalNodeIds(XDMFMAP * map, int remoteTaskId);

XDMF_EXPORT int XdmfMapRetrieveNumberLocalNodeIds(XDMFMAP * map, int remoteTaskId);

XDMF_EXPORT int XdmfMapRetrieveNumberRemoteTaskIds(XDMFMAP * map);

XDMF_EXPORT int XdmfMapRetrieveNumberRemoteNodeIds(XDMFMAP * map, int remoteTaskId, int localNodeId);

XDMF_EXPORT int * XdmfMapRetrieveRemoteTaskIds(XDMFMAP * map);

XDMF_EXPORT int * XdmfMapRetrieveRemoteNodeIds(XDMFMAP * map, int remoteTaskId, int localNodeId);

XDMF_EXPORT void XdmfMapSetHeavyDataControllers(XDMFMAP * map,
                                                XDMFHEAVYDATACONTROLLER ** remoteTaskControllers,
                                                int numRemoteTaskControllers,
                                                XDMFHEAVYDATACONTROLLER ** localNodeControllers,
                                                int numberLocalNodeControllers,
                                                XDMFHEAVYDATACONTROLLER ** remoteLocalNodeControllers,
                                                int numRemoteLocalNodeControllers,
                                                int passControl,
                                                int * status);

XDMF_EXPORT void XdmfMapSetName(XDMFMAP * map, char * newName);

XDMF_ITEM_C_CHILD_DECLARE(XdmfMap, XDMFMAP, XDMF)

#ifdef __cplusplus
}
#endif

481
#endif /* XDMFMAP_HPP_ */