Skip to content

Update README.md #68

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cenlinhe merged 1 commit into from
Mar 10, 2023
Merged

Update README.md #68

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 59 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,39 +1,79 @@
# noahmp
Noah-MP Community Repository
# Noah-MP Community Model Repository


This is the official Noah-MP unified Github repository for code downloading and contribution. Note that Noah-MP is a community model contributed by the whole Noah-MP scientific community. For maintenance and release of this GitHub, please contact: Cenlin He (cenlinhe@ucar.edu) and Fei Chen (feichen@ucar.edu).
Noah-MP is a widely-used state-of-the-art land surface model used in many research and operational weather/climate models (e.g., HRLDAS, WRF, MPAS, WRF-Hydro/NWM, NOAA/UFS, NASA/LIS, etc.).

Some changes have been made to the structure of archiving the stand-alone version of Noah-MP/HRLDAS code in the Github repository. Now, it separately archives the core Noah-MP source code, Noah-MP driver, and parameter tables in this unified Noah-MP Github repository and the rest of the HRLDAS related files (e.g., module_sf_urban.F, etc.) in another unified HRLDAS Github repository (https://github.com/NCAR/hrldas). The HRLDAS Github repo is already linked to this unified core Noah-MP code repository. This new archiving structure will allow different host model platforms/systems (e.g., HRLDAS, WRF, UFS, NWM, LIS, etc.) to connect to the core Noah-MP source code and develop their own host model drivers.
This is the official Noah-MP land surface model unified repository for code downloading and contribution. Noah-MP is a community open-source model developed with the contributions from the entire scientific community. For development, maintenance, and release of the community Noah-MP GitHub code, please contact: Cenlin He (cenlinhe@ucar.edu) and Fei Chen (feichen@ucar.edu).

Model developers can make code development based on the develop branch and create pull request to the develop branch. The pull request will be reviewed by Noah-MP model release team and if everything looks good, the new code development will be merged to the develop branch. Eventually, the updates in the develop branch will be merged to the master branch for official Noah-MP model release.

Branch structures of this Noah-MP repository:
## New: Release of Noah-MP version 5.0 (Refactored/Modernized version)

1. "master" branch: most stable & recent version, updated whenever there are bug fixes or major model update/release;
The latest Noah-MP model version (version 5.0) has been released in March 9, 2023, which is a modernized/refactored version by re-writing the entire model with modern Fortran code infrastructure and data structures. All future Noah-MP developments and updates will be made only to this modernized/refactored version. The version 5.0 has the same model physics as the version 4.5, but with a different code infrastructure. More details about the Noah-MP version 5.0 can be found in the model description paper (He et al., 2023b, in review) and the technical documentation (He et al. 2023a). Currently, the Noah-MP version 5.0 coupling with HRLDAS has been completed, but its coupling with other host models (e.g., WRF-Hydro, NASA/LIS, WRF, MPAS, UFS, etc.) is still on-going.

2. "develop" branch: used for continuous NoahMP development, keep being updated by including bug fixes and code updates (e.g., new physics options, processes, etc.);

3. "develop_no_gecros" branch: same as the "develop" branch, except for excluding the gecros crop section (to be consistent with recent Noah-MP changes for National Water Model (NWM));
## Noah-MP technical documentation and model description papers

4. "release-v4.3-WRF" branch: version archive of the stable version consistent with the WRFv4.3 release;
Technical documentation freely available at http://dx.doi.org/10.5065/ew8g-yr95

5. "release-v4.3-NWM" branch: version archive, same as the "release-v4.3-WRF" branch, except for excluding the gecros crop section (to be consistent with recent Noah-MP changes for National Water Model (NWM));
**To cite the technical documentation**: He, C., P. Valayamkunnath, M. Barlage, F. Chen, D. Gochis, R. Cabell, T. Schneider, R. Rasmussen, G.-Y. Niu, Z.-L. Yang, D. Niyogi, and M. Ek (2023): The Community Noah-MP Land Surface Modeling System Technical Description Version 5.0, (No. NCAR/TN-575+STR). doi:10.5065/ew8g-yr95

Some suggestions for model developers to contribute to Noah-MP code through the Github repository (typical procedures):
**Original Noah-MP model description paper**: Niu, G. Y., Yang, Z. L., Mitchell, K. E., Chen, F., Ek, M. B., Barlage, M., ... & Xia, Y. (2011). The community Noah land surface model with multiparameterization options (Noah‐MP): 1. Model description and evaluation with local‐scale measurements. Journal of Geophysical Research: Atmospheres, 116(D12).

1. Step (1) Create a fork of this official NoahMP repository to your own Github account;
**Noah-MP version 5.0 model description paper**: He, C., P. Valayamkunnath, M. Barlage, F. Chen, D. Gochis, R. Cabell, T. Schneider, R. Rasmussen, G.-Y. Niu, Z.-L. Yang, D. Niyogi, and M. Ek (2023): Modernizing the open-source community Noah-MP land surface model (version 5.0) with enhanced modularity, interoperability, and applicability, GMD, in review.

2. Step (2) Make code updates based on the "develop" branch of the forked repository under your own account;

## Noah-MP GitHub structures

**The folders**:

1. docs/: Noah-MP variable glossary and technical documentation;

2. drivers/: Noah-MP driver and interface code to connect to different host models (each host model will has its own subdirectory under this driver/);

3. parameters/: Noah-MP parameter table (note that the original 3 parameter tables have been merged into one NoahmpTable.TBL starting from version 5.0);

4. src/: Noah-MP source code modules;

5. utility/: Noah-MP utility code.

**The branches**:

1. "master" branch: (currently version 5.0), most stable & latest version, updated whenever there are bug fixes or major model update/release (by merging from the "develop" branch);

2. "develop" branch: (currently version 5.0), used for continuous NoahMP development, keep updated by including bug fixes and code updates (e.g., new physics options, processes, etc.);

3. other version release branches: store different released code versions.


## Important notes

This GitHub repository only provides the Noah-MP source code and driver/interface code. To run Noah-MP in either offline or online mode, users need to have the host model system/framework coupled with Noah-MP.

NCAR also maintains and releases the HRLDAS (High Resolution Land Data Assimilation System) coupled with Noah-MP to allow offline Noah-MP simulations. Please see the HRLDAS GitHub repository (https://github.com/NCAR/hrldas) for details. For users who are interested in other host models that couple with Noah-MP, please refer to those host model GitHub repositories.

For users who are interested in previous Noah-MP code versions (prior to version 5.0), please refer to the different GitHub branches in this repository. Particularly, the "release-v4.5-WRF" branch has the same model physics as the Noah-MP version 5.0, but with an old model code structures, which is consistent with the Noah-MP code released along with WRF version 4.5.


## Code contribution via GitHub

Users are welcome to make code development and contributions through GitHub pull requests. The pull request will be reviewed by the Noah-MP model physics and code release team, and if everything looks good, the pull request of new code development or bug fixes will be merged into the develop branch. During each year's major version release period, the updated develop branch will be further merged into the master branch for official release of a new Noah-MP model version.

Some suggestions for model developers to contribute to Noah-MP code through the GitHub repository (typical procedures):

1. Step (1) Create a fork of this official Noah-MP repository to your own GitHub account;

2. Step (2) Create a new branch based on the latest "develop" branch and make code updates/changes in the forked repository under your own account;

3. Step (3) Finalize and test the code updates you make;

4. Step (4) Submit a pull request for your model updates from your own forked Github repository to the "develop" branch of the official repository;
4. Step (4) Submit a pull request for your code updates from your own forked Github repository to the "develop" branch of this official Noah-MP repository;

5. Step (5) The Noah-MP physics and code review committee reviews and tests the model updates in the submitted pull request and discusses with the developer if there is any problem;

6. Step (6) The Noah-MP physics and code review committee confirms the pull request and merges the updated code to the "develop" branch in this official Noah-MP repository;

5. Step (5) The Noah-MP release team reviews and tests the model updates in the submitted pull request and discusses with the developer if there is any problem;
7. Step (7) The Noah-MP physics and code review committee merges the updated "develop" branch to the master branch during the annual release of new model versions.

6. Step (6) The Noah-MP release team confirms the pull request and merges the updated code to the "develop" and "develop_no_gecros" branches in the official repository;

7. Step (7) The Noah-MP release team will merge the updated "develop" branch to the master branch and version-release branch during the annual model release.

Note: If updates are made to both the core NoahMP source codes and other HRLDAS files, two separate pull requests need to be submitted to this NoahMP repository and the HRLDAS repository (https://github.com/NCAR/hrldas), respectively, regarding the changes in the Noah-MP code files and other HRLDAS-related files. This could be done by using the same titles for the two pull requests to ensure that the submitted code changes are handled together by the release team in the two repositories.
Updated on March 9, 2023