HyMAP Version 3 - Initial implementation

[agetiran]

Description

Description
This pull request adds HyMAP-3 to LIS (second attempt).
HyMAP-3 includes ~4 years of new developments and improvements in surface water modeling. Compared to its previous version, HyMAP-2, it includes:

simplified/built-in configuration,
more numerical stability,
urban flood module,
coastal flood module,
water management module,
levees module,
beaver dam module,
new reservoir operation module
initial implementation of vectorization (this is unfinished, and not yet functional)
This addition will be followed with some changes in LDT.

A HyMAP-3 Tech Memo is in the works. The document will provide technical background and instructions on how to use HyMAP-3 options in the LIS config file.

References:

Getirana, A., Biswas, N.K., Kumar, S., Nie, W., Ahmad, S., Maina, F., et al., 2025. Deltaic freshwater scarcity driven by unsustainable groundwater-fed irrigation. Nature Sustainability. DOI: 10.1038/s41893-025-01566-0

Getirana, A., Kumar, S., Konapala, G., Nie, W., Locke, K., Loomis, B., Birkett, C., Ricko, M., Simard, M., 2023. Climate and Human Impacts on Hydrological Processes and Flood Risk in Southern Louisiana. Water Resources Research. DOI: 10.1029/2022WR033238

Getirana, A., Mandarino, F., Montezuma, P.N., Kirschbaum, D., 2023. An urban drainage scheme for large-scale flood models. Journal of Hydrology. DOI: 10.1016/j.jhydrol.2023.130410.

Getirana, A., Kumar, S., Konapala, G., Ndehedehe, C.E., 2021. Impacts of fully coupling land surface and flood models on the simulation of large wetlands’ water dynamics: the case of the Inner Niger Delta. J. Adv. Model. Earth Syst. DOI: 10.1029/2021MS002463

Testcase

Input files for the tests can be found in
/discover/nobackup/projects/eis_nldas3/agetiran/hymap_1d_test/

[emkemp]

Good morning @agetiran

A few comments:

(1) The pull request was missing the code to actually register HYMAP3 at runtime, and LIS would seg fault when I ran your test case. I added this in commit 16cc413, and I now get identical results for 201101210000. Yay!

(2) I can't find a test case for running LDT with HYMAP3 support. Please provide one.

(3) There is no HYMAP3 documentation to both the LDT and LIS User Guides. Please provide this.

(4) Some of the code have old copyright blocks (references to LIS 7.2). I will coordinate with @jvgeiger on resolving this.

[emkemp]

Also, there are variables for filenames and directories that do not use the new LIS_CONST_PATH_LEN and LDT_CONST_PATH_LEN. I will work to fix this.

[emkemp]

Also, there are hardwired unit numbers for file I/O. These should use LIS_getNextUnitNumber and LIS_releaseUnitNumber. I will correct this as well.

[agetiran]

@emkemp
(1) Thanks for catching that issue and fixing it.

(2) Basic HyMAP3 capabilities work with the existing LDT configuration. I'll provide LDT updates to process HyMAP3 data for advanced capabilities at a later time.

(3) I'm also wrapping up a HyMAP3 tech memo, which could be referred to copied and pasted into the LIS User Guide

(4) I discussed that topic with Jim and he said there was an automated way to update the copyright blocks.

Thanks!

[emkemp]

Two other issues:

(1) There are a few 'print*' statements. I will replace with write(LIS_logunit,*).

(2) There is at least one stop statement. I will replace with a call to LIS_endrun.

[agetiran]

Can you point me to these "print" and "stop" statements? They may be debugging leftovers

[emkemp]

Hi @agetiran

I fixed the cases in /discover/nobackup/projects/usaf_lis/emkemp/pr/1731/LISF/lis/routing/HYMAP3_router before I saw your message. There may be other cases in the da_WL and runoffdata subdirectories.

[emkemp]

Thanks @agetiran

It looks like there are still some undocumented entries for ldt.config. When you have time, please update the ldt.config.adoc as well.