Merge branch 'main' into HydrogenFractionByMass

doc/source/Integration.rst

@@ -73,15 +73,13 @@ Seven header files are installed with the grackle library.  They are:
     * **grackle_macros.h** - contains some macros used internally.
 
 For C and C++ codes, the only source file that needs to be included in your
-simulation code is **grackle.h**.  For Fortran, use **grackle.def**.  Since
-Grackle is written in C, including **grackle.h** in a C++ code requires the
-*extern "C"* directive.
+simulation code is **grackle.h**.  For Fortran, use **grackle.def**.
 
-.. code-block:: c++
+.. note::
 
-  extern "C" {
-  #include <grackle.h>
-  }
+   Earlier versions of Grackle required C++ codes to enclose the ``#include <grackle.h>`` include-directive within a C "language-linkage block" (the block starts with ``extern "C" {``).
+   C++ codes should now directly include the header **(without the block)**.
+   The headers internally use a standard idiom to properly handle this case.
 
 Data Types
 ----------

src/clib/Make.config.assemble

@@ -195,8 +195,13 @@
     DEFINES = $(MACH_DEFINES) \
               $(ASSEMBLE_IO_DEFINES)
 
+    PUBLIC_HEADER_SRCDIR = $(GRACKLE_DIR)/../include
+
+    BUILD_INCLUDES = -I$(PUBLIC_HEADER_SRCDIR) -I$(GRACKLE_DIR)
+
     INCLUDES = $(MACH_INCLUDES) \
-               $(MAKEFILE_INCLUDES)   -I.
+               $(MAKEFILE_INCLUDES) \
+               $(BUILD_INCLUDES)
 
     OBJS_LIB = $(OBJS_CONFIG_LIB)
 

src/clib/Makefile

