XdmfMap.hpp 11.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 27
#ifndef XDMFMAP_HPP_
#define XDMFMAP_HPP_

// Forward Declarations
28
class XdmfArray;
29
class XdmfAttribute;
30
class XdmfHeavyDataController;
31 32

// Includes
33
#include "Xdmf.hpp"
34 35
#include "XdmfItem.hpp"

36 37
#include <set>

38
/**
39 40
 * @brief Boundary communicator map for partitioned spatial
 * collections.
41
 *
42 43 44
 * 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.
45 46 47
 *
 * There are two methods for constructing XdmfMaps:
 *
48 49 50
 * Calling New() with no parameters will construct an empty map. The
 * map can be filled manually with subsequent insert commands.
 *
51
 * Calling New(const std::vector<shared_ptr<XdmfAttribute> > &
52 53 54 55
 * 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.
56
 */
57
class XDMF_EXPORT XdmfMap : public XdmfItem {
58

59
public:
60

61 62 63 64
  typedef int node_id;
  typedef int task_id;
  typedef std::map<node_id, std::set<node_id> > node_id_map;

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

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

  virtual ~XdmfMap();

117
  LOKI_DEFINE_VISITABLE(XdmfMap, XdmfItem)
118 119 120 121 122
  static const std::string ItemTag;

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

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

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

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

  std::string getItemTag() const;

  using XdmfItem::insert;

209 210 211
  /**
   * Insert a new entry in map.
   *
212 213 214 215
   * Example of use:
   *
   * C++
   *
216
   * @dontinclude ExampleXdmfMap.cpp
217 218 219 220
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#inserttuple
   * @until //#inserttuple
221 222 223
   *
   * Python
   *
224
   * @dontinclude XdmfExampleMap.py
225 226 227 228
   * @skipline #//initialization
   * @until #//initialization
   * @skipline #//inserttuple
   * @until #//inserttuple
229
   *
230 231 232 233 234
   * @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.
235
   */
236
  void insert(const task_id  remoteTaskId,
237 238
              const node_id  localNodeId,
              const node_id  remoteLocalNodeId);
239 240

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

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

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

  /**
   * Set the heavy data controllers for this map.
   *
315 316 317 318
   * Example of use:
   *
   * C++
   *
319
   * @dontinclude ExampleXdmfMap.cpp
320 321 322 323
   * @skipline //#initialization
   * @until //#initialization
   * @skipline //#setHeavyDataController
   * @until //#setHeavyDataController
324 325 326
   *
   * Python
   *
327
   * @dontinclude XdmfExampleMap.py
328 329 330 331
   * @skipline //#initialization
   * @until //#initialization
   * @skipline #//setHeavyDataController
   * @until #//setHeavyDataController
332
   *
333 334 335 336 337 338
   * @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.
339 340
   */
  void
341 342 343
  setHeavyDataControllers(std::vector<shared_ptr<XdmfHeavyDataController> > remoteTaskIdsControllers,
                          std::vector<shared_ptr<XdmfHeavyDataController> > localNodeIdsControllers,
                          std::vector<shared_ptr<XdmfHeavyDataController> > remoteLocalNodeIdsControllers);
344

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

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

395
  void traverse(const shared_ptr<XdmfBaseVisitor> visitor);
396

397
protected:
398 399 400 401 402

  XdmfMap();

  virtual void
  populateItem(const std::map<std::string, std::string> & itemProperties,
403
               const std::vector<shared_ptr<XdmfItem> > & childItems,
404 405
               const XdmfCoreReader * const reader);

406
private:
407 408 409 410

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

411
  std::vector<shared_ptr<XdmfHeavyDataController> > mLocalNodeIdsControllers;
412 413
  // remoteTaskId | localNodeId | remoteLocalNodeId
  std::map<task_id, node_id_map > mMap;
414
  std::string mName;
415 416
  std::vector<shared_ptr<XdmfHeavyDataController> > mRemoteLocalNodeIdsControllers;
  std::vector<shared_ptr<XdmfHeavyDataController> > mRemoteTaskIdsControllers;
417 418 419 420

};

#endif /* XDMFMAP_HPP_ */