Add User's Guide page: creating-hillslope-datasets.rst.

doc/source/users_guide/using-clm-tools/creating-hillslope-datasets.rst

@@ -0,0 +1,77 @@
+.. _rst_creating_hillslope_datasets:
+
+===========================
+Creating hillslope datasets
+===========================
+
+Creating hillslope datasets for use in CTSM is a multi-step process:
+
+#. Perform the Height Above Nearest Drainage (HAND) analysis, which processes the DEM data for each gridcell, breaking the work into a number of "chunks."
+#. Combine the per-gridcell files from the HAND analysis into one file per chunk.
+#. Combine the per-chunk files into a ``hillslope_file`` for use in CTSM.
+
+HAND analysis
+===============
+
+The HAND analysis uses the optional ``Representative_Hillslopes`` submodule. Before following these instructions, do ``bin/git-fleximod update -o`` to make sure that's been downloaded. Then the instructions assume:
+
+#. You've installed the ``Representative_Hillslopes`` Conda environment, if needed (``conda env create -f tools/external/representative-hillslopes/conda_yml/casper.yml``).
+#. You've activated that environment (``conda activate Representative_Hillslopes``).
+#. You've changed your working directory to ``tools/external/representative-hillslopes/shell_scripts/``.
+
+.. mdinclude:: ../../../../tools/external/representative-hillslopes/shell_scripts/README.md
+
+Gridcell files to chunk files
+=============================
+
+(Instructions here assume you have activated the ``ctsm_pylib`` Conda environment.)
+
+This is performed by the ``tools/hillslopes/combine_gridcell_files`` script; do ``tools/hillslopes/combine_gridcell_files --help`` for usage help. Briefly, you need to provide three things:
+
+* ``-i``, input surface dataset: The CTSM surface dataset (``fsurdat``) you used in the HAND analysis above.
+* ``-d``, input directory: The directory the HAND analysis above saved files to (``outdir`` in those instructions).
+* ``-o``, output directory: The directory where you want the chunk files generated by ``combine_gridcell_files`` to be saved.
+
+Example
+--------
+
+This example can be run on the NSF NCAR Casper machine; it assumes you've activated the ``ctsm_pylib`` Conda environment.
+
+.. code-block:: bash
+    
+    fsurdat=/glade/campaign/cesm/cesmdata/inputdata/lnd/clm2/surfdata_esmf/ctsm5.2.0/surfdata_5x5_amazon_hist_2000_78pfts_c240216.nc
+    indir=/glade/derecho/scratch/samrabin/hillslopes_5x5_amazon/hand_analysis_global
+    outdir=/glade/derecho/scratch/samrabin/hillslopes_5x5_amazon/hand_analysis_global/combined
+    
+    python tools/hillslopes/combine_gridcell_files \
+        -i $fsurdat \
+        -d $indir \
+        -o $outdir
+
+
+Chunk files to ``hillslope_file``
+=================================
+
+(Instructions here assume you have activated the ``ctsm_pylib`` Conda environment.)
+
+This is performed by the ``tools/hillslopes/combine_chunk_files`` script; do ``tools/hillslopes/combine_chunk_files --help`` for usage help. Briefly, you need to provide three things:
+
+* ``-i``, input surface dataset: The CTSM surface dataset (``fsurdat``) you used in the steps above.
+* ``-d``, input directory: The directory where ``combine_gridcell_files`` saved the chunk files (``-o`` in those instructions above).
+* ``-o``, output file: The file path where you want the output ``hillslope_file`` to be saved.
+
+Example
+--------
+
+This example can be run on the NSF NCAR Casper machine; it assumes you've activated the ``ctsm_pylib`` Conda environment.
+
+.. code-block:: bash
+    
+    fsurdat=/glade/campaign/cesm/cesmdata/inputdata/lnd/clm2/surfdata_esmf/ctsm5.2.0/surfdata_5x5_amazon_hist_2000_78pfts_c240216.nc
+    indir=/glade/derecho/scratch/samrabin/hillslopes_5x5_amazon/hand_analysis_global/combined
+    outfile=${indir}/$(basename ${fsurdat} | sed "s@surfdata@hilldata@")
+    
+    python tools/hillslopes/combine_chunk_files \
+        -i $fsurdat \
+        -d $indir \
+        -o $outfile

doc/source/users_guide/using-clm-tools/index.rst

@@ -18,6 +18,7 @@ Using CLM tools
    building-the-clm-tools.rst
    creating-input-for-surface-dataset-generation.rst
    creating-surface-datasets.rst
+   creating-hillslope-datasets.rst
    creating-domain-files.rst
    observational-sites-datasets.rst
    cprnc.rst