@@ -148,7 +148,7 @@ verbose: VERBOSE = 1
 	@rm -f $@
 	@(if [ $(VERBOSE) -eq 0 ]; then \
 	  echo "Compiling $<" ; \
-	  $(LIBTOOL) --mode=compile --tag=FC $(FC) -c $(FFLAGS) $(DEFINES) $*.F >& $(OUTPUT) ; \
+	  $(LIBTOOL) --mode=compile --tag=FC $(FC) -c $(FFLAGS) $(DEFINES) $(BUILD_INCLUDES) $*.F >& $(OUTPUT) ; \
 	  if [ ! -e $@ ]; then \
              echo; \
 	     echo "Compiling $< failed!"; \
@@ -157,7 +157,7 @@ verbose: VERBOSE = 1
              exit 1; \
           fi ; \
 	else \
-	  $(LIBTOOL) --mode=compile --tag=FC $(FC) -c $(FFLAGS) $(DEFINES) $*.F; \
+	  $(LIBTOOL) --mode=compile --tag=FC $(FC) -c $(FFLAGS) $(DEFINES) $(BUILD_INCLUDES) $*.F; \
 	  if [ ! -e $@ ]; then \
 	     exit 1; \
 	  fi ; \
@@ -214,10 +214,10 @@ autogen: config_type auto_general.c
 # in following recipe, GRACKLE_FLOAT_MACRO is set to either GRACKLE_FLOAT_4 or
 # GRACKLE_FLOAT_8
 .PHONY: config_type
-config_type: grackle_float.h.in
+config_type: $(PUBLIC_HEADER_SRCDIR)/grackle_float.h.in
 	@($(CONFIG_DIR)/configure_file.py --clobber \
-	    --input grackle_float.h.in \
-	    --output grackle_float.h \
+	    --input $< \
+	    --output $(PUBLIC_HEADER_SRCDIR)/grackle_float.h \
 	    GRACKLE_FLOAT_MACRO=GRACKLE_FLOAT_$(ASSEMBLE_PRECISION_NUMBER));
 
 # Force update of auto_general.c
@@ -277,12 +277,16 @@ help:
 # INSTALLATION TARGET
 #-----------------------------------------------------------------------
 
+# we make a point to try to clean up any previously installed headers (this is
+# mostly done to avoid confusions if/when we change the name of or delete a
+# public header file
 install:
 	@echo "Installing grackle header files to $(INSTALL_INCLUDE_DIR)."
 	@(if [ ! -d $(INSTALL_INCLUDE_DIR) ]; then \
 		mkdir $(INSTALL_INCLUDE_DIR); \
 	fi)
-	@cp grackle.h grackle_macros.h grackle_float.h grackle_types.h grackle_chemistry_data.h grackle_rate_functions.h grackle.def grackle_fortran_types.def grackle_fortran_interface.def $(INSTALL_INCLUDE_DIR)
+	@rm -f $(INSTALL_INCLUDE_DIR)/grackle*.h $(INSTALL_INCLUDE_DIR)/grackle*.def
+	@cp ../include/*.h ../include/*.def $(INSTALL_INCLUDE_DIR)
 	@(if [ ! -d $(INSTALL_LIB_DIR) ]; then \
 		mkdir $(INSTALL_LIB_DIR); \
 	fi)
@@ -292,7 +296,7 @@ install:
 #-----------------------------------------------------------------------
 
 clean:
-	-@rm -f *.la .libs/* *.o *.lo DEPEND.bak *~ $(OUTPUT) grackle_float.h *.exe auto_*.c temp.show-* DEPEND out.make.DEPEND
+	-@rm -f *.la .libs/* *.o *.lo DEPEND.bak *~ $(OUTPUT) $(PUBLIC_HEADER_SRCDIR)/grackle_float.h *.exe auto_*.c temp.show-* DEPEND out.make.DEPEND
 	-@touch DEPEND
 
 #-----------------------------------------------------------------------

src/clib/README.md

@@ -0,0 +1,42 @@
+# Basic Code Organization
+
+This directory contains all of Grackle's C and Fortran source code files. It also contains all private header files.
+
+The directory located at `../include` (i.e. the `include` directory at `src/include`) contains Grackle's public header files.
+
+We review the differences between these headers further down this page.
+
+# Include-Directive Conventions
+
+<!-- I feel like this needs to be near the top of the page to increase the
+     chance that people see this
+     -> I'm giving this advice to make it easy for us to move things around
+        later.
+ -->
+
+When including a public header file inside one of the source files contained by this directory, please directly specify the name of the header file and **NOT** a relative path.
+
+Suppose we had a file called ``./my_source.c``. To include the ``grackle.h`` file:
+- you should write ``include "grackle.h"``
+- you should NOT write ``include "../include/grackle.h"``
+
+(we use the `-I` flag to tell the compiler where to search for the public headers)
+
+# More info and some conventions
+
+**What is the difference between public and private headers?**
+
+For the uninitiated:
+
+- public header files get installed with Grackle.
+  - These are the header files that are made available to downstream applications.
+  - Declarations for all of the functions and types that are part of our public API [described here](https://grackle.readthedocs.io/en/latest/Reference.html) must be stored in the so that files.
+
+- private header files are only used internal during the compilation process of Grackle. They include functions and types that are only used inside of Grackle. You should think of these as functions as private implementation details.
+
+*NOTE: just because a function/type is in the public header does not mean it is a part of the public API (the functions/types that are part of the public API are explicitly listed in the documentation at the above link). For example, we reserve the write to alter the contents of the * `chemistry_data_storage` * struct and it's contained structs*.
+
+Going forward, new private functions or types should generally be declared in the private headers.
+
+**How do we name files?**
+In general, all public header files should probably include ``grackle`` at the start of their names (to avoid name-conflicts during installation). There's no need for a private header file to do this (in fact, it's probably preferable if they don't do this to make it easier to distinguish whether its public or private. A public header must **NOT** share a name with a private header.

src/example/cxx_example.C

@@ -17,9 +17,7 @@
 #include <string.h>
 #include <unistd.h>
 
-extern "C" {
 #include <grackle.h>
-}
 
 #define mh     1.67262171e-24   
 #define kboltz 1.3806504e-16

src/example/cxx_grid_example.C

@@ -22,9 +22,7 @@
 #include <vector>
 #include <string>
 
-extern "C" {
 #include <grackle.h>
-}
 
 #define mh     1.67262171e-24   
 #define kboltz 1.3806504e-16

src/example/cxx_omp_example.C

@@ -21,9 +21,7 @@
 #include <omp.h>
 #endif
 
-extern "C" {
 #include <grackle.h>
-}
 
 #define mh     1.67262171e-24
 #define kboltz 1.3806504e-16

src/clib/grackle.h → src/include/grackle.h

@@ -17,6 +17,10 @@
 #include "grackle_types.h"
 #include "grackle_chemistry_data.h"
 
+#ifdef __cplusplus
+extern "C" {
+#endif /* __cplusplus */
+
 extern int grackle_verbose;
 
 extern chemistry_data *grackle_data;
@@ -117,4 +121,8 @@ int local_free_chemistry_data(chemistry_data *my_chemistry, chemistry_data_stora
 
 grackle_version get_grackle_version(void);
 
-#endif
+#ifdef __cplusplus
+} /* extern "C" */
+#endif /* __cplusplus */
+
+#endif /* __GRACKLE_H__ */

src/clib/grackle_chemistry_data.h → src/include/grackle_chemistry_data.h

@@ -14,6 +14,10 @@
 #ifndef __CHEMISTRY_DATA_H__
 #define __CHEMISTRY_DATA_H__
 
+#ifdef __cplusplus
+extern "C" {
+#endif /* __cplusplus */
+
 /**********************************
  *** Grackle runtime parameters ***
  **********************************/
@@ -448,4 +452,8 @@ typedef struct
 
 } photo_rate_storage;
 
-#endif
+#ifdef __cplusplus
+} /* extern "C" */
+#endif /* __cplusplus */
+
+#endif /* __CHEMISTRY_DATA_H__ */

