Improve load balancing documentation

doc/userdoc.org

@@ -4499,10 +4499,58 @@ A good example of the use of this kind of function is mass fractions.
 
 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 is the balance variables using the input
+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
@@ -4510,6 +4558,28 @@ 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