Deploying to main from @ AMReX-Codes/amrex@1be7257 🚀

amrex/docs_html/Basics.html

@@ -2349,10 +2349,25 @@ <h2>Fine Mask<a class="headerlink" href="#fine-mask" title="Permalink to this he
 </section>
 <section id="memory-allocation">
 <h1>Memory Allocation<a class="headerlink" href="#memory-allocation" title="Permalink to this heading"></a></h1>
-<p>Some constructors of <code class="code highlight cpp c++ docutils literal highlight-c++"><span class="n">MultiFab</span><span class="w"></span></code>, <code class="code highlight cpp c++ docutils literal highlight-c++"><span class="n">FArrayBox</span><span class="w"></span></code>, etc. can take
-an <code class="code highlight cpp c++ docutils literal highlight-c++"><span class="n">Arena</span><span class="w"></span></code> argument for memory allocation. This is usually not
-important for CPU codes, but very important for GPU codes. We will
-present more details in <a class="reference internal" href="GPU.html#sec-gpu-memory"><span class="std std-ref">Memory Allocation</span></a> in Chapter GPU.</p>
+<p>Some constructors of <code class="code highlight cpp c++ docutils literal highlight-c++"><span class="n">MultiFab</span><span class="w"></span></code>, <code class="code highlight cpp c++ docutils literal highlight-c++"><span class="n">FArrayBox</span><span class="w"></span></code>, etc. can take an
+<code class="code highlight cpp c++ docutils literal highlight-c++"><span class="n">Arena</span><span class="w"></span></code> argument for memory allocation. Some constructors of
+<code class="code highlight cpp c++ docutils literal highlight-c++"><span class="n">MultiFab</span><span class="w"></span></code> can take an optional argument <code class="code highlight cpp c++ docutils literal highlight-c++"><span class="n">MFInfo</span><span class="w"></span></code>, which can be
+used to set the arena. This is usually not important for CPU codes, but
+very important for GPU codes. We will present more details about memory
+arenas in <a class="reference internal" href="GPU.html#sec-gpu-memory"><span class="std std-ref">Memory Allocation</span></a> in Chapter GPU.</p>
+<p>Every <code class="code highlight cpp c++ docutils literal highlight-c++"><span class="n">FArrayBox</span><span class="w"></span></code> in a <code class="code highlight cpp c++ docutils literal highlight-c++"><span class="n">MultiFab</span><span class="w"></span></code> has a contiguous chunk of memory
+for floating point data, whereas by default <code class="code highlight cpp c++ docutils literal highlight-c++"><span class="n">MultiFab</span><span class="w"></span></code> as a collection
+of multiple <code class="code highlight cpp c++ docutils literal highlight-c++"><span class="n">FArrayBox</span><span class="w"></span></code>s does not store all floating point data in
+contiguous chunk of memory. This behavior can be changed for all
+<code class="code highlight cpp c++ docutils literal highlight-c++"><span class="n">MultiFab</span><span class="w"></span></code>s with the <code class="code highlight cpp c++ docutils literal highlight-c++"><span class="n">ParmParse</span><span class="w"></span></code> parameter,
+<code class="docutils literal notranslate"><span class="pre">amrex.mf.alloc_single_chunk=1</span></code>, or for a specific <code class="code highlight cpp c++ docutils literal highlight-c++"><span class="n">MultiFab</span><span class="w"></span></code> by
+passing a <code class="code highlight cpp c++ docutils literal highlight-c++"><span class="n">MFInfo</span><span class="w"></span></code> object (e.g.,
+<code class="docutils literal notranslate"><span class="pre">MFInfo().SetAllocSingleChunk(true)</span></code>) to the constructor. One can call
+<code class="code highlight cpp c++ docutils literal highlight-c++"><span class="n">MultiFab</span><span class="o">::</span><span class="n">singleChunkPtr</span><span class="p">()</span><span class="w"></span></code> to obtain a pointer to the single chunk
+memory. Note that the function returns a null pointer if the <code class="code highlight cpp c++ docutils literal highlight-c++"><span class="n">MultiFab</span><span class="w"></span></code>
+does not use a single contiguous chunk of memory. One can also call
+<code class="code highlight cpp c++ docutils literal highlight-c++"><span class="n">MultiFab</span><span class="o">::</span><span class="n">singleChunkSize</span><span class="p">()</span><span class="w"></span></code> to obtain the size in bytes of the single
+chunk memory.</p>
 <p>AMReX has a Fortran module, <code class="code highlight fortran docutils literal highlight-fortran"><span class="n">amrex_mempool_module</span><span class="w"></span></code> that can be used to
 allocate memory for Fortran pointers. The reason that such a module exists in
 AMReX is that memory allocation is often very slow in multi-threaded OpenMP

