factor out shared logic from cool1d_multi_g and calc_tdust_3d_g

.circleci/config.yml

@@ -215,22 +215,33 @@ commands:
               export PYTEST_CODE_LINK_CHOICE="" # we skip test_code_examples.py
             fi
 
-            # configure variables for generating test answers
-            if [ << parameters.generate >> == 'true' ]; then
-              export GENERATE_PYGRACKLE_TEST_RESULTS=1
-            else
-              export GENERATE_PYGRACKLE_TEST_RESULTS=0
-            fi
-
             # actually execute the tests
             if [ << parameters.omp >> == 'true' ]; then
               export OMP_NUM_THREADS=4
               cd example
               make cxx_omp_example
               ./cxx_omp_example
               make clean
-            else
+            elif [ ! -f ./python/tests/conftest.py ]; then
+              # this is the old way to control the answer-test mode
+              # - We can stop supporting this case once the most recent gold
+              #   standard tags a repository version containing conftest.py
+              if [ << parameters.generate >> == 'true' ]; then
+                export GENERATE_PYGRACKLE_TEST_RESULTS=1
+              else
+                export GENERATE_PYGRACKLE_TEST_RESULTS=0
+              fi
               py.test python/tests
+            else
+              # ANSWER_DIR was picked to ensure that it matches up with the old
+              # hardcoded location (we can change it once the most recent gold
+              # standard tags a repository version containing conftest.py)
+              ANSWER_DIR=./python/tests/test_answers
+              if [ << parameters.generate >> == 'true' ]; then
+                py.test --answer-dir=${ANSWER_DIR} --answer-store python/tests
+              else
+                py.test --answer-dir=${ANSWER_DIR} python/tests
+              fi
             fi
 
   build-docs:
@@ -281,14 +292,14 @@ jobs:
           build_kind: 'classic'
           generate: 'true'
 
-      - install-grackle:
-          omp: 'true'
-          classic_build: 'true'
-          tag: $CIRCLE_BRANCH
+      # - install-grackle:
+      #     omp: 'true'
+      #     classic_build: 'true'
+      #     tag: $CIRCLE_BRANCH
 
-      - run-tests:
-          omp: 'true'
-          build_kind: 'classic'
+      # - run-tests:
+      #     omp: 'true'
+      #     build_kind: 'classic'
 
       - install-grackle:
           omp: 'false'

.readthedocs.yml

@@ -8,3 +8,7 @@ build:
 python:
    install:
    - requirements: doc/source/requirements.txt
+
+sphinx:
+  # Path to your Sphinx configuration file.
+  configuration: doc/source/conf.py

doc/source/Python.rst

@@ -185,8 +185,8 @@ a parcel of gas at constant density or in a free-fall model.  Each example
 will produce a figure as well as a dataset that can be loaded and analyzed
 with `yt <http://yt-project.org/>`__.
 
-Configuring the path to Grackle input data
-++++++++++++++++++++++++++++++++++++++++++
+Editable Install Requirement
+++++++++++++++++++++++++++++
 
 All of the example scripts discussed below use the following line to
 make a guess at where the Grackle input files are located.
@@ -195,19 +195,15 @@ make a guess at where the Grackle input files are located.
 
    from pygrackle.utilities.data_path import grackle_data_dir
 
-This will typically work for any 'editable' Pygrackle installation
+This currently **ONLY** works for an 'editable' Pygrackle installation
 (i.e., one installed with ``pip install -e .`` as directed
 above). In this case, it will be assumed that the data files can be
 found in a directory called ``input`` in the top level of the source
-repository. However, this will not work with non-editable
-installations. In this case you can use the ``GRACKLE_DATA_DIR``
-environment variable to set the path to the data. This will be picked
-up by the Python code above and the ``grackle_data_dir`` variable will
-contain the proper path.
+repository.
 
-.. code-block:: shell-session
+.. note::
 
-   export GRACKLE_DATA_DIR=/path/to/data
+   `GitHub PR #235 <https://github.com/grackle-project/grackle/pull/235>`__ is a pending pull request that seeks to add functionality to make this work in a regular Pygrackle installation (i.e. a non-'editable' install).
 
 Cooling Rate Figure Example
 +++++++++++++++++++++++++++

doc/source/Testing.rst

@@ -26,8 +26,9 @@ the following:
 Answer tests are those whose correct answers must be generated from a
 prior, trusted version of Grackle (i.e., the "gold standard"). The
 tests are first run using this trusted version to generate the
-results, then run again on the latest version to compate. These tests
-include:
+results (in *store-mode*), then run again on the latest version to
+compare (in *compare-mode*).
+These tests include:
 
  - all code examples build, run, and return correct results
 
@@ -37,40 +38,51 @@ include:
  - all grackle 'calculate' functions return correct results for sets
    of random field values
 
-Tests Without Answer Verification
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+We refer to the location where the results of answer-tests are stored as the "answer-directory." This is an arbitrary user-specified location.
 
-If you only want to quickly verify that everything runs, you can skip
-generating the answer test results using the latest gold standard. To
-run this way, first set the ``GENERATE_PYGRACKLE_TEST_RESULTS``
-environment variable to 1.
+Quick Primer on the Test Runner's CLI
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. code-block:: shell-session
+By default, the pytest test-runner always runs all available test cases.
 
-   ~ $ export GENERATE_PYGRACKLE_TEST_RESULTS=1
+ - The unit tests are **ALWAYS** available.
 
