.. _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=python/ctsm/test/testinputs/surfdata_5x5_amazon_hist_16pfts_CMIP6_2000_c231031.nc
    indir=$SCRATCH/hillslopes_5x5_amazon/hand_analysis_global
    outdir=$SCRATCH/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=python/ctsm/test/testinputs/surfdata_5x5_amazon_hist_16pfts_CMIP6_2000_c231031.nc
    indir=$SCRATCH/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