From c114731a5d48b09d1376dbd9ddeee4e2e21d9777 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Henrotte?= <francois.henrotte@uclouvain.be>
Date: Sat, 21 Oct 2017 11:21:38 +0200
Subject: [PATCH] relecture du tuto et amelioration des explications

---
 ElectrostaticsFloating/floating.pro | 94 +++++++++++++++++------------
 1 file changed, 56 insertions(+), 38 deletions(-)

diff --git a/ElectrostaticsFloating/floating.pro b/ElectrostaticsFloating/floating.pro
index cb82243..4eb75fc 100644
--- a/ElectrostaticsFloating/floating.pro
+++ b/ElectrostaticsFloating/floating.pro
@@ -13,21 +13,23 @@
    ------------------------------------------------------------------- */
 
 /*
-  A thing GetDP is pretty good at is the management of global (non-local) basis functions.
-  Finite element expansions typically associate basis functions to individual nodes 
-  or edges in the mesh. But consider the situation where a scalar field is set to be uniform 
-  over a region of the problem (Say a floating potential electrode 
-  in an Electrostatics problem, to fix the idea).
-  By factorizing the identical nodal value "v_electrode", 
+  A thing GetDP is pretty good at is the management of global (non-local) basis
+  functions. Finite element expansions typically associate basis functions to
+  individual nodes or edges in the mesh. But consider the situation
+  where a scalar field is set to be uniform over a region of the problem 
+  (Say a floating potential electrode in an Electrostatics problem, 
+  to fix the idea). By factorizing the identical nodal value "v_electrode",
   a global (non-local) basis function "BF_electrode" is obtained as factor 
-  which is the sum of the shape functions of all the nodes in the electrode region.
-  This basis function "BF_electrode" 
-  - is a continuous function
-  - is equal to 1 at the nodes of the electrode region, and to 0 at all other nodes
-  - decreases from 1 to 0 over the one element thick layer of outside finite elements
-    immediately in contact with the electrode region.
-  One such glabal basis function can be associated with each electrode in the system,
-  so that the finite element expansion of the electric scalar potential reads:
+  which is the sum of the shape functions of all the nodes in the electrode
+  region. This basis function "BF_electrode" 
+  - is a continuous function, scalar in this case,
+  - is equal to 1 at the nodes of the electrode region, and to 0 
+    at all other nodes
+  - decreases from 1 to 0 over the one element thick layer of outside 
+    finite elements immediately in contact with the electrode region.
+  One such glabal basis function can be associated with each electrode 
+  in the system, so that the finite element expansion of the electric 
+  scalar potential reads:
 
    v = Sum_k sn_k vn_k + Sum_electrode v_electrode BF_electrode
 
@@ -36,10 +38,10 @@
    - to reduce the number of unknowns
    - to compute efficiently the electrode charges "Q_electrode", 
      which are precisely the energy duals of the global "v_electrode" quantities
-   - to deal with floating potentials, which are the computed electrode potential
-     when the electrode charge is imposed
-   - to provide output quantities (charges, armature voltages, capacitances, ...)
-     that can be immediately used in a external circuit.
+   - to deal with floating potentials, which are the computed electrode 
+     potential when the electrode charge is imposed
+   - to provide output quantities (charges, armature voltages, 
+     capacitances, ...) that can be immediately used in a external circuit.
  */
 
 
