Introduce gr_initialize_field_data

doc/source/Integration.rst

@@ -604,6 +604,9 @@ not intend to use.
   // Create struct for storing grackle field data
   grackle_field_data my_fields;
 
+  // initialize members of my_fields to sensible defaults
+  gr_initialize_field_data(&my_fields);
+
   // Set grid dimension and size.
   // grid_start and grid_end are used to ignore ghost zones.
   int field_size = 1;

doc/source/Reference.rst

@@ -13,6 +13,8 @@ Grackle has two versions of most functions.
    and :c:data:`chemistry_data_storage` instances to be provided as
    arguments. These are explicity thread-safe as they use no global data.
 
+Additionally, there are also some :ref:`misc_functions` and :ref:`rate-functions`.
+
 .. _primary_functions:
 
 Primary Functions
@@ -417,3 +419,20 @@ The following functions are used to query the name of the ith field of the :c:da
    :param unsigned int i: The index of the accessed parameter
    :rtype: const char*
    :returns: Pointer to the string-literal specifying the name. This is ``NULL``, if :c:data:`chemistry_data` has ``i`` or fewer ``string`` members.
+
+.. _misc_functions:
+
+Miscellaneous Functions
+-----------------------
+
+.. c:function:: int gr_initialize_field_data(grackle_field_data *my_fields);
+
+   Initializes the struct-members stored in the :c:type:`grackle_field_data` data structure to their default values.
+
+   This function must assume that any existing data within the data structure is garbage data.
+   In other words, when this function goes to overwrite a given member of :c:type:`grackle_field_data`, it completely ignores the value currently held by the member (i.e. the function does not provide special handling for members holding non- ``NULL`` pointers).
+   Consequently, this function should **ONLY** be called **BEFORE** initializing any members of the data structure (if it's called at any other time, the program may leak memory resources).
+
+   :param grackle_field_data \*my_fields: uninitialized field data storage
+   :rtype: int
+   :returns: 1 (success) or 0 (failure)

src/clib/grackle.h

@@ -117,4 +117,6 @@ int local_free_chemistry_data(chemistry_data *my_chemistry, chemistry_data_stora
 
 grackle_version get_grackle_version(void);
 
+int gr_initialize_field_data(grackle_field_data *my_fields);
+
 #endif

src/clib/grackle_field_data_fdatamembers.def

@@ -0,0 +1,57 @@
+/***********************************************************************
+/
+/ this file lists each member of the grackle_field_data struct that is
+/ intended to hold field data. This list is intended to be used with
+/ X-Macros in *.c files (to reduce the amount of code required to
+/ interact with these fields)
+/
+/ The following information is specified for each field:
+/    1. the field_name
+/    2. a 1 or 0 to denote whether the field_name corresponds to a
+/       passive-scalar density field
+/
+/
+/ Copyright (c) 2013, Enzo/Grackle Development Team.
+/
+/ Distributed under the terms of the Enzo Public Licence.
+/
+/ The full license is in the file LICENSE, distributed with this
+/ software.
+************************************************************************/
+
+ENTRY(density, 0)
+ENTRY(HI_density, 1)
+ENTRY(HII_density, 1)
+ENTRY(HM_density, 1)
+ENTRY(HeI_density, 1)
+ENTRY(HeII_density, 1)
+ENTRY(HeIII_density, 1)
+ENTRY(H2I_density, 1)
+ENTRY(H2II_density, 1)
+ENTRY(DI_density, 1)
+ENTRY(DII_density, 1)
+ENTRY(HDI_density, 1)
+ENTRY(e_density, 1)
+ENTRY(metal_density, 1)
+ENTRY(dust_density, 1)
+
+ENTRY(internal_energy, 0)
+ENTRY(x_velocity, 0)
+ENTRY(y_velocity, 0)
+ENTRY(z_velocity, 0)
+
+ENTRY(volumetric_heating_rate, 0)
+ENTRY(specific_heating_rate, 0)
+
+ENTRY(temperature_floor, 0)
+
+ENTRY(RT_heating_rate, 0)
+ENTRY(RT_HI_ionization_rate, 0)
+ENTRY(RT_HeI_ionization_rate, 0)
+ENTRY(RT_HeII_ionization_rate, 0)
+ENTRY(RT_H2_dissociation_rate, 0)
+
+ENTRY(H2_self_shielding_length, 0)
+ENTRY(H2_custom_shielding_factor, 0)
+
+ENTRY(isrf_habing, 0)

src/clib/grackle_fortran_interface.def

@@ -245,3 +245,11 @@ c     The following define the fortran interfaces to the C routines
             REAL(C_DOUBLE), INTENT(OUT) :: dust_temperature(*)
          END FUNCTION calculate_dust_temperature
       END INTERFACE
+
+      INTERFACE
+         INTEGER(C_INT) FUNCTION gr_initialize_field_data(my_fields)
+     &        bind(C)
+            IMPORT
+            TYPE(grackle_field_data), INTENT(INOUT) :: my_fields
+         END FUNCTION gr_initialize_field_data
+      END INTERFACE

src/clib/set_default_chemistry_parameters.c

@@ -41,3 +41,25 @@ int set_default_chemistry_parameters(chemistry_data *my_grackle)
   grackle_data = my_grackle;
   return local_initialize_chemistry_parameters(my_grackle);
 }
+
+int gr_initialize_field_data(grackle_field_data *my_fields)
+{
+  if (my_fields == NULL) {
+    fprintf(stderr, "gr_initial_field_data was passed a NULL pointer\n");
+    return FAIL;
+  }
+
+  my_fields->grid_rank = -1;
+  my_fields->grid_dimension = NULL;
+  my_fields->grid_start = NULL;
+  my_fields->grid_end = NULL;
+  my_fields->grid_dx = -1.0;
+
+  // now, modify all members holding datafields to have values of NULL
+  // (we use X-Macros to do this)
+  #define ENTRY(MEMBER_NAME, _1) my_fields->MEMBER_NAME = NULL;
+  #include "grackle_field_data_fdatamembers.def"
+  #undef ENTRY
+
+  return SUCCESS;
+}

src/example/c_example.c

@@ -77,6 +77,7 @@ int main(int argc, char *argv[])
 
   // Create struct for storing grackle field data
   grackle_field_data my_fields;
+  gr_initialize_field_data(&my_fields);
 
   // Set grid dimension and size.
   // grid_start and grid_end are used to ignore ghost zones.
@@ -244,4 +245,4 @@ int main(int argc, char *argv[])
   fprintf(stderr, "dust_temperature = %g K.\n", dust_temperature[0]);
 
   return EXIT_SUCCESS;
-}
+}

