ECP-WarpX · ax3l · Jun 25, 2021 · May 9, 2021 · May 10, 2021 · May 10, 2021
diff --git a/Docs/source/developers/repo_organization.rst b/Docs/source/developers/repo_organization.rst
@@ -28,15 +28,63 @@ All WarpX header files need to be specified relative to the ``Source/`` director
 - e.g. ``#include "Utils/WarpXConst.H"``
 - files in the same directory as the including header-file can be included with ``#include "FileName.H"``
 
-The `include order <https://github.com/ECP-WarpX/WarpX/pull/874#issuecomment-607038803>`_ and `proper quotation marks <https://gcc.gnu.org/onlinedocs/cpp/Include-Syntax.html>`_ are:
+By default, in a ``MyName.cpp`` source file we do not include headers already included in ``MyName.H``. Besides this exception, if a function or a class
+is used in a source file, the header file containing its declaration must be included, unless the inclusion of a façade header is more appropriate. This is
+sometimes the case for AMReX headers. For instance ``AMReX_GpuLaunch.H`` is a façade header for ``AMReX_GpuLaunchFunctsC.H`` and ``AMReX_GpuLaunchFunctsG.H``, which
+contain respectively the CPU and the GPU implemetation of some methods, and which should not be included directly.
+Whenever possible, forward declarations headers are included instead of the actual headers, in order to save compilation time (see dedicated section below). In WarpX forward
+declaration headers have the suffix ``*_fwd.H``, while in AMReX they have the suffix ``*Fwd.H``.
+The include order (see `PR #874 <https://github.com/ECP-WarpX/WarpX/pull/874#issuecomment-607038803>` _ and `PR #1947 <https://github.com/ECP-WarpX/WarpX/pull/1947>` ) _ and `proper quotation marks <https://gcc.gnu.org/onlinedocs/cpp/Include-Syntax.html>`_ are:
 
-1. In a ``<MyName>.cpp`` file: ``#include "<MyName>.H"`` (its header) then
+1. In a ``MyName.cpp`` file: ``#include "MyName.H"`` (its header) then
 2. (further) WarpX header files ``#include "..."`` then
-3. PICSAR and AMReX header files ``#include <...>`` then
-4. other third party includes ``#include <...>`` then
-5. standard library includes, e.g. ``#include <vector>``
+3. WarpX forward declaration header files ``#include "..._fwd.H"``
+4. AMReX header files ``#include <...>`` then
+5. AMReX forward declaration header files ``#include <...Fwd.H>`` then
+6. PICSAR header files ``#include <...>`` then
+7. other third party includes ``#include <...>`` then
+8. standard library includes, e.g. ``#include <vector>``
 
-For details why this is needed, please see `PR #874 <https://github.com/ECP-WarpX/WarpX/pull/874#issuecomment-607038803>`_, the `LLVM guidelines <https://llvm.org/docs/CodingStandards.html#include-style>`_, and `include-what-you-use <https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/WhyIWYU.md>`_.
+1. In a ``MyName.H`` file: ``#include "MyName_fwd.H"`` (the corresponding forward declaration header, if it exists) then
+2. WarpX header files ``#include "..."`` then
+3. WarpX forward declaration header files ``#include "..._fwd.H"``
+4. AMReX header files ``#include <...>`` then
+5. AMReX forward declaration header files ``#include <...Fwd.H>`` then
+6. PICSAR header files ``#include <...>`` then
+7. other third party includes ``#include <...>`` then
+8. standard library includes, e.g. ``#include <vector>``
+
+Each of these groups of header files should ideally be sorted alphabetically, and a blank line should be placed between the groups.
+
+For details why this is needed, please see `PR #874 <https://github.com/ECP-WarpX/WarpX/pull/874#issuecomment-607038803>`_, `PR #1947 <https://github.com/ECP-WarpX/WarpX/pull/1947>`_, the `LLVM guidelines <https://llvm.org/docs/CodingStandards.html#include-style>`_, and `include-what-you-use <https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/WhyIWYU.md>`_.
+
+Forward declaration headers
+------------
+Forward declarations can be used when a header file needs only to know that a given class exists, without any further detail (e.g., when only a pointer to an instance of
+that class is used). Forward declaration headers are a convenient way to organize forward declarations. If a forward declaration is needed for a given class ``MyClass``, declared in ``MyClass.H``,
+the forward declaration should appear in a header file named ``MyClass_fwd.H``, placed in the same folder containing ``MyClass.H``.
+Below we provide a simple example:
+
+``MyClass_fwd.H``:
+.. code-block:: cpp
+  class MyClass;
+
+``MyClass.H``:
+.. code-block:: cpp
+  #include “MyClass_fwd.H”
+  #include “someHeader.H”
+  class MyClass{/* stuff */};
+
+``MyClass.cpp``:
+.. code-block:: cpp
+  #include “MyClass.H”
+  class MyClass{/* stuff */};
+
+Usage:
+``SimpleUsage.H``
+.. code-block:: cpp
+  #include “MyClass_fwd.H”
+  #include <memory>
 
 WarpX-specific vocabulary
 -------------------------

