Enhanced inline documentation of EB related data (#2562)

* Enhanced inline documentation of EB related data

* Added ECT to the glossary

* Made the EB documentation doxygen-compatible

Author: lgiacome

Docs/source/glossary.rst

@@ -18,6 +18,7 @@ Abbreviations
 * **CI:** continuous integration, automated tests that we perform before a proposed code-change is accepted; see PR
 * **CPU:** `central processing unit <https://en.wikipedia.org/wiki/Central_processing_unit>`__, we usual mean a socket or generally the host-side of a computer (compared to the accelerator, e.g. GPU)
 * **DOE:** `The United States Department of Energy <https://en.wikipedia.org/wiki/United_States_Department_of_Energy>`__, the largest sponsor of national laboratory research in the United States of America
+* **ECT:** `Enlarged Cell Technique <https://ieeexplore.ieee.org/document/4463918>`__, an electromagnetic solver with accurate resolution of perfectly conducting embedded boundaries
 * **EB:** embedded boundary, boundary conditions inside the simulation box, e.g. following material surfaces
 * **EM:** electromagnetic, e.g. EM PIC
 * **ES:** electrostatic, e.g. ES PIC

Source/WarpX.H

@@ -1035,17 +1035,46 @@ private:
     amrex::Vector<std::array< std::unique_ptr<amrex::MultiFab>, 3 > > Efield_avg_fp;
     amrex::Vector<std::array< std::unique_ptr<amrex::MultiFab>, 3 > > Bfield_avg_fp;
 
-    //EB grid info
-    amrex::Vector<std::array< std::unique_ptr<amrex::MultiFab>, 3 > > Venl;
+    //! EB: Lengths of the mesh edges
     amrex::Vector<std::array< std::unique_ptr<amrex::MultiFab>, 3 > > m_edge_lengths;
+    //! EB: Areas of the mesh faces
     amrex::Vector<std::array< std::unique_ptr<amrex::MultiFab>, 3 > > m_face_areas;
+
+    /** EB: for every mesh face flag_info_face contains a:
+     *           * 0 if the face needs to be extended
+     *          * 1 if the face is large enough to lend area to other faces
+     *          * 2 if the face is actually intruded by other face
+     * It is initialized in WarpX::MarkCells
+     * This is only used for the ECT solver.*/
     amrex::Vector<std::array< std::unique_ptr<amrex::iMultiFab>, 3 > > m_flag_info_face;
+    /** EB: for every mesh face face flag_ext_face contains a:
+     *          * 1 if the face needs to be extended
+     *          * 0 otherwise
+     * It is initialized in WarpX::MarkCells and then modified in WarpX::ComputeOneWayExtensions
+     * and in WarpX::ComputeEightWaysExtensions
+     * This is only used for the ECT solver.*/
     amrex::Vector<std::array< std::unique_ptr<amrex::iMultiFab>, 3 > > m_flag_ext_face;
+    /** EB: m_area_mod contains the modified areas of the mesh faces, i.e. if a face is enlarged it
+     * contains the area of the enlarged face
+     * This is only used for the ECT solver.*/
     amrex::Vector<std::array< std::unique_ptr<amrex::MultiFab>, 3 > > m_area_mod;
+    /** EB: m_borrowing contains the info about the enlarged cells, i.e. for every enlarged cell it
+     * contains the info of which neighbors are being intruded (and the amount of borrowed area).
+     * This is only used for the ECT solver.*/
     amrex::Vector<std::array< std::unique_ptr<amrex::LayoutData<FaceInfoBox> >, 3 > > m_borrowing;
 
-    //This is just needed for the ECT solver
+    /** ECTRhofield is needed only by the ect
+     * solver and it contains the electromotive force density for every mesh face.
+     * The name ECTRhofield has been used to comply with the notation of the paper
+     * https://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=4463918 (page 9, equation 4
+     * and below).
+     * Although it's called rho it has nothing to do with the charge density!
+     * This is only used for the ECT solver.*/
     amrex::Vector<std::array< std::unique_ptr<amrex::MultiFab>, 3 > > ECTRhofield;
+    /** Venl contains the electromotive force for every mesh face, i.e. every entry is
+     * the corresponding entry in ECTRhofield multiplied by the total area (possibly with enlargement)
+     * This is only used for the ECT solver.*/
+    amrex::Vector<std::array< std::unique_ptr<amrex::MultiFab>, 3 > > Venl;
 
     //EB level set
     amrex::Vector<std::unique_ptr<amrex::MultiFab> > m_distance_to_eb;

Source/WarpX.cpp

@@ -1637,11 +1637,7 @@ WarpX::AllocLevelMFs (int lev, const BoxArray& ba, const DistributionMapping& dm
             Venl[lev][0] = std::make_unique<MultiFab>(amrex::convert(ba, Bx_nodal_flag), dm, ncomps, ngE, tag("Venl[x]"));
             Venl[lev][1] = std::make_unique<MultiFab>(amrex::convert(ba, By_nodal_flag), dm, ncomps, ngE, tag("Venl[y]"));
             Venl[lev][2] = std::make_unique<MultiFab>(amrex::convert(ba, Bz_nodal_flag), dm, ncomps, ngE, tag("Venl[z]"));
-            // DISCLAIMER: ECTRhofield is NOT the charge density. This multifab is needed only by the ect
-            // solver and it represents the electromotive force density. The name ECTRhofield has been used
-            // to comply with the notation of the paper
-            // https://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=4463918 (page 9, equation 4
-            // and below).
+
             ECTRhofield[lev][0] = std::make_unique<MultiFab>(amrex::convert(ba, Bx_nodal_flag), dm, ncomps, ngE, tag("ECTRhofield[x]"));
             ECTRhofield[lev][1] = std::make_unique<MultiFab>(amrex::convert(ba, By_nodal_flag), dm, ncomps, ngE, tag("ECTRhofield[y]"));
             ECTRhofield[lev][2] = std::make_unique<MultiFab>(amrex::convert(ba, Bz_nodal_flag), dm, ncomps, ngE, tag("ECTRhofield[z]"));