Remove m_cell_global_index from Connectivity

• now this information is computed when needed (load balance)
• closes #11 (closed)

doc/userdoc.org

@@ -2689,9 +2689,9 @@ actually stored in the ~checkpoint.h5~ file, the script is not a command
 line argument.
 
 By now, it is not possible to *simply* modify the script while
-resuming. This is done in purpose since it remains unclear if such a
-dangerous functionality should be make easy. Indeed allowing
-script modifications may lead to undefined behaviors.
+resuming. This is done on purpose since it remains unclear if such a
+dangerous functionality should be make easy. Indeed allowing script
+modifications may lead to undefined behaviors.
 #+END_note
 
 #+BEGIN_warning
@@ -3431,6 +3431,30 @@ In this example, we set three arrays defined at all nodes, all the
 - ~face_values~ interpolates ~f~ at the centers of the faces of ~m~,
 - ~cell_values~ interpolates ~f~ at the centers of the cells of ~m~.
 
+***** ~load_balance:mesh -> mesh~
+
+Creates a new partition of a mesh in parallel (~MPI~).
+#+BEGIN_SRC pugs :exports both :results none
+  import mesh;
+
+  let m1:mesh, m1 = cartesianMesh([0,0], [1,1], (10,10));
+  let m2:mesh, m2 = load_balance(m1);
+#+END_SRC
+In this example the mesh ~m2~ is a new parallel partition of the mesh
+~m1~. This implies that the two meshes, while being identical from the
+mathematical point of view, are now different (and are not defined on
+a same connectivity: the connectivity is actually balanced).
+
+Discrete functions defined on ~m1~ are *not* implicitly transferred on the
+mesh ~m2~! The function ~load_balance:(Vh)->(Vh)~ must be used to perform
+mesh and data load balancing.
+
+#+BEGIN_note
+To simplify development of large calculations. A sequential call of
+this function has the same effect: the mesh and its connectivity are
+copied!
+#+END_note
+
 ***** ~transform: mesh*function -> mesh~
 
 This function allows to compute a new mesh as the transformation of a
@@ -4471,6 +4495,109 @@ to different meshes.
 
 A good example of the use of this kind of function is mass fractions.
 
+***** ~get_mesh:Vh -> mesh~
+
+This function allows to retrieve the mesh that is used to define a
+discrete function.
+#+BEGIN_SRC pugs :exports both :results none
+  import mesh;
+  import scheme;
+
+  let m1:mesh, m1 = cartesianMesh(0, [1,1], (10,10));
+
+  let f: R^2 -> R, x -> 2*x[0]+x[1];
+  let fh:Vh, fh = interpolate(m1, P0(), f);
+
+  let m2: mesh, m2 = get_mesh(fh);
+#+END_SRC
+Observe that in this example the two variables ~m1~ and ~m2~ refer to the
+same exact mesh. There is no duplication.
+
+***** ~load_balance: (Vh) -> (Vh)~
+
+This function performs a parallel load balancing of a list of ~Vh~
+variables. All the input variables must be defined on a same mesh. The
+return list consists of the balanced variables sorted using the input
+ordering. The new (balanced) mesh is carried out by the new variables
+and can be retrieved using the ~get_mesh: Vh -> mesh~ function.
+
+Here is an example of use.
+#+BEGIN_SRC pugs :exports both :results none
+  import mesh;
+  import scheme;
+
+  let m:mesh, m = cartesianMesh(0, [1,1], (10,10));
+
+  let f: R^2 -> R, x -> 2*x[0]+x[1];
+  let g: R^2 -> R, x -> 3*x[1]-x[0];
+
+  let fh:Vh, fh = interpolate(m, P0(), f);
+  let gh:Vh, gh = interpolate(m, P0(), g);
+
+  (fh,gh) = load_balance((fh, gh));
+  let sum:Vh, sum = fh+gh;
+
+  m = get_mesh(sum);
+#+END_SRC
+
+#+BEGIN_note
+One notices the parenthesis enclosing the list ~(fh,gh)~ when invoking
+the ~load_balance~ function.
+#+END_note
+
+One should also observe that the in the previous example, balancing ~fh~
+and ~gh~ separately defines two new different meshes so that the resulting
+discrete functions are no more defined on the same one. The following
+example enlightens this behavior.
+
+#+NAME: separate-load-balance
+#+BEGIN_SRC pugs-error :exports both :results output
+  import mesh;
+  import scheme;
+
+  let m:mesh, m = cartesianMesh(0, [1,1], (10,10));
+
+  let f: R^2 -> R, x -> 2*x[0]+x[1];
+  let g: R^2 -> R, x -> 3*x[1]-x[0];
+
+  let fh:Vh, fh = interpolate(m, P0(), f);
+  let gh:Vh, gh = interpolate(m, P0(), g);
+
+  fh = load_balance(fh);
+  gh = load_balance(gh);
+  let sum:Vh, sum = fh+gh;
+#+END_SRC
+#+RESULTS: separate-load-balance
+
+#+BEGIN_warning
+Using this function in a sequential calculation has the same behavior:
+the discrete functions, the mesh and its connectivity are copied. This
+is intended to simplify development of large calculations on simpler
+tests, and for consistency.
+#+END_warning
+
+The following example illustrates this remark: even for sequential
+calculations a new mesh (and connectivity) is built *on purpose* when
+invoking ~load_balance~
+#+NAME: serial-effect-load-balance
+#+BEGIN_SRC pugs-error :exports both :results output
+  import mesh;
+  import scheme;
+
+  let m:mesh, m = cartesianMesh(0, [1,1], (10,10));
+
+  let f: R^2 -> R, x -> 2*x[0]+x[1];
+
+  let fh:Vh, fh = interpolate(m, P0(), f);
+  let gh:Vh, gh = load_balance(fh);
+
+  let sum:Vh, sum = fh+gh;
+#+END_SRC
+#+RESULTS: serial-effect-load-balance
+Even if the functions are similar (mathematically ~fh~ = ~gh~) they do not
+live on the same mesh from ~pugs~ point of view, thus one cannot perform
+simple algebra.
+
 ***** Numerical methods
 
 We describe rapidly two functions that embed numerical methods. These