Feature 1183 memory documentation

docs/Contributors_Guide/add_use_case.rst

@@ -120,6 +120,11 @@ Use Case Rules
   processed for analysis. Users can take an example and modify the run times
   to produce more output as desired.
 - No errors should result from running the use case.
+- The amount of required processing memory should not exceed the current limit 
+  of Github Actions. To accomplish this, pare down input data to the minimum 
+  for the use case to successfully run and, if the use case utilizes a Python 
+  embedding script, make use of a Python memory profiler of your choice to 
+  monitor Python embedding memory usage.
 - All data that is input to the use case (not generated by METplus) should
   be referenced relative to {INPUT_BASE} and the directory structure of the
   use case. For example, if adding a new model application use case found under
@@ -144,8 +149,20 @@ Use Case Rules
 - The use case should be run by someone other than the author to ensure that it
   runs smoothly outside of the development environment set up by the author.
 
-.. _use_case_documentation:
+.. _memory-intense-use-cases:
+
+Use Cases That Exceed Github Actions Memory Limit
+-------------------------------------------------
+
+Below is a list of use cases in the repository that cannot be run in Github Actions 
+due to their excessive memory usage. They have been tested and cleared by reviewers 
+of any other issues and can be used by METplus users in the same manner as all 
+other use cases.
+
+- model_applications/marine_and_cryosphere/GridStat_fcstRTOFS_obsGHRSST_climWOA_sst
 
+.. _use_case_documentation:
+
 Document New Use Case
 ---------------------
 
@@ -1024,6 +1041,17 @@ with "Use Case Tests." Click on the job and search for the use case config
 filename in the log output by using the search box on the top right of the
 log output.
 
+If the use case does not run successfully in Github Actions and standard error checking 
+is unsuccessful/your system runs the use case successfully, a recommended step for 
+use cases that utilize a Python embedding script is to employ a Python memory profiler 
+to check for the Python script’s memory usage. Github Actions 
+has a `limited memory storage <https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources>`_ and when exceeded by a use case, will cause the 
+use case to fail. If your use case exceeds this limit, try to pare down the data held 
+in memory and use less memory intensive Python routines.
+
+If memory mitigation cannot move the use case’s memory usage below the Github Actions limit, 
+see :ref:`exceeded-Github-Actions` for next steps.
+
 Verify that the use case ran in a reasonable amount of time
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1039,6 +1067,40 @@ run the set of use cases is now above 20 minutes or so, consider creating a
 new job for the new use case. See the :ref:`subset_category` section and the
 multiple medium_range jobs for an example.
 
+
+.. _exceeded-Github-Actions:
+
+Use Cases That Exceed Memory Allocations of Github Actions
+----------------------------------------------------------
+
+If a use case utilizing Python embedding does not run successfully in 
+Github Actions due to exceeding the memory limit and memory mitigation 
+steps were unsuccessful in lowering memory usage, please take the following steps.
+
+- Document the Github Actions failure in the Github use case issue. 
+  Utilize a Python memory profiler to identify as specifically as possible 
+  where the script exceeds the memory limit.
+- Add the use case to the :ref:`memory-intense-use-cases` list.
+- In the internal_tests/use_cases/all_use_cases.txt file, ensure that the 
+  use case is listed as the lowest-listed use case in its respective category. 
+  Change the number in front of the new use case to a letter, preceeded 
+  by the ‘#’ character::
+
+	#X::GridStat_fcstRTOFS_obsGHRSST_climWOA_sst::model_applications/marine_and_cryosphere/GridStat_fcstRTOFS_obsGHRSST_climWOA_sst.conf, model_applications/marine_and_cryosphere/GridStat_fcstRTOFS_obsGHRSST_climWOA_sst/ci_overrides.conf:: icecover_env, py_embed
+
+- In the **.github/parm/use_case_groups.json** file, change the “run” variable 
+  for the entry that was added during the :ref:`add_new_category_to_test_runs` 
+  for the new use case to false. 
+- Push these two updated files to your branch in Github and confirm that it 
+  now compiles successfully.
+- During the :ref:`create-a-pull-request` creation, inform the reviewer of 
+  the Github Actions failure. The reviewer should confirm the use case is 
+  successful when run manually, that the memory profiler output confirms that 
+  the Python embedding script exceeds the Github Actions limit, and that 
+  there are no other Github Actions compiling errors.
+
+.. _create-a-pull-request:
+
 Create a Pull Request
 =====================