amrex/docs_html/BuildingAMReX.html

@@ -780,8 +780,7 @@ <h2>ccache<a class="headerlink" href="#ccache" title="Permalink to this heading"
 <tr class="row-even"><td><p>AMReX_FLATTEN_FOR</p></td>
 <td><p>Enable flattening of ParallelFor and similar
 functions for host code</p></td>
-<td><p>YES unless for Debug
-build</p></td>
+<td><p>NO</p></td>
 <td><p>YES, NO</p></td>
 </tr>
 </tbody>

amrex/docs_html/_sources/Basics.rst.txt

@@ -2735,10 +2735,26 @@ covered by fine level grids.
 Memory Allocation
 =================
 
-Some constructors of :cpp:`MultiFab`, :cpp:`FArrayBox`, etc. can take
-an :cpp:`Arena` argument for memory allocation. This is usually not
-important for CPU codes, but very important for GPU codes. We will
-present more details in :ref:`sec:gpu:memory` in Chapter GPU.
+Some constructors of :cpp:`MultiFab`, :cpp:`FArrayBox`, etc. can take an
+:cpp:`Arena` argument for memory allocation. Some constructors of
+:cpp:`MultiFab` can take an optional argument :cpp:`MFInfo`, which can be
+used to set the arena. This is usually not important for CPU codes, but
+very important for GPU codes. We will present more details about memory
+arenas in :ref:`sec:gpu:memory` in Chapter GPU.
+
+Every :cpp:`FArrayBox` in a :cpp:`MultiFab` has a contiguous chunk of memory
+for floating point data, whereas by default :cpp:`MultiFab` as a collection
+of multiple :cpp:`FArrayBox`\ s does not store all floating point data in
+contiguous chunk of memory. This behavior can be changed for all
+:cpp:`MultiFab`\ s with the :cpp:`ParmParse` parameter,
+``amrex.mf.alloc_single_chunk=1``, or for a specific :cpp:`MultiFab` by
+passing a :cpp:`MFInfo` object (e.g.,
+``MFInfo().SetAllocSingleChunk(true)``) to the constructor. One can call
+:cpp:`MultiFab::singleChunkPtr()` to obtain a pointer to the single chunk
+memory. Note that the function returns a null pointer if the :cpp:`MultiFab`
+does not use a single contiguous chunk of memory. One can also call
+:cpp:`MultiFab::singleChunkSize()` to obtain the size in bytes of the single
+chunk memory.
 
 AMReX has a Fortran module, :fortran:`amrex_mempool_module` that can be used to
 allocate memory for Fortran pointers. The reason that such a module exists in

amrex/docs_html/_sources/BuildingAMReX.rst.txt

@@ -532,8 +532,8 @@ The list of available options is reported in the :ref:`table <tab:cmakevar>` bel
  +------------------------------+-------------------------------------------------+-------------------------+-----------------------+
  | AMReX_PROBINIT | Enable support for probin file | Platform dependent | YES, NO |
  +------------------------------+-------------------------------------------------+-------------------------+-----------------------+
- | AMReX_FLATTEN_FOR | Enable flattening of ParallelFor and similar | YES unless for Debug | YES, NO |
- | | functions for host code | build | |
+ | AMReX_FLATTEN_FOR | Enable flattening of ParallelFor and similar | NO  | YES, NO |
+ | | functions for host code |   | |
  +------------------------------+-------------------------------------------------+-------------------------+-----------------------+
 .. raw:: latex
 

amrex/docs_html/doxygen/AMReX__AmrLevel_8H_source.html

