nmizukami / mizuroute

Stand-alone river network routing model

mizuRoute

Stand-alone mizuRoute is a post-processor of runoff output from a hydrologic model or Land surface model to produce streamflow estimates in the river network provided by a user. The tool was developed for the large scale, network based river routing (e.g., river network over contiguous United States), but works for gridded river network as well.

Technical documentation is now being built on readthedocs

To get started

1. Obtaining mizuRoute package. Just to use the tool, download the package by clicking “Download Zip” button on right column.

2. Fortran compiler. Since we do not use any compiler-specific extensions, mizuRoute should be complied with any Fortran compilers. We have successfully used the intel Fortran compiler (ifort), the GNU Fortran compiler (gfortran), and PGI fortran compiler (pgf90). If the user does not have a Fortran compiler, gfortran can be installed for free. The easiest way is to use a package manager. Which package manager depends on your machine flavor. We tested with the following compilers:

   • gfortran 8.3.0
   • ifort 18.0.5
   • pgi 19.3

3. NetCDF libraries. NetCDF or the Network Common Data Format, is a set of software libraries and self-describing, machine-independent data formats that support the creation, access, and sharing of array-oriented scientific data. All the mizuRoute I/O (except control file and parameter namelist) use NetCDF. The user needs to ensure that: NetCDF version 4.x is installed in the linux-like machine. NetCDF Fortran library is installed (libnetcdff.*) and not just the C-version. The NetCDF libraries are compiled with the same compiler as you plan to compile mizuRoute The user may use netcdf test code to check if NetCDF libraries are properly installed.

4. Compiling the source code. Once you have all the above, you can compile mizuRoute source codes using the following steps: Navigate to your local copy of the mizuRoute directory and go to the build subdirectory.

   1. Edit F_MASTER (name of path befor build directory) and FC (compiler name: gnu, intel or pgi) and FC_EXE (compiler executable name). You may also need to set NCDF_PATH. You may need to add some extra entries if you are using a different Fortran compiler or your setup is different (if someone wants to contribute an actual configure script that would be great). openMP (shared memory parallel processing) directive is implemented to prallelize the routing process. To activate openMP, set isOpenMP= yes.

   2. Type make under directory where Makefile is located. If all goes well, this will create the executable runoff_route.exe to the bin directory. You may get some warnings (depending on your compiler settings), but you should not get any errors.

   3. Pay attention to the make output. You may need to set some environment variables (LD_LIBRARY_PATH in particular) to support dynamic linking;

   4. Try running the executables:

        ./route_runoff.exe
       	FATAL ERROR: need to supply name of the control file as a command-line argument
      

If you get this far then mizuRoute is built correctly and functional. Now, the user will have to generate input data, runoff data, river network topology and runoff mapping data (depending on input runoff option). Please look at readthedocs to learn more about mizuRoute input data.

The user are encouraged to start with example data to get familiarize the process. testCase are being now developed and posted separately.

For real application, getting river network data and mapping data in netCDF format correctly take work because this most likely requires GIS process and convert shapefile to netCDF).

mizuroute's Issues

MPI scatter

global input in this scatter function (first argument) has lbound and ubound specification and arrays on task complain. For this scatter function, global array in a root node has proper values but array on other tasks do not. The global array is declared with a size. so why this global array is not recognized on other tasks?

mizuRoute/route/build/src/mpi_process.f90

Lines 342 to 349 in e27caca

	call shr_mpi_scatterV(segId (nRch_mainstem+1:nRch_in), rch_per_proc(0:nNodes-1), segId_local, ierr, cmessage)
	call shr_mpi_scatterV(downSegId(nRch_mainstem+1:nRch_in), rch_per_proc(0:nNodes-1), downSegId_local, ierr, cmessage)
	call shr_mpi_scatterV(slope (nRch_mainstem+1:nRch_in), rch_per_proc(0:nNodes-1), slope_local, ierr, cmessage)
	call shr_mpi_scatterV(length (nRch_mainstem+1:nRch_in), rch_per_proc(0:nNodes-1), length_local, ierr, cmessage)
	call shr_mpi_scatterV(hruId (nHRU_mainstem+1:nHRU_in), hru_per_proc(0:nNodes-1), hruId_local, ierr, cmessage)
	call shr_mpi_scatterV(hruSegId (nHRU_mainstem+1:nHRU_in), hru_per_proc(0:nNodes-1), hruSegId_local, ierr, cmessage)
	call shr_mpi_scatterV(area (nHRU_mainstem+1:nHRU_in), hru_per_proc(0:nNodes-1), area_local, ierr, cmessage)