src/clib/grackle_rate_functions.h → src/include/grackle_rate_functions.h

@@ -4,6 +4,10 @@
 #ifndef RATE_FUNCTIONS_H
 #define RATE_FUNCTIONS_H
 
+#ifdef __cplusplus
+extern "C" {
+#endif /* __cplusplus */
+
 double k1_rate(double T, double units,  chemistry_data *my_chemistry);
 double k2_rate(double T, double units,  chemistry_data *my_chemistry);
 double k3_rate(double T, double units,  chemistry_data *my_chemistry);
@@ -89,4 +93,8 @@ double comp_rate(double units, chemistry_data *my_chemistry);
 double gammah_rate(double units, chemistry_data *my_chemistry);
 double gamma_isrf_rate(double units, chemistry_data *my_chemistry);
 
-#endif
+#ifdef __cplusplus
+} /* extern "C" */
+#endif /* __cplusplus */
+
+#endif /* RATE_FUNCTIONS_H */

src/clib/grackle_types.h → src/include/grackle_types.h

@@ -21,6 +21,10 @@
 
 #include "grackle_float.h"
 
+#ifdef __cplusplus
+extern "C" {
+#endif /* __cplusplus */
+
 #ifdef GRACKLE_FLOAT_4
 #define gr_float float
 #endif
@@ -104,4 +108,8 @@ typedef struct
 
 } grackle_version;
 
-#endif
+#ifdef __cplusplus
+} /* extern "C" */
+#endif /* __cplusplus */
+
+#endif /* __GRACKLE_TYPES_H__ */

src/python/setup.py

@@ -7,7 +7,7 @@
     Extension(
         "pygrackle.grackle_wrapper",
         ["pygrackle/grackle_wrapper.pyx"],
-        include_dirs=["../clib"],
+        include_dirs=["../clib", "../include"],
         library_dirs=["../clib/.libs/"],
         libraries=["grackle"],
         define_macros=[

src/python/tests/test_chemistry_struct_synched.py

@@ -187,7 +187,7 @@ def test_grackle_chemistry_field_synched():
     member_list = query_struct_fields(
         struct_name = "chemistry_data",
         path = os.path.join(os.path.dirname(os.path.abspath(__file__)),
-                            "../../clib/grackle_chemistry_data.h")
+                            "../../include/grackle_chemistry_data.h")
     )
 
     # now, categorize the fields by their datatype