src/example/c_local_example.c

@@ -78,6 +78,7 @@ int main(int argc, char *argv[])
 
   // Create struct for storing grackle field data
   grackle_field_data my_fields;
+  gr_initialize_field_data(&my_fields);
 
   // Set grid dimension and size.
   // grid_start and grid_end are used to ignore ghost zones.

src/example/cxx_grid_example.C

@@ -76,6 +76,7 @@ grackle_field_data construct_field_data(grid_props& my_grid_props,
 
   // Create struct for storing grackle field data
   grackle_field_data my_fields;
+  gr_initialize_field_data(&my_fields);
 
   // Set grid dimension and size.
   // grid_start and grid_end are used to ignore ghost zones.

src/example/cxx_omp_example.C

@@ -181,6 +181,8 @@ int main(int argc, char *argv[])
   }
 
   grackle_field_data my_fields_t1, my_fields_tN;
+  gr_initialize_field_data(&my_fields_t1);
+  gr_initialize_field_data(&my_fields_tN);
 
   // Set grid dimension and size.
   // grid_start and grid_end are used to ignore ghost zones.

src/example/fortran_example.F

@@ -121,6 +121,7 @@ program fortran_example
       iresult = initialize_chemistry_data(my_units)
 
 c     Set field arrays
+      iresult = gr_initialize_field_data(my_fields)
 
 c     If grid rank is less than 3, set the other dimensions, 
 c     start indices, and end indices to 0.

src/python/pygrackle/grackle_defs.pxd

@@ -249,3 +249,5 @@ cdef extern from "grackle.h":
         c_chemistry_data_storage *my_rates)
 
     c_grackle_version c_get_grackle_version "get_grackle_version"()
+
+    int gr_initialize_field_data(c_field_data *my_fields)

src/python/pygrackle/grackle_wrapper.pyx

@@ -696,6 +696,7 @@ cdef c_field_data setup_field_data(object fc, int[::1] buf,
 
     # now initialize my_fields
     cdef c_field_data my_fields
+    gr_initialize_field_data(&my_fields)
     my_fields.grid_rank = 1
     my_fields.grid_dimension = grid_dimension
     my_fields.grid_start = grid_start