{ "cells": [ { "cell_type": "markdown", "id": "4768bbb9-77eb-4e56-83c9-0dbcbd35ff39", "metadata": {}, "source": [ "# Configure CLM inputs from template" ] }, { "cell_type": "markdown", "id": "156d03da-9bcd-4318-84de-ce8596b0c491", "metadata": {}, "source": [ "To launch this notebook interactively in a Jupyter notebook-like browser interface, please click the \"Launch Binder\" button below. Note that Binder may take several minutes to launch.\n", "\n", "[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/hydroframe/subsettools-binder/HEAD?labpath=subsettools%2Fconfigure_clm_from_template.ipynb)" ] }, { "cell_type": "markdown", "id": "73fa69ca", "metadata": {}, "source": [ "The CLM model is a land modification of the Community Land Model that is coupled to ParFlow. If you want to complete transient simulations using ParFlow-CLM you will need additional input files specifically for CLM (you can refer to the ParFlow short courses for more information on ParFlow-CLM [here](https://hydroframe.org/parflow-resources)). \n", "\n", "The additional inputs you will need to run a ParFlow-CLM file are: \n", "1. `CLM Driver File`: This provides additional settings to configure the CLM run which are not included in the ParFlow run script. We will show you how to start from an existing template.\n", "2. `Vegm File`: This file assigns a land cover type to every cell in the model and is formatted specifically for CLM. You can subset this from the national run for your domain. \n", "3. `Vegp File`: This has all of the parameters for every land cover type. You can use the national vegp file as a template and will only need to modify if you want to change the parameters of a specific landcover type or introduce a new land cover category. \n", "\n", "There are currently two available CLM configurations one for the [ParFlow CONUS1 model](https://www.hydroframe.org/parflow-conus1) and one for the [ParFlow CONUS2 model](https://www.hydroframe.org/parflow-conus2). The biggest difference between these two configurations is just the updated landcover types for the CONUS2 model. **You should use the CLM configuration that matches the grid you have selected for the rest of your subsetting** " ] }, { "cell_type": "markdown", "id": "a421017a", "metadata": {}, "source": [ "### 1. Setup \n", "\n", "In all examples you will need to import the following packages and register your pin in order to have access to the HydroData datasets. \n", "\n", "Refer to the [getting started](https://hydroframesubsettools.readthedocs.io/en/latest/getting_started.html) instructions for creating your pin if you have not done this already." ] }, { "cell_type": "code", "execution_count": 1, "id": "61d84526-545e-41c4-a7c2-c2c4aee3f878", "metadata": {}, "outputs": [], "source": [ "import subsettools as st\n", "import hf_hydrodata as hf\n", "from parflow import Run\n", "import numpy as np\n", "\n", "hf.register_api_pin(\"your_email\", \"your_pin\")" ] }, { "cell_type": "markdown", "id": "a09dfacf-f441-4003-a24f-85781a161021", "metadata": {}, "source": [ "## 2. Configuring_clm with the `config_clm` function \n", "The `config_clm` function (API reference [here](https://hydroframesubsettools.readthedocs.io/en/latest/autoapi/subsettools/index.html#subsettools.config_clm)) will complete all three of the steps listed above: \n", " 1. Grabbing a clm-driver file for you to start from and modifying it to match your domain\n", " 2. Subsetting the the vegm file for your subdomain\n", " 3. Grabbing a vegp file for you to use\n", "\n", "As with our other subsetting steps we will pass the `ij_box_bounds` (refer to the [Define your subset domain](https://hydroframesubsettools.readthedocs.io/en/latest/examples/definte_subset.html) tutorial for details). We will also need `start` and `end` dates for our ParFlow simulation, a dataset to get our CLM files from and the directory path where the files are going to be written to. \n", "\n", "The function will return a dictionary in which the keys are (“vegp”, “vegm”, “drv_clm”) and the values are file paths where the CLM files were written.\n", "\n", "**NOTE:** *If you choose to provide a timezone while setting up a ParFlow simulation, it should be consistent across the functions `subset_press_init`, `subset_forcing` and `config_clm`.* This is an important parameter in CLM that is used to calculate solar zenith angle so its critical that the time zone you provide match your run. \n", "\n", "**NOTE:** The grid you use for your ij bounds must match the grid of the CLM files you are subsetting. " ] }, { "cell_type": "code", "execution_count": 4, "id": "97d055f7-5a38-4f5b-8332-bbf6dd84b1d4", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "bounding box: (2285, 436, 2358, 495)\n", "processing vegp\n", "copied vegp\n", "processing vegm\n", "subset vegm\n", "processing drv_clm\n", "copied drv_clmin\n", "edited drv_clmin\n" ] } ], "source": [ "#Set the ij bounds for the new model\n", "ij_box_bounds, _ = st.define_latlon_domain(latlon_bounds=[[37.91, -91.43], [37.34, -90.63]], grid=\"conus1\")\n", "print(f\"bounding box: {ij_box_bounds}\") \n", "\n", "#Get the CLM inputs\n", "file_paths = st.config_clm(\n", " ij_box_bounds, \n", " start=\"2005-10-01\", \n", " end=\"2006-10-01\", \n", " dataset=\"conus1_baseline_mod\",\n", " write_dir=\"/path/to/your/write/directory\",\n", ")" ] }, { "cell_type": "markdown", "id": "757e171d-5538-41d8-be51-32f79293d536", "metadata": {}, "source": [ "## 3. Getting the clm input files with the HydroData API\n", "The `config_clm` function is the easiest way to get all your CLM inputs configured for your domain in one step. However, as with all the other subsetting steps you can also obtain any of the input files directly on their own using the HydroData API. \n", "\n", "To do this we will use the `get_raw_file` function to get the `vegp` and `drv_clm` files. These are small text files and the `get_raw_file` function is going to get them from HydroData and write them to the given directory path. Note that the `get_raw_file` function is going to copy the files as they are - it will not modify them like the `config_clm` function.\n", "\n", "**NOTE:** Technically you can also use this approach to get the national `vegm` landcover file however subsetting this file requires a specific approach due to the formatting of the `vegm` file so we highly recommend you use the `config_clm` function above to get the subset for your domain directly. " ] }, { "cell_type": "code", "execution_count": 6, "id": "6c68fea9-3d11-4cb8-a935-c3430b7cbdc7", "metadata": {}, "outputs": [], "source": [ "# get the vegp file and write it to filepath:\n", "hf.get_raw_file(filepath=\"/path/to/your/write/directory\",\n", " dataset=\"conus1_baseline_mod\",\n", " file_type=\"vegp\",\n", ")\n", "\n", "# get the drv_clm file and write it to filepath:\n", "hf.get_raw_file(filepath=\"/path/to/your/write/directory\",\n", " dataset=\"conus1_baseline_mod\",\n", " file_type=\"drv_clm\",\n", ")" ] }, { "cell_type": "markdown", "id": "70810768-3916-4661-a93c-48b263bcc611", "metadata": {}, "source": [ "### 4. Cite the data sources\n", "\n", "Please make sure to cite all data sources that you use. We will use the `hf.get_citations` function, which takes as an argument a dataset name and returns citation information about that dataset:" ] }, { "cell_type": "code", "execution_count": 3, "id": "30b996dd-3497-4156-be41-4309a36a6aa2", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "'Modern CONUS1 simulations WY 2003-2006\\n Source: https://doi.org/10.5194/gmd-14-7223-2021\\n'" ] }, "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ "hf.get_citations(\"conus1_baseline_mod\")" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.9.17" } }, "nbformat": 4, "nbformat_minor": 5 }