From ff998ea873b4081a3667acbc8a558b0752f07997 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?St=C3=A9phane=20Del=20Pino?= <stephane.delpino44@gmail.com>
Date: Tue, 25 Feb 2025 19:10:13 +0100
Subject: [PATCH] Add user doc for load_balance:mesh -> mesh

---
 doc/userdoc.org | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/doc/userdoc.org b/doc/userdoc.org
index 169f041f3..96bcd3f76 100644
--- a/doc/userdoc.org
+++ b/doc/userdoc.org
@@ -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
-- 
GitLab