-
Notifications
You must be signed in to change notification settings - Fork 4
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* revised documentation. * config changed to configs * Updated INSTALL.md * Updated INSTALL.md, and renamed test dir. * more updates. * Update README.md * Update README.md * update readme and realization files, tested examples. * Update README.md * Update RUN.md * Update CMakeLists.txt * merged RUN.md with INSTALL.md * Update README.md * Update INSTALL.md * Update INSTALL.md * Update README.md * updated test to tests in yaml file. * updated config to configs in yaml file. * fixed path in the realization file. * fixed path in the realization file.
- Loading branch information
Showing
23 changed files
with
171 additions
and
70 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| # Guidance on how to contribute | ||
|
|
||
| > All contributions to this project will be released to the public domain. | ||
| > By submitting a pull request or filing a bug, issue, or | ||
| > feature request, you are agreeing to comply with this waiver of copyright interest. | ||
| > Details can be found in our [TERMS](TERMS.md) and [LICENSE](LICENSE). | ||
|
|
||
| There are two primary ways to help: | ||
| - Using the issue tracker, and | ||
| - Changing the code-base. | ||
|
|
||
|
|
||
| ## Using the issue tracker | ||
|
|
||
| Use the issue tracker to suggest feature requests, report bugs, and ask questions. | ||
| This is also a great way to connect with the developers of the project as well | ||
| as others who are interested in this solution. | ||
|
|
||
| Use the issue tracker to find ways to contribute. Find a bug or a feature, mention in | ||
| the issue that you will take on that effort, then follow the _Changing the code-base_ | ||
| guidance below. | ||
|
|
||
|
|
||
| ## Changing the code-base | ||
|
|
||
| Generally speaking, you should fork this repository, make changes in your | ||
| own fork, and then submit a pull request. All new code should have associated | ||
| unit tests that validate implemented features and the presence or lack of defects. | ||
| Additionally, the code should follow any stylistic and architectural guidelines | ||
| prescribed by the project. In the absence of such guidelines, mimic the styles | ||
| and patterns in the existing code-base. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,54 @@ | ||
| # Installation instructions | ||
| Detailed instructions on how to build and run SoilMoistureProfiles for different setups/modes (standalone, with topmodel, and nextgen framework) are provided below. The schemes assume you have [GCC](https://gcc.gnu.org) and [CMAKE](https://cmake.org/) on your machine. These are simple examples providing a one-way coupling (model --> SoilMoistureProfiles) and are only for demonstration purposes. However, in real examples when coupled to other models, the soil moisture profiles effect freeze-thaw and other hydrological processes (such as infiltration). | ||
|
|
||
| **Note**: Before running the following examples, it is recommended to run the unittests [tests](https://github.com/NOAA-OWP/SoilMoistureProfiles/tree/ajk/doc_update/tests). | ||
|
|
||
| ## Standalone example | ||
| The example runs SMP for a hypothetical conceptual soil reservoir (with prescribed soil_storage and soil_storage_change SMP BMI input variables) to compute `watertable` and `soil_moisture_profile` and compare the results against benchmark results. The hypothetical conceptual soil reservoir mimics CFE. | ||
| ### Build | ||
| ``` | ||
| git clone https://github.com/NOAA-OWP/SoilMoistureProfiles && cd SoilMoistureProfiles | ||
| mkdir build && cd build | ||
| cmake ../ -DSTANDALONE=ON | ||
| make && cd .. | ||
| ``` | ||
|
|
||
| ### Run | ||
| <pre> | ||
| Run: <a href="https://github.com/NOAA-OWP/SoilMoistureProfiles/blob/ajk/doc_update/run_sft.sh">./run_smp.sh</a> STANDALONE (from SoilMoistureProfiles directory) | ||
| </pre> | ||
|
|
||
| ## Pseudo framework example | ||
| An example coupling TopModel to SMP to compute `watertable` and `soil_moisture_profile` from soil moisture deficit. | ||
| ### Build | ||
| ``` | ||
| git clone https://github.com/NOAA-OWP/SoilMoistureProfiles && cd SoilMoistureProfiles | ||
| git clone https://github.com/NOAA-OWP/topmodel extern/topmodel | ||
| mkdir build && cd build | ||
| cmake ../ -DWITHTOPMODEL=ON | ||
| make && cd .. | ||
| ``` | ||
| ### Run | ||
| <pre> | ||
| Run: <a href="https://github.com/NOAA-OWP/SoilMoistureProfiles/blob/ajk/doc_update/run_sft.sh"> ./run_smp.sh</a> WITHTOPMODEL (from SoilMoistureProfiles directory) | ||
| </pre> | ||
|
|
||
| ## Nextgen framework example | ||
| Detailed instructions for running and building SoilMoistureProfiles coupled to other models (for instance, CFE or SFT) in the nextgen framework are provided at [instructions](https://github.com/NOAA-OWP/SoilFreezeThaw/blob/master/INSTALL.md). | ||
| ### Build | ||
| ``` | ||
| mkdir smp && cd smp (in the nextgen directory) | ||
| ln -s ../extern | ||
| ln -s ../data | ||
| ln -s extern/SoilMoistureProfiles/SoilMoistureProfiles/realizations | ||
| ``` | ||
| ### Run | ||
| - Standalone example | ||
| ``` | ||
| ../cmake_build/ngen data/catchment_data.geojson cat-27 data/nexus_data.geojson nex-26 realizations/realization_config_smp.json | ||
| ``` | ||
| - With Topmodel example | ||
| ``` | ||
| cp ./extern/topmodel/topmodel/data/* data | ||
| ../cmake_build/ngen data/catchment_data.geojson cat-27 data/nexus_data.geojson nex-26 realizations/realization_config_smp_topmodel.json | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,60 +1,46 @@ | ||
| ## SoilMoistureProfiles | ||
| Three schemes are provided here to compute vertical soil moisture profiles. | ||
| * Scheme for conceptual soil reserviors **(e.g., CFE)** | ||
| * Schemes for layered soil reservoirs **(e.g., LGAR)** | ||
| * Schemes for topmodel (details are provided below) | ||
| # SoilMoistureProfiles | ||
| The soil moisture profiles schemes provide soil moisture distributed over a one-dimensional vertical column. These schemes facilitate coupling among different models such as (CFE and SFT or LASAM and SFT). The following three schemes are provided here to compute vertical soil moisture profiles. | ||
| * Scheme for conceptual soil reservoirs (e.g., **[CFE](https://github.com/NOAA-OWP/cfe))** | ||
| * Schemes for layered soil reservoirs (e.g., **[LGAR](https://github.com/NOAA-OWP/LGAR-C))** | ||
| * Schemes for topmodel (details are provided below; **[TopModel](https://github.com/NOAA-OWP/topmodel))** | ||
|
|
||
| ### Conceptual soil reservior | ||
| For conceptual reservoirs, see the following schematic and algorithm. We use the Clap-Hornberger soil moisture characteristic function here, and **soil moisture storage** is the main input passed through a BMI. | ||
| ## Conceptual soil reservoir | ||
| For conceptual reservoirs, see the following schematic and algorithm. We use the Clap-Hornberger soil moisture characteristic function here, and **soil moisture storage** is the main input passed through a BMI. | ||
|
|
||
|  | ||
|
|
||
| ### Layered soil reservior | ||
| For layered soil reserviors, the two options include | ||
| ## Layered soil reservoir | ||
| For layered soil reservoirs, the two options include | ||
| * constant by layer, and Clap-Horngerger soil moisture characteristic function for the profile below the depth of the last layer | ||
| * linearly interpolated profile between consecutive layers, and Clap-Horngerger soil moisture characteristic function for the profile below the depth of the last layer | ||
|
|
||
| ### Topmodel based soil reservoir | ||
| ## Topmodel based soil reservoir | ||
| * (flux-based method) A method using an iterative scheme to first compute watertable depth and then soil moisture profile ([Blazkova et al. (2002)](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2001WR000912)) | ||
| * (deficit-based method) A method using catchment deficit to first compute watertable depth and then soil moisture profile ([Franchini et al. (1996)](https://www.sciencedirect.com/science/article/abs/pii/S0022169496800151) | ||
|
|
||
|
|
||
| ### Compiling and Running SoilMoistureProfiles | ||
| There are two examples (CFE and Topmodel) for running SoilMoistureProfiles as described below. They assume you have [GCC](https://gcc.gnu.org) and [CMAKE](https://cmake.org/) on your machine. These are simple examples and provide a one-way coupling (model --> SoilMoistureProfiles), does not change the functionality of the model, and are only for demonstration purposes. | ||
|
|
||
| 1. `Option STANDALONE` : An example of using `soil_storage` (conceptual reservoir; CFE) to compute `soil_moisture_profile` | ||
| 2. `Option WITHTOPMODEL` : An example of using topmodel's outputs to compute `watertable` and `soil_moisture_profile` | ||
| ``` | ||
| git clone https://github.com/NOAA-OWP/SoilMoistureProfiles.git | ||
| cd SoilMoistureProfiles | ||
| git clone https://github.com/NOAA-OWP/topmodel extern/topmodel (needed for running with Topmodel, i.e., -DWITHTOPMODEL=ON) | ||
| mkdir build && cd build | ||
| cmake ../ [-DSTANDALONE=ON,-DWITHTOPMODEL=ON] (pick one option, e.g. `cmake ../ -DSTANDALONE=ON`) | ||
| make && cd .. | ||
| ./run_smp.sh [STANDALONE, WITHTOPMODEL] (pick one option) | ||
| ``` | ||
|
|
||
| ### Coupled mode (ngen and pseudo frameworks): | ||
| * Coupling SoilMoistureProfiles to any module (for instance, CFE or SFT) **must** follow these [instructions](https://github.com/NOAA-OWP/SoilFreezeThaw) for building and running. **Note separate instructions are provided for building/running in the ngen framework on the SoilFreezeThaw repo.** | ||
| * Follow this example: [couple SMP with SFT](https://github.com/NOAA-OWP/SoilFreezeThaw/blob/master/src/main_cfe_aorc_pet_ftm.cxx) | ||
|
|
||
|
|
||
| _________________________________________________________________ | ||
| ## Description of the parameters in the config file | ||
|
|
||
| | Variable _____________________ | Datatype _______________ | Limits _________________ | Units ____ | Role ___ | Description _____________________________________________________________________| | ||
| | :-------- | :-------- | :------ | :----- | :---- | :----------------------- | | ||
| | smcmax | double (1D array) | - | - | - | the maximum moisture content (i.e., porosity). Note porosity for layered-based models vary by layers | | ||
| | b | double | - | - | - | the pore size distribution, beta exponent in Clapp-Hornberger function | | ||
| | satpsi | double | - | - | - | saturated capillary head (saturated moisture potential) | | ||
| | soil_z | double (1D array) | - | m | - | vertical resolution of the soil moisture profile (depths from the surface) | | ||
| | soil_storage_model_depth | double | - | m | - | depth of the soil reservoir model (e.g., CFE). Note: this depth can be different from the depth of the soil moisture profile which is based on `soil_z` | | ||
| | soil_storage_model | string | conceptual or layered or topmodel | - | - | if `conceptual`, conceptual models are used for computing the soil moisture profile (e.g., CFE). If `layered`, layered-based soil moisture models are used (e.g., LGAR). If `topmodel`, topmodel's variables are used | ||
| | soil_moisture_profile_option | string | constant or linear | - | - | `constant` for layered-constant profile. `linear` for linearly interpolated values between two consecutive layers. Needed if `soil_storage_model = layered`. | ||
| | soil_depth_layers | double (1D array) | - | - | - | Absolute depth of soil layers. Needed if `soil_storage_model = layered`. | ||
| | soil_moisture_fraction_depth | double | (0, domain_depth] | m | - | *user specified depth for the soil moisture fraction (default is 40 cm) | ||
| | water_table_based_method | string | flux-based or deficit-based | - | - | Needed if `soil_storage_model = topmodel`. `flux-based` uses an iterative scheme, and `deficit-based` uses catchment deficit to compute soil moisture profile | ||
|
|
||
| *Note: SoilMoistureProfiles has a bmi output called soil_moisture_fraction (water in the topsoil over total water in the soil column) needs the depth of the topsoil (`soil_moisture_fraction_depth`, default is set to 40 cm -- the top two cells in the soil column of the NWM 3.0) | ||
| _________________________________________________________________ | ||
| ## Build and Run Instructions | ||
| Detailed instructions on how to build and run SoilMoistureProfiels (SMP) can be found here [INSTALL](https://github.com/NOAA-OWP/SoilMoistureProfiles/blob/ajk/doc_update/INSTALL.md). | ||
| - Test examples highlights | ||
| - Unittest: (see [tests](https://github.com/NOAA-OWP/SoilMoistureProfiles/blob/ajk/doc_update/tests/README.md)) | ||
| - Standalone: An example computing `watertable` and `soil_moisture_profile` using a soil conceptual reservoir (see [build/run](https://github.com/NOAA-OWP/SoilMoistureProfiles/blob/ajk/doc_update/INSTALL.md#standalone-example)) | ||
| - With topmodel: An example coupling TopModel to SMP (Soil Moisture Profiles) to compute `watertable` and `soil_moisture_profile` (see [build/run](https://github.com/NOAA-OWP/SoilMoistureProfiles/blob/ajk/doc_update/INSTALL.md#pseudo-framework-example)) | ||
| - Nextgen examples: Realization files for the two above examples (Standalone and with topmodel) are provided [here](https://github.com/NOAA-OWP/SoilMoistureProfiles/blob/ajk/doc_update/realizations) (see [build/run](https://github.com/NOAA-OWP/SoilMoistureProfiles/blob/ajk/doc_update/INSTALL.md#nextgen-framework-example)). | ||
|
|
||
| ## Model Configuration File | ||
| Detailed description of the parameters for model configuration is provided ([here](https://github.com/NOAA-OWP/SoilMoistureProfiles/tree/ajk/doc_update/configs/README.md)) | ||
|
|
||
| ## Getting help | ||
| For questions, please contact Ahmad Jan (ahmad.jan(at)noaa.gov), the main developer/maintainer of the repository. | ||
|
|
||
| ## Known issues or raise an issue | ||
| We are constantly looking to improve the model and/or fix bugs as they arise. Please see the Git Issues for known issues or if you want to suggest adding a capability or to report a bug, please open an issue. | ||
|
|
||
| ## Getting involved | ||
| See general instructions to contribute to the model development ([instructions](https://github.com/NOAA-OWP/SoilMoistureProfiles/blob/ajk/doc_update/CONTRIBUTING.md)) or simply fork the repository and submit a pull request. | ||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| ## Configuration Files | ||
| Example configuration files are provided here. To run the given examples see the instructions ([here](https://github.com/NOAA-OWP/SoilMoistureProfiles/blob/ajk/doc_update/RUN.md)). | ||
|
|
||
| A detailed description of the parameters for model configuration (i.e., initialize/setup) is provided below. The asterisk (*) denotes calibratable parameters (i.e., `smcmax, b, and satpsi` can be calibrated) | ||
|
|
||
| | Variable _____________________ | Datatype _______________ | Limits _________________ | Units ____ | Role ___ | Description _____________________________________________________________________| | ||
| | :-------- | :-------- | :------ | :----- | :---- | :----------------------- | | ||
| | *smcmax | double (1D array) | - | - | - | the maximum moisture content (i.e., porosity). Note porosity for layered-based models vary by layers | | ||
| | *b | double | - | - | - | the pore size distribution, beta exponent in Clapp-Hornberger function | | ||
| | *satpsi | double | - | - | - | saturated capillary head (saturated moisture potential) | | ||
| | soil_z | double (1D array) | - | m | - | vertical resolution of the soil moisture profile (depths from the surface) | | ||
| | soil_storage_model_depth | double | - | m | - | depth of the soil reservoir model (e.g., CFE). Note: this depth can be different from the depth of the soil moisture profile which is based on `soil_z` | | ||
| | soil_storage_model | string | conceptual or layered or topmodel | - | - | if `conceptual`, conceptual models are used for computing the soil moisture profile (e.g., CFE). If `layered`, layered-based soil moisture models are used (e.g., LGAR). If `topmodel`, topmodel's variables are used | ||
| | soil_moisture_profile_option | string | constant or linear | - | - | `constant` for layered-constant profile. `linear` for linearly interpolated values between two consecutive layers. Needed if `soil_storage_model = layered`. | ||
| | soil_depth_layers | double (1D array) | - | - | - | Absolute depth of soil layers. Needed if `soil_storage_model = layered`. | ||
| | soil_moisture_fraction_depth | double | (0, domain_depth] | m | - | **user specified depth for the soil moisture fraction (default is 40 cm) | ||
| | water_table_based_method | string | flux-based or deficit-based | - | - | Needed if `soil_storage_model = topmodel`. `flux-based` uses an iterative scheme, and `deficit-based` uses catchment deficit to compute soil moisture profile | ||
|
|
||
| **Note: SoilMoistureProfiles has a bmi output called soil_moisture_fraction (water in the topsoil over total water in the soil column) needs the depth of the topsoil (`soil_moisture_fraction_depth`, default is set to 40 cm -- the top two cells in the soil column of the NWM 3.0) | ||
| _________________________________________________________________ |
File renamed without changes.
File renamed without changes.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.