diff --git a/Source/BoundaryConditions/PML.H b/Source/BoundaryConditions/PML.H
@@ -9,17 +9,28 @@
 #ifndef WARPX_PML_H_
 #define WARPX_PML_H_
 
-#include "Utils/WarpXProfilerWrapper.H"
+#include "PML_fwd.H"
 
 #ifdef WARPX_USE_PSATD
 #   include "FieldSolver/SpectralSolver/SpectralSolver.H"
 #endif
 
 #include <AMReX_MultiFab.H>
-#include <AMReX_Geometry.H>
+#include <AMReX_BoxArray.H>
+#include <AMReX_Config.H>
+#include <AMReX_FabArray.H>
+#include <AMReX_FabFactory.H>
+#include <AMReX_GpuContainers.H>
+#include <AMReX_IntVect.H>
+#include <AMReX_REAL.H>
+#include <AMReX_Vector.H>
 
-#include <array>
+#include <AMReX_BaseFwd.H>
 
+#include <array>
+#include <memory>
+#include <string>
+#include <vector>
 
 struct Sigma : amrex::Gpu::DeviceVector<amrex::Real>
 {
@@ -170,6 +181,8 @@ public:
 
     static void Exchange (amrex::MultiFab& pml, amrex::MultiFab& reg, const amrex::Geometry& geom, int do_pml_in_domain);
 
+    ~PML () = default;
+
 private:
     bool m_ok;
 

diff --git a/Source/BoundaryConditions/PML.cpp b/Source/BoundaryConditions/PML.cpp
@@ -6,23 +6,46 @@
  *
  * License: BSD-3-Clause-LBNL
  */
+#include "PML.H"
+
 #include "BoundaryConditions/PML.H"
 #include "BoundaryConditions/PMLComponent.H"
-#include "Utils/WarpXConst.H"
+#ifdef WARPX_USE_PSATD
+#   include "FieldSolver/SpectralSolver/SpectralFieldData.H"
+#endif
 #include "Utils/WarpXAlgorithmSelection.H"
+#include "Utils/WarpXConst.H"
+#include "Utils/WarpXProfilerWrapper.H"
 #include "WarpX.H"
 
 #include <AMReX.H>
-#include <AMReX_Print.H>
+#include <AMReX_Algorithm.H>
+#include <AMReX_Array.H>
+#include <AMReX_Array4.H>
+#include <AMReX_BLassert.H>
+#include <AMReX_Box.H>
+#include <AMReX_BoxList.H>
+#include <AMReX_DistributionMapping.H>
+#include <AMReX_FArrayBox.H>
+#include <AMReX_FBI.H>
+#include <AMReX_FabArrayBase.H>
+#include <AMReX_Geometry.H>
+#include <AMReX_GpuControl.H>
+#include <AMReX_GpuDevice.H>
+#include <AMReX_GpuLaunch.H>
+#include <AMReX_GpuQualifiers.H>
+#include <AMReX_IndexType.H>
+#include <AMReX_MFIter.H>
+#include <AMReX_ParmParse.H>
+#include <AMReX_RealVect.H>
+#include <AMReX_SPACE.H>
 #include <AMReX_VisMF.H>
-
-#ifdef AMREX_USE_OMP
-#   include <omp.h>
-#endif
+#include <AMReX_ccse-mpi.H>
 
 #include <algorithm>
+#include <cmath>
 #include <memory>
-
+#include <utility>
 
 using namespace amrex;
 

diff --git a/Source/BoundaryConditions/PML_current.H b/Source/BoundaryConditions/PML_current.H
@@ -9,6 +9,7 @@
 #define PML_CURRENT_H_
 
 #include "BoundaryConditions/PMLComponent.H"
+
 #include <AMReX.H>
 #include <AMReX_FArrayBox.H>
 

diff --git a/Source/BoundaryConditions/PML_fwd.H b/Source/BoundaryConditions/PML_fwd.H
@@ -0,0 +1,16 @@
+/* Copyright 2021 Luca Fedeli
+ *
+ * This file is part of WarpX.
+ *
+ * License: BSD-3-Clause-LBNL
+ */
+
+struct Sigma;
+struct SigmaBox;
+
+class SigmaBoxFactory;
+class MultiSigmaBox;
+
+enum struct PatchType;
+
+class PML;
diff --git a/Source/BoundaryConditions/WarpXEvolvePML.cpp b/Source/BoundaryConditions/WarpXEvolvePML.cpp
@@ -6,18 +6,33 @@
  * License: BSD-3-Clause-LBNL
  */
 #include "WarpX.H"
-#include "Utils/WarpXConst.H"
-#include "WarpX_PML_kernels.H"
 
+#include "BoundaryConditions/PML.H"
 #include "PML_current.H"
+#include "Utils/WarpXProfilerWrapper.H"
+#include "WarpX_PML_kernels.H"
 
 #ifdef BL_USE_SENSEI_INSITU
 #   include <AMReX_AmrMeshInSituBridge.H>
 #endif
-
-#include <cmath>
-#include <limits>
-
+#include <AMReX_Array4.H>
+#include <AMReX_Config.H>
+#include <AMReX_Extension.H>
+#include <AMReX_FabArray.H>
+#include <AMReX_GpuControl.H>
+#include <AMReX_GpuLaunch.H>
+#include <AMReX_GpuQualifiers.H>
+#include <AMReX_IndexType.H>
+#include <AMReX_IntVect.H>
+#include <AMReX_MFIter.H>
+#include <AMReX_MultiFab.H>
+#include <AMReX_REAL.H>
+#include <AMReX_Vector.H>
+
+#include <AMReX_BaseFwd.H>
+
+#include <array>
+#include <memory>
 
 using namespace amrex;
 

diff --git a/Source/BoundaryConditions/WarpXFieldBoundaries.cpp b/Source/BoundaryConditions/WarpXFieldBoundaries.cpp
@@ -1,8 +1,13 @@
 #include "WarpX.H"
+
 #include "WarpX_PEC.H"
-#include <AMReX.H>
+
+#include <AMReX_REAL.H>
 #include <AMReX_Vector.H>
-#include <AMReX_MultiFab.H>
+
+#include <array>
+#include <memory>
+
 using namespace amrex::literals;
 
 void WarpX::ApplyEfieldBoundary(const int lev, PatchType patch_type)

diff --git a/Source/BoundaryConditions/WarpX_PEC.H b/Source/BoundaryConditions/WarpX_PEC.H
@@ -4,6 +4,18 @@
 #include "WarpX.H"
 #include "Utils/WarpXAlgorithmSelection.H"
 
+#include <AMReX_Array.H>
+#include <AMReX_Array4.H>
+#include <AMReX_Config.H>
+#include <AMReX_Extension.H>
+#include <AMReX_GpuQualifiers.H>
+#include <AMReX_IntVect.H>
+#include <AMReX_REAL.H>
+
+#include <AMReX_BaseFwd.H>
+
+#include <array>
+#include <memory>
 
 namespace PEC {
 using namespace amrex;

diff --git a/Source/BoundaryConditions/WarpX_PEC.cpp b/Source/BoundaryConditions/WarpX_PEC.cpp
@@ -1,10 +1,18 @@
 #include "BoundaryConditions/WarpX_PEC.H"
+
 #include "WarpX.H"
-#include <AMReX.H>
-#include <AMReX_Vector.H>
+
+#include <AMReX_Box.H>
+#include <AMReX_Geometry.H>
+#include <AMReX_GpuControl.H>
+#include <AMReX_GpuLaunch.H>
+#include <AMReX_IndexType.H>
+#include <AMReX_MFIter.H>
 #include <AMReX_MultiFab.H>
-using namespace amrex::literals;
+#include <AMReX_SPACE.H>
+#include <AMReX_Vector.H>
 
+using namespace amrex::literals;
 
 bool
 PEC::isAnyBoundaryPEC() {

diff --git a/Source/BoundaryConditions/WarpX_PML_kernels.H b/Source/BoundaryConditions/WarpX_PML_kernels.H
@@ -9,6 +9,7 @@
 #define WARPX_PML_KERNELS_H_
 
 #include "BoundaryConditions/PMLComponent.H"
+
 #include <AMReX.H>
 #include <AMReX_FArrayBox.H>
 

diff --git a/Source/Diagnostics/BTD_Plotfile_Header_Impl.H b/Source/Diagnostics/BTD_Plotfile_Header_Impl.H
@@ -1,10 +1,15 @@
 #ifndef BTD_PLOTFILE_HEADER_IMPL_H
 #define BTD_PLOTFILE_HEADER_IMPL_H
 
-#include <string>
+#include <AMReX_Array.H>
+#include <AMReX_Box.H>
+#include <AMReX_BoxArray.H>
+#include <AMReX_Config.H>
+#include <AMReX_REAL.H>
+#include <AMReX_SPACE.H>
 #include <AMReX_Vector.H>
-#include <AMReX_MultiFab.H>
 
+#include <string>
 
 /**
  * \brief Class to read, modify, and write plotfile header when

diff --git a/Source/Diagnostics/BTD_Plotfile_Header_Impl.cpp b/Source/Diagnostics/BTD_Plotfile_Header_Impl.cpp
@@ -1,14 +1,17 @@
 #include "BTD_Plotfile_Header_Impl.H"
+
 #include "WarpX.H"
 
-#include <AMReX_ParallelDescriptor.H>
-#include <AMReX_PlotFileUtil.H>
+#include <AMReX.H>
 #include <AMReX_FileSystem.H>
 #include <AMReX_INT.H>
-#include <memory>
+#include <AMReX_Print.H>
+#include <AMReX_Utility.H>
 
-using namespace amrex::literals;
+#include <array>
+#include <istream>
 
+using namespace amrex::literals;
 
 BTDPlotfileHeaderImpl::BTDPlotfileHeaderImpl (std::string const & Headerfile_path)
     : m_Header_path(Headerfile_path)

diff --git a/Source/Diagnostics/BTDiagnostics.H b/Source/Diagnostics/BTDiagnostics.H
@@ -2,6 +2,20 @@
 #define WARPX_BTDIAGNOSTICS_H_
 
 #include "Diagnostics.H"
+#include "Diagnostics/ComputeDiagFunctors/ComputeDiagFunctor.H"
+#include "Utils/WarpXConst.H"
+
+#include <AMReX_Box.H>
+#include <AMReX_Geometry.H>
+#include <AMReX_IntVect.H>
+#include <AMReX_MultiFab.H>
+#include <AMReX_REAL.H>
+#include <AMReX_RealBox.H>
+#include <AMReX_Vector.H>
+
+#include <limits>
+#include <memory>
+#include <string>
 
 class
 BTDiagnostics final : public Diagnostics

diff --git a/Source/Diagnostics/BTDiagnostics.cpp b/Source/Diagnostics/BTDiagnostics.cpp
@@ -1,19 +1,35 @@
 #include "BTDiagnostics.H"
+
 #include "BTD_Plotfile_Header_Impl.H"
-#include "WarpX.H"
-#include "Utils/WarpXConst.H"
-#include "ComputeDiagFunctors/ComputeDiagFunctor.H"
-#include "ComputeDiagFunctors/CellCenterFunctor.H"
 #include "ComputeDiagFunctors/BackTransformFunctor.H"
+#include "ComputeDiagFunctors/CellCenterFunctor.H"
+#include "ComputeDiagFunctors/ComputeDiagFunctor.H"
 #include "ComputeDiagFunctors/RhoFunctor.H"
+#include "Diagnostics/Diagnostics.H"
+#include "Diagnostics/FlushFormats/FlushFormat.H"
 #include "Utils/CoarsenIO.H"
+#include "Utils/WarpXConst.H"
+#include "Utils/WarpXUtil.H"
+#include "WarpX.H"
 
-
+#include <AMReX.H>
+#include <AMReX_Algorithm.H>
+#include <AMReX_BLassert.H>
+#include <AMReX_BoxArray.H>
+#include <AMReX_Config.H>
+#include <AMReX_CoordSys.H>
+#include <AMReX_DistributionMapping.H>
+#include <AMReX_FileSystem.H>
+#include <AMReX_ParallelContext.H>
 #include <AMReX_ParallelDescriptor.H>
-#include <AMReX_PlotFileUtil.H>
-#include <AMReX_VisMF.H>
+#include <AMReX_ParmParse.H>
+#include <AMReX_Utility.H>
 
+#include <algorithm>
+#include <cmath>
+#include <cstdio>
 #include <memory>
+#include <vector>
 
 using namespace amrex::literals;