[newchem-cpp] Introduce GRIMPL_NS macro

src/clib/CMakeLists.txt

@@ -131,6 +131,7 @@ add_library(Grackle_Grackle
   utils-cpp.cpp utils-cpp.hpp
   utils-field.hpp
   fortran_func_wrappers.hpp
+  support/config.hpp
   visitor/common.hpp
   visitor/copy.hpp
   visitor/memory.hpp

src/clib/ceiling_species.hpp

@@ -16,173 +16,177 @@
 // This file was initially generated automatically during conversion of the
 // ceiling_species_g function from FORTRAN to C++
 
+#include "grackle.h"  // my_chemistry, my_fields
+#include "support/config.hpp"
+#include <cmath>  // std::fmax
+
 #ifndef CEILING_SPECIES_HPP
 #define CEILING_SPECIES_HPP
 
-namespace grackle::impl {
+namespace GRIMPL_NAMESPACE_DECL {
 
 inline void ceiling_species(int imetal, chemistry_data* my_chemistry,
                             grackle_field_data* my_fields) {
-  grackle::impl::View<gr_float***> d(
+  GRIMPL_NS::View<gr_float***> d(
       my_fields->density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> de(
+  GRIMPL_NS::View<gr_float***> de(
       my_fields->e_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> HI(
+  GRIMPL_NS::View<gr_float***> HI(
       my_fields->HI_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> HII(
+  GRIMPL_NS::View<gr_float***> HII(
       my_fields->HII_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> HeI(
+  GRIMPL_NS::View<gr_float***> HeI(
       my_fields->HeI_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> HeII(
+  GRIMPL_NS::View<gr_float***> HeII(
       my_fields->HeII_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> HeIII(
+  GRIMPL_NS::View<gr_float***> HeIII(
       my_fields->HeIII_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> HM(
+  GRIMPL_NS::View<gr_float***> HM(
       my_fields->HM_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> H2I(
+  GRIMPL_NS::View<gr_float***> H2I(
       my_fields->H2I_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> H2II(
+  GRIMPL_NS::View<gr_float***> H2II(
       my_fields->H2II_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> DI(
+  GRIMPL_NS::View<gr_float***> DI(
       my_fields->DI_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> DII(
+  GRIMPL_NS::View<gr_float***> DII(
       my_fields->DII_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> HDI(
+  GRIMPL_NS::View<gr_float***> HDI(
       my_fields->HDI_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> metal(
+  GRIMPL_NS::View<gr_float***> metal(
       my_fields->metal_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> dust(
+  GRIMPL_NS::View<gr_float***> dust(
       my_fields->dust_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> DM(
+  GRIMPL_NS::View<gr_float***> DM(
       my_fields->DM_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> HDII(
+  GRIMPL_NS::View<gr_float***> HDII(
       my_fields->HDII_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> HeHII(
+  GRIMPL_NS::View<gr_float***> HeHII(
       my_fields->HeHII_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> CI(
+  GRIMPL_NS::View<gr_float***> CI(
       my_fields->CI_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> CII(
+  GRIMPL_NS::View<gr_float***> CII(
       my_fields->CII_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> CO(
+  GRIMPL_NS::View<gr_float***> CO(
       my_fields->CO_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> CO2(
+  GRIMPL_NS::View<gr_float***> CO2(
       my_fields->CO2_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> OI(
+  GRIMPL_NS::View<gr_float***> OI(
       my_fields->OI_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> OH(
+  GRIMPL_NS::View<gr_float***> OH(
       my_fields->OH_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> H2O(
+  GRIMPL_NS::View<gr_float***> H2O(
       my_fields->H2O_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> O2(
+  GRIMPL_NS::View<gr_float***> O2(
       my_fields->O2_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> SiI(
+  GRIMPL_NS::View<gr_float***> SiI(
       my_fields->SiI_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> SiOI(
+  GRIMPL_NS::View<gr_float***> SiOI(
       my_fields->SiOI_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> SiO2I(
+  GRIMPL_NS::View<gr_float***> SiO2I(
       my_fields->SiO2I_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> CH(
+  GRIMPL_NS::View<gr_float***> CH(
       my_fields->CH_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> CH2(
+  GRIMPL_NS::View<gr_float***> CH2(
       my_fields->CH2_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> COII(
+  GRIMPL_NS::View<gr_float***> COII(
       my_fields->COII_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> OII(
+  GRIMPL_NS::View<gr_float***> OII(
       my_fields->OII_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> OHII(
+  GRIMPL_NS::View<gr_float***> OHII(
       my_fields->OHII_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> H2OII(
+  GRIMPL_NS::View<gr_float***> H2OII(
       my_fields->H2OII_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> H3OII(
+  GRIMPL_NS::View<gr_float***> H3OII(
       my_fields->H3OII_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> O2II(
+  GRIMPL_NS::View<gr_float***> O2II(
       my_fields->O2II_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> Mg(
+  GRIMPL_NS::View<gr_float***> Mg(
       my_fields->Mg_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> Al(
+  GRIMPL_NS::View<gr_float***> Al(
       my_fields->Al_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> S(
+  GRIMPL_NS::View<gr_float***> S(
       my_fields->S_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> Fe(
+  GRIMPL_NS::View<gr_float***> Fe(
       my_fields->Fe_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> SiM(
+  GRIMPL_NS::View<gr_float***> SiM(
       my_fields->SiM_dust_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> FeM(
+  GRIMPL_NS::View<gr_float***> FeM(
       my_fields->FeM_dust_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> Mg2SiO4(
+  GRIMPL_NS::View<gr_float***> Mg2SiO4(
       my_fields->Mg2SiO4_dust_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> MgSiO3(
+  GRIMPL_NS::View<gr_float***> MgSiO3(
       my_fields->MgSiO3_dust_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> Fe3O4(
+  GRIMPL_NS::View<gr_float***> Fe3O4(
       my_fields->Fe3O4_dust_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> AC(
+  GRIMPL_NS::View<gr_float***> AC(
       my_fields->AC_dust_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> SiO2D(
+  GRIMPL_NS::View<gr_float***> SiO2D(
       my_fields->SiO2_dust_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> MgO(
+  GRIMPL_NS::View<gr_float***> MgO(
       my_fields->MgO_dust_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> FeS(
+  GRIMPL_NS::View<gr_float***> FeS(
       my_fields->FeS_dust_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> Al2O3(
+  GRIMPL_NS::View<gr_float***> Al2O3(
       my_fields->Al2O3_dust_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> reforg(
+  GRIMPL_NS::View<gr_float***> reforg(
       my_fields->ref_org_dust_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> volorg(
+  GRIMPL_NS::View<gr_float***> volorg(
       my_fields->vol_org_dust_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
-  grackle::impl::View<gr_float***> H2Oice(
+  GRIMPL_NS::View<gr_float***> H2Oice(
       my_fields->H2O_ice_dust_density, my_fields->grid_dimension[0],
       my_fields->grid_dimension[1], my_fields->grid_dimension[2]);
 
@@ -337,6 +341,6 @@ inline void ceiling_species(int imetal, chemistry_data* my_chemistry,
   return;
 }
 
-}  // namespace grackle::impl
+}  // namespace GRIMPL_NAMESPACE_DECL
 
 #endif /* CEILING_SPECIES_CPP_H */

src/clib/chemistry_solver_funcs.hpp

@@ -1,6 +1,11 @@
-// See LICENSE file for license and copyright information
-
-/// @file chemistry_solver_funcs.hpp
+//===----------------------------------------------------------------------===//
+//
+// See the LICENSE file for license and copyright information
+// SPDX-License-Identifier: NCSA AND BSD-3-Clause
+//
+//===----------------------------------------------------------------------===//
+///
+/// @file
 /// @brief Defines chemistry reaction related functions invoked by the
 ///     grackle solver in order to integrate the species densities over time.
 ///
@@ -14,6 +19,8 @@
 ///     be decoupled from the derivative calculation for primoridial species
 ///   - it may also make sense to further divide logic by the kinds of species
 ///     that are affected (e.g. primordial vs grains)
+///
+//===----------------------------------------------------------------------===//
 
 #ifndef CHEMISTRY_SOLVER_FUNCS_HPP
 #define CHEMISTRY_SOLVER_FUNCS_HPP
@@ -579,7 +586,9 @@ inline void species_density_updates_gauss_seidel(
 
         if ( (my_chemistry->metal_chemistry == 1)  && 
              (itmask_metal[i] != MASK_FALSE) )  {
-          scoef = scoef;
+          // we comment out the following line that assigns scoef to itself since
+          // it has no practical impact and produces a compiler warning
+          // scoef = scoef;
           acoef = acoef
               + kcol_buf.data[CollisionalRxnLUT::kz44][i] *   CII(i,j,k) / 12.
               + kcol_buf.data[CollisionalRxnLUT::kz45][i] *   OII(i,j,k) / 16.
@@ -1932,7 +1941,9 @@ inline void species_density_derivatives_0d(
 
     if ((my_chemistry->metal_chemistry == 1)  && 
         (itmask_metal[0] != MASK_FALSE))  {
-      scoef = scoef;
+      // we comment out the following line that assigns scoef to itself since
+      // it has no practical impact and produces a compiler warning
+      // scoef = scoef;
       acoef = acoef
           + kcr_buf.data[CollisionalRxnLUT::kz44][0]    *   CII        / 12.
           + kcr_buf.data[CollisionalRxnLUT::kz45][0]    *   OII        / 16.

src/clib/solve_rate_cool_g-cpp.cpp

@@ -791,7 +791,7 @@ int solve_rate_cool_g(
       // declare 2 variables (primarily used for subcycling, but also used in
       // error reporting)
       int iter;
-      double ttmin;
+      double ttmin = huge8;
 
       // ------------------ Loop over subcycles ----------------
 

src/clib/support/config.hpp

@@ -0,0 +1,71 @@
+//===----------------------------------------------------------------------===//
+//
+// See the LICENSE file for license and copyright information
+// SPDX-License-Identifier: NCSA AND BSD-3-Clause
+//
+//===----------------------------------------------------------------------===//
+///
+/// @file
+/// This is a lightweight header file that defines a few macros that are used
+/// throughout the codebase
+///
+//===----------------------------------------------------------------------===//
+#ifndef SUPPORT_CONFIG_HPP
+#define SUPPORT_CONFIG_HPP
+
+/// Expands to Grackle's global internal namespace enclosing the implementation
+///
+/// This is used when referring to the qualified name of a PREVIOUSLY DECLARED
+/// entity (a function, class/struct, etc.) that is a member of this namespace.
+///
+/// For example, suppose that a function <tt> int foo(const char* s) </tt> was
+/// as part of this namespace. From global scope, we could use this macro to
+/// call the function with <tt> GRIMPL_NS::foo(s) </tt>.
+///
+/// @important
+/// This macro should NOT be used to open namespace blocks. You should use
+/// GRIMPL_NAMESPACE_DECL for that purpose.
+///
+/// @par Motivation
+/// The existence of this macro has 3 motivations:
+/// 1. Once we use it everywhere, the name will be easier to change. The current
+///    choice, <tt> grackle::impl </tt> was picked because it was relatively
+///    short (there are probably slightly more descriptive alternatives).
+/// 2. Relatedly, it might be convenient to encode the current version number
+///    in the namespace. This comes up in the context of header-only libraries.
+///    (It would also open the door to linking and testing 2 Grackle versions
+///    in the same program).
+/// 3. It also goes hand-in-hand with the GRIMPL_NAMESPACE_DECL macro. See its
+///    docstring for the benefits that it brings.
+#define GRIMPL_NS grackle::impl
+
+/// Used for opening the namespace block of Grackle's global internal namespace
+/// that is used to enclose Grackle's implementation
+///
+/// To declare a function <tt> int foo(const char* s) </tt> in this namespace,
+/// you might write something like:
+/// @code{.cpp}
+/// #include "support/config.hpp"
+///
+/// namespace GRIMPL_NAMESPACE_DECL {
+/// int foo(const char* s)
+/// }  //  namespace GRIMPL_NAMESPACE_DECL
+/// @endcode
+///
+/// @par Motivation
+/// This is primarily inspired by a similar macro, \c LIBC_NAMESPACE_DECL from
+/// LLVM-libc (LLVM's implementation of the C standard library), which is
+/// described at https://libc.llvm.org/dev/code_style.html#libc-namespace-decl
+///
+/// @par
+/// Once we adopt this everywhere, we would change this macro's definition to
+/// <tt> [[gnu::visibility("hidden")]] GRIMPL_NS </tt> when compiling Grackle
+/// as a shared library, which would declare all enclosed symbols as having
+/// hidden visibility. A brief primer on symbol visibility is provided by
+/// https://cs.dartmouth.edu/~sergey/cs258/ABI/UlrichDrepper-How-To-Write-Shared-Libraries.pdf
+/// This would effectively reduce the size of the Grackle shared library,
+/// improve startup time of programs linked against a Grackle shared library
+/// and enforce that private functions shouldn't be used outside of Grackle
+#define GRIMPL_NAMESPACE_DECL GRIMPL_NS
+
+#endif  // SUPPORT_CONFIG_HPP