@@ -739,8 +739,8 @@
 <div class="ttc" id="aclassamrex_1_1DistributionMapping_html"><div class="ttname"><a href="classamrex_1_1DistributionMapping.html">amrex::DistributionMapping</a></div><div class="ttdoc">Calculates the distribution of FABs to MPI processes.</div><div class="ttdef"><b>Definition:</b> AMReX_DistributionMapping.H:41</div></div>
 <div class="ttc" id="aclassamrex_1_1EBFArrayBoxFactory_html"><div class="ttname"><a href="classamrex_1_1EBFArrayBoxFactory.html">amrex::EBFArrayBoxFactory</a></div><div class="ttdef"><b>Definition:</b> AMReX_EBFabFactory.H:22</div></div>
 <div class="ttc" id="aclassamrex_1_1FArrayBox_html"><div class="ttname"><a href="classamrex_1_1FArrayBox.html">amrex::FArrayBox</a></div><div class="ttdoc">A Fortran Array of REALs.</div><div class="ttdef"><b>Definition:</b> AMReX_FArrayBox.H:229</div></div>
-<div class="ttc" id="aclassamrex_1_1FabArrayBase_html_a92cef599b0ae34401a5463ec6fddc606"><div class="ttname"><a href="classamrex_1_1FabArrayBase.html#a92cef599b0ae34401a5463ec6fddc606">amrex::FabArrayBase::nGrow</a></div><div class="ttdeci">int nGrow(int direction=0) const noexcept</div><div class="ttdoc">Return the grow factor that defines the region of definition.</div><div class="ttdef"><b>Definition:</b> AMReX_FabArrayBase.H:76</div></div>
-<div class="ttc" id="aclassamrex_1_1FabArrayBase_html_aec6647af0d0a9f2d760d502a8975d6f1"><div class="ttname"><a href="classamrex_1_1FabArrayBase.html#aec6647af0d0a9f2d760d502a8975d6f1">amrex::FabArrayBase::nComp</a></div><div class="ttdeci">int nComp() const noexcept</div><div class="ttdoc">Return number of variables (aka components) associated with each point.</div><div class="ttdef"><b>Definition:</b> AMReX_FabArrayBase.H:81</div></div>
+<div class="ttc" id="aclassamrex_1_1FabArrayBase_html_a92cef599b0ae34401a5463ec6fddc606"><div class="ttname"><a href="classamrex_1_1FabArrayBase.html#a92cef599b0ae34401a5463ec6fddc606">amrex::FabArrayBase::nGrow</a></div><div class="ttdeci">int nGrow(int direction=0) const noexcept</div><div class="ttdoc">Return the grow factor that defines the region of definition.</div><div class="ttdef"><b>Definition:</b> AMReX_FabArrayBase.H:77</div></div>
+<div class="ttc" id="aclassamrex_1_1FabArrayBase_html_aec6647af0d0a9f2d760d502a8975d6f1"><div class="ttname"><a href="classamrex_1_1FabArrayBase.html#aec6647af0d0a9f2d760d502a8975d6f1">amrex::FabArrayBase::nComp</a></div><div class="ttdeci">int nComp() const noexcept</div><div class="ttdoc">Return number of variables (aka components) associated with each point.</div><div class="ttdef"><b>Definition:</b> AMReX_FabArrayBase.H:82</div></div>
 <div class="ttc" id="aclassamrex_1_1FabFactory_html"><div class="ttname"><a href="classamrex_1_1FabFactory.html">amrex::FabFactory&lt; FArrayBox &gt;</a></div></div>
 <div class="ttc" id="aclassamrex_1_1FillPatchIteratorHelper_html"><div class="ttname"><a href="classamrex_1_1FillPatchIteratorHelper.html">amrex::FillPatchIteratorHelper</a></div><div class="ttdef"><b>Definition:</b> AMReX_AmrLevel.H:564</div></div>
 <div class="ttc" id="aclassamrex_1_1FillPatchIteratorHelper_html_a01e9092eaa18c9803bd850d15dbd64c8"><div class="ttname"><a href="classamrex_1_1FillPatchIteratorHelper.html#a01e9092eaa18c9803bd850d15dbd64c8">amrex::FillPatchIteratorHelper::Initialize</a></div><div class="ttdeci">void Initialize(int boxGrow, Real time, int idx, int scomp, int ncomp, InterpBase *mapper)</div><div class="ttdef"><b>Definition:</b> AMReX_AmrLevel.cpp:738</div></div>

amrex/docs_html/doxygen/AMReX__BoxArray_8H_source.html