some easy fix

Add IRFlakeVol write option
see

mizuRoute/route/build/src/read_control.f90

Line 183 in 720f671

! OUTPUT OPTIONS

reach length check

issue: if reach length is negative, the program keep runs without checking but died in kinematic wave without meaningful, clear message.

resolution: add length check and if it is negative, the program states so, and stop graceful

array type in state data

can I put integer array back?
fcaa636

MPI: scatter runoff

mizuRoute/route/build/src/mpi_process.f90

Lines 536 to 546 in e27caca

	! sort the basin runoff in terms of nodes/domains
	if (pid == root) then ! this is a root process
	do iHru = 1,nHRU
	basinRunoff_sorted(iHru) = runoff_data%basinRunoff(ixHRU_order(iHru))
	enddo
	end if
	call system_clock(startTime)
	! Distribute the basin runoff to each process
	call shr_mpi_scatterV(basinRunoff_sorted(hru_per_proc(-1)+1:nHRU), hru_per_proc(0:nNodes-1), basinRunoff_local, ierr, cmessage)
	if(ierr/=0)then; message=trim(message)//trim(cmessage); return; endif

ixHRU size is number of hru contributing to reach not total hru in network data. if running over CONUS, nHRU is different than size of nContribHRU.

nHRU need to be replaced by size(ixHRU_order)

parallel do

Use "parallel do" instead of using defining "parallel region" and "do loop" inside

OMP and Serial runoff input

Try reading runoff with chunk of time steps to speed up. Need test

lake volume restart not implemented

feature/mpi-pio.lake_update_Nov
IRFlakeVol restart is not implemented. To implement, see commit 71a2534 (feature/mpi-pio.multi-input-lake-update)

MPI: need to distribute restart states to tributary

issue: restart states/fluxes information is read into global data structure and need to scatter them to node.

downstream ID

Current assumption on outlet of basin: if downstream ID is less than zero, it is outlet of the basin. kwt_routine use this assumption. This might not be good assumption based on downIndex routine in network_topo.f90. However, downstreamID can be any number and if the routine does not find segment ID matching with downstream ID, downstream index get missing. Also reach with downstreamID <=0 also get missing downstream Index. missing downIndex indicate outlet of the basin.

For MPI version, tributary basin (which connected to mainstem) preserve downstream ID from the entire network data and downstream index get missingVal during augmentation process. For this reason, kwt_routine cannot use downIndex <0 (or =missingVal) for outlet reach identification because outlet of tributary basin routine in task is not really outlet for the entire network. The KWT routine can use downstream ID (<=0 condition) to identify outlet within the tributary basin in task and outlet of the entire networks, but this relies on current downstream ID assumption.

To alleviate potential error in identifying outlet (tributary basin in task and entire network), downstream ID for entire network need to be set to missing. This way, tributary basin outlet in task still holds downstream ID.

config_archive.xml error

In line https://github.com/nmizukami/mizuRoute/blob/cesm-coupling/cime_config/config_archive.xml#L4
the regular expression is incorrect and should be changed to h..*.nc$

runoff order

if runoff data is already at RN_HRU, no need to remap, but will have to make sure that the order of RN_HRU in runoff data is the same as RN_HRU in river network data. See develop branch sort_runoff subroutine.

reading augmented river network data

Need 1) augmentationMode and 2) subsetMode.
augmentationMode write full set network variables for the entire network
subsetMode write the network variable specified in metadata for subset network.

PIO-output

Inconsistent, random failure
Could be pio open/close netcdf timing among task

• open at top and close at bottom instead of open/close for each variable writing

Could be root node got faster than tasks to reach write_netcdf statement in write_simoutput_pio.f90

• try putting barrier before write_netcdf statement in write_simoutput_pio.f90

reach volume exceeding maximum lake storage

Hello,

I found that my simulated reach volumes at some reaches are larger than maximum lake storage. I guess it is more reasonable to control it below the storage. In my implementation, I modified section "#updating the storage" in lake_route.f90 by simply limiting the storage to min(RCHFLX_out(iens,segIndex)%REACH_VOL(1), RPARAM_in(segIndex)%D03_MaxStorage), but this is only applied when maxstorage is supplied and larger than 1 (1 basically means it does not follow this fill-spill scheme). As for remaining water, it should be added to downstream

Hope this makes sense. Thanks
Zhi

River network from HydroSHEDS

Hi all,

I have a global runoff data and the NHDFlowliine seems available for the US. is there any way to use mizuRoute using other rivernetworks such as from HydroSHEDS https://www.hydrosheds.org/downloads

Best regards,
Solomon