-This will tell the test suite to simply generate new answers and not
-compare with previously existing ones.
+ - By default, **all** answer-tests are fully disabled.
+   Command-line options make them available in *store-mode* or *compare-mode*.
+   The ``--answer-dir=<PATH/TO/ANSWER-DIR>`` flag is required for both modes; it specifies the path to the user's chosen "answer-directory" (where answer-tests results are stored/read-from).
+   The ``--answer-store`` flag enables *store-mode*, while its absence enables *compare-mode*.
 
-Once you have installed :ref:`pygrackle and the development
-dependencies <pygrackle-dev>`, the tests can be run from the **src**
-directory by typing ``make test``:
+*For contributors:* you may find pytest's `build-in command-line interface <https://docs.pytest.org/en/stable/how-to/usage.html>`__ useful during debugging (e.g. you can instruct pytest to only run a subset of all available tests).
 
-.. code-block:: shell-session
+.. _test_without_answer_verification:
 
-   ~ $ cd grackle/src
-   ~/grackle/src $ make test
+Tests Without Answer Verification
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you only want to quickly verify that everything runs, you can skip
+generating the answer test results using the latest gold standard.
 
-or from the **src/python** directory by typing ``py.test``:
+Once you have installed :ref:`pygrackle and the development dependencies <pygrackle-dev>`, this is relatively straight-forward.
+
+Simply invoke ``py.test`` from the **src/python** directory with the ``--answer-dir=<PATH/TO/ANSWER-DIR>`` option **and** the ``--answer-store`` option.
+For the former You can specify an arbitrary path where the test-answers will be recorded.
+A concrete example of what this looks like is shown down below.
 
 .. code-block:: shell-session
 
    ~ $ cd grackle/src/python
-   ~/grackle/src $ py.test
+   ~/grackle/src/python $ py.test --answer-dir=./my_test_answers --answer-store
+
+The above snippet instructs each answer-test to store the test result in the directory called **./my_test_answers**; an answer-test reports that it has "passed" as long as it is able to successfully store the result.
+After you run the test-suite, you can delete the **./my_test_answers** directory (since we don't actually care about the test results).
+
+When you launch the tests, the output will look like the following:
+
+.. code-block:: shell-session
 
   ==================================== test session starts ====================================
   platform darwin -- Python 3.11.9, pytest-8.2.1, pluggy-1.5.0
-  rootdir: /Users/britton/Documents/work/research/simulation/grackle/grackle-git/src
+  rootdir: /Users/britton/Documents/work/research/simulation/grackle/grackle-git/src/python
   plugins: cov-5.0.0
   collected 65 items
 
@@ -112,11 +124,18 @@ steps:
 #. Re-compile the Grackle library and :ref:`re-install pygrackle
    <install-pygrackle>`.
 
-#. Set the ``GENERATE_PYGRACKLE_TEST_RESULTS`` environment variable to
-   1.
+#. Execute the test suite using command-line flags to instruct the test-runner to run answer tests in *store-mode*.
+   This was already illustrated :ref:`above <test_without_answer_verification>`, we repeat the instructions here:
+
+   - Execute ``py.test`` from the **src/python** directory while specifing the path  to the *answer-directory* with ``--answer-dir=<PATH/TO/ANSWER-DIR>`` **and** specifying the ``--answer-store`` option.
+
+   - Be aware, this will directly overwrite any files that were previously stored in the answer-dir.
+
+   - If we wanted to store the test-answers in **./my-test-answers**, we would invoke:
 
-#. Run the test suite as described above. This will create test result
-   files in the directory **src/python/tests/test_answers**.
+     .. code-block:: shell-session
+
+        ~/grackle/src/python $ py.test --answer-dir=./my_test_answers --answer-store
 
 #. Return to the branch of the repository you started with. If you just
    cloned the main repository, this will be called 'main', in which
@@ -125,8 +144,16 @@ steps:
 #. Re-compile the Grackle library and :ref:`re-install pygrackle
    <install-pygrackle>`.
 
-#. Set the ``GENERATE_PYGRACKLE_TEST_RESULTS`` environment variable to
-   0.
+#. Run the test suite again using a command-line flag to instruct the test runner to evaluate the answer-tests in *compare-mode*:
+
+   - you just need to specify the *answer-directory* path with ``--answer-dir=<PATH/TO/ANSWER-DIR>``.
+
+   - Do **NOT** pass the ``--answer-store`` flag.
+     The absence of this flag is how the test-runner knows to use *compare-mode*.
+     (If the flag were present, then the answer-tests would overwrite the answers)
+
+   - To compare against the results previously written to **./my-test-answers**, you would invoke:
+
+     .. code-block:: shell-session
 
-#. Run the test suite again. This time, the answer tests will be
-   compared with the previously generated results.
+        ~/grackle/src/python $ py.test --answer-dir=./my_test_answers --answer-store

src/clib/CMakeLists.txt

@@ -105,6 +105,7 @@ add_library(Grackle_Grackle
   ${CMAKE_CURRENT_BINARY_DIR}/auto_general.c
 
   # Fortran Source Files
+  calc_all_tdust_gasgr_1d_g.F
   calc_tdust_1d_g.F
   calc_tdust_3d_g.F
   calc_temp1d_cloudy_g.F

src/clib/Make.config.objects

@@ -40,6 +40,7 @@ OBJS_CONFIG_LIB = \
         solve_rate_cool_g.lo \
         update_UVbackground_rates.lo \
         lookup_cool_rates0d.lo \
+        calc_all_tdust_gasgr_1d_g.lo \
         calc_tdust_1d_g.lo \
         calc_tdust_3d_g.lo \
         calc_grain_size_increment_1d.lo \