@@ -100,9 +102,10 @@ Constraint {
 
   { Name SetGlobalPotential; Type Assign;
     Case {
-      /* Define the imposed potential regionwise on the different parts of "Electrodes_Ele".
-	 No voltage imposed to the Microstrip electrode
-	 when the "Fixed charge" option is enabled ( MicrostripTypeBC = true ). */
+      /* Define the imposed potential regionwise on the different parts of
+	 "Electrodes_Ele". No voltage imposed to the Microstrip electrode
+	 when the "Fixed charge" option is enabled 
+	 ( MicrostripTypeBC = true ). */
       { Region Ground; Value 0; }
       If( !MicrostripTypeBC )
 	{ Region Microstrip; Value MicrostripValueBC; }
@@ -128,15 +131,28 @@ Group{
 
 FunctionSpace {
   /* The magic in the treatment of global quantitities by GetDP is in the fact 
-     that nearly all the work is done at the level of the FunctionSpace definition.
-
-     The finite element expansion is 
+     that nearly all the work is done at the level of the FunctionSpace
+     definition. The finite element expansion of "v" is 
 
      v = Sum_k sn_k vn_k + Sum_electrode v_electrode BF_electrode
 
-     The sum_k runs over all nodes except those of the electrode regions.
-     "sf" stands for "BF_electrode"
-     "vf" stands for "v_electrode"
+     with the the sum_k running over all nodes except those of the electrode
+     regions. This is exactly what one finds in the FunctionSpace definotion 
+     below with "sf" standing for "BF_electrode" and "vf" for "v_electrode".
+     The global quantities are also be attributed a more explicit 
+     and meaningful name. Moreover the "AssociatedWith" statement manifests 
+     the fact that the global potential of an electrode is the (electrostatic)
+     energy dual of the electric charge carried by that electrode. 
+     By checking the "Display global basis functions" checkbox and running 
+     the model, you can take a look on how the two "BF_electrode" basis 
+     functions in this model look like. 
+     Constraints can then be set on either component of the FunctionSpace.
+     Besides the usual Dirichlet boundary condition conditions, which is 
+     left here for the sake of completeness but is not used in this model, 
+     there is the possibility to fix either the GlobalPotential or the
+     ArmatureCharge of each indidual electrode (not both, of course). 
+     When the ArmatureCharge is fixed, the computed GlobalPotential computed 
+     for that electrode is the so-called floating potential. 
   */
 
   { Name Hgrad_v_Ele; Type Form0;
@@ -186,8 +202,9 @@ Integration {
 Formulation {
   /* Only minor changes in the formulation.
      The global quantities are declared in the "Quantity{}" section,
-     and a "GlobalTerm" is added that triggers the assembly of an additional equation
-     per electrode in the system to compute the charge Q_electrode 
+     and a "GlobalTerm" is added that triggers the assembly 
+     of an additional equation per electrode in the system 
+     to compute the charge Q_electrode accordint to:
 
      Q_electrode = (-epsr[] Grad v, Grad BF_electrode)_Vol_Dielectric_Ele
    */
@@ -239,7 +256,7 @@ PostProcessing {
 	  }
 	}
       }
-      // next lines only needed to display global basis functions in PostProcessing
+      // next lines only needed to display global BF in PostProcessing
       { Name BFGround; Value { Term { [ BF {vf} ]; In Dom_Hgrad_v_Ele; 
 	    SubRegion Ground; Jacobian Vol; } } }
       { Name BFMicrostrip; Value { Term { [ BF {vf} ]; In Dom_Hgrad_v_Ele; 
@@ -249,12 +266,11 @@ PostProcessing {
   }
 }
 
-/* Various output results are generated. 
-   They are both displayed in the graphical user interface, and stored in disk files.
-   In particular, global quantities related results are stored in the "output.txt" file. 
-   There is a user option to display the global basis functions of the two electrodes. 
-   Another option allows the user to chose to not overwrite
-   the "output.txt" file when running a new simulation. */
+/* Various output results are generated, which are both displayed 
+   in the graphical user interface, and stored in disk files. 
+   In particular, global quantities related results are stored 
+   in the "output.txt" file. A user option allows to chose 
+   to not overwrite the "output.txt" file when running a new simulation. */
 
 PostOperation {
   { Name Map; NameOfPostProcessing EleSta_v;
@@ -267,7 +283,8 @@ PostOperation {
 		      "View[l].ShowElement = 1;"],
 	       File "BFGround.opt", LastTimeStepOnly] ;
 
-	 Print[ BFMicrostrip, OnElementsOf Dom_Hgrad_v_Ele, File "BFMicrostrip.pos" ];
+	 Print[ BFMicrostrip, OnElementsOf Dom_Hgrad_v_Ele, 
+		File "BFMicrostrip.pos" ];
 	 Echo[ StrCat["l=PostProcessing.NbViews-1;", 
 		      "View[l].IntervalsType = 1;",
 		      "View[l].NbIso = 40;",
@@ -294,7 +311,8 @@ PostOperation {
        Print[ C, OnRegion Microstrip, File > "output.txt", Color "AliceBlue",
 	      Format Table, SendToServer "Output/Global/Capacitance [F]" ];
        Echo[ "Electrostatic energy [J]:", Format Table, File > "output.txt"] ;
-       Print[ energy, OnRegion Vol_Dielectric_Ele, File > "output.txt", Color "AliceBlue",
+       Print[ energy, OnRegion Vol_Dielectric_Ele, File > "output.txt", 
+	      Color "AliceBlue",
 	      Format Table, SendToServer "Output/Global/Energy [J]" ];
      }
   }
-- 
GitLab