@@ -890,7 +890,7 @@
 <div class="ttc" id="aclassamrex_1_1BoxArray_html_afed0e52f6570fe4960ce4758f5558761"><div class="ttname"><a href="classamrex_1_1BoxArray.html#afed0e52f6570fe4960ce4758f5558761">amrex::BoxArray::clear</a></div><div class="ttdeci">void clear()</div><div class="ttdoc">Remove all Boxes from the BoxArray.</div><div class="ttdef"><b>Definition:</b> AMReX_BoxArray.cpp:369</div></div>
 <div class="ttc" id="aclassamrex_1_1BoxList_html"><div class="ttname"><a href="classamrex_1_1BoxList.html">amrex::BoxList</a></div><div class="ttdoc">A class for managing a List of Boxes that share a common IndexType. This class implements operations ...</div><div class="ttdef"><b>Definition:</b> AMReX_BoxList.H:52</div></div>
 <div class="ttc" id="aclassamrex_1_1Box_html"><div class="ttname"><a href="classamrex_1_1Box.html">amrex::Box</a></div><div class="ttdoc">A Rectangular Domain on an Integer Lattice.</div><div class="ttdef"><b>Definition:</b> AMReX_Box.H:39</div></div>
-<div class="ttc" id="aclassamrex_1_1FabArrayBase_html"><div class="ttname"><a href="classamrex_1_1FabArrayBase.html">amrex::FabArrayBase</a></div><div class="ttdoc">Base class for FabArray.</div><div class="ttdef"><b>Definition:</b> AMReX_FabArrayBase.H:40</div></div>
+<div class="ttc" id="aclassamrex_1_1FabArrayBase_html"><div class="ttname"><a href="classamrex_1_1FabArrayBase.html">amrex::FabArrayBase</a></div><div class="ttdoc">Base class for FabArray.</div><div class="ttdef"><b>Definition:</b> AMReX_FabArrayBase.H:41</div></div>
 <div class="ttc" id="aclassamrex_1_1IndexType_html"><div class="ttname"><a href="classamrex_1_1IndexType.html">amrex::IndexType</a></div><div class="ttdoc">Cell-Based or Node-Based Indices.</div><div class="ttdef"><b>Definition:</b> AMReX_IndexType.H:23</div></div>
 <div class="ttc" id="aclassamrex_1_1IndexType_html_a3ddfa522c3996c79af3aa5985c8af10a"><div class="ttname"><a href="classamrex_1_1IndexType.html#a3ddfa522c3996c79af3aa5985c8af10a">amrex::IndexType::ixType</a></div><div class="ttdeci">AMREX_GPU_HOST_DEVICE AMREX_FORCE_INLINE CellIndex ixType(int dir) const noexcept</div><div class="ttdoc">Returns the CellIndex in direction dir.</div><div class="ttdef"><b>Definition:</b> AMReX_IndexType.H:97</div></div>
 <div class="ttc" id="aclassamrex_1_1IntVect_1_1shift__hasher_html"><div class="ttname"><a href="classamrex_1_1IntVect_1_1shift__hasher.html">amrex::IntVect::shift_hasher</a></div><div class="ttdef"><b>Definition:</b> AMReX_IntVect.H:50</div></div>

amrex/docs_html/doxygen/AMReX__COORDSYS__1D__C_8H_source.html

@@ -243,7 +243,7 @@
 <div class="ttc" id="anamespaceamrex_html_a6ce6b4176121c2c23327903a8139af0c"><div class="ttname"><a href="namespaceamrex.html#a6ce6b4176121c2c23327903a8139af0c">amrex::ubound</a></div><div class="ttdeci">AMREX_GPU_HOST_DEVICE AMREX_FORCE_INLINE Dim3 ubound(Array4&lt; T &gt; const &amp;a) noexcept</div><div class="ttdef"><b>Definition:</b> AMReX_Array4.H:279</div></div>
 <div class="ttc" id="anamespaceamrex_html_a71600c8a528e0f1863154e4cf0183cbc"><div class="ttname"><a href="namespaceamrex.html#a71600c8a528e0f1863154e4cf0183cbc">amrex::lbound</a></div><div class="ttdeci">AMREX_GPU_HOST_DEVICE AMREX_FORCE_INLINE Dim3 lbound(Array4&lt; T &gt; const &amp;a) noexcept</div><div class="ttdef"><b>Definition:</b> AMReX_Array4.H:272</div></div>
 <div class="ttc" id="anamespaceamrex_html_ad42f89d350fa1e06dfc8594fe3021a64"><div class="ttname"><a href="namespaceamrex.html#ad42f89d350fa1e06dfc8594fe3021a64">amrex::amrex_setdloga</a></div><div class="ttdeci">AMREX_GPU_HOST_DEVICE void amrex_setdloga(Box const &amp;bx, Array4&lt; Real &gt; const &amp;dloga, GpuArray&lt; Real, 1 &gt; const &amp;offset, GpuArray&lt; Real, 1 &gt; const &amp;dx, const int, const int coord) noexcept</div><div class="ttdef"><b>Definition:</b> AMReX_COORDSYS_1D_C.H:96</div></div>
