doc/user/doxygen/doxfiles/reference/arrays/numbering.dox

   1 /*!
   2 \page numbering Array indexing and numbering
   3
   4 The MED library make constant use of arrays of integer or double to represent the various
   5 data it needs. The arrays of integer (\ref ParaMEDMEM::DataArrayInt "DataArrayInt") are of special importance as they
   6 often constitutes the return value of the functions provided by the API. This can be
   7 a list of nodes, a list of cells, a way to rearrange the cell in a mesh (a permutation), a part of the
   8 domain when doing parallel computation, etc ...
   9
  10 This page tries to cover all the form such a data can take and points to the most important
  11 functions available to convert from one format to the other.
  12
  13 Formally a "renumbering" is a mathematical application that can be surjective, injective or bijective.
  14 This application is defined using an instance of
  15 \ref ParaMEDMEM::DataArrayInt "DataArrayInt". There are different ways to define this application.
  16
  17 \section MEDCouplingArrayRenumberingO2N Old-to-new mode
  18
  19 The old to new mode is particularly recommanded for surjective and bijective applications. This
  20 is typically the case of \ref ParaMEDMEM::MEDCouplingUMesh::mergeNodes "MEDCouplingUMesh::mergeNodes" method.
  21 Let's consider a call to \ref ParaMEDMEM::MEDCouplingUMesh::mergeNodes "mergeNodes" that reduces the
  22 number of nodes from 5 nodes to 3 nodes.\n
  23 In old to new mode the array \b MySurjection that specifies this surjection will have 5 tuples
  24 and 1 component. The content of the 5*1 values will be in {0,1,2}.\n
  25
  26 If \b MySujection equals [2,1,0,1,2], it means that :
  27
  28 - old id #0 will have new id equal to 2
  29 - old id #1 will have new id equal to 1
  30 - old id #2 will have new id equal to 0
  31 - old id #3 will have new id equal to 1 like old id #1
  32 - old id #4 will have new id equal to 2 like old id #0
  33
  34 This is the most common mode of renumbering in MEDCoupling because there is more methods
  35 implying renumbering that reduce the number of entities than method that increase number of entities.
  36
  37 Method in old to new mode that works on bijective applications :
  38
  39 - \ref ParaMEDMEM::DataArrayDouble::renumber "DataArrayDouble::renumber"
  40 - \ref ParaMEDMEM::DataArrayDouble::renumberInPlace "DataArrayDouble::renumberInPlace"
  41
  42 Method in old to new mode that works on surjective applications :
  43
  44 - \ref ParaMEDMEM::DataArrayDouble::renumberAndReduce "DataArrayDouble::renumberAndReduce"
  45
  46 Sometimes the format old to new for surjections can be replaced by another format with 2 arrays.
  47 Less compact in memory. The \ref ParaMEDMEM::DataArrayInt::changeSurjectiveFormat "DataArrayInt::changeSurjectiveFormat" method performs that.
  48
  49 \section MEDCouplingArrayRenumberingN2O New-to-old mode
  50
  51 The new-to-old mode is particularly recommended for strictly injective and bijective permutations.
  52 This is particularly useful for methods that increase the number of entities like for example
  53 \ref ParaMEDMEM::MEDCouplingUMesh::simplexize "MEDCouplingUMesh::simplexize".\n
  54 All non static methods in \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble"
  55 or \ref ParaMEDMEM::DataArrayInt "DataArrayInt" having as last letter \b R (meaning Reversed) in
  56 capital works with the mode new to old.
  57 Let's consider a call to \ref ParaMEDMEM::MEDCouplingUMesh::simplexize "simplexize" that increases
  58 the number of cell from 4 cells to 6 cells.\n
  59 In new-to-old mode the array \b MyInjection that specifies this injection will have 6 tuples
  60 and 1 component. The content of the 5*1 values will be in {0,1,2,3}.\n
  61 If \b MyInjection equals [2,0,1,1,3,0] it means that :
  62
  63 - new id #0 comes from old id 2
  64 - new id #1 comes from old id 0
  65 - new id #2 comes from old id 1
  66 - new id #3 comes from old id 1
  67 - new id #4 comes from old id 3
  68 - new id #5 comes from old id 0
  69
  70 Method in new-to-old mode that works on bijective applications :
  71
  72 - \ref ParaMEDMEM::DataArrayDouble::renumberR "DataArrayDouble::renumberR"
  73 - \ref ParaMEDMEM::DataArrayDouble::renumberInPlace "DataArrayDouble::renumberInPlaceR"
  74
  75 Method in new-to-old mode that works on surjective applications :
  76
  77 - \ref ParaMEDMEM::DataArrayDouble::selectByTupleId "DataArrayDouble::selectByTupleId"
  78 - \ref ParaMEDMEM::DataArrayDouble::selectByTupleIdSafe "DataArrayDouble::selectByTupleIdSafe"
  79 - \ref ParaMEDMEM::DataArrayDouble::selectByTupleId2 "DataArrayDouble::selectByTupleId2"
  80 - \ref ParaMEDMEM::DataArrayDouble::selectByTupleRanges "DataArrayDouble::selectByTupleRanges"
  81
  82 \section numbering-indirect Indirect indexing
  83
  84 The indirect indexing format is made of two \ref arrays "arrays of int (DataArrayInt)" and
  85 is used to describe a set of groups (a group being here understood as a simple pack of int identifiers).
  86 Each group of identifier can for example represent a set of coincident nodes, or a set of nodes belonging
  87 to the same cell, etc ...
  88
  89 \image html IndirectIndex.jpg "Indirect indexing principle"
  90
  91 Denoting \c tab and \c tabI the two arrays of the indirect indexing format,
  92 we see at the top in the picture above the \c tab array, which contains n packs of identifiers
  93 (first pack is 3,1,4,6, second pack is 4,3,2,6,5, etc ...), and below the array \c tabI
  94 which provides the necessary offsets to extract a given pack from \c tab.
  95
  96 This format is widely used internally (this is how the connectivity of
  97 \ref MEDCouplingUMeshPage "unstructured cells" is stored for example), and is also returned by
  98 many functions, e.g.:
  99 - \ref  ParaMEDMEM::MEDCouplingPointSet::findCommonCells "MEDCouplingPointSet::findCommonCells"
 100 - \ref  ParaMEDMEM::MEDCouplingPointSet::findCommonNodes "MEDCouplingPointSet::findCommonNodes"
 101 - \ref  ParaMEDMEM::MEDCouplingPointSet::getNodeIdsNearPoints "MEDCouplingPointSet::getNodeIdsNearPoints"
 102 - \ref  ParaMEDMEM::MEDCouplingUMesh::buildDescendingConnectivity "MEDCouplingUMesh::buildDescendingConnectivity"
 103 - \ref  ParaMEDMEM::MEDCouplingUMesh::computeNeighborsOfNodes "MEDCouplingUMesh::computeNeighborsOfNodes"
 104 - \ref  ParaMEDMEM::MEDCouplingUMesh::convertNodalConnectivityToDynamicGeoTypeMesh "MEDCouplingUMesh::convertNodalConnectivityToDynamicGeoTypeMesh"
 105 - \ref  ParaMEDMEM::MEDCouplingUMesh::setConnectivity "MEDCouplingUMesh::setConnectivity"
 106 - \ref  ParaMEDMEM::MEDCouplingUMesh::split2DCells "MEDCouplingUMesh::split2DCells"
 107
 108 Some functions in the API to manipulate this format:
 109 - \ref ParaMEDMEM::DataArrayInt::changeSurjectiveFormat "DataArrayInt::changeSurjectiveFormat"
 110 - \ref ParaMEDMEM::MEDCouplingUMesh::ExtractFromIndexedArrays "(static) MEDCouplingUMesh::ExtractFromIndexedArrays"
 111 - \ref ParaMEDMEM::MEDCouplingUMesh::ExtractFromIndexedArrays2 "(static) MEDCouplingUMesh::ExtractFromIndexedArrays2"
 112
 113 */