From 4b8dd0373188ca6505e3a9dfaaafbaf4b7fe5ffe Mon Sep 17 00:00:00 2001 From: Edward Basso Date: Tue, 28 Nov 2023 19:07:39 -0600 Subject: [PATCH] Comments on FAB-related classes and methods (#3636) New or updated comments for various FAB-related classes and methods. Descriptions are tweaked to match standard comment conventions and make IntelliSense happy. For example, some descriptions get moved to be just before their respective class declarations. --- Src/Base/AMReX_BaseFab.H | 96 ++++++++++++------------- Src/Base/AMReX_BoxArray.H | 12 ++-- Src/Base/AMReX_FArrayBox.H | 2 - Src/Base/AMReX_FabArray.H | 120 ++++++++++++++++---------------- Src/Base/AMReX_FabArrayBase.H | 6 ++ Src/Base/AMReX_FabConv.H | 86 +++++++++++------------ Src/Base/AMReX_MultiFab.H | 98 ++++++++++++++------------ Src/Base/AMReX_MultiFabUtil.H | 42 +++++++---- Src/Base/AMReX_MultiFabUtil.cpp | 3 - 9 files changed, 243 insertions(+), 222 deletions(-) diff --git a/Src/Base/AMReX_BaseFab.H b/Src/Base/AMReX_BaseFab.H index 99132038397..006d7639ad6 100644 --- a/Src/Base/AMReX_BaseFab.H +++ b/Src/Base/AMReX_BaseFab.H @@ -90,54 +90,6 @@ makeArray4 (T* p, Box const& bx, int ncomp) noexcept return Array4{p, amrex::begin(bx), amrex::end(bx), ncomp}; } -/** -* \brief A Fortran Array-like Object -* BaseFab emulates the Fortran array concept. -* Useful operations can be performed upon -* BaseFabs in C++, and they provide a convenient interface to -* Fortran when it is necessary to retreat into that language. - -* BaseFab is a template class. Through use of the -* template, a BaseFab may be based upon any class. So far at least, -* most applications have been based upon simple types like integers, -* real*4s, or real*8s. Most applications do not use BaseFabs -* directly, but utilize specialized classes derived from BaseFab. - -* Classes derived from BaseFab include FArrayBox, IArrayBox, TagBox, -* Mask, EBFArrayBox, EBCellFlag and CutFab. - -* BaseFab objects depend on the dimensionality of space -* (indirectly through the DOMAIN Box member). It is -* typical to define the macro SPACEDIM to be 1, 2, or 3 to indicate -* the dimension of space. See the discussion of class Box for more -* information. A BaseFab contains a Box DOMAIN, which indicates the -* integer indexing space over which the array is defined. A BaseFab -* also has NVAR components. By components, we mean that for each -* point in the rectangular indexing space, there are NVAR values -* associated with that point. A Fortran array corresponding to a -* BaseFab would have (SPACEDIM+1) dimensions. - -* By design, the array layout in a BaseFab mirrors that of a -* Fortran array. The first index (x direction for example) varies -* most rapidly, the next index (y direction), if any, varies next -* fastest. The component index varies last, after all the spatial -* indices. - -* It is sometimes convenient to be able to treat a sub-array within an -* existing BaseFab as a BaseFab in its own right. This is often -* referred to as aliasing the BaseFab. Note that when aliasing is -* used, the BaseFabs domain will not, in general, be the same as the -* parent BaseFabs domain, nor will the number of components. -* BaseFab is a dimension dependent class, so SPACEDIM must be -* defined as either 1, 2, or 3 when compiling. - -* This is NOT a polymorphic class. - -* It does NOT provide a copy constructor or assignment operator. - -* T MUST have a default constructor and an assignment operator. -*/ - template typename std::enable_if::value>::type placementNew (T* const /*ptr*/, Long /*n*/) @@ -178,6 +130,54 @@ placementDelete (T* const ptr, Long n) }); } +/** + * \brief A FortranArrayBox(FAB)-like object + * + * BaseFab emulates the Fortran array concept. + * Useful operations can be performed upon + * BaseFabs in C++, and they provide a convenient interface to + * Fortran when it is necessary to retreat into that language. + * + * BaseFab is a template class. Through use of the + * template, a BaseFab may be based upon any class. So far at least, + * most applications have been based upon simple types like integers, + * real*4s, or real*8s. Most applications do not use BaseFabs + * directly, but utilize specialized classes derived from BaseFab. + * + * Classes derived from BaseFab include FArrayBox, IArrayBox, TagBox, + * Mask, EBFArrayBox, EBCellFlag and CutFab. + * + * BaseFab objects depend on the dimensionality of space + * (indirectly through the DOMAIN Box member). It is + * typical to define the macro SPACEDIM to be 1, 2, or 3 to indicate + * the dimension of space. See the discussion of class Box for more + * information. A BaseFab contains a Box DOMAIN, which indicates the + * integer indexing space over which the array is defined. A BaseFab + * also has NVAR components. By components, we mean that for each + * point in the rectangular indexing space, there are NVAR values + * associated with that point. A Fortran array corresponding to a + * BaseFab would have (SPACEDIM+1) dimensions. + * + * By design, the array layout in a BaseFab mirrors that of a + * Fortran array. The first index (x direction for example) varies + * most rapidly, the next index (y direction), if any, varies next + * fastest. The component index varies last, after all the spatial + * indices. + * + * It is sometimes convenient to be able to treat a sub-array within an + * existing BaseFab as a BaseFab in its own right. This is often + * referred to as aliasing the BaseFab. Note that when aliasing is + * used, the BaseFabs domain will not, in general, be the same as the + * parent BaseFabs domain, nor will the number of components. + * BaseFab is a dimension dependent class, so SPACEDIM must be + * defined as either 1, 2, or 3 when compiling. + * + * This is NOT a polymorphic class. + * + * It does NOT provide a copy constructor or assignment operator. + * + * \tparam T MUST have a default constructor and an assignment operator. + */ template class BaseFab : public DataAllocator diff --git a/Src/Base/AMReX_BoxArray.H b/Src/Base/AMReX_BoxArray.H index 807cd9d8516..94358f580a4 100644 --- a/Src/Base/AMReX_BoxArray.H +++ b/Src/Base/AMReX_BoxArray.H @@ -515,16 +515,16 @@ struct BATransformer // for backward compatibility using BndryBATransformer = BATransformer; -/** -* \brief A collection of Boxes stored in an Array. It is a -* reference-counted concrete class, not a polymorphic one; i.e. you -* cannot use any of the List member functions with a BoxList. -*/ - class MFIter; class AmrMesh; class FabArrayBase; +/** + * \brief A collection of Boxes stored in an Array. + * + * It is a reference-counted concrete class, not a polymorphic one; i.e. you + * cannot use any of the List member functions with a BoxList. + */ class BoxArray { public: diff --git a/Src/Base/AMReX_FArrayBox.H b/Src/Base/AMReX_FArrayBox.H index b6dc4e887c8..2dda4e6b0a0 100644 --- a/Src/Base/AMReX_FArrayBox.H +++ b/Src/Base/AMReX_FArrayBox.H @@ -26,7 +26,6 @@ class FArrayBox; * primarily for FArrayBox implementers; i.e. user's shouldn't * call any of the member functions in this class directly. */ - class FABio // NOLINT(cppcoreguidelines-special-member-functions) { public: @@ -224,7 +223,6 @@ private: * This class does NOT provide a copy constructor or assignment operator, * but it has a move constructor. */ - class FArrayBox : public BaseFab diff --git a/Src/Base/AMReX_FabArray.H b/Src/Base/AMReX_FabArray.H index 96efc1f18fa..56300d4cfef 100644 --- a/Src/Base/AMReX_FabArray.H +++ b/Src/Base/AMReX_FabArray.H @@ -56,64 +56,11 @@ Long nBytesOwned (T const&) noexcept { return 0; } template Long nBytesOwned (BaseFab const& fab) noexcept { return fab.nBytesOwned(); } -/* - A Collection of Fortran Array-like Objects - - - The FabArray class implements a collection (stored as an array) of - Fortran array-like objects. The parameterized type FAB is intended to be - any class derived from BaseFab. For example, FAB may be a BaseFab of - integers, so we could write: - - FabArray > int_fabs; - - Then int_fabs is a FabArray that can hold a collection of BaseFab - objects. - - FabArray is not just a general container class for Fortran arrays. It is - intended to hold "grid" data for use in finite difference calculations in - which the data is defined on a union of (usually disjoint) rectangular - regions embedded in a uniform index space. This region, called the valid - region, is represented by a BoxArray. For the purposes of this discussion, - the Kth Box in the BoxArray represents the interior region of the Kth grid. - - Since the intent is to be used with finite difference calculations a - FabArray also includes the notion of a boundary region for each grid. The - boundary region is specified by the ngrow parameter which tells the FabArray - to allocate each FAB to be ngrow cells larger in all directions than the - underlying Box. The larger region covered by the union of all the FABs is - called the region of definition. The underlying notion is that the valid - region contains the grid interior data and the region of definition includes - the interior region plus the boundary areas. - - Operations are available to copy data from the valid regions into these - boundary areas where the two overlap. The number of components, that is, - the number of values that can be stored in each cell of a FAB, is either - given as an argument to the constructor or is inherent in the definition of - the underlying FAB. Each FAB in the FabArray will have the same number of - components. - - In summary, a FabArray is an array of FABs. The Kth element contains a FAB - that holds the data for the Kth grid, a Box that defines the valid region - of the Kth grid. - - A typical use for a FabArray would be to hold the solution vector or - right-hand-side when solving a linear system of equations on a union of - rectangular grids. The copy operations would be used to copy data from the - valid regions of neighboring grids into the boundary regions after each - relaxation step of the iterative method. If a multigrid method is used, a - FabArray could be used to hold the data at each level in the multigrid - hierarchy. - - This class is a concrete class not a polymorphic one. - - This class does NOT provide a copy constructor or assignment operator. -*/ - -// -// alloc: allocate memory or not -// +/** + * \brief FabArray memory allocation information + */ struct MFInfo { + // alloc: allocate memory or not bool alloc = true; Arena* arena = nullptr; Vector tags; @@ -314,6 +261,60 @@ Add (FabArray& dst, FabArray const& src, int srccomp, int dstcomp, int } } +/** + * \brief An Array of FortranArrayBox(FAB)-like Objects + * + * The FabArray class implements a collection (stored as an array) of + * Fortran array box-like ( \p FAB ) objects. The parameterized type \p FAB is intended to be + * any class derived from BaseFab. For example, \p FAB may be a BaseFab of + * integers, so we could write: + * + * FabArray > int_fabs; + * + * Then int_fabs is a FabArray that can hold a collection of BaseFab + * objects. + * + * FabArray is not just a general container class for Fortran arrays. It is + * intended to hold "grid" data for use in finite difference calculations in + * which the data is defined on a union of (usually disjoint) rectangular + * regions embedded in a uniform index space. This region, called the valid + * region, is represented by a BoxArray. For the purposes of this discussion, + * the Kth Box in the BoxArray represents the interior region of the Kth grid. + * + * Since the intent is to be used with finite difference calculations a + * FabArray also includes the notion of a boundary region for each grid. The + * boundary region is specified by the ngrow parameter which tells the FabArray + * to allocate each \p FAB to be ngrow cells larger in all directions than the + * underlying Box. The larger region covered by the union of all the \p FABs is + * called the region of definition. The underlying notion is that the valid + * region contains the grid interior data and the region of definition includes + * the interior region plus the boundary areas. + * + * Operations are available to copy data from the valid regions into these + * boundary areas where the two overlap. The number of components, that is, + * the number of values that can be stored in each cell of a \p FAB, is either + * given as an argument to the constructor or is inherent in the definition of + * the underlying \p FAB. Each \p FAB in the FabArray will have the same number of + * components. + * + * In summary, a FabArray is an array of \p FABs. The Kth element contains a \p FAB + * that holds the data for the Kth grid, a Box that defines the valid region + * of the Kth grid. + * + * A typical use for a FabArray would be to hold the solution vector or + * right-hand-side when solving a linear system of equations on a union of + * rectangular grids. The copy operations would be used to copy data from the + * valid regions of neighboring grids into the boundary regions after each + * relaxation step of the iterative method. If a multigrid method is used, a + * FabArray could be used to hold the data at each level in the multigrid + * hierarchy. + * + * This class is a concrete class not a polymorphic one. + * + * This class does NOT provide a copy constructor or assignment operator. + * + * \tparam FAB FortranArrayBox-like object. Typically a derived class of BaseFab. Not to be confused with FabArrayBase. + */ template class FabArray : @@ -338,8 +339,9 @@ public: FabArray () noexcept; /** - * \brief Construct an empty FabArray that has a default Arena. If - * `define` is called later with a nullptr as MFInfo's arena, the + * \brief Construct an empty FabArray that has a default Arena. + * + * If `define` is called later with a nullptr as MFInfo's arena, the * default Arena `a` will be used. If the arena in MFInfo is not a * nullptr, the MFInfo's arena will be used. */ diff --git a/Src/Base/AMReX_FabArrayBase.H b/Src/Base/AMReX_FabArrayBase.H index 29d3d63b29e..d8bc4411874 100644 --- a/Src/Base/AMReX_FabArrayBase.H +++ b/Src/Base/AMReX_FabArrayBase.H @@ -28,6 +28,12 @@ template class FabArray; namespace EB2 { class IndexSpace; } +/** + * \brief Base class for FabArray. + * + * Not to be confused with FArrayBox or `FAB` shorthands. + * Can be read as FArrayBox-like Array Base. + */ class FabArrayBase { friend class MFIter; diff --git a/Src/Base/AMReX_FabConv.H b/Src/Base/AMReX_FabConv.H index 78554000f25..25dae063de7 100644 --- a/Src/Base/AMReX_FabConv.H +++ b/Src/Base/AMReX_FabConv.H @@ -13,20 +13,18 @@ namespace amrex { -// -// A Descriptor of the Long Integer type - /** -* This class is meant to hold all information needed to completely -* describe the "int" or "Long" type on a machine. To describe an integer both -* the number of bytes and their ordering, relative to canonical -* ordering 1 .. sizeof(Long), needs to be specified. -* This allows us to write out integers in the native format on a machine, -* and then by also saving the IntDescriptor, we can read them back in on -* another machine and have enough information to construct the exact same -* values. -*/ - + * \brief A Descriptor of the Long Integer type + * + * This class is meant to hold all information needed to completely + * describe the "int" or "Long" type on a machine. To describe an integer both + * the number of bytes and their ordering, relative to canonical + * ordering 1 .. sizeof(Long), needs to be specified. + * This allows us to write out integers in the native format on a machine, + * and then by also saving the IntDescriptor, we can read them back in on + * another machine and have enough information to construct the exact same + * values. + */ class IntDescriptor { @@ -72,39 +70,37 @@ std::ostream& operator<< (std::ostream& os, const IntDescriptor& id); //! std::istream& operator>> (std::istream& is, IntDescriptor& id); - - //A Descriptor of the Real Type - /** -* \brief This class is meant to hold all information needed to completely -* describe the "Real" floating-point type on a machine. By "Real" here we -* mean either the "float" or "double" type that this version of AMReX -* was built with, which corresponds to whether BL_USE_FLOAT or -* BL_USE_DOUBLE was used to build the version of the library. -* -* To describe a "Real" type two arrays are needed: one detailing the ordering -* of the bytes in the Real, relative to the canonical ordering -* 1 .. sizeof(Real) and the other detailing the format of the floating-point -* number. -* -* The array detailing the format of a floating-point number is an eight-element -* array of longs containing the following information: -* -* format[0] = number of bits per number -* format[1] = number of bits in exponent -* format[2] = number of bits in mantissa -* format[3] = start bit of sign -* format[4] = start bit of exponent -* format[5] = start bit of mantissa -* format[6] = high order mantissa bit (CRAY needs this) -* format[7] = bias of exponent -* -* This allows us to write out "Real"s in the native format on a machine, -* and then by also saving the IntDescriptor, we can read them back in on -* another machine and have enough information to construct the exact same -* "Real" values, provided the Reals have the same size on the two machines. -*/ - + * \brief A Descriptor of the Real Type + * + * This class is meant to hold all information needed to completely + * describe the "Real" floating-point type on a machine. By "Real" here we + * mean either the "float" or "double" type that this version of AMReX + * was built with, which corresponds to whether BL_USE_FLOAT or + * BL_USE_DOUBLE was used to build the version of the library. + * + * To describe a "Real" type two arrays are needed: one detailing the ordering + * of the bytes in the Real, relative to the canonical ordering + * 1 .. sizeof(Real) and the other detailing the format of the floating-point + * number. + * + * The array detailing the format of a floating-point number is an eight-element + * array of longs containing the following information: + * + * format[0] = number of bits per number + * format[1] = number of bits in exponent + * format[2] = number of bits in mantissa + * format[3] = start bit of sign + * format[4] = start bit of exponent + * format[5] = start bit of mantissa + * format[6] = high order mantissa bit (CRAY needs this) + * format[7] = bias of exponent + * + * This allows us to write out "Real"s in the native format on a machine, + * and then by also saving the IntDescriptor, we can read them back in on + * another machine and have enough information to construct the exact same + * "Real" values, provided the Reals have the same size on the two machines. + */ class RealDescriptor { public: diff --git a/Src/Base/AMReX_MultiFab.H b/Src/Base/AMReX_MultiFab.H index 1a6c1d7f15f..fdf2e67cbd8 100644 --- a/Src/Base/AMReX_MultiFab.H +++ b/Src/Base/AMReX_MultiFab.H @@ -24,16 +24,17 @@ using fMultiFab = FabArray >; class iMultiFab; /** - * \brief - * A collection (stored as an array) of FArrayBox objects. + * \brief A collection (stored as an array) of FArrayBox objects. + * * This class is useful for storing floating point data on a domain defined by * a union of rectangular regions embedded in a uniform index space. * MultiFab class extends the function of the underlying FabArray class just * as the FArrayBox class extends the function of BaseFab. - * Additional member functions are defined for I/O and simple arithmetic operations on these aggregate objects. + * Additional member functions are defined for I/O and simple arithmetic + * operations on these aggregate objects. + * * This class does NOT provide a copy constructor or assignment operator. */ - class MultiFab : public FabArray @@ -41,34 +42,36 @@ class MultiFab public: /** - * \brief Constructs an empty MultiFab. Data can be defined at a later - * time using the define member functions inherited - * from FabArray. + * \brief Constructs an empty MultiFab. + * + * Data can be defined at a later time using the define member functions + * inherited from FabArray. */ MultiFab () noexcept; /** - * \brief Constructs an empty MultiFab. Data can be defined at a later - * time using the define member functions inherited from FabArray. If - * `define` is called later with a nullptr as MFInfo's arena, the default - * Arena `a` will be used. If the arena in MFInfo is not a nullptr, the - * MFInfo's arena will be used. + * \brief Constructs an empty MultiFab. + * + * Data can be defined at a later time using the define member functions. + * If `define` is called later with a nullptr as MFInfo's arena, the + * default Arena `a` will be used. If the arena in MFInfo is not a + * nullptr, the MFInfo's arena will be used. */ explicit MultiFab (Arena* a) noexcept; /** - * \brief - * Constructs a MultiFab - * \param bs a valid region - * \param dm a DistributionMapping + * \brief Constructs a MultiFab + * + * The size of the FArrayBox is given by the Box grown by \p ngrow, and + * the number of components is given by \p ncomp. If \p info is set to + * not allocating memory, then no FArrayBoxes are allocated at + * this time but can be defined later. + * + * \param bxs a valid region + * \param dm a DistribuionMapping * \param ncomp number of components * \param ngrow number of cells the region grows * \param info MFInfo - - * The size of the FArrayBox is given by the Box grown by ngrow, and - * the number of components is given by ncomp. If info is set to - * not allocating memory, then no FArrayBoxes are allocated at - * this time but can be defined later. */ MultiFab (const BoxArray& bxs, const DistributionMapping& dm, @@ -95,10 +98,11 @@ public: #endif /** - * \brief Make an alias MultiFab. maketype must be - * amrex::make_alias. scomp is the starting component of the - * alias and ncomp is the number of components in the new aliasing - * MultiFab. + * \brief Make an alias MultiFab. + * + * Note that \p maketype must be `amrex::make_alias`, + * \p scomp is the starting component of the alias, and + * \p ncomp is the number of components in the new aliasing MultiFab. */ MultiFab (const MultiFab& rhs, MakeType maketype, int scomp, int ncomp); @@ -135,11 +139,13 @@ public: #endif MultiFab& operator= (Real r); - // + /** - * \brief Returns the minimum value contained in component comp of the - * MultiFab. The parameter nghost determines the number of - * boundary cells to search for the minimum. The default is to + * \brief Returns the minimum value contained in component \p comp of the + * MultiFab. + * + * The parameter \p nghost determines the number of + * boundary cells to search for the minimum. The default is to * search only the valid regions of the FArrayBoxes. */ [[nodiscard]] Real min (int comp, @@ -154,16 +160,18 @@ public: int nghost = 0, bool local = false) const; /** - * \brief Returns the maximum value contained in component comp of the - * MultiFab. The parameter nghost determines the number of - * boundary cells to search for the maximum. The default is to + * \brief Returns the maximum value contained in component \p comp of the + * MultiFab. + * + * The parameter \p nghost determines the number of + * boundary cells to search for the maximum. The default is to * search only the valid regions of the FArrayBoxes. */ [[nodiscard]] Real max (int comp, int nghost = 0, bool local = false) const; /** - * \brief Identical to the previous max() function, but confines its + * \brief Identical to the previous `max()` function, but confines its * search to intersection of Box b and the MultiFab. */ [[nodiscard]] Real max (const Box& region, @@ -191,7 +199,7 @@ public: /** * \brief Returns the maximum *absolute* values contained in - * each component of "comps" of the MultiFab. "nghost" ghost cells are used. + * each component of \p comps of the MultiFab. \p nghost ghost cells are used. */ [[nodiscard]] Vector norm0 (const Vector& comps, int nghost = 0, bool local = false, bool ignore_covered = false ) const; [[nodiscard]] Vector norminf (const Vector& comps, int nghost = 0, bool local = false, bool ignore_covered = false) const { @@ -199,13 +207,14 @@ public: } /** - * \brief Returns the L1 norm of component "comp" over the MultiFab. + * \brief Returns the L1 norm of component \p comp over the MultiFab. + * * No ghost cells are used. This version has no double counting for nodal data. */ [[nodiscard]] Real norm1 (int comp, const Periodicity& period, bool ignore_covered = false) const; /** - * \brief Returns the L1 norm of component "comp" over the MultiFab. - * ngrow ghost cells are used. + * \brief Returns the L1 norm of component \p comp over the MultiFab. + * \p ngrow ghost cells are used. */ [[nodiscard]] Real norm1 (int comp = 0, int ngrow = 0, bool local = false) const; /** @@ -214,12 +223,12 @@ public: */ [[nodiscard]] Vector norm1 (const Vector& comps, int ngrow = 0, bool local = false) const; /** - * \brief Returns the L2 norm of component "comp" over the MultiFab. + * \brief Returns the L2 norm of component \p comp over the MultiFab. * No ghost cells are used. */ [[nodiscard]] Real norm2 (int comp = 0) const; /** - * \brief Returns the L2 norm of component "comp" over the MultiFab. + * \brief Returns the L2 norm of component \p comp over the MultiFab. * No ghost cells are used. This version has no double counting for nodal data. */ [[nodiscard]] Real norm2 (int comp, const Periodicity& period) const; @@ -236,16 +245,17 @@ public: using FabArray::sum; /** - * \brief Same as sum with local=false, but for non-cell-centered data, this - * skips non-unique points that are owned by multiple boxes. + * \brief Same as sum with \p local =false, but for non-cell-centered data, this + * skips non-unique points that are owned by multiple boxes. */ [[nodiscard]] Real sum_unique (int comp = 0, bool local = false, const Periodicity& period = Periodicity::NonPeriodic()) const; /** - * \brief Adds the scalar value val to the value of each cell in the - * specified subregion of the MultiFab. The subregion consists - * of the num_comp components starting at component comp. + * \brief Adds the scalar value \p val to the value of each cell in the + * specified subregion of the MultiFab. + * + * The subregion consists of the \p num_comp components starting at component \p comp. * The value of nghost specifies the number of cells in the * boundary region of each FArrayBox in the subregion that should * be modified. diff --git a/Src/Base/AMReX_MultiFabUtil.H b/Src/Base/AMReX_MultiFabUtil.H index 064b8a1b19f..29af89ba88e 100644 --- a/Src/Base/AMReX_MultiFabUtil.H +++ b/Src/Base/AMReX_MultiFabUtil.H @@ -19,67 +19,76 @@ namespace amrex const MultiFab& nd, int scomp, int ncomp, int ngrow = 0); - //! Average edge-based MultiFab onto cell-centered MultiFab. This fills in - //! ngrow ghost cells in the cell-centered MultiFab. Both cell centered and - //! edge centered MultiFabs need to have ngrow ghost values + /** + * \brief Average edge-based MultiFab onto cell-centered MultiFab. + * + * This fills in \p ngrow ghost cells in the cell-centered MultiFab. Both cell centered and + * edge centered MultiFabs need to have \p ngrow ghost values. + */ void average_edge_to_cellcenter (MultiFab& cc, int dcomp, const Vector& edge, int ngrow = 0); - //! Average face-based MultiFab onto cell-centered MultiFab. void average_face_to_cellcenter (MultiFab& cc, int dcomp, const Vector& fc, int ngrow = 0); - + //! Average face-based FabArray onto cell-centered FabArray. template && IsFabArray_v, int> = 0> void average_face_to_cellcenter (CMF& cc, int dcomp, const Array& fc, int ngrow = 0); - + //! Average face-based MultiFab onto cell-centered MultiFab with geometric weighting. void average_face_to_cellcenter (MultiFab& cc, const Vector& fc, const Geometry& geom); + //! Average face-based MultiFab onto cell-centered MultiFab with geometric weighting. void average_face_to_cellcenter (MultiFab& cc, const Array& fc, const Geometry& geom); - - //! Average cell-centered MultiFab onto face-based MultiFab. + //! Average cell-centered MultiFab onto face-based MultiFab with geometric weighting. void average_cellcenter_to_face (const Vector& fc, const MultiFab& cc, const Geometry& geom, int ncomp = 1, bool use_harmonic_averaging = false); + //! Average cell-centered MultiFab onto face-based MultiFab with geometric weighting. void average_cellcenter_to_face (const Array& fc, const MultiFab& cc, const Geometry& geom, int ncomp = 1, bool use_harmonic_averaging = false); - //! Average fine face-based MultiFab onto crse face-based MultiFab. + //! Average fine face-based FabArray onto crse face-based FabArray. template ::value,int> = 0> void average_down_faces (const Vector& fine, const Vector& crse, const IntVect& ratio, int ngcrse = 0); + //! Average fine face-based FabArray onto crse face-based FabArray. template ::value,int> = 0> void average_down_faces (const Vector& fine, const Vector& crse, int ratio, int ngcrse = 0); + //! Average fine face-based FabArray onto crse face-based FabArray. template ::value,int> = 0> void average_down_faces (const Array& fine, const Array& crse, const IntVect& ratio, int ngcrse = 0); + //! Average fine face-based FabArray onto crse face-based FabArray. template ::value,int> = 0> void average_down_faces (const Array& fine, const Array& crse, int ratio, int ngcrse = 0); - //! This version does average down for one direction. - //! It uses the IndexType of MultiFabs to determine the direction. - //! It is expected that one direction is nodal and the rest are cell-centered. + /** + * \brief This version does average down for one face direction. + * + * It uses the IndexType of MultiFabs to determine the direction. + * It is expected that one direction is nodal and the rest are cell-centered. + */ template void average_down_faces (const FabArray& fine, FabArray& crse, const IntVect& ratio, int ngcrse=0); @@ -117,9 +126,12 @@ namespace amrex int ngcrse = 0, bool mfiter_is_definitely_safe=false); - //! Average fine cell-based MultiFab onto crse cell-centered MultiFab using - //! volume-weighting. This routine DOES NOT assume that the crse BoxArray is - //! a coarsened version of the fine BoxArray. + /** + * \brief Volume weighed average of fine MultiFab onto coarse MultiFab. + * + * Both MultiFabs are assumed to be cell-centered. This routine DOES NOT assume that + * the crse BoxArray is a coarsened version of the fine BoxArray. + */ void average_down (const MultiFab& S_fine, MultiFab& S_crse, const Geometry& fgeom, const Geometry& cgeom, int scomp, int ncomp, const IntVect& ratio); diff --git a/Src/Base/AMReX_MultiFabUtil.cpp b/Src/Base/AMReX_MultiFabUtil.cpp index 5520c6164d7..27efbffca0f 100644 --- a/Src/Base/AMReX_MultiFabUtil.cpp +++ b/Src/Base/AMReX_MultiFabUtil.cpp @@ -308,9 +308,6 @@ namespace amrex // ************************************************************************************************************* - // Average fine cell-based MultiFab onto crse cell-centered MultiFab. - // We do NOT assume that the coarse layout is a coarsened version of the fine layout. - // This version DOES use volume-weighting. void average_down (const MultiFab& S_fine, MultiFab& S_crse, const Geometry& fgeom, const Geometry& cgeom, int scomp, int ncomp, int rr)