-<div class="ttc" id="astructamrex_1_1Array4_html"><div class="ttname"><a href="structamrex_1_1Array4.html">amrex::Array4&lt; Real &gt;</a></div></div>
+<div class="ttc" id="astructamrex_1_1Array4_html"><div class="ttname"><a href="structamrex_1_1Array4.html">amrex::Array4</a></div><div class="ttdef"><b>Definition:</b> AMReX_Array4.H:61</div></div>
 <div class="ttc" id="astructamrex_1_1GpuArray_html"><div class="ttname"><a href="structamrex_1_1GpuArray.html">amrex::GpuArray</a></div><div class="ttdef"><b>Definition:</b> AMReX_Array.H:33</div></div>
 </div><!-- fragment --></div><!-- contents -->
 </div><!-- doc-content -->

amrex/docs_html/doxygen/AMReX__COORDSYS__2D__C_8H_source.html

@@ -327,7 +327,7 @@
 <div class="ttc" id="anamespaceamrex_html_a6ce6b4176121c2c23327903a8139af0c"><div class="ttname"><a href="namespaceamrex.html#a6ce6b4176121c2c23327903a8139af0c">amrex::ubound</a></div><div class="ttdeci">AMREX_GPU_HOST_DEVICE AMREX_FORCE_INLINE Dim3 ubound(Array4&lt; T &gt; const &amp;a) noexcept</div><div class="ttdef"><b>Definition:</b> AMReX_Array4.H:279</div></div>
 <div class="ttc" id="anamespaceamrex_html_a71600c8a528e0f1863154e4cf0183cbc"><div class="ttname"><a href="namespaceamrex.html#a71600c8a528e0f1863154e4cf0183cbc">amrex::lbound</a></div><div class="ttdeci">AMREX_GPU_HOST_DEVICE AMREX_FORCE_INLINE Dim3 lbound(Array4&lt; T &gt; const &amp;a) noexcept</div><div class="ttdef"><b>Definition:</b> AMReX_Array4.H:272</div></div>
 <div class="ttc" id="anamespaceamrex_html_ad42f89d350fa1e06dfc8594fe3021a64"><div class="ttname"><a href="namespaceamrex.html#ad42f89d350fa1e06dfc8594fe3021a64">amrex::amrex_setdloga</a></div><div class="ttdeci">AMREX_GPU_HOST_DEVICE void amrex_setdloga(Box const &amp;bx, Array4&lt; Real &gt; const &amp;dloga, GpuArray&lt; Real, 1 &gt; const &amp;offset, GpuArray&lt; Real, 1 &gt; const &amp;dx, const int, const int coord) noexcept</div><div class="ttdef"><b>Definition:</b> AMReX_COORDSYS_1D_C.H:96</div></div>
-<div class="ttc" id="astructamrex_1_1Array4_html"><div class="ttname"><a href="structamrex_1_1Array4.html">amrex::Array4&lt; Real &gt;</a></div></div>
+<div class="ttc" id="astructamrex_1_1Array4_html"><div class="ttname"><a href="structamrex_1_1Array4.html">amrex::Array4</a></div><div class="ttdef"><b>Definition:</b> AMReX_Array4.H:61</div></div>
 <div class="ttc" id="astructamrex_1_1GpuArray_html"><div class="ttname"><a href="structamrex_1_1GpuArray.html">amrex::GpuArray</a></div><div class="ttdef"><b>Definition:</b> AMReX_Array.H:33</div></div>
 </div><!-- fragment --></div><!-- contents -->
 </div><!-- doc-content -->