Repository: NCAR/wrf_hydro_nwm_public Branch: main Commit: 694109d42232 Files: 740 Total size: 9.5 MB Directory structure: gitextract_36al2cpr/ ├── .github/ │ ├── CODESTYLE.md │ ├── CONTRIBUTING.md │ ├── ISSUE_TEMPLATE/ │ │ └── bug_report.md │ ├── PULL_REQUEST_TEMPLATE.md │ └── workflows/ │ └── test-pr.yml ├── .gitignore ├── .readthedocs.yaml ├── CITATION.cff ├── CMakeLists.txt ├── CODE_OF_CONDUCT.md ├── LICENSE.txt ├── NEWS.md ├── docs/ │ ├── BUILD.rst │ ├── Makefile │ ├── requirements.txt │ └── userguide/ │ ├── _static/ │ │ └── ug_theme.css │ ├── appendices.rest │ ├── conf.py │ ├── index.rest │ ├── input-tables/ │ │ ├── Fulldom_hires.tsv │ │ ├── geo_em.tsv │ │ └── wrfinput.tsv │ ├── introduction.rest │ ├── meta.rest │ ├── model-code-config.rest │ ├── model-inputs-preproc.rest │ ├── model-outputs.rest │ ├── model-physics.rest │ ├── nudging.rest │ ├── output-tables/ │ │ ├── CHANOBS_DOMAIN.csv │ │ ├── CHRTOUT_DOMAIN.csv │ │ ├── CHRTOUT_GRID.csv │ │ ├── GWOUT_DOMAIN.csv │ │ ├── LAKEOUT_DOMAIN.csv │ │ ├── LDASOUT_DOMAIN.csv │ │ ├── LSMOUT.csv │ │ └── RTOUT_DOMAIN.csv │ └── references.rest ├── src/ │ ├── .nwm_version │ ├── .version │ ├── CMakeLists.txt │ ├── CPL/ │ │ ├── CLM_cpl/ │ │ │ ├── Makefile │ │ │ ├── Makefile.cpl │ │ │ ├── bat2.csh │ │ │ ├── cesm_cpl_compiling.csh │ │ │ ├── clm_drv_HYDRO.F │ │ │ └── module_clm_HYDRO.F │ │ ├── LIS_cpl/ │ │ │ ├── Makefile │ │ │ ├── Makefile.cpl │ │ │ ├── lis_drv_HYDRO.F │ │ │ └── module_lis_HYDRO.F │ │ ├── NUOPC_cpl/ │ │ │ ├── .gitignore │ │ │ ├── CMakeLists.txt │ │ │ ├── Doxyfile │ │ │ ├── Makefile │ │ │ ├── WRFHydro_ESMF_Extensions.F90 │ │ │ ├── WRFHydro_NUOPC_Cap.F90 │ │ │ ├── WRFHydro_NUOPC_Fields.F90 │ │ │ ├── WRFHydro_NUOPC_Flags.F90 │ │ │ ├── WRFHydro_NUOPC_Gluecode.F90 │ │ │ ├── WRFHydro_NUOPC_Macros.h │ │ │ └── analysis/ │ │ │ ├── ferret_NUOPC_import.jnl │ │ │ ├── ferret_NUOPC_mask.jnl │ │ │ ├── grid_NUOPC_CONUS.ncl │ │ │ └── grid_NUOPC_Global.ncl │ │ ├── NoahMP_cpl/ │ │ │ ├── CMakeLists.txt │ │ │ ├── Makefile │ │ │ ├── hrldas_drv_HYDRO.F │ │ │ └── module_hrldas_HYDRO.F │ │ ├── Noah_cpl/ │ │ │ ├── Makefile │ │ │ ├── hrldas_drv_HYDRO.F │ │ │ └── module_hrldas_HYDRO.F │ │ └── WRF_cpl/ │ │ ├── CMakeLists.txt │ │ ├── Makefile │ │ ├── Makefile.cpl │ │ ├── module_wrf_HYDRO.F90 │ │ ├── module_wrf_HYDRO_downscale.F90 │ │ └── wrf_drv_HYDRO.F90 │ ├── Data_Rec/ │ │ ├── CMakeLists.txt │ │ ├── Makefile │ │ ├── module_RT_data.F90 │ │ ├── module_gw_gw2d_data.F90 │ │ ├── module_namelist.F90 │ │ ├── module_namelist_inc.F90 │ │ └── module_rt_inc.F90 │ ├── Debug_Utilities/ │ │ ├── CMakeLists.txt │ │ ├── Makefile │ │ └── debug_dump_variable.F90 │ ├── Doc/ │ │ └── link_to_documentation.txt │ ├── HYDRO_drv/ │ │ ├── CMakeLists.txt │ │ ├── Makefile │ │ └── module_HYDRO_drv.F90 │ ├── IO/ │ │ ├── CMakeLists.txt │ │ ├── Makefile │ │ └── netcdf_layer.F90 │ ├── Land_models/ │ │ ├── Noah/ │ │ │ ├── CHANGES │ │ │ ├── CMakeLists.txt │ │ │ ├── GRAPHICS/ │ │ │ │ ├── HORIZ/ │ │ │ │ │ ├── Makefile │ │ │ │ │ ├── kwm_date_utilities.F │ │ │ │ │ ├── kwm_string_utilities.F │ │ │ │ │ ├── lccone.F │ │ │ │ │ ├── llxy_generic.F │ │ │ │ │ ├── module_2ddata.F │ │ │ │ │ ├── module_plot2d_graphics.F │ │ │ │ │ ├── namelist.plt2d │ │ │ │ │ └── plt2d.F │ │ │ │ └── TIME_SERIES/ │ │ │ │ ├── Makefile │ │ │ │ ├── kwm_date_utilities.F │ │ │ │ ├── kwm_string_utilities.F │ │ │ │ ├── lccone.F │ │ │ │ ├── ldasout_timeseries.F │ │ │ │ ├── llxy_generic.F │ │ │ │ ├── module_plotts_graphics.F │ │ │ │ ├── module_ptdata.F │ │ │ │ ├── namelist.pltts │ │ │ │ └── namelist.pltts.sample │ │ │ ├── HRLDAS_COLLECT_DATA/ │ │ │ │ ├── GRIB_TABLES/ │ │ │ │ │ ├── GRIB1_PARAMETER_TABLE │ │ │ │ │ └── GRIB2_PARAMETER_TABLE │ │ │ │ ├── Makefile │ │ │ │ ├── consolidate_grib.F │ │ │ │ ├── lib/ │ │ │ │ │ ├── Makefile │ │ │ │ │ ├── arguments_module.F │ │ │ │ │ ├── cio.c │ │ │ │ │ ├── decode_jpeg2000.c │ │ │ │ │ ├── gbytesys.F │ │ │ │ │ ├── get_unused_unit.F │ │ │ │ │ ├── io_f.c │ │ │ │ │ ├── kwm_date_utilities.F │ │ │ │ │ ├── kwm_grid_utilities.F │ │ │ │ │ ├── kwm_string_utilities.F │ │ │ │ │ ├── kwm_timing_utilities.F │ │ │ │ │ ├── module_geo_em.F │ │ │ │ │ ├── module_grib.F │ │ │ │ │ ├── module_grib1.F │ │ │ │ │ ├── module_grib2.F │ │ │ │ │ ├── module_grib2_tables.F │ │ │ │ │ ├── module_grib_common.F │ │ │ │ │ ├── module_input_data_structure.F │ │ │ │ │ ├── module_llxy.F │ │ │ │ │ ├── module_mapinfo.F │ │ │ │ │ ├── module_wrfinputfile.F │ │ │ │ │ ├── swap4c.c │ │ │ │ │ ├── swap4f.F │ │ │ │ │ └── trig_degrees.F │ │ │ │ └── run/ │ │ │ │ ├── Makefile │ │ │ │ ├── README.namelist │ │ │ │ ├── namelist.example.complex │ │ │ │ ├── namelist.example.simple │ │ │ │ └── namelist.input │ │ │ ├── IO_code/ │ │ │ │ ├── Makefile │ │ │ │ ├── Noah_hrldas_driver.F │ │ │ │ └── module_hrldas_netcdf_io.F │ │ │ ├── Makefile │ │ │ ├── Noah/ │ │ │ │ ├── CMakeLists.txt │ │ │ │ ├── Makefile │ │ │ │ ├── module_sf_noahlsm.F │ │ │ │ ├── module_sf_noahlsm.F.org │ │ │ │ └── module_sf_urban.F │ │ │ ├── Run/ │ │ │ │ ├── GENPARM.TBL │ │ │ │ ├── LANDUSE.TBL │ │ │ │ ├── Makefile │ │ │ │ ├── SOILPARM.TBL │ │ │ │ ├── URBPARM.TBL │ │ │ │ └── VEGPARM.TBL │ │ │ ├── Utility_programs/ │ │ │ │ ├── Makefile │ │ │ │ ├── gcip_sw_to_grib/ │ │ │ │ │ ├── Makefile │ │ │ │ │ ├── srb_daily_to_grib.F │ │ │ │ │ └── srb_monthly_to_grib.F │ │ │ │ ├── geth_newdate.c │ │ │ │ ├── gribbyte.c │ │ │ │ ├── gribedition.c │ │ │ │ ├── gribextract.c │ │ │ │ ├── hrldas_extract_point.F │ │ │ │ ├── lccone.F │ │ │ │ ├── llxy_generic.F │ │ │ │ ├── modify_wrfinput.F │ │ │ │ └── vectorize/ │ │ │ │ ├── check_test.ncl │ │ │ │ ├── check_wrfinput.ncl │ │ │ │ ├── namelist.vectorize │ │ │ │ ├── procedure.txt │ │ │ │ ├── vectorize.perl │ │ │ │ ├── vectorize_geo_em.F │ │ │ │ ├── vectorize_ldasin.F │ │ │ │ └── vectorize_wrfinput.f90 │ │ │ ├── Utility_routines/ │ │ │ │ ├── CMakeLists.txt │ │ │ │ ├── Makefile │ │ │ │ ├── kwm_string_utilities.F │ │ │ │ ├── module_Noahlsm_utility.F │ │ │ │ ├── module_date_utilities.F │ │ │ │ ├── module_model_constants.F │ │ │ │ └── module_sfcdif_wrf.F │ │ │ ├── Utility_scripts/ │ │ │ │ ├── modify_wrfinput.ncl │ │ │ │ ├── nam_3d_gribextract.csh │ │ │ │ ├── ncep_rad_gribextract.csh │ │ │ │ └── ndas_surface_gribextract.csh │ │ │ ├── VERIFICATION/ │ │ │ │ ├── Fluxes_statistics/ │ │ │ │ │ ├── Makefile │ │ │ │ │ ├── fluxes_statistics.F │ │ │ │ │ ├── get_unused_unit.F │ │ │ │ │ ├── kwm_date_utilities.F │ │ │ │ │ ├── kwm_grid_utilities.F │ │ │ │ │ ├── kwm_plot_utilities.F │ │ │ │ │ ├── kwm_string_utilities.F │ │ │ │ │ ├── lccone.F │ │ │ │ │ ├── llxy_generic.F │ │ │ │ │ ├── module_hd.F │ │ │ │ │ └── namelist.fluxstats │ │ │ │ └── OKMeso_statistics/ │ │ │ │ ├── Makefile │ │ │ │ ├── get_unused_unit.F │ │ │ │ ├── kwm_date_utilities.F │ │ │ │ ├── kwm_plot_utilities.F │ │ │ │ ├── kwm_string_utilities.F │ │ │ │ ├── lccone.F │ │ │ │ ├── llxy_generic.F │ │ │ │ ├── module_hd.F │ │ │ │ ├── okmeso.namelist │ │ │ │ ├── rdbz.c │ │ │ │ ├── rdmet.F │ │ │ │ ├── rdsom.F │ │ │ │ └── rdsom_mem.F │ │ │ ├── user_build_options.bak │ │ │ ├── user_build_options.gfort │ │ │ ├── user_build_options.gfortran │ │ │ ├── user_build_options.linux │ │ │ └── user_build_options.linux.sequential │ │ └── NoahMP/ │ │ ├── CMakeLists.txt │ │ ├── HRLDAS_forcing/ │ │ │ ├── Makefile │ │ │ ├── create_forcing.F │ │ │ ├── lib/ │ │ │ │ ├── Makefile │ │ │ │ ├── arguments_module.F │ │ │ │ ├── cio.c │ │ │ │ ├── decode_jpeg2000.c │ │ │ │ ├── gbytesys.F │ │ │ │ ├── get_unused_unit.F │ │ │ │ ├── io_f.c │ │ │ │ ├── kwm_date_utilities.F │ │ │ │ ├── kwm_grid_utilities.F │ │ │ │ ├── kwm_string_utilities.F │ │ │ │ ├── kwm_timing_utilities.F │ │ │ │ ├── module_geo_em.F │ │ │ │ ├── module_grib.F │ │ │ │ ├── module_grib1.F │ │ │ │ ├── module_grib2.F │ │ │ │ ├── module_grib2_tables.F │ │ │ │ ├── module_grib_common.F │ │ │ │ ├── module_input_data_structure.F │ │ │ │ ├── module_llxy.F │ │ │ │ ├── module_mapinfo.F │ │ │ │ ├── module_wrfinputfile.F │ │ │ │ ├── swap4c.c │ │ │ │ ├── swap4f.F │ │ │ │ └── trig_degrees.F │ │ │ └── run/ │ │ │ ├── Makefile │ │ │ ├── README.namelist │ │ │ └── examples/ │ │ │ ├── GLDAS/ │ │ │ │ ├── check_SW.ncl │ │ │ │ ├── combine_precips.f90 │ │ │ │ ├── combine_precips.perl │ │ │ │ ├── create_UV.f90 │ │ │ │ ├── create_UV.perl │ │ │ │ ├── extract_gldas.perl │ │ │ │ ├── extract_gldas_init.perl │ │ │ │ ├── fill_SSRD.f90 │ │ │ │ ├── fill_SSRD.perl │ │ │ │ ├── gribtab_GLDAS_NOAH.gtb │ │ │ │ └── namelist.input.GLDAS │ │ │ ├── NARR/ │ │ │ │ ├── check_SW.ncl │ │ │ │ ├── extract_narr_30m.perl │ │ │ │ ├── extract_narr_init.perl │ │ │ │ ├── extract_narr_sfc.perl │ │ │ │ ├── fill_DSWRF.f90 │ │ │ │ ├── fill_DSWRF.perl │ │ │ │ └── namelist.input.NARR │ │ │ ├── NLDAS/ │ │ │ │ ├── extract_nldas.perl │ │ │ │ ├── extract_nldas_init.perl │ │ │ │ └── namelist.input.NLDAS │ │ │ ├── namelist.example.complex │ │ │ ├── namelist.example.simple │ │ │ └── vector/ │ │ │ ├── create_ldasin_files.ncl │ │ │ └── create_setup.ncl │ │ ├── IO_code/ │ │ │ ├── Makefile │ │ │ ├── main_hrldas_driver.F │ │ │ ├── module_NoahMP_hrldas_driver.F │ │ │ └── module_hrldas_netcdf_io.F │ │ ├── Makefile │ │ ├── README │ │ ├── Utility_routines/ │ │ │ ├── CMakeLists.txt │ │ │ ├── Makefile │ │ │ ├── kwm_string_utilities.F │ │ │ ├── module_date_utilities.F │ │ │ ├── module_model_constants.F │ │ │ └── module_wrf_utilities.F │ │ ├── data_structures/ │ │ │ ├── CMakeLists.txt │ │ │ ├── Makefile │ │ │ ├── forcing.f90 │ │ │ ├── geometry.f90 │ │ │ ├── parameters.f90 │ │ │ └── state.f90 │ │ ├── hydro/ │ │ │ ├── Makefile.hydro │ │ │ ├── Makefile_run │ │ │ └── user_build_options.bak │ │ ├── phys/ │ │ │ ├── CMakeLists.txt │ │ │ ├── Makefile │ │ │ ├── module_sf_noahmp_glacier.F │ │ │ ├── module_sf_noahmp_groundwater.F │ │ │ ├── module_sf_noahmpdrv.F │ │ │ ├── module_sf_noahmplsm.F │ │ │ └── surfex/ │ │ │ ├── CMakeLists.txt │ │ │ ├── Makefile │ │ │ ├── ini_csts.F │ │ │ ├── modd_csts.F │ │ │ ├── modd_snow_metamo.F │ │ │ ├── modd_snow_par.F │ │ │ ├── modd_surf_atm.F │ │ │ ├── mode_snow3l.F │ │ │ ├── mode_surf_coefs.F │ │ │ ├── mode_thermos.F │ │ │ ├── module_snowcro.F │ │ │ ├── module_snowcro_intercept.F │ │ │ └── tridiag_ground_snowcro.F │ │ ├── run/ │ │ │ ├── GENPARM.TBL │ │ │ ├── MPTABLE.TBL │ │ │ ├── Makefile │ │ │ └── SOILPARM.TBL │ │ └── version │ ├── MPP/ │ │ ├── CMakeLists.txt │ │ ├── CPL_WRF.F90 │ │ ├── Makefile │ │ ├── Makefile.NoahMP │ │ ├── hashtable.F90 │ │ ├── module_mpp_GWBUCKET.F90 │ │ ├── module_mpp_ReachLS.F90 │ │ └── mpp_land.F90 │ ├── Makefile │ ├── OrchestratorLayer/ │ │ ├── CMakeLists.txt │ │ ├── Makefile │ │ ├── config.F90 │ │ ├── io_manager.F90 │ │ └── orchestrator.F90 │ ├── README.build.md │ ├── Rapid_routing/ │ │ ├── .gitignore │ │ ├── .rapid_init.F90.swp │ │ ├── LICENSE │ │ ├── README │ │ ├── hrldas_RAPID_drv.F90 │ │ ├── hrldas_RAPID_wrapper.F90 │ │ ├── makefile │ │ ├── makefile.cpl │ │ ├── makefile.orig │ │ ├── rapid_arrays.F90 │ │ ├── rapid_close_Qfor_file.F90 │ │ ├── rapid_close_Qhum_file.F90 │ │ ├── rapid_close_Qobs_file.F90 │ │ ├── rapid_close_Qout_file.F90 │ │ ├── rapid_close_Vlat_file.F90 │ │ ├── rapid_create_Qout_file.F90 │ │ ├── rapid_create_obj.F90 │ │ ├── rapid_destro_obj.F90 │ │ ├── rapid_final.F90 │ │ ├── rapid_get_Qdam.F90 │ │ ├── rapid_hsh_mat.F90 │ │ ├── rapid_init.F90 │ │ ├── rapid_main.F90 │ │ ├── rapid_namelist │ │ ├── rapid_net_mat.F90 │ │ ├── rapid_net_mat_brk.F90 │ │ ├── rapid_obs_mat.F90 │ │ ├── rapid_open_Qfor_file.F90 │ │ ├── rapid_open_Qhum_file.F90 │ │ ├── rapid_open_Qobs_file.F90 │ │ ├── rapid_open_Qout_file.F90 │ │ ├── rapid_open_Vlat_file.F90 │ │ ├── rapid_phiroutine.F90 │ │ ├── rapid_read_Qfor_file.F90 │ │ ├── rapid_read_Qhum_file.F90 │ │ ├── rapid_read_Qobs_file.F90 │ │ ├── rapid_read_Vlat_file.F90 │ │ ├── rapid_read_namelist.F90 │ │ ├── rapid_routing.F90 │ │ ├── rapid_routing_param.F90 │ │ ├── rapid_script.sh │ │ ├── rapid_set_Qext0.F90 │ │ ├── rapid_var.F90 │ │ └── rapid_write_Qout_file.F90 │ ├── Routing/ │ │ ├── CMakeLists.txt │ │ ├── Diversions/ │ │ │ ├── CMakeLists.txt │ │ │ ├── Makefile │ │ │ ├── module_diversions.F90 │ │ │ └── module_diversions_timeslice.F90 │ │ ├── Makefile │ │ ├── Noah_distr_routing.F90 │ │ ├── Noah_distr_routing_overland.F90 │ │ ├── Noah_distr_routing_subsurface.F90 │ │ ├── Overland/ │ │ │ ├── CMakeLists.txt │ │ │ ├── Makefile │ │ │ ├── module_overland.F90 │ │ │ ├── module_overland_control.F90 │ │ │ ├── module_overland_mass_balance.F90 │ │ │ ├── module_overland_routing_properties.F90 │ │ │ ├── module_overland_streams_and_lakes.F90 │ │ │ ├── overland.md │ │ │ └── overland_tests.F90 │ │ ├── Reservoirs/ │ │ │ ├── .gitignore │ │ │ ├── CMakeLists.txt │ │ │ ├── Level_Pool/ │ │ │ │ ├── CMakeLists.txt │ │ │ │ ├── Makefile │ │ │ │ ├── module_levelpool.F90 │ │ │ │ ├── module_levelpool_properties.F90 │ │ │ │ ├── module_levelpool_state.F90 │ │ │ │ └── module_levelpool_tests.F90 │ │ │ ├── Makefile │ │ │ ├── Persistence_Level_Pool_Hybrid/ │ │ │ │ ├── CMakeLists.txt │ │ │ │ ├── Makefile │ │ │ │ ├── module_persistence_levelpool_hybrid.F90 │ │ │ │ ├── module_persistence_levelpool_hybrid_properties.F90 │ │ │ │ ├── module_persistence_levelpool_hybrid_state.F90 │ │ │ │ └── module_persistence_levelpool_hybrid_tests.F90 │ │ │ ├── Persistence_Level_Pool_Hybrid_Module_README.md │ │ │ ├── RFC_Forecasts/ │ │ │ │ ├── CMakeLists.txt │ │ │ │ ├── Makefile │ │ │ │ ├── module_rfc_forecasts.F90 │ │ │ │ ├── module_rfc_forecasts_properties.F90 │ │ │ │ ├── module_rfc_forecasts_state.F90 │ │ │ │ └── module_rfc_forecasts_tests.F90 │ │ │ ├── RFC_Forecasts_Module_README.md │ │ │ ├── module_reservoir.F90 │ │ │ ├── module_reservoir_read_rfc_time_series_data.F90 │ │ │ ├── module_reservoir_read_timeslice_data.F90 │ │ │ ├── module_reservoir_utilities.F90 │ │ │ └── reservoir_tests.F90 │ │ ├── Subsurface/ │ │ │ ├── CMakeLists.txt │ │ │ ├── Makefile │ │ │ ├── module_subsurface.F90 │ │ │ ├── module_subsurface_grid_transform.F90 │ │ │ ├── module_subsurface_input.F90 │ │ │ ├── module_subsurface_output.F90 │ │ │ ├── module_subsurface_properties.F90 │ │ │ ├── module_subsurface_state.F90 │ │ │ ├── module_subsurface_static_data.F90 │ │ │ └── subsurface_tests.F90 │ │ ├── module_GW_baseflow.F90 │ │ ├── module_HYDRO_io.F90 │ │ ├── module_HYDRO_utils.F90 │ │ ├── module_NWM_io.F90 │ │ ├── module_NWM_io_dict.F90 │ │ ├── module_RT.F90 │ │ ├── module_UDMAP.F90 │ │ ├── module_channel_routing.F90 │ │ ├── module_date_utilities_rt.F90 │ │ ├── module_gw_gw2d.F90 │ │ ├── module_lsm_forcing.F90 │ │ ├── module_noah_chan_param_init_rt.F90 │ │ └── module_reservoir_routing.F90 │ ├── arc/ │ │ ├── Makefile.Noah │ │ ├── Makefile.NoahMP │ │ ├── Makefile.mpp │ │ ├── macros.gordon │ │ ├── macros.gordon.debug │ │ ├── macros.mpp.IBM.xlf90_r │ │ ├── macros.mpp.cray_fortran │ │ ├── macros.mpp.gfort │ │ ├── macros.mpp.ifort │ │ ├── macros.mpp.ifort.omp │ │ ├── macros.mpp.intel.cray_xc │ │ ├── macros.mpp.linux │ │ └── macros.mpp.mpiifort │ ├── cmake-modules/ │ │ ├── FindESMF.cmake │ │ └── FindNetCDF.cmake │ ├── compile_offline_Noah.sh │ ├── compile_offline_NoahMP.sh │ ├── compile_options.json │ ├── configure │ ├── deprecated/ │ │ ├── README.build.txt │ │ ├── build_install.sh │ │ └── build_install_theia.sh │ ├── hrldas_namelists.json │ ├── hydro_namelists.json │ ├── nudging/ │ │ ├── CMakeLists.txt │ │ ├── Makefile │ │ ├── Nudging_frxst_gage.csv │ │ ├── io/ │ │ │ ├── CMakeLists.txt │ │ │ └── module_nudging_io.F90 │ │ ├── module_date_utils_nudging.F90 │ │ ├── module_nudging_utils.F90 │ │ └── module_stream_nudging.F90 │ ├── nwm.md │ ├── nwm_doxyfile │ ├── template/ │ │ ├── HYDRO/ │ │ │ ├── CHANPARM.TBL │ │ │ ├── HYDRO.TBL │ │ │ ├── HYDRO_MODIS.TBL │ │ │ └── hydro.namelist │ │ ├── Noah/ │ │ │ └── namelist.hrldas │ │ ├── NoahMP/ │ │ │ └── namelist.hrldas │ │ ├── examples/ │ │ │ └── nwm/ │ │ │ ├── namelists/ │ │ │ │ ├── v2.0/ │ │ │ │ │ ├── analysis_assim/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ ├── analysis_assim_extended/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ ├── analysis_assim_long_range/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ ├── hi_analysis_assim/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ ├── hi_short_range/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ ├── long_range/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ ├── medium_range/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ └── short_range/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── v2.0_reforecasts/ │ │ │ │ │ ├── analysis_assim/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ ├── analysis_assim_extended/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ ├── analysis_assim_long_range/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ ├── long_range/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ ├── medium_range/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ └── short_range/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── v2.1/ │ │ │ │ │ ├── analysis_assim/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ ├── analysis_assim_extended/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ ├── analysis_assim_longrange/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ ├── hi_analysis_assim/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ ├── hi_short_range/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ ├── long_range/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ ├── medium_range/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ ├── pr_analysis_assim/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ ├── pr_short_range/ │ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ │ └── namelist.hrldas │ │ │ │ │ └── short_range/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ └── v3.0/ │ │ │ │ ├── ak_analysis_assim/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── ak_analysis_assim_extended/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── ak_analysis_assim_extended_no_da/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── ak_analysis_assim_no_da/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── ak_medium_range/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── ak_medium_range_no_da/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── ak_short_range/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── analysis_assim/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── analysis_assim_extended/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── analysis_assim_extended_no_da/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── analysis_assim_longrange/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── analysis_assim_longrange_no_da/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── analysis_assim_no_da/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── hi_analysis_assim/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── hi_analysis_assim_no_da/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── hi_short_range/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── hi_short_range_no_da/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── long_range/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── medium_range/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── medium_range_no_da/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── pr_analysis_assim/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── pr_analysis_assim_no_da/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── pr_short_range/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ ├── pr_short_range_no_da/ │ │ │ │ │ ├── hydro.namelist │ │ │ │ │ └── namelist.hrldas │ │ │ │ └── short_range/ │ │ │ │ ├── hydro.namelist │ │ │ │ └── namelist.hrldas │ │ │ └── parameter_tables/ │ │ │ ├── v2.0/ │ │ │ │ ├── CHANPARM.TBL │ │ │ │ ├── GENPARM.TBL │ │ │ │ ├── HYDRO.TBL │ │ │ │ ├── MPTABLE.TBL │ │ │ │ └── SOILPARM.TBL │ │ │ ├── v2.1/ │ │ │ │ ├── CHANPARM.TBL │ │ │ │ ├── GENPARM.TBL │ │ │ │ ├── HYDRO.TBL │ │ │ │ ├── MPTABLE.TBL │ │ │ │ └── SOILPARM.TBL │ │ │ └── v3.0/ │ │ │ ├── Alaska/ │ │ │ │ ├── CHANPARM.TBL │ │ │ │ ├── GENPARM.TBL │ │ │ │ ├── HYDRO.TBL │ │ │ │ ├── MPTABLE.TBL │ │ │ │ └── SOILPARM.TBL │ │ │ ├── CONUS/ │ │ │ │ ├── CHANPARM.TBL │ │ │ │ ├── GENPARM.TBL │ │ │ │ ├── HYDRO.TBL │ │ │ │ ├── MPTABLE.TBL │ │ │ │ └── SOILPARM.TBL │ │ │ ├── Hawaii/ │ │ │ │ ├── CHANPARM.TBL │ │ │ │ ├── GENPARM.TBL │ │ │ │ ├── HYDRO.TBL │ │ │ │ ├── MPTABLE.TBL │ │ │ │ └── SOILPARM.TBL │ │ │ └── PuertoRico/ │ │ │ ├── CHANPARM.TBL │ │ │ ├── GENPARM.TBL │ │ │ ├── HYDRO.TBL │ │ │ ├── MPTABLE.TBL │ │ │ └── SOILPARM.TBL │ │ └── setEnvar.sh │ ├── utils/ │ │ ├── CMakeLists.txt │ │ ├── Makefile │ │ ├── fortglob/ │ │ │ ├── CMakeLists.txt │ │ │ ├── Makefile │ │ │ ├── fortglob.F90 │ │ │ ├── libfortglob.c │ │ │ └── libfortglob.h │ │ ├── module_hydro_stop.F90 │ │ └── module_version.F90 │ └── wrf_hydro_config └── tests/ ├── __init__.py ├── config_file_meta/ │ ├── croton_NY/ │ │ ├── nwm_ana/ │ │ │ ├── FORCING.md5 │ │ │ ├── NWM/ │ │ │ │ ├── DOMAIN/ │ │ │ │ │ ├── Fulldom_hires.cdl │ │ │ │ │ ├── Fulldom_hires.md5 │ │ │ │ │ ├── GEOGRID_LDASOUT_Spatial_Metadata.cdl │ │ │ │ │ ├── GEOGRID_LDASOUT_Spatial_Metadata.md5 │ │ │ │ │ ├── GWBUCKPARM.cdl │ │ │ │ │ ├── GWBUCKPARM.md5 │ │ │ │ │ ├── LAKEPARM.cdl │ │ │ │ │ ├── LAKEPARM.md5 │ │ │ │ │ ├── Route_Link.cdl │ │ │ │ │ ├── Route_Link.md5 │ │ │ │ │ ├── geo_em.d01.cdl │ │ │ │ │ ├── geo_em.d01.md5 │ │ │ │ │ ├── hydro2dtbl.cdl │ │ │ │ │ ├── hydro2dtbl.md5 │ │ │ │ │ ├── nudgingParams.cdl │ │ │ │ │ ├── nudgingParams.md5 │ │ │ │ │ ├── soil_properties.cdl │ │ │ │ │ ├── soil_properties.md5 │ │ │ │ │ ├── spatialweights.cdl │ │ │ │ │ ├── spatialweights.md5 │ │ │ │ │ ├── wrfinput_d01.cdl │ │ │ │ │ └── wrfinput_d01.md5 │ │ │ │ ├── RESTART/ │ │ │ │ │ ├── HYDRO_RST.2011-08-26_00:00_DOMAIN1.cdl │ │ │ │ │ ├── HYDRO_RST.2011-08-26_00:00_DOMAIN1.md5 │ │ │ │ │ ├── RESTART.2011082600_DOMAIN1.cdl │ │ │ │ │ ├── RESTART.2011082600_DOMAIN1.md5 │ │ │ │ │ ├── nudgingLastObs.2011-08-26_00:00:00.cdl │ │ │ │ │ └── nudgingLastObs.2011-08-26_00:00:00.md5 │ │ │ │ └── nudgingTimeSliceObs.md5 │ │ │ ├── hydro.namelist │ │ │ └── namelist.hrldas │ │ └── nwm_long_range/ │ │ ├── FORCING.md5 │ │ ├── NWM/ │ │ │ ├── DOMAIN/ │ │ │ │ ├── nudgingParams.cdl │ │ │ │ └── nudgingParams.md5 │ │ │ ├── DOMAIN_LR/ │ │ │ │ ├── Fulldom_hires.cdl │ │ │ │ ├── Fulldom_hires.md5 │ │ │ │ ├── GEOGRID_LDASOUT_Spatial_Metadata.cdl │ │ │ │ ├── GEOGRID_LDASOUT_Spatial_Metadata.md5 │ │ │ │ ├── GWBUCKPARM.cdl │ │ │ │ ├── GWBUCKPARM.md5 │ │ │ │ ├── LAKEPARM.cdl │ │ │ │ ├── LAKEPARM.md5 │ │ │ │ ├── Route_Link.cdl │ │ │ │ ├── Route_Link.md5 │ │ │ │ ├── geo_em.d01.cdl │ │ │ │ ├── geo_em.d01.md5 │ │ │ │ ├── hydro2dtbl.cdl │ │ │ │ ├── hydro2dtbl.md5 │ │ │ │ ├── soil_properties.cdl │ │ │ │ ├── soil_properties.md5 │ │ │ │ ├── spatialweights.cdl │ │ │ │ ├── spatialweights.md5 │ │ │ │ ├── wrfinput_d01.cdl │ │ │ │ └── wrfinput_d01.md5 │ │ │ ├── RESTART/ │ │ │ │ ├── nudgingLastObs.2011-08-26_00:00:00.cdl │ │ │ │ └── nudgingLastObs.2011-08-26_00:00:00.md5 │ │ │ ├── RESTART_LR/ │ │ │ │ ├── HYDRO_RST.2011-08-26_00:00_DOMAIN1.cdl │ │ │ │ ├── HYDRO_RST.2011-08-26_00:00_DOMAIN1.md5 │ │ │ │ ├── RESTART.2011082600_DOMAIN1.cdl │ │ │ │ └── RESTART.2011082600_DOMAIN1.md5 │ │ │ └── nudgingTimeSliceObs.md5 │ │ ├── hydro.namelist │ │ └── namelist.hrldas │ └── get_config_file_meta_data.py ├── conftest.py ├── ctests/ │ ├── CMakeLists.txt │ ├── run_cmake_testcase.sh │ ├── run_dir_makefile.mk │ ├── setup_cmake_testcase.sh │ ├── should_fail.f90 │ └── should_not_fail.f90 ├── hrldas_option_suites.json ├── hydro_option_suites.json ├── local/ │ ├── derecho/ │ │ ├── example_croton_test.sh │ │ └── model_test.sh │ ├── examples/ │ │ ├── ex1_run_croton_derecho.sh │ │ ├── ex2_run_conus_derecho.sh │ │ └── ex3_run_croton_docker.sh │ ├── requirements.txt │ ├── reservoir_testing_files/ │ │ ├── 2010-10-01_06:00:00.15min.usgsTimeSlice.ncdf │ │ ├── 2016-10-10_00:00:00.15min.usaceTimeSlice.ncdf │ │ ├── 2019-08-18_00.60min.CCHC1.RFCTimeSeries.ncdf │ │ ├── 2019-08-18_00.60min.SNOA2.RFCTimeSeries.ncdf │ │ ├── 2019-09-18_00.60min.CCHC1.RFCTimeSeries.ncdf │ │ ├── 2019-10-18_00.60min.CCHC1.RFCTimeSeries.ncdf │ │ ├── 2019-11-18_00.60min.CCHC1.RFCTimeSeries.ncdf │ │ ├── 2019-12-19_05.60min.CCHC1.RFCTimeSeries.ncdf │ │ ├── reservoir_index_AnA_represents_Extended_MR.nc │ │ ├── reservoir_index_Long_Range_AnA.nc │ │ ├── reservoir_index_Standard_AnA_APRFC_GDLs.nc │ │ └── reservoir_index_short_range.nc │ ├── run_tests.py │ └── utils/ │ ├── attach_all_plots.bash │ ├── attach_plots_to_pr.py │ ├── generate_diff_plots.py │ ├── nwm_testing.yml │ ├── releaseapi.py │ ├── requirements.txt │ └── thresholds.csv ├── test_1_fundamental.py ├── test_2_regression.py ├── test_3_outputs.py ├── test_supp_1_channel_only.py ├── test_supp_2_nwm_output.py ├── utilities.py └── utils/ ├── compare_output.py ├── xrcmp.py └── xrnan.py ================================================ FILE CONTENTS ================================================ ================================================ FILE: .github/CODESTYLE.md ================================================ # WRF-Hydro Fortran Conventions Guide # Fortran standard New code contributions should be written to at least [Fortran 2003 standard](https://gcc.gnu.org/wiki/GFortranStandards#Fortran_2003). # Source Code Formatting * Max line length 100 characters. All wrapped code statements shall at least be indented one additional level beyond the previous level. * Do NOT use tab characters. * Indentation: 3 spaces (no tabs) for all control below the subroutine/function level (indenting less often saves a lot of space). Tightly nested do loops can be exceptions. Put comments at same indentation level as the code which it is commenting. ```fortran module my_module integer :: local_var !================================================================================================== subroutine foo implicit none !no indent until control units, line breaks between units do i=1,2 ! white space in-line not crucial for readability as in long subroutine calls count=i end do ! i=1,2 do i=1,2 do j=i,(i*2) count = i + j end do ! j=i,(i*2) end do ! i=1,2 do i=1,2 do j=i,(i*2) ! control structure is compact, easy to perceive without indentations count = i + j end do ! j=i,(i*2) end do ! i=1,2 end subroutine foo end module my_module ``` * Generally use lower case except for where emphasis is needed. * Camel case, vs underscores * firstLowerCamelCase: use most generally * FirstUpperCamelCase: Classes * lowecase_underscore_separated: use for mouldes, subroutines, functions * UPPERCASE_UNDERSCORE_SEPARATED: constants * Line up related pieces of syntax (readability when there are repeated elements, ability to count the position of arguments), including end-of-line characters. ```fortran # WRONG foo=function(apple, banana, corn, & durian, eggplant, fig) # CORRECT foo=function(apple, banana, corn, & durian, eggplant, fig ) ``` * Place the same number of arguments on each line except the last for countability/position matching. ```fortran # WRONG foo=function(a,b,c = 1) # CORRECT foo = function(a, b, c=1) ``` * Horizontal white space: enhances readability, esp w respect to function/subroutine arguments. Whitespace helps identify separate things. * Vertical white space: * No vertical white space: Used to group closely-related lines of code. * Single vertical white space: Separate less-related lines of code. After control structures. * Two vertical white spaces: only used to emphasize separation between functions, subroutines and occasionally large code blocks. * Control structures identified against their opening statement. * #ifdef: When nested. * If, do, while, case: Best practice: All the time. Required: when spanning more than one page of vertical space. ```fortran #ifdef HYDRO_D #ifdef OBSCURE_THING … #endif /* HYDRO_D */ #endif /* OBSCURE_THING */ if(a .eq. 100) then ….. endif ! if(a .eq. 100) or if(a .eq. 100) then !! a .eq. 100 block … endif !! a .eq. 100 block ``` * Comment blocks above every unit (module, subtroutine, function), with the following form. This should be the NCO standard template. ```fortran !=================================================================================================== ! Subroutine Name: ! subroutine read_nudging_last_obs ! Author(s)/Contact(s): ! James L McCreight ! Abstract: ! does some fancy thing ! History Log: ! 02/03/16 -Created, JLM. ! Usage: ! Parameters: ! Input Files: ! Output Files: ! Condition codes: ! User controllable options: None. ! Notes: Needs better error handling... ``` * Allocate/deallocate statements do NOT span multiple lines. This is so grep can reveal all allocation/deallocation pairs. ```fortran # WRONG allocate(foo, & bar) # CORRECT allocate(foo) allocate(bar) allocate(foo, bar) ``` # Naming ## Source file names * The name of the source file or script shall represent its purpose. All of the functions in a file shall have a common purpose. * Source file names SHALL NOT include spaces nor colons (‘:’) nor any other special characters. * End in the `.Fxx` extension, with `xx` corresponding to the fortran standard, e.g. `.F90` * Filenames shall use the `lowercase_underscore_separated.Fxx` convention. ## Output file names * Source file names SHALL NOT include spaces nor colons (`:`) nor any other special characters. ## Variable names * Variable names shall convey their intended use to other developers who did not author the code. This eliminates need for inline comments that describe variables. * DO NOT strive to much for shortening of variable names, prefer meaningful name: local shortening is often possible with the associate construct. * Comments/descriptions on variables: * All variables in argument lists will be described in the definition using FORD syntax. * Derived type arguments only need documented in bulk, their individual components only need defined where the derived type is defined. * Variable descriptions will not be redundant with the variable name * Descriptions will describe the physical quantity * Descriptions will include units. * Variable names shall contain a noun. * Exception: when widely accepted equations have simple variable names. (e.g. `F=m*a`) * Loop counters should typically have names. * Loop counters should NOT be single letters. Simply doubling the letter makes it easier to search for the use (and possibly replace). * Conventions for special kinds of variables: * Accumulation variables: “acc” prefix, e.g. * MPI global variables * prognostic vs diagnostic variables * logical variables must be named to reflect the state they are used to convey, most with the verb to be, e.g. : * `lib_is_initialized` vs `lib_init` * `obj_has_parent` vs `obj_parent` ## Function/Subroutine Names * Function names shall contain at least one verb, e.g. `get_name`, `parse_control_string`. * Function names shall convey their intended use to other developers who did not author the code. * Follow the `lowercase_underscore_separated` convention. ## Constant names * Name all constants: Numbers should not be used in the code except in variable definitions. * All constants are defined as parameters. * Exceptions: should be rare and clearly typed (float, double, etc). * Constants follow the `UPPERCASE_UNDERSCORE SEPARATED` convention for naming. * Constant names shall describe what the contained value represents within context, e.g. `NO_DATA_VALUE`, `PLANCK_LENGTH`, `HIGH_TEMPERATURE_THRESHOLD`, etc. # Documenting in the source * Code documentation should be a primary source of overall documentation. By following simple practices, such documentation can be extracted to live separately if needed. But keeping it close as possible to the source maintains consistency and improves communication among developers: all you need is the source to understand the code (not other random documents) * Write code that documents itself. Try to make code as clear as possible (“self-documenting”) to avoid use of comments and redundancy between the two which needs synchronized or is confusingly out of sync. Writing self-documenting code includes using variable names with obvious meaning and documenting ambiguities in variable names when they exist. Minimize commenting “what” (repeating the code with comments) but do it when it is necessary for interpretation. * Document why (not what). Algorithmic choices are often the hardest thing to perceive, not function calls on variables. * Indent comments to the indentation level of the code which is being commented. * Comments shall be written in English with good spelling, punctuation, and grammar. * Documentation shall be placed in the code and [FORD](https://github.com/cmacmackin/ford) will be used to generate documentation. * TODO: Comments used to remind developers of future or unfinished actions in source code shall begin with “TODO FML” (first middle last initials, as available), and describe the action to be taken. TODO comments shall also list a specific date or event by which the TODO action will be completed. ```fortran ! TODO JLM : Rename the variable foo to discharge. Target Date: 12/25/20 ! TODO JLM : Rename the variable foo to discharge. ! TODO JLM : Target Date: 12/25/20 ``` * DEPRECATED: Flagging deprecated code sections shall be done in the following way for automated removal at end-of-version code release. ```fortran !DEPRECATED >>> !code !code !<<< DEPRECATED ``` # File header comments * Each source file shall contain one file header comment. * File header comments shall contain the following: * A concise description of the collective purpose of file contents. * Exception: When a file contains only one class or function definition, this description shall simply state the file is an implementation or definition file for class/function ``. The class or function description will be written into the class or function header comment. * Organization name: National Center for Atmospheric Research * Current maintainer * Author names. Multiple authors should be listed when more than one developer has worked on a source file over time. ```fortran ! module_super_foo.F ! Purpose: This module file contains the derived type and ! methods for the super_foo class. ! National Center for Atmospheric Research ! Responsible: James L McCreight ucar ! Authors: James McCreight, Logan Karsten, Wei Yu ``` # Module/Subroutines/Function Usage * Always use modules. * Intent: all arguments should be given an intent (in,out, inout), * Each argument is defined on its own line. Document details in- or below- line using [FORD](https://github.com/cmacmackin/ford/wiki/Writing-Documentation) conventions. * FORD will ignore a normal comments preceded with a single exclamation mark (!) However, comments with two exclamation marks (!!) are interpreted as documentation and will be captured for inclusion in the FORD output. By default, FORD documentation comes after whatever it is that you are documenting, either at the end of the line or on a subsequent line. * For longer blocks of documentation, it can be inconvenient to continually type the "docmark" = ‘!!’. For such situations, the docmark_alt (set to * by default) may be used in the first line of the documentation comment. Any immediately following lines containing only a comment will then be included in the block of documentation, without needing the "docmark". Example: ```fortran subroutine feed_pets(cats, dogs, food, angry) !! Feeds your cats and dogs, if enough food is available. If not enough !! food is available, some of your pets will get angry. ! Arguments integer, intent(in) :: cats !! The number of cats to keep track of. integer, intent(in) :: dogs !! The number of dogs to keep track of. real, intent(inout) :: food !! The amount of pet food (in kilograms) which you have on hand. integer, intent(out) :: angry !! The number of pets angry because they weren't fed. !... return end subroutine feed_pets ``` * Avoid “side effects” (return values are the only thing modified: files are not created, module/global variables are not changed, etc). Use pure functions? * `implicit none` for all program units * Use `use, only:` as much as possible. * Restrict number of passed variables per line in the function/subroutine definition/call to 4 max. Line up variables vertically for ease of reading and counting. Match the call layout to the definition layout. * Have a local variables section separate from passed variables ```fortran # WRONG some_function(a,b,c,d,e,f,g,h & ,i,j,k,l) real :: a,b,c,d,e,f Ingeter :: localVar Real, intent(in) :: h,i,j,k,l call some_function(a,b,c,d & ,e,f & g,h,i,j,k,l) # CORRECT some_function(a, b, c, d & ,e, f, g, h & ,i, j, k, l ) Use module_great_stuff: only, shiny_object, rad_tool Implicit none real, intent(in) :: a !! acceleration (m/s2) real, intent(in) :: b !! brownian coeff (-) real, intent(out) :: c !! celerity (m/s) … (etc) … real, intent(in) :: l !! lousy variable (kgmsK) !! Local variables integer :: localVar call some_function(a, b, c, d & ,e, f, g, h & ,i, j, k, l ) ``` # Variable Scoping and Definition * Minimize global data. * Global data should be limited to constants as much as possible. * Define and use global type parameters. * Make all derived type components private. # Run-time error messages * Must indicate the function/routine in which they occur. * Should be informative. # Compiler warning messages * Compilers generally issue two types of messages: warnings and errors. Extent of compiler warning messages can typically be tuned with a compiler option. Compiler warnings normally do not stop the compile process, but can still result in run-time problems. Compiler errors do stop the compile process, forcing the developer to fix the problem and recompile. STANDARD: * When available, compiler options should be set to produce the maximum number of warning messages. * Compiler and linker warnings shall be treated as errors and fixed. # Other general guidelines * Code should always be written with cleanliness and clarity in mind. Algorithm implementations should not be unnecessarily complicated without significant performance gains over simpler alternatives. * Structured programming - do NOT use GOTO * Related resources * http://research.metoffice.gov.uk/research/nwp/numerical/fortran90/f90_standards.html * https://github.com/szaghi/zen-of-fortran#standard * http://www.fortran.com/Fortran_Style.pdf ================================================ FILE: .github/CONTRIBUTING.md ================================================ # Contributing to WRF-Hydro® All bug reports, bug fixes, code, and documentation contributions are welcome and encouraged. However, guidelines need to be established and followed to ensure that community contributions can be effectively incorporated. Please read the following guidelines carefully before contributing. # Guidelines **Failure to adhere to the following guidelines may result in your contributions being permanently rejected if they are unable to be merged.** All contributions must be made through the [NCAR/wrf_hydro_nwm_public](https://github.com/NCAR/wrf_hydro_nwm_public) GitHub page. Contributions submitted via email or help desk will not be processed. ## Bug reports, feature requests, and documentation suggestions All bug reports, feature requests, and documentation suggestions should be submitted via [GitHub issues](https://github.com/NCAR/wrf_hydro_nwm_public/issues). Before submitting your issue, please search for a few keywords related to your issue in the open and closed issues to discover if your issue has already been logged and/or resolved. An issue template has been provided to assist with submitting bug reports. For more information on using GitHub issues, please see https://help.github.com/articles/about-issues/. ### Bug reports Please use the supplied issue template when submitting bug reports. This will help ensure that your bug is described in sufficient detail. You can read more on how to construct an appropriate bug report here: https://stackoverflow.com/help/mcve ### Feature requests Please follow similar guidelines when suggesting new features as you would for reporting bugs. Be specific and detail the added value of your suggested feature. ### Documentation suggestions All technical documentation for the WRF-Hydro model will eventually be formatted as markdown, which will greatly simplify updates and changes in the future. In the meantime, please reference the document title, page number and quote the line or section for suggesting changes to the documentation. ## Code contributions All code development contributions will be made via [forks](https://help.github.com/articles/about-forks/) and [pull requests](https://help.github.com/articles/about-pull-requests/). If you are unfamiliar with GitHub, forks, or pull requests, see [collaborating with issues and pull requests](https://help.github.com/categories/collaborating-with-issues-and-pull-requests/) for guidance. ### WRF-Hydro Fortran code style standards Please see our Fortran [code style guidelines](CODESTYLE.md) ### Universal guidelines * All code contributions must be made through GitHub following specific guidelines listed below. * All contributions must be made in an open, and public way via the GitHub repository. There will be no embargo period for code contributions. * All contributions must be able to be merged without conflict. It is the responsibility of the contributor to resolve any merge conflicts **prior** to submitting a pull request. * All contributions must pass relevant automated testing procedures. These tests are executed automatically when you submit your pull request. * Be respectful when giving and receiving feedback on contributions or issues (see our community [code of conduct](../CODE_OF_CONDUCT.md). ### Pull requests #### Contributor responsibility Pull requests will only be accepted if they follow the best practices described below. Not following best practices described below is grounds for rejection of pull requests and may result in excessive manual work for contributors. It is the contributors’ responsibility to know and follow best git practices. #### Commits: practices & messages Learning to use commits wisely and “atomically” is the foundation for success. As users gain familiarity with basics of how git works and the merging practices we are using. The next level of sophistication is interaction with the git log. Reading logs is greatly facilitated by writing good logs, or “commit messages”. The following webpage gives a crash course on how to write good commit messages: https://chris.beams.io/posts/git-commit/ #### Frequency Pull requests should happen with high enough frequency to minimize the scope of the code review. Commits which do not changes answers (pass regression testing) MUST be kept separate from commits which do change answers even when the work is on the same feature or bug. The portion of the code which changes the answer must be isolated as much as possible into its own pull request. ### Types of code contributions #### Bug fixes All bug fixes must address a specific [GitHub issue](https://github.com/NCAR/wrf_hydro_nwm_public/issues). Only issues labeled with ["community dev"](https://github.com/NCAR/wrf_hydro_nwm_public/labels/community%20dev) are open to community contributions. The majority of issues will be open to community contributions, but some cases may require more careful handling. Issues without the "community dev" label are either still being investigated, are of broad scope, or involve changes to code that is actively being developed internally. All code changes to address issues must be submitted using a pull request, and the corresponding issue number must be referenced in the pull request. For more information on referencing issues, see [issues and keywords](https://help.github.com/articles/closing-issues-using-keywords/). #### New features Code contributions for minor model enhancements or new features follow a similar pattern to bug fixes. The proposed feature must be submitted as a GitHub issue and all discussions regarding the new feature should reside in the issue thread. Additionally, work should not begin on the new feature until the issue has been tagged with "community dev". Depending on the scope of the new feature, a WRF-Hydro core contributor may suggest you create a [branch](https://help.github.com/articles/about-branches/) to hold all development for the new feature. #### Research development Larger-scale research development, e.g. model coupling, must be coordinated with a WRF-Hydro team member prior to beginning work. This type of development may impact other community projects and requires more careful governance to help steer the direction of model development and maximize harmony among the various NCAR, NOAA, and WRF-Hydro community research efforts. ### Checklist for new feature contributions #### You should have the following to submit a new feature contribution to the WRF-Hydro code base: 1. A WRF-Hydro team point of contact (POC). Early in your development process, it is always a good idea to reach out to the WRF-Hydro team and find a good POC for your new feature. This person will help keep you informed of new developments as they may relate to your feature, advise you on which branches to keep current with (if other than main), and provide pointers on requirements. 2. New feature code integrated in with the latest WRF-Hydro main branch (or other as advised by your WRF-Hydro POC). This merged code should exist in your own fork, but can be in your own main branch or a separate feature branch. * *TIP #1*: It is always a good strategy to pull the latest WRF-Hydro main code into your branch fairly often throughout your development cycle. Leaving months of code changes to merge at the end of your development cycle can result in lots of merge conflicts, time-consuming manual edits, and higher potential for making errors. * *TIP #2*: New code should follow the [WRF-Hydro code contribution guidelines](https://github.com/NCAR/wrf_hydro_nwm_public/blob/main/.github/CONTRIBUTING.md). 3. Documentation for your new feature. This should include (1) a simple summary in the release notes (added to [NEWS.md](https://github.com/NCAR/wrf_hydro_nwm_public/blob/main/NEWS.md)), and (2) a detailed description of the new feature suitable to be included within the [WRF-Hydro Technical Description](https://ral.ucar.edu/sites/default/files/public/projects/wrf_hydro/technical-description-user-guide/wrf-hydro-v5.1.1-technical-description.pdf), included as a new markdown document in the [Doc](https://github.com/NCAR/wrf_hydro_nwm_public/tree/main/trunk/NDHMS/Doc) folder. 4. An updated [standalone test case](https://ral.ucar.edu/projects/wrf_hydro/testcases) demonstrating how your new feature works, based on one of the existing WRF-Hydro test cases (e.g., Croton). If you cannot adapt an existing test case and need to create something new, please consult with your POC. The test case should include: * Domain and parameter files * Namelists * Example forcings if needed (idealized forcing use is OK) * Test case documentation 5. Testing - you must clearly demonstrate that your new feature: * Does no harm to the existing code (e.g., produces identical solutions EXCEPT when the new feature is activated by a namelist or parameter setting). * Fixes a documented issue (reference existing issue in the [WRF-Hydro GitHub issue tracking](https://github.com/NCAR/wrf_hydro_nwm_public/issues) - this could also be a feature request). * If model performance is improved, for example through more efficient IO, memory utilization, or other software-specific improvements, it must be demonstrable and measurable. * *TIP*: All pull requests go through automated CI testing, but for a new feature it is important to do thorough testing ahead of time so you have a good sense of the model impacts and can explain/justify them. Do not wait until automated CI testing to test your new feature. 6. A pull request from a branch on your fork to the WRF-Hydro main branch (or other as advised by your WRF-Hydro POC). Make sure to also follow the specific [WRF-Hydro pull request guidelines](https://github.com/NCAR/wrf_hydro_nwm_public/blob/main/.github/PULL_REQUEST_TEMPLATE.md). ================================================ FILE: .github/ISSUE_TEMPLATE/bug_report.md ================================================ --- name: Bug report about: Create a report to help us improve title: '' labels: '' assignees: '' --- **Describe the bug** A clear and concise description of what the bug is. **To Reproduce** Steps to reproduce the behavior: 1. Go to '...' 2. Configure '....' 3. Run '....' 4. See error **Expected behavior** A clear and concise description of what you expected to happen. **Screenshots** If applicable, add screenshots to help explain your problem. **Additional context** Add any other context about the problem here. ================================================ FILE: .github/PULL_REQUEST_TEMPLATE.md ================================================ TYPE: choose one of [bug fix, enhancement, new feature, feature removed, no impact, text only] KEYWORDS: approximately 3 to 6 words (more is always better) related to your commit, separated by commas SOURCE: Developer's name and affiliation DESCRIPTION OF CHANGES: One or more paragraphs describing problem, solution, and required changes. ISSUE: The GitHub Issue that this PR addresses. For issue number 123, it would be `Fixes #123` TESTS CONDUCTED: Explicitly state if regression, integration, or unit tests were run before submitting. NOTES: Optional, as appropriate. Delete if not used. ================================================ FILE: .github/workflows/test-pr.yml ================================================ name: build on: push: branches: [ main ] pull_request: branches: [ main ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: inputs: pr: description: "PR to test" required: true jobs: Model_Testing: if: github.repository == 'NCAR/wrf_hydro_nwm_public' strategy: fail-fast: false max-parallel: 4 matrix: configuration: [nwm_ana, nwm_long_range, gridded, reach, reach_lakes] runs-on: ubuntu-latest env: MPI_HOME: /usr/share/miniconda NETCDF: /usr/share/miniconda NETCDF_INCLUDES: /usr/share/miniconda/include NETCDF_LIBRARIES: /usr/share/miniconda/lib steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: '3.11' - name: Checkout candidate (pull request / push) if: ${{ github.event_name == 'pull_request' || github.event_name == 'push' }} uses: actions/checkout@v4 with: path: candidate - name: Checkout candidate (manual) if: ${{ github.event_name == 'workflow_dispatch' }} env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} run: gh repo clone ${{ github.repository }} candidate && cd candidate && gh pr checkout -R ${{ github.repository }} ${{ github.event.inputs.pr }} - name: Checkout reference (pull request) if: ${{ github.event_name == 'pull_request' }} uses: actions/checkout@v4 with: ref: ${{ github.event.pull_request.base.ref }} path: reference - name: Checkout reference (push) if: ${{ github.event_name == 'push' }} uses: actions/checkout@v4 with: ref: ${{ github.event.before }} path: reference - name: Checkout reference (manual) if: ${{ github.event_name == 'workflow_dispatch' }} env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} run: gh repo clone ${{ github.repository }} reference && cd reference && git checkout origin/$(gh pr view ${{ github.event.inputs.pr }} --json baseRefName --jq '.baseRefName') - name: Install dependencies with apt-get run: | sudo apt-get update \ && sudo apt-get install -yq --no-install-recommends \ wget \ curl \ bzip2 \ ca-certificates \ libhdf5-dev \ gfortran \ g++ \ m4 \ make \ libswitch-perl \ git \ bc \ openmpi-bin openmpi-common libopenmpi-dev \ libxml2-dev \ libnetcdf-dev \ libnetcdff-dev - name: Install dependencies with pip run: | python3 -m pip install matplotlib numpy xarray dask netCDF4 pygithub - name: Compile reference run: | cd $GITHUB_WORKSPACE/reference cmake -B build make -C build -j - name: Compile candidate run: | cd $GITHUB_WORKSPACE/candidate cmake -B build make -C build -j - name: Run reference model run: | cd $GITHUB_WORKSPACE/reference/build/Run make run-croton-${{ matrix.configuration }} - name: Run candidate model run: | cd $GITHUB_WORKSPACE/candidate/build/Run make run-croton-${{ matrix.configuration }} - name: generic - Compare HYDRO_RST.* output with xrcmp if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run for file in output_${{ matrix.configuration }}/HYDRO_RST.*; do\ python ${GITHUB_WORKSPACE}/candidate/tests/utils/xrcmp.py \ --candidate $file \ --reference $GITHUB_WORKSPACE/reference/build/Run/$file \ --log_file $file_diff.txt \ --n_cores 1; \ done - name: generic - Compare RESTART.* output with xrcmp if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run for file in output_${{ matrix.configuration }}/RESTART.*; do\ python ${GITHUB_WORKSPACE}/candidate/tests/utils/xrcmp.py \ --candidate $file \ --reference $GITHUB_WORKSPACE/reference/build/Run/$file \ --log_file $file_diff.txt \ --n_cores 1; \ done - name: generic - Compare last *.CHANOBS_DOMAIN1 output with xrcmp if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run file=$(ls -t output_${{ matrix.configuration }}/*.CHANOBS_DOMAIN1 | head -n 1) python ${GITHUB_WORKSPACE}/candidate/tests/utils/xrcmp.py \ --candidate $file \ --reference $GITHUB_WORKSPACE/reference/build/Run/$file \ --log_file $file_diff.txt \ --n_cores 1; \ - name: generic - Compare last *.CHRTOUT_DOMAIN1 output with xrcmp if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run file=$(ls -t output_${{ matrix.configuration }}/*.CHRTOUT_DOMAIN1 | head -n 1) python ${GITHUB_WORKSPACE}/candidate/tests/utils/xrcmp.py \ --candidate $file \ --reference $GITHUB_WORKSPACE/reference/build/Run/$file \ --log_file $file_diff.txt \ --n_cores 1; \ - name: generic - Compare last *.LSMOUT_DOMAIN1 output with xrcmp if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run file=$(ls -t output_${{ matrix.configuration }}/*.LSMOUT_DOMAIN1 | head -n 1) python ${GITHUB_WORKSPACE}/candidate/tests/utils/xrcmp.py \ --candidate $file \ --reference $GITHUB_WORKSPACE/reference/build/Run/$file \ --log_file $file_diff.txt \ --n_cores 1; \ - name: generic - Compare last *.RTOUT_DOMAIN1 output with xrcmp if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run file=$(ls -t output_${{ matrix.configuration }}/*.RTOUT_DOMAIN1 | head -n 1) python ${GITHUB_WORKSPACE}/candidate/tests/utils/xrcmp.py \ --candidate $file \ --reference $GITHUB_WORKSPACE/reference/build/Run/$file \ --log_file $file_diff.txt \ --n_cores 1; \ - name: generic - Compare output with compare_output if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run mkdir output_diff python -c \ "import sys; \ sys.path.append('${GITHUB_WORKSPACE}/candidate/tests/utils'); \ import compare_output; \ from pathlib import Path; \ compare_output.plot_diffs('${GITHUB_WORKSPACE}/candidate/build/Run/output_diff', \ '${GITHUB_WORKSPACE}/candidate/build/Run/output_${{ matrix.configuration }}/', \ '${GITHUB_WORKSPACE}/reference/build/Run/output_${{ matrix.configuration }}/', \ '${{ matrix.configuration }}')" - name: generic - Copy test results from container if: ${{ always() }} run: | mkdir -p $GITHUB_WORKSPACE/test_report cp -r $GITHUB_WORKSPACE/candidate/build/Run/output_diff/diff_plots/* $GITHUB_WORKSPACE/test_report/ - name: generic - Attach diff plots to PR if: ${{ failure() }} shell: bash run: | cd $GITHUB_WORKSPACE/candidate/tests/local/utils bash attach_all_plots.bash $(jq --raw-output .pull_request.number "$GITHUB_EVENT_PATH") ${{ matrix.configuration }} generic - name: generic - Archive test results to GitHub if: ${{ failure() }} uses: actions/upload-artifact@v4 with: name: test-reports path: | ${{ github.workspace }}/test_report/* # n-cores test - name: Run parallel candidate model run: | rm -r $GITHUB_WORKSPACE/test_report/ cd $GITHUB_WORKSPACE/candidate/build/Run make clean make run-croton-${{ matrix.configuration }}-parallel - name: n-cores - Compare HYDRO_RST.* output with xrcmp if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run for file in output_${{ matrix.configuration }}/HYDRO_RST.*; do\ python ${GITHUB_WORKSPACE}/candidate/tests/utils/xrcmp.py \ --candidate $file \ --reference $GITHUB_WORKSPACE/reference/build/Run/$file \ --log_file $file_diff.txt \ --n_cores 1; \ done - name: n-cores - Compare RESTART.* output with xrcmp if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run for file in output_${{ matrix.configuration }}/RESTART.*; do\ python ${GITHUB_WORKSPACE}/candidate/tests/utils/xrcmp.py \ --candidate $file \ --reference $GITHUB_WORKSPACE/reference/build/Run/$file \ --log_file $file_diff.txt \ --n_cores 1; \ done - name: n-cores - Compare last *.CHANOBS_DOMAIN1 output with xrcmp if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run file=$(ls -t output_${{ matrix.configuration }}/*.CHANOBS_DOMAIN1 | head -n 1) python ${GITHUB_WORKSPACE}/candidate/tests/utils/xrcmp.py \ --candidate $file \ --reference $GITHUB_WORKSPACE/reference/build/Run/$file \ --log_file $file_diff.txt \ --n_cores 1; \ - name: n-cores - Compare last *.CHRTOUT_DOMAIN1 output with xrcmp if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run file=$(ls -t output_${{ matrix.configuration }}/*.CHRTOUT_DOMAIN1 | head -n 1) python ${GITHUB_WORKSPACE}/candidate/tests/utils/xrcmp.py \ --candidate $file \ --reference $GITHUB_WORKSPACE/reference/build/Run/$file \ --log_file $file_diff.txt \ --n_cores 1; \ - name: n-cores - Compare last *.LSMOUT_DOMAIN1 output with xrcmp if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run file=$(ls -t output_${{ matrix.configuration }}/*.LSMOUT_DOMAIN1 | head -n 1) python ${GITHUB_WORKSPACE}/candidate/tests/utils/xrcmp.py \ --candidate $file \ --reference $GITHUB_WORKSPACE/reference/build/Run/$file \ --log_file $file_diff.txt \ --n_cores 1; \ - name: n-cores - Compare last *.RTOUT_DOMAIN1 output with xrcmp if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run file=$(ls -t output_${{ matrix.configuration }}/*.RTOUT_DOMAIN1 | head -n 1) python ${GITHUB_WORKSPACE}/candidate/tests/utils/xrcmp.py \ --candidate $file \ --reference $GITHUB_WORKSPACE/reference/build/Run/$file \ --log_file $file_diff.txt \ --n_cores 1; \ - name: n-cores - Compare output with compare_output if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run rm -rf output_diff mkdir output_diff python -c \ "import sys; \ sys.path.append('${GITHUB_WORKSPACE}/candidate/tests/utils'); \ import compare_output; \ from pathlib import Path; \ compare_output.plot_diffs('${GITHUB_WORKSPACE}/candidate/build/Run/output_diff', \ '${GITHUB_WORKSPACE}/candidate/build/Run/output_${{ matrix.configuration }}/', \ '${GITHUB_WORKSPACE}/reference/build/Run/output_${{ matrix.configuration }}/', \ '${{ matrix.configuration }}')" - name: n-cores - Copy test results from container if: ${{ always() }} run: | mkdir -p $GITHUB_WORKSPACE/test_report cp -r $GITHUB_WORKSPACE/candidate/build/Run/output_diff/diff_plots/* $GITHUB_WORKSPACE/test_report/ - name: n-cores - Attach diff plots to PR if: ${{ failure() }} shell: bash run: | cd $GITHUB_WORKSPACE/candidate/tests/local/utils bash attach_all_plots.bash $(jq --raw-output .pull_request.number "$GITHUB_EVENT_PATH") ${{ matrix.configuration }} n-cores - name: n-cores - Archive test results to GitHub if: ${{ failure() }} uses: actions/upload-artifact@v4 with: name: test-reports path: | ${{ github.workspace }}/test_report/* # Testing perfect restart, not cleaning candidate model output - name: Setup and run candidate model perfect restart startup run: | rm -r $GITHUB_WORKSPACE/test_report/ cd $GITHUB_WORKSPACE/candidate/build/Run sed -i 's|RESTART_FILENAME_REQUESTED = "RESTART/RESTART.2011082600_DOMAIN1"|RESTART_FILENAME_REQUESTED = "./RESTART.2011090100_DOMAIN1"|' namelist.hrldas sed -i 's/KDAY = 7/KDAY = 1/' namelist.hrldas rm output_${{ matrix.configuration }}/RESTART.2011090200_DOMAIN1 rm output_${{ matrix.configuration }}/HYDRO_RST.2011-09-02_00:00_DOMAIN1 make run-croton-${{ matrix.configuration }}-parallel - name: restart - Compare HYDRO_RST.* output with xrcmp if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run for file in output_${{ matrix.configuration }}/HYDRO_RST.2011-09-02_00:00_DOMAIN1; do\ python ${GITHUB_WORKSPACE}/candidate/tests/utils/xrcmp.py \ --candidate $file \ --reference $GITHUB_WORKSPACE/reference/build/Run/$file \ --log_file $file_diff.txt \ --n_cores 1; \ done - name: restart - Compare RESTART.* output with xrcmp if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run for file in output_${{ matrix.configuration }}/RESTART.2011090200_DOMAIN1; do\ python ${GITHUB_WORKSPACE}/candidate/tests/utils/xrcmp.py \ --candidate $file \ --reference $GITHUB_WORKSPACE/reference/build/Run/$file \ --log_file $file_diff.txt \ --n_cores 1; \ done - name: restart - Compare last *.CHANOBS_DOMAIN1 output with xrcmp if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run file=$(ls -t output_${{ matrix.configuration }}/*.CHANOBS_DOMAIN1 | head -n 1) python ${GITHUB_WORKSPACE}/candidate/tests/utils/xrcmp.py \ --candidate $file \ --reference $GITHUB_WORKSPACE/reference/build/Run/$file \ --log_file $file_diff.txt \ --n_cores 1; \ - name: restart - Compare last *.CHRTOUT_DOMAIN1 output with xrcmp if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run file=$(ls -t output_${{ matrix.configuration }}/*.CHRTOUT_DOMAIN1 | head -n 1) python ${GITHUB_WORKSPACE}/candidate/tests/utils/xrcmp.py \ --candidate $file \ --reference $GITHUB_WORKSPACE/reference/build/Run/$file \ --log_file $file_diff.txt \ --n_cores 1; \ - name: restart - Compare last *.LSMOUT_DOMAIN1 output with xrcmp if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run file=$(ls -t output_${{ matrix.configuration }}/*.LSMOUT_DOMAIN1 | head -n 1) python ${GITHUB_WORKSPACE}/candidate/tests/utils/xrcmp.py \ --candidate $file \ --reference $GITHUB_WORKSPACE/reference/build/Run/$file \ --log_file $file_diff.txt \ --n_cores 1; \ - name: restart - Compare last *.RTOUT_DOMAIN1 output with xrcmp if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run file=$(ls -t output_${{ matrix.configuration }}/*.RTOUT_DOMAIN1 | head -n 1) python ${GITHUB_WORKSPACE}/candidate/tests/utils/xrcmp.py \ --candidate $file \ --reference $GITHUB_WORKSPACE/reference/build/Run/$file \ --log_file $file_diff.txt \ --n_cores 1; \ - name: restart - Compare output with compare_output if: ${{ always() }} run: | cd $GITHUB_WORKSPACE/candidate/build/Run rm -rf output_diff mkdir output_diff python -c \ "import sys; \ sys.path.append('${GITHUB_WORKSPACE}/candidate/tests/utils'); \ import compare_output; \ from pathlib import Path; \ compare_output.plot_diffs('${GITHUB_WORKSPACE}/candidate/build/Run/output_diff', \ '${GITHUB_WORKSPACE}/candidate/build/Run/output_${{ matrix.configuration }}/', \ '${GITHUB_WORKSPACE}/reference/build/Run/output_${{ matrix.configuration }}/', \ '${{ matrix.configuration }}')" - name: restart - Copy test results from container if: ${{ always() }} run: | mkdir -p $GITHUB_WORKSPACE/test_report cp -r $GITHUB_WORKSPACE/candidate/build/Run/output_diff/diff_plots/* $GITHUB_WORKSPACE/test_report/ - name: restart - Attach diff plots to PR if: ${{ failure() }} shell: bash run: | cd $GITHUB_WORKSPACE/candidate/tests/local/utils bash attach_all_plots.bash $(jq --raw-output .pull_request.number "$GITHUB_EVENT_PATH") ${{ matrix.configuration }} perfect-restart - name: restart - Archive test results to GitHub if: ${{ failure() }} uses: actions/upload-artifact@v4 with: name: test-reports path: | ${{ github.workspace }}/test_report/* ================================================ FILE: .gitignore ================================================ *.o *.so *.so.* *.mod *.lst *~ Makefile.comm docs/_build/ src/lib/* src/macros src/HRLDAS/user_build_options *exe /.project src/Run src/Run/ src/setEnvar.sh src/Makefile.comm src/Land_models/NoahMP/user_build_options src/Land_models/Noah/user_build_options src/LandModel src/LandModel_cpl src/Land_models/NoahMP/MPP build/ README.md /.idea *__pycache__* *pytest_cache* *.log compile_options.sh .DS_Store .venv .vscode ================================================ FILE: .readthedocs.yaml ================================================ # Read the Docs configuration file for Sphinx projects # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details # Required version: 2 # Set the OS, Python version and other tools you might need build: os: ubuntu-22.04 tools: python: "3.11" # You can also specify other tool versions: # nodejs: "20" # rust: "1.70" # golang: "1.20" # Build documentation in the "docs/" directory with Sphinx sphinx: configuration: docs/userguide/conf.py # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs # builder: "dirhtml" # Fail on all warnings to avoid broken references # fail_on_warning: true # Optionally build your docs in additional formats such as PDF and ePub formats: - pdf # - epub # Optional but recommended, declare the Python requirements required # to build your documentation # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html python: install: - requirements: docs/requirements.txt ================================================ FILE: CITATION.cff ================================================ authors: - family-names: Gochis given-names: David orcid: 0000-0001-8668-4850 # origin: technical doc - family-names: Barlage given-names: Michael # orcid: # origin: technical doc - family-names: Cabell given-names: Ryan orcid: 0000-0002-3623-5130 # origin: technical doc - family-names: Casali given-names: Matthew # orcid: 0000-0001-6939-0332 # origin: technical doc # - family-names: # given-names: champham # orcid: # origin: github - family-names: Dugger given-names: Aubrey orcid: 0000-0001-8250-4218 # origin: technical doc - family-names: Eidhammer given-names: Trude orcid: 0000-0003-2281-9351 # origin: github - family-names: Enzminger given-names: Tom orcid: 0000-0001-5072-3854 # origin: technical doc - family-names: FitzGerald given-names: Katelyn orcid: 0000-0003-4184-1917 # origin: technical doc - family-names: Felfelani given-names: Farshid orcid: 0000-0003-1360-5095 # origin: technical doc - family-names: Gaydos given-names: Andy # origin: technical doc - family-names: Mazrooei given-names: Amir orcid: 0000-0001-9171-9595 # origin: technical doc - family-names: McAllister given-names: Molly # orcid: # origin: technical doc - family-names: McCreight given-names: James orcid: 0000-0001-6018-425X # origin: technical doc - family-names: McCluskey given-names: Alyssa # orcid: # origin: technical doc - family-names: Omani given-names: Nina # orcid: # origin: technical doc - family-names: RafieeiNasab given-names: Arezoo # github-names: arezoorn orcid: 0000-0001-8557-107X # origin: technical doc - family-names: Rasmussen given-names: Soren #github-names: scrasmussen orcid: 0000-0003-3899-1463 # origin: github - family-names: Read given-names: Laura orcid: 0000-0003-3476-1249 # origin: technical doc - family-names: Sampson given-names: Kevin orcid: 0000-0002-5537-7775 # origin: technical doc - family-names: Srivastava given-names: Ishita orcid: 0009-0002-4060-6659 # origin: technical doc - family-names: Yates given-names: David orcid: 0000-0002-0688-3460 # origin: technical doc - family-names: Zhang given-names: Yongxin orcid: 0000-0001-6321-1276 # origin: technical doc - family-names: Yu given-names: Wei # github-names: # orcid: # origin: - family-names: Karsten given-names: Logan # github-names: logankarsten # orcid: # origin: github - family-names: Dunlap given-names: Rocky # orcid: # origin: github - family-names: Fanfarillo given-names: Alessandro orcid: 0000-0003-3487-7452 # origin: github - family-names: Fersch given-names: Benjamin # orcid: # origin: github - family-names: Heldmyer given-names: Aaron # github: aheldmyer orcid: 0000-0001-8608-4927 # origin: github - family-names: Johnson given-names: Donald # github-names: donaldwj # orcid: # origin: github - family-names: Lahmers given-names: Tim # orcid: # origin: github - family-names: Mattern given-names: David # orcid: # origin: github # - family-names: # given-names: Nels # orcid: # origin: github - family-names: Rosen given-names: Dan # orcid: # origin: github - family-names: Valayamkunnath given-names: Prasanth orcid: 0000-0003-2270-0780 # origin: github cff-version: 1.2.0 date-released: "2025-03-14" title: "WRF-Hydro" repository-code: "https://github.com/NCAR/wrf_hydro_nwm_public" version: 5.4.0 url: "https://ral.ucar.edu/projects/wrf_hydro" keywords: - "hydrologic model" - "hydrology" - "hydrometeorology" license-url: "https://github.com/NCAR/wrf_hydro_nwm_public/blob/main/LICENSE.txt" identifiers: - description: "This is the archived snapshot of all versions of WRF-Hydro" type: doi value: 10.5281/zenodo.3625237 - description: "This is the archived snapshot of version v5.4.0 of WRF-Hydro" type: doi value: 10.5281/zenodo.15040873 - description: "This is the archived snapshot of version v5.3.0 of WRF-Hydro" type: doi value: 10.5281/zenodo.5773161 - description: "This is the archived snapshot of version v5.2.0 of WRF-Hydro" type: doi value: 10.5281/zenodo.4479912 - description: "This is the archived snapshot of version v5.1.2 of WRF-Hydro" type: doi value: 10.5281/zenodo.3678643 - description: "This is the archived snapshot of version v5.1.1 of WRF-Hydro" type: doi value: 10.5281/zenodo.3625238 message: "Please cite this software using the metadata from this file." ================================================ FILE: CMakeLists.txt ================================================ cmake_minimum_required (VERSION 3.12) cmake_policy(SET CMP0074 NEW) # use xxxx_ROOT env vars if (NOT CMAKE_BUILD_TYPE) set(CMAKE_BUILD_TYPE "Release") endif() # set project name and version numbers project (WRF_Hydro LANGUAGES Fortran C) set (WRF_Hydro_VERSION_MAJOR 5) set (WRF_Hydro_VERSION_MINOR 4) set (WRF_Hydro_VERSION_PATCH 0) set (National_Water_Model_VERSION_MAJOR 3) set (National_Water_Model_VERSION_MINOR 1) set (National_Water_Model_VERSION_PATCH beta) # set cmake to work with MPI Fortran find_package(MPI REQUIRED) add_compile_options(${MPI_Fortran_COMPILE_FLAGS}) include_directories(${MPI_Fortran_INCLUDE_PATH}) link_directories(${MPI_Fortran_LIBRARIES}) set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE) set(CMAKE_SKIP_BUILD_RPATH FALSE) set(CMAKE_BUILD_WITH_INSTALL_RPATH TRUE) # enable ctests enable_testing() #message("-- MPI Include directories: " ${MPI_INCLUDE_PATH} ) #message("-- MPI C COMPILER : " ${MPI_C_COMPILER} ) #message("-- MPI CXX COMPILER : " ${MPI_CXX_COMPILER} ) #message("-- MPI Fortran COMPILER : " ${MPI_Fortran_COMPILER} ) #message("-- MPI COMPILE FLAGS : " ${MPI_COMPILE_FLAGS} ) #message("-- MPI LINK FLAGS : " ${MPI_LINK_FLAGS} ) #message("-- MPI Fortran LINK FLAGS : " ${MPI_Fortran_LINK_FLAGS} ) #message("-- MPI Fortran LINK LIBRARIES : " ${MPI_Fortran_LIBRARIES} ) #message("-- MPI LIBRARY : " ${MPI_LIBRARY} ) #message("-- MPI EXTRA LIBRARY : " ${MPI_EXTRA_LIBRARY} ) #message("-- MPI LIBRARIES : " ${MPI_LIBRARIES} ) # netcdf does not have a built in package locator so add custom module directory # that contains FindNetCDF.cmake set(CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/src/cmake-modules) # try to find the installed NETCDF library if (NOT TARGET netCDF::netcdff AND TARGET NetCDF::NetCDF_Fortran) add_library(netCDF::netcdff ALIAS NetCDF::NetCDF_Fortran) endif() if (NOT TARGET netCDF::netcdff) set(NETCDF_F90 "YES") set(NETCDF_F77 "YES") find_package(NetCDF REQUIRED) message("-- NetCDF Include Dir(s): ${NETCDF_INCLUDES_F77} ${NETCDF_INCLUDES_F90}") endif() # set user controled enviorment variables set(HYDRO_LSM $ENV{HYDRO_LSM} CACHE STRING "Name of the Land Surface Model to Use") # set enviorment variables if they have not been set if ("${HYDRO_LSM}" STREQUAL "") set(HYDRO_LSM "NoahMP") message("-- Setting LSM to: NoahMP") endif() # get the variables defined by setEnvar.sh set(WRF_HYDRO $ENV{WRF_HYDRO} CACHE STRING "WRF environment variable. Always set to 1 for WRF-Hydro") set(HYDRO_D $ENV{HYDRO_D} CACHE STRING "Print additional debug information in WRF-Hydro") set(WRF_HYDRO_RAPID $ENV{WRF_HYDRO_RAPID} CACHE STRING "WRF-Hydro coupling to RAPID routing model 0=off 1=on") set(SPATIAL_SOIL $ENV{SPATIAL_SOIL} CACHE STRING "Spatially distributed soil parameters for NoahMP 0=off 1=on") set(WRFIO_NCD_LARGE_FILE_SUPPORT $ENV{WRFIO_NCD_LARGE_FILE_SUPPORT} CACHE STRING "Large netCDF file support 0=off, 1=on") set(NCEP_WCOSS $ENV{NCEP_WCOSS} CACHE STRING "WCOSS file units 0=off 1=on") set(NWM_META $ENV{NWM_META} CACHE STRING "NWM output metadata 0=off 1=on") set(WRF_HYDRO_NUDGING $ENV{WRF_HYDRO_NUDGING} CACHE STRING "Streamflow nudging 0=off 1=on") set(OUTPUT_CHAN_CONN $ENV{OUTPUT_CHAN_CONN} CACHE STRING "Output channel connections") set(PRECIP_DOUBLE $ENV{PRECIP_DOUBLE} CACHE STRING "Precipitation as double") set(WRF_HYDRO_NUOPC $ENV{WRF_HYDRO_NUOPC} CACHE STRING "NUOPC library 0=off 1=on") #set default values for env variables if (WRF_HYDRO STREQUAL "") set(WRF_HYDRO "1" CACHE STRING "WRF environment variable. Always set to 1 for WRF-Hydro" FORCE) endif() if (HYDRO_D STREQUAL "") if (CMAKE_BUILD_TYPE STREQUAL "Debug") set(HYDRO_D "1" CACHE STRING "Print additonal debug information in WRF-Hydro" FORCE) else() set(HYDRO_D "0" CACHE STRING "Print additonal debug information in WRF-Hydro" FORCE) endif() endif() if (WRF_HYDRO_RAPID STREQUAL "") set(WRF_HYDRO_RAPID "0" CACHE STRING "WRF-Hydro coupling to RAPID routing model 0=off 1=on" FORCE) endif() if (SPATIAL_SOIL STREQUAL "") set(SPATIAL_SOIL "0" CACHE STRING "Spatially distributed soil parameters for NoahMP 0=off 1=on" FORCE) endif() if (WRFIO_NCD_LARGE_FILE_SUPPORT STREQUAL "") set(WRFIO_NCD_LARGE_FILE_SUPPORT "0" CACHE STRING "Large netCDF file support 0=off, 1=on" FORCE) endif() if (NCEP_WCOSS STREQUAL "") set(NCEP_WCOSS "0" CACHE STRING "WCOSS file units 0=off, 1=on" FORCE) endif() if (NWM_META STREQUAL "") set(NWM_META "0" CACHE STRING "NWM output metadata 0=off, 1=on" FORCE) endif() if (WRF_HYDRO_NUDGING STREQUAL "") set(WRF_HYDRO_NUDGING "0" CACHE STRING "Streamflow nudging 0=off, 1=on" FORCE) endif() if (OUTPUT_CHAN_CONN STREQUAL "") set(OUTPUT_CHAN_CONN "0" CACHE STRING "Output channel connections" FORCE) endif() if (PRECIP_DOUBLE STREQUAL "") set(PRECIP_DOUBLE "0" CACHE STRING "Precipitation as double" FORCE) endif() if (WRF_HYDRO_NUOPC STREQUAL "") set(WRF_HYDRO_NUOPC "0" CACHE STRING "NUOPC library 0=off, 1=on" FORCE) endif() # add preprocessor defines using env variables message("=============================================================") message("-- Start of WRF-Hydro Env VARIABLES" ) #always use -DMPP_LAND add_definitions(-DMPP_LAND) # set -DWRF_HYDRO from env message("WRF_HYDRO = " ${WRF_HYDRO} ) if (WRF_HYDRO STREQUAL "1" ) add_definitions(-DWRF_HYDRO) endif() #set -DHYDRO_D from env message("HYDRO_D = " ${HYDRO_D} ) if (HYDRO_D STREQUAL "1" ) add_definitions(-DHYDRO_D) endif() # set -DWRF_HYDRO_RAPID from env if (WRF_HYDRO_RAPID STREQUAL "1" ) message("WRF_HYDRO_RAPID = " ${WRF_HYDRO_RAPID} ) add_definitions(-DWRF_HYDRO_RAPID) endif() #set -DSPATIAL_SOIL from env message("SPATIAL_SOIL = " ${SPATIAL_SOIL} ) if (SPATIAL_SOIL STREQUAL "1" ) add_definitions(-DSPATIAL_SOIL) endif() #set -DWRFIO_NCD_LARGE_FILE_SUPPORT from env message("WRFIO_NCD_LARGE_FILE_SUPPORT = " ${WRFIO_NCD_LARGE_FILE_SUPPORT} ) if(WRFIO_NCD_LARGE_FILE_SUPPORT STREQUAL "1" ) add_definitions(-DWRFIO_NCD_LARGE_FILE_SUPPORT) endif() #set -DNCEP_WCOSS from env message("NCEP_WCOSS = " ${NCEP_WCOSS} ) if (NCEP_WCOSS STREQUAL "1" ) add_definitions(-DNCEP_WCOSS) endif() #set -DNWM_META from env message("NWM_META = " ${NWM_META} ) if (NWM_META STREQUAL "1" ) add_definitions(-DNWM_META) endif() #set -DWRF_HYDRO_NUDGING from env message("WRF_HYDRO_NUDGING = " ${WRF_HYDRO_NUDGING} ) if (WRF_HYDRO_NUDGING STREQUAL "1" ) add_definitions(-DWRF_HYDRO_NUDGING) endif() #set -DOUTPUT_CHAN_CONN from env if (OUTPUT_CHAN_CONN STREQUAL "1" ) message("OUTPUT_CHAN_CONN = " ${OUTPUT_CHAN_CONN} ) add_definitions(-DOUTPUT_CHAN_CONN) # requires nudging io module set(WRF_HYDRO_NUDGING_IO "1") endif() #set -DPRECIP_DOUBLE from env message("PRECIP_DOUBLE = " ${PRECIP_DOUBLE} ) if (PRECIP_DOUBLE STREQUAL "1" ) add_definitions(-DPRECIP_DOUBLE) endif() #set -DWRF_HYDRO_NUOPC from env message("WRF_HYDRO_NUOPC = " ${WRF_HYDRO_NUOPC} ) if (WRF_HYDRO_NUOPC STREQUAL "1" ) add_definitions(-DWRF_HYDRO_NUOPC) endif() option(BUILD_CROCUS "Build Crocus" ON) option(WRF_HYDRO_CREATE_EXE_SYMLINK "Create symlink wrfhydro.exe -> wrfhydro" ON) message("WRF_HYDRO_CREATE_EXE_SYMLINK = " ${WRF_HYDRO_CREATE_EXE_SYMLINK} ) message("=============================================================") #set compile flags based on compiler id if (CMAKE_Fortran_COMPILER_ID MATCHES "GNU.*") # set compile flags for gfortran message( "-- Using gfortran") set(CMAKE_Fortran_FLAGS "-cpp -w -ffree-form -ffree-line-length-none -fconvert=big-endian -frecord-marker=4") if (CMAKE_Fortran_COMPILER_VERSION VERSION_GREATER_EQUAL 9) set(CMAKE_Fortran_FLAGS "${CMAKE_Fortran_FLAGS} -fallow-argument-mismatch") endif() set(CMAKE_Fortran_FLAGS_RELEASE "-O2") set(CMAKE_Fortran_FLAGS_DEBUG "-O0 -g -fbacktrace") elseif (CMAKE_Fortran_COMPILER_ID MATCHES "Intel.*") # set compile flags for ifort message( "-- Using ifort") set(CMAKE_Fortran_FLAGS "-fpp -w -ftz -align all -fno-alias -fp-model precise -FR -convert big_endian") set(CMAKE_Fortran_FLAGS_RELEASE "-O2 -march=core-avx2") set(CMAKE_Fortran_FLAGS_DEBUG "-O0 -g -traceback") elseif ((CMAKE_Fortran_COMPILER_ID MATCHES "PGI.*") OR (CMAKE_Fortran_COMPILER_ID MATCHES "NVHPC.*")) message("-- Using NVHPC / PGI") set(CMAKE_Fortran_FLAGS "-Mpreprocess -Mfree -byteswapio -Kieee ") set(CMAKE_Fortran_FLAGS_RELEASE "-O2") set(CMAKE_Fortran_FLAGS_DEBUG "-O0 -g -traceback") elseif ((CMAKE_Fortran_COMPILER_ID MATCHES "Cray*")) message("-- Using Cray") set(CMAKE_Fortran_FLAGS "-eZ -ffree -ef -h alias=none -h fp1 -hbyteswapio") set(CMAKE_Fortran_FLAGS_RELEASE "-O3 -G2") set(CMAKE_Fortran_FLAGS_DEBUG "-O0 -G0") # -traceback") else() message("CMAKE_Fortran_COMPILER full path: " ${CMAKE_Fortran_COMPILER}) message("Fortran compiler: " ${Fortran_COMPILER_NAME}) message("No optimized Fortran compiler flags are known, we just try -O2...") set(CMAKE_Fortran_FLAGS "-cpp") set(CMAKE_Fortran_FLAGS_RELEASE "-O2") set(CMAKE_Fortran_FLAGS_DEBUG "-O0 -g") endif() message("-- CMAKE_Fortran_COMPILER full path: " ${CMAKE_Fortran_COMPILER}) #set output directories for libraries binaries and fortran .mod files set(CMAKE_BINARY_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/bin) set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/lib) set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/lib) set(CMAKE_Fortran_MODULE_DIRECTORY ${PROJECT_BINARY_DIR}/mods) #add common include directores need in the build include_directories(AFTER ${PROJECT_BINARY_DIR}/mods) include_directories(AFTER ${MPI_INCLUDE_PATH}) # include_directories(AFTER ${NETCDF_INCLUDES}) # NOTE: We don't need the C include for netCDF include_directories(AFTER ${NETCDF_INCLUDES_F77}) include_directories(AFTER ${NETCDF_INCLUDES_F90}) include_directories(AFTER ${PROJECT_SOURCE_DIR}/src/Data_Rec) add_subdirectory("src") add_subdirectory("tests/ctests") ================================================ FILE: CODE_OF_CONDUCT.md ================================================ # Contributor Code of Conduct ## Our Pledge We, as contributors, creators, stewards, and maintainers of WRF-Hydro® pledge to make participation in our software, system or hardware project and community a safe, productive, welcoming and inclusive experience for everyone. All participants are required to abide by this Code of Conduct. This includes respectful treatment of everyone regardless of age, body size, disability, ethnicity, gender identity or expression, level of experience, nationality, political affiliation, veteran status, pregnancy, genetic information, physical appearance, race, religion, or sexual orientation, as well as any other characteristic protected under applicable US federal or state law. ## Our Standards Examples of behavior that contribute to creating a positive environment include: * All participants are treated with respect and consideration, valuing a diversity of views and opinions * Be considerate, respectful, and collaborative * Communicate openly with respect for others, critiquing ideas rather than individuals and gracefully accepting criticism * Acknowledging the contributions of others * Avoid personal attacks directed toward other participants * Be mindful of your surroundings and of your fellow participants * Alert UCAR staff and suppliers/vendors if you notice a dangerous situation or someone in distress * Respect the rules and policies of the project and venue Examples of unacceptable behavior by participants include: * Harassment, intimidation, or discrimination in any form * Physical, verbal, or written abuse by anyone to anyone, including repeated use of pronouns other than those requested * Unwelcome sexual attention or advances * Personal attacks directed at other guests, members, participants, etc. * Publishing others' private information such as a physical or electronic address, without explicit permission * Alarming, intimidating, threatening, or hostile comments or conduct * Inappropriate use of nudity and/or sexual images * Threatening or stalking anyone, including a participant * Other conduct which could reasonably be considered inappropriate in a professional setting ## Scope This Code of Conduct applies to all spaces managed by the project whether they be physical, online or face-to-face. This includes project code, code repository, associated web pages, documentation, mailing lists, project websites and wiki pages, issue tracker, meetings, telecon, events, project social media accounts, and any other forums created by the project team which the community uses for communication. In addition, violations of this Code of Conduct outside these spaces may affect a person's ability to participate within them. Representation of a project may be further defined and clarified by project maintainers. ## Community Responsibilities Everyone in the community is empowered to respond to people who are showing unacceptable behavior. They can talk to them privately or publicly. Anyone requested to stop unacceptable behavior is expected to comply immediately. If the behavior continues concerns may be brought to the project administrators or to any other party listed in the *Reporting* section below. ## Project Administrator Responsibilities Project administrators are responsible for clarifying the standards of acceptable behavior and are encouraged to model appropriate behavior and provide support when people in the community point out inappropriate behavior. Project administrator(s) are normally the ones that would be tasked to carry out the actions in the *Consequences* section below. Project administrators are also expected to keep this *Code of Conduct* updated with the main one housed at UCAR as listed below in the *Attribution* section. ## Reporting Instances of unacceptable behavior can be brought to the attention of the [project administrator(s)](https://ral.ucar.edu/projects/wrf_hydro/team) who may take any action as outlined in the *Consequences* section below. However, making a report to a project administrator is not considered an 'official report' to UCAR. Instances of unacceptable behavior may also be reported directly to UCAR via [UCAR's Harassment Reporting and Complaint Procedure](https://operations.ucar.edu/procedures/hr/harassment-reporting-and-complaint-procedure) or anonymously through [UCAR's EthicsPoint Hotline](https://www.ucar.edu/who-we-are/ethics). Complaints received by UCAR will be handled pursuant to the procedures outlined in UCAR's Harassment Reporting and Complaint Procedure. Complaints to UCAR will be held as confidential as practicable under the circumstances, and retaliation against a person who initiates a complaint or an inquiry about inappropriate behavior will not be tolerated. Any contributor can use these reporting methods even if they are not directly affiliated with UCAR. For more information, view the [Frequently Asked Questions (FAQ)](https://operations.ucar.edu/procedures/hr/reporting-faqs) page for reporting. ## Consequences Upon receipt of a complaint, the project administrator(s) may take any action deemed necessary and appropriate under the circumstances. Such action can include things such as: removing, editing, or rejecting comments, commits, code, wiki edits, email, issues, and other contributions that are not aligned to this Code of Conduct, or banning temporarily or permanently any contributor for other behaviors that are deemed inappropriate, threatening, offensive, or harmful. Project administrators also have the right to report violations to UCAR HR and/or UCAR's Office of Diversity, Equity, and Inclusion (ODEI) as well as a participant's home institution and/or law enforcement. In the event an incident is reported to UCAR, UCAR will follow its [Harassment Reporting and Complaint Procedure](https://operations.ucar.edu/procedures/hr/harassment-reporting-and-complaint-procedure). ## Process for Changes All UCAR-managed projects are required to adopt this Contributor Code of Conduct. Adoption is assumed even if not expressly stated in the repository. Projects should fill in sections where prompted with project-specific information, including, project name, email addresses, adoption date, etc. There is one section below marked "optional", which may not apply to a given project. Projects that adopt this Code of Conduct need to stay up to date with UCAR's Contributor Code of Conduct, linked in the *Attribution* section below. Projects can make limited substantive changes to the Code of Conduct; however, the changes must be limited in scope and may not contradict the UCAR Contributor Code of Conduct. ## Attribution This Code of Conduct was originally adapted from the Contributor Covenant, version 1.4.1. We then aligned it with the UCAR Participant Code of Conduct, which also borrows from the American Geophysical Union (AGU) Code of Conduct. The UCAR Participant Code of Conduct applies to both UCAR employees, as well as participants in activities run by UCAR. We modified the Scope section with the Django Project description. The original version of this for all software projects that have strong management from UCAR or UCAR staff is available on the UCAR website at https://www.ucar.edu/who-we-are/ethics-integrity/codes-conduct/contributors (the date that it was adopted by this project was 10 July 2019). When responding to complaints, UCAR HR and ODEI will do so based on the latest published version. Therefore, any project-specific changes should follow the Process for Changes section above. ================================================ FILE: LICENSE.txt ================================================ USE OF THIS SOFTWARE IS SUBJECT TO THE FOLLOWING TERMS AND CONDITIONS: 1. License. Subject to these terms and conditions, University Corporation for Atmospheric Research (UCAR) grants you a non-exclusive, royalty-free license to use, create derivative works, publish, distribute, disseminate, transfer, modify, revise and copy the WRF-Hydro® software, in both object and source code (the "Software"). You shall not sell, license or transfer for a fee the Software, or any work that in any manner contains the Software. 2. Disclaimer of Warranty on Software. Use of the Software is at your sole risk. The Software is provided "AS IS" and without warranty of any kind and UCAR EXPRESSLY DISCLAIMS ALL WARRANTIES AND/OR CONDITIONS OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT OF A THIRD PARTY?S INTELLECTUAL PROPERTY, MERCHANTABILITY OR SATISFACTORY QUALITY AND FITNESS FOR A PARTICULAR PURPOSE. THE PARTIES EXPRESSLY DISCLAIM THAT THE UNIFORM COMPUTER INFORMATION TRANSACTIONS ACT (UCITA) APPLIES TO OR GOVERNS THIS AGREEMENT. No oral or written information or advice given by UCAR or a UCAR authorized representative shall create a warranty or in any way increase the scope of this warranty. Should the Software prove defective, you (and neither UCAR nor any UCAR representative) assume the cost of all necessary correction. 3. Limitation of Liability. UNDER NO CIRCUMSTANCES, INCLUDING NEGLIGENCE, SHALL UCAR BE LIABLE FOR ANY DIRECT, INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES INCLUDING LOST REVENUE, PROFIT OR DATA, WHETHER IN AN ACTION IN CONTRACT OR TORT ARISING OUT OF OR RELATING TO THE USE OF OR INABILITY TO USE THE SOFTWARE, EVEN IF UCAR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 4. Compliance with Law. All Software and any technical data delivered under this Agreement are subject to U.S. export control laws and may be subject to export or import regulations in other countries. You agree to comply strictly with all applicable laws and regulations in connection with use and distribution of the Software, including export control laws, and you acknowledge that you have responsibility to obtain any required license to export, re-export, or import as may be required. 5. No Endorsement/No Support. The names UCAR/NCAR, National Center for Atmospheric Research and the University Corporation for Atmospheric Research may not be used in any advertising or publicity to endorse or promote any products or commercial entity unless specific written permission is obtained from UCAR. The Software is provided without any support or maintenance, and without any obligation to provide you with modifications, improvements, enhancements, or updates of the Software. 6. Controlling Law and Severability. This Agreement shall be governed by the laws of the United States and the State of Colorado. If for any reason a court of competent jurisdiction finds any provision, or portion thereof, to be unenforceable, the remainder of this Agreement shall continue in full force and effect. This Agreement shall not be governed by the United Nations Convention on Contracts for the International Sale of Goods, the application of which is hereby expressly excluded. 7. Termination. Your rights under this Agreement will terminate automatically without notice from UCAR if you fail to comply with any term(s) of this Agreement. You may terminate this Agreement at any time by destroying the Software and any related documentation and any complete or partial copies thereof. Upon termination, all rights granted under this Agreement shall terminate. The following provisions shall survive termination: Sections 2, 3, 6 and 9. 8. Complete Agreement. This Agreement constitutes the entire agreement between the parties with respect to the use of the Software and supersedes all prior or contemporaneous understandings regarding such subject matter. No amendment to or modification of this Agreement will be binding unless in a writing and signed by UCAR. 9. Notices and Additional Terms. Copyright in Software is held by UCAR. You must include, with each copy of the Software and associated documentation, a copy of this Agreement and the following notice: "The source of this material is the Research Applications Laboratory at the National Center for Atmospheric Research, a program of the University Corporation for Atmospheric Research (UCAR) pursuant to a Cooperative Agreement with the National Science Foundation; ©2007 University Corporation for Atmospheric Research. All Rights Reserved." The following notice shall be displayed on any scholarly works associated with, related to or derived from the Software: "The WRF-Hydro modeling system was developed at the National Center for Atmospheric Research (NCAR) through grants from the National Aeronautics and Space Administration (NASA) and the National Oceanic and Atmospheric Administration (NOAA). NCAR is sponsored by the United States National Science Foundation." BY USING OR DOWNLOADING THIS SOFTWARE, YOU AGREE TO BE BOUND BY THE TERMS AND CONDITIONS OF THIS AGREEMENT. ================================================ FILE: NEWS.md ================================================ # WRF-Hydro® v5.4.0 Release Notes Please note that starting with WRF-Hydro v5.4, CMake is the preferred build system. The legacy configure/compile scripts are still present, but should be considered deprecated and will not be supported in future releases. WRF-Hydro model documentation has been migrated from individual Word and PDF files to an online documentation system that will be hosted alongside the model code in the GitHub repository. Please see the docs/ directory for more details and view the documentation on the web at: https://wrf-hydro.readthedocs.io/en/latest For specific updates, reference the PRs listed in the following sections: ## Model Improvements - PR#756: Add initial support for gage-assisted diversions in channel routing, which requires a new optional Diversion netCDF parameter file. This also adds a C compiler dependency - PR#725: `lake_option` added to `&hydro_namelist` to override lake physics options (or turn off lakes completely). Reservoir options have been moved to a new, separate `&reservoir_nlist` namelist - PR#743: liquid water fraction (or snow) added as optional forcing input variables Forcing variables names can now be supplied as namelist inputs - PR#782: documentation converted to readthedocs, also PR#786, PR#785, PR#774, PR#789, PR#795, PR#796, PR#792, PR#799, PR#798, PR#791, PR#799, PR#798, PR#797, PR#805, PR#804, PR#809, PR#810 ## Bugfixes: - PR#803, PR#808: `lake_option` bugfixes - PR#813: Finding NetCDF fix for new Derecho environment - PR#811: Adding routing diversion Makefiles - PR#785: Support Fedora MPI environmental variables for NetCDF - PR#752: LSM accumulations not reset if `RSTRT_SWC` equals `no reset` - PR#729: Crocus glacier arrays changed to `optional` from `allocatable` - Bugfixes: CMake nudging parallel build ## General cleanup and misc. - PR#802: increment version numbers - PR#794: input namelists and parametere tables - PR#790: PR template updates - PR#764: adding deprecation warning to configure build, CMake preferred - PR#739: general CMake improvements, tabs to spaces - PR#720: header info from files removed - PR#724: redundant return statements removed - PR#723: MPI case style fixed - PR#733: .F -> .F90 file renaming - PR#717: Added citation file ================================================ FILE: docs/BUILD.rst ================================================ Build =========== Requirements ~~~~~~~~~~~~ +------------+---------+ |Compiler | Version | +============+=========+ | GNU | 11+ | +------------+---------+ | Intel | 2023+ | +------------+---------+ | NVidia | 23+ | +------------+---------+ | Cray | 15+ | +------------+---------+ +--------------------+---------+ | Libraries/Software | Version | +====================+=========+ | MPI | 3.x+ | +--------------------+---------+ | Fortran NetCDF | 4.4+ | +--------------------+---------+ | CMake | 3.12+ | +--------------------+---------+ Note: Supported compiler versions are chosen based on long-term support (LTS) status, ensuring they continue to receive security and bug fixes. Install dependencies for Debain/Ubuntu ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash $ apt install -y git cmake libnetcdff-dev mpi-default-dev Install/activate dependencies for Red Hat/Fedora ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash $ dnf install -y git cmake netcdf-fortran-mpich-devel $ module load mpi CMake Build ~~~~~~~~~~~ .. code-block:: bash $ mkdir build $ cd build $ cmake .. $ make -j 4 The executables, namelists and tables are now in the ``build/Run`` directory. Testcases with domain setups can be found `here `_. To build with additional functionality, enter ``cmake .. -DFOO=1`` where the available options are described in the following table. +------------------------------------+-------------------------------------------------------------------------------+ | CMake WRF-Hydro Specific Options | Functionality | +====================================+===============================================================================+ | ``-DWRF_HYDRO=1`` | Default: turn on WRF-Hydro | +------------------------------------+-------------------------------------------------------------------------------+ | ``-DHYDRO_D=1`` | Enhanced diagnostic output for debugging | +------------------------------------+-------------------------------------------------------------------------------+ | ``-DSPATIAL_SOIL=1`` | Spatially distributed parameters for NoahMP | +------------------------------------+-------------------------------------------------------------------------------+ | ``-DWRF_HYDRO_NUDGING=1`` | Enable the streamflow nudging routines for Muskingum-Cunge Routing | +------------------------------------+-------------------------------------------------------------------------------+ | ``-DNWM_META=1`` | Output NWM Metadata | +------------------------------------+-------------------------------------------------------------------------------+ | ``-DPRECIP_DOUBLE=1`` | Double precipitation from hydro forcing | +------------------------------------+-------------------------------------------------------------------------------+ | ``-DNCEP_WCOSS=1`` | Do not use unless working on the WCOSS machines | +------------------------------------+-------------------------------------------------------------------------------+ +------------------------------------+-------------------------------------------------------------------------------+ | Unsupported Functionality | | +====================================+===============================================================================+ | ``-DWRF_HYDRO_NUOPC=1`` | Coupling with NUOPC, this option is not currently supported | +------------------------------------+-------------------------------------------------------------------------------+ CMake Testcase ~~~~~~~~~~~~~~ To download and setup the Croton testcase in ``build/Run`` use one of the following commands. The first time the ``croton.tar.gz`` file will be downloaded, extracted, and configured. Future commands will reconfigure the ``Run`` directory. +---------------------------------+ | Make Command | +=================================+ | make croton | +---------------------------------+ | make croton-gridded | +---------------------------------+ | make croton-gridded-no-lakes | +---------------------------------+ | make croton-nwm | +---------------------------------+ | make croton-nwm_ana | +---------------------------------+ | make croton-nwm_longe_range | +---------------------------------+ | make croton-reach | +---------------------------------+ | make croton-reach-lakes | +---------------------------------+ ================================================ FILE: docs/Makefile ================================================ SOURCEDIR = userguide/ BUILDDIR = _build/html # List all source files to track dependencies SOURCE_FILES = $(shell find . -name '*.rst' -o -name '*.rest' -o -name '*.py' -o -name '*.css') all: build build: $(BUILDDIR)/index.html $(BUILDDIR)/index.html: $(SOURCE_FILES) @echo "Building readthedocs documentation" sphinx-build -b html $(SOURCEDIR) $(BUILDDIR) @echo "Open $(BUILDDIR)/index.html to preview readthedocs documentation" open: build open $(BUILDDIR)/index.html clean: rm -rf _build ================================================ FILE: docs/requirements.txt ================================================ sphinx_rtd_theme ================================================ FILE: docs/userguide/_static/ug_theme.css ================================================ .wy-nav-content { max-width: 1000px !important; } .center { text-align: center; } .underline { text-decoration: underline; } .filename { font-family: Courier, "Courier New", monospace; white-space: pre-wrap; } .program { font-family: Courier, "Courier New", monospace; white-space: pre-wrap; color: greenyellow; background-color: black; padding-left: 5px; padding-right: 5px; } .wy-table-responsive table td, .wy-table-responsive table th { white-space: normal; } ================================================ FILE: docs/userguide/appendices.rest ================================================ .. vim: syntax=rst .. include:: meta.rest .. role:: raw-html(raw) :format: html APPENDICES ========== This section contains supplementary information. .. _section-a1: A1. Standalone (Uncoupled) WRF-Hydro Test Case User Guide --------------------------------------------------------- Purpose ^^^^^^^ This example test case is meant to orient you to running the WRF-Hydro modelling system using prepared geographical inputs, and prepared forcing data for a specific region (domain). We provide baseline instructions to test that your WRF-Hydro executable was compiled correctly and is able to run on your system. Please see the Readme.txt file provided with the test case for specific file descriptions and a regional description. This test case provides example namelists and prepared geographical input files for three routing configurations. While the step-by-step walkthrough instructions here guide you through running the Gridded configuration we suggest that you explore the other routing configurations and related namelists for reference. For further information on the WRF-Hydro modeling system and possible training opportunities, please visit https://ral.ucar.edu/projects/wrf_hydro. Requirements ^^^^^^^^^^^^ - WRF-Hydro source code: - https://github.com/NCAR/wrf_hydro_nwm_public.git - ``git clone`` into directory where you will be running this case - An official WRF-Hydro example test case: - Download from: https://ral.ucar.edu/projects/wrf_hydro/testcases - or from release assets at: https://github.com/NCAR/wrf_hydro_nwm_public/releases - All system libraries needed by the WRF-Hydro modeling system can be found in the :ref:`build instructions `. Step-by-step walkthrough ^^^^^^^^^^^^^^^^^^^^^^^^ **Directory structure setup**: We will organize all files and folders under a common top-level directory to simplify commands in this walkthrough. All paths mentioned in this walkthrough will be relative to this top-level directory. For example, :file:`/home/user/project_directory/example_case/` will be referred to as :file:`example_case/`. #. Open a terminal window #. Create a top-level directory that will hold all subdirectories and files used for this walkthrough. Hereafter referred to as the ‘project directory’. #. Copy the uncompressed WRF-Hydro source code into the project directory created in step 2. #. Copy the example case directory into the project directory as well. #. An example of your project directory structure using the Croton, NY example test case would look like the following: .. code-block:: console project_directory/ ├──wrf_hydro_nwm_public/ | ├──src/ | ├──example_case/ ├──Gridded_no_lakes/ ├──Gridded/ ├──NWM/ ├──Reach/ ├──ReachLakes/ ├──FORCING/ ├──supplemental/ ├──Readme.txt Compiling the Code ^^^^^^^^^^^^^^^^^^ If you have not built WRF-Hydro before on your current system, please follow the instructions in the :ref:`build instructions ` to ensure you have all the necessary library dependencies available. If you have already built WRF-Hydro, you can skip to step "CMake Build", repeated here: .. code-block:: bash $ cd project_directory/wrf_hydro_nwm_public # project_directory/ from above $ mkdir build $ cd build $ cmake -DHYDRO_D=1 [-DWRF_HYDRO_NUDGING=1] .. # include -DWRF_HYDRO_NUDGING=1 if you want to use the NWM test case $ make -j 4 The executables, namelists and tables will be created in the ``build/Run`` directory. Running a WRF-Hydro Simulation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In this section we will use our compiled WRF-Hydro model and an example test case to run a WRF-Hydro simulation. This walkthrough is using the Croton, NY example test case. After extracting the Croton tarball details on the domain and time period of the simulation are provided in the :file:`example_case/Readme.txt` file. 1. First we need to copy the TBL and executable files in the :file:`wrf_hydro_nwm_public*/src/build/Run` directory to the directory containing the domain and forcing files. For the WRF-Hydro Gridded configuration, these files are located in the directory :file:`example_case/Gridded`. Copy the :file:`*.TBL` files to the example configuration directory: | *(from your project directory)* | :code:`cp wrf_hydro_nwm_public*/build/Run/\*.TBL example_case/Gridded` Copy the :file:`wrf_hydro` file: :code:`cp wrf_hydro_nwm_public*/build/Run/wrf_hydro example_case/Gridded` .. note:: There are other configuration subfolders with the names such as :file:`Gridded`, :file:`nwm`, and :file:`Reach`. These folders contain prepared files for other configurations of WRF-Hydro. They are found under the :file:`src/template/` directory. Information regarding physics options and routing configurations can be found in the main body of the *WRF-Hydro* v\ |version_short| *Technical Description*. Also, note that there is only one :file:`FORCING/` directory. The same forcing data can be used for all configurations. 2. Next, we need to link our forcing data to the :file:`Gridded/` directory. From the :file:`example_case/Gridded directory`, create a symlink: :code:`ln -s ../FORCING .` Your project directory should now have the following directory structure and files: .. code-block:: console project_directory/ ├──wrf_hydro_nwm_public/ | ├──src/ | ├──build/ | ├──example_case/ ├──Gridded/ ├──FORCING/ ├──DOMAIN/ ├──RESTART/ ├──referenceSim/ ├──CHANPARM.TBL ├──GENPARM.TBL ├──HYDRO.TBL ├──MPTABLE.TBL ├──SOILPARM.TBL ├──hydro.namelist ├──namelist.hydrodas ├──wrf_hydro 3. Now we will run the simulation. Note that there are many options and filepaths that need to be set in the two namelist files :file:`hydro.namelist` and :file:`namelist.hrldas`. However, for this walkthrough these files have been prepared for you. Before running the model, ensure you are in the :file:`example_case/Gridded` directory. We will now run the model using :command:`mpirun` with 2 cores. This command may differ depending on your system configuration, but here is an example of what this might look like: .. code-block:: bash mpirun -np 2 ./wrf_hydro 4. If your simulation ran successfully, there should now be a large number of output files. Descriptions of the output files and their contents can be found in :ref:`Appendix A19 `. There are also two important files for determining the success or failure of the run, :file:`diag_hydro.00000` and :file:`diag_hydro.00001`. These :file:`diag_hydro` files contain logs and diagnostics on the simulation run, and one file is produced per core used in the run. Since we ran using 2 cores, we have 2 :file:`diag_hydro` files. You can check that your simulation ran successfully by examining the last line of the diag files, which should read: .. code-block:: console The model finished successfully........ If this line is not present, the simulation did not finish successfully. 5. You can check the validity of your simulation results by comparing the restart files produced during your model run with the restart files included in the :file:`example_case/Gridded/referenceSim` directory. The restart files contain all the model states and thus provide a simple means for testing if two simulations produced the same results. .. note:: Our current example test cases have only been run and tested with the Noah-MP land surface model. For information regarding running WRF-Hydro with Noah please see :ref:`Appendix A3 `. .. _section-a2: A2. Coupled WRF | WRF-Hydro Test Case User Guide ------------------------------------------------ Purpose ^^^^^^^ This test case for the coupled WRF | WRF-Hydro modeling system is meant to orient you to running the modeling system using prepared geographical inputs for WRF-Hydro and sample initial and boundary conditions for WRF. Note that some of the initial and boundary conditions for this test case have been modified in order to produce a hydrologic response over a very limited spatial domain. Results generated from this test case should not be interpreted as a real simulation and users should consult the WRF and WPS documentation for best practices with respect to domain and model configuration. The purpose of this test case is to provide baseline instructions and a computationally tractable test case for users to familiarize themselves with the modeling system and help ensure the modeling system is running properly on their systems. Please see the README.txt file provided with the test case for a more detailed description of the contents. For a detailed technical description of WRF-Hydro and instructions on how to run WRF | WRF-Hydro in coupled mode see the `WRF-Hydro Technical Description documentation `_ and How to Run WRF-Hydro V5 in Coupled Mode user guide available from https://ral.ucar.edu/projects/wrf_hydro. For further information regarding the WRF model and the WRF Preprocessing System (WPS) see the WRF Users’ Guide located here: http://www2.mmm.ucar.edu/wrf/users/docs/user_guide_v4/contents.html Requirements ^^^^^^^^^^^^ - WRF-Hydro source code: https://github.com/NCAR/wrf_hydro_nwm_public.git - Git clone into directory where you will be running this case - Download WRF and WPS source code: - WRF: https://github.com/wrf-model/WRF - WPS: https://github.com/wrf-model/WPS - WPS geographic data http://www2.mmm.ucar.edu/wrf/src/wps_files/geog_high_res_mandatory.tar.gz - An official WRF-Hydro coupled test case: https://ral.ucar.edu/projects/wrf_hydro/testcases - All system libraries needed by the WRF-Hydro modelling system can be found in the How To Build & Run WRF-Hydro V5 in Standalone Mode user guide and the FAQ web page located at https://ral.ucar.edu/projects/wrf_hydro - All system libraries needed by the WRF modeling system and WPS can be found in the WRF User’s Guide located here: http://www2.mmm.ucar.edu/wrf/users/docs/user_guide_v4/contents.html Step-by-step walkthrough ^^^^^^^^^^^^^^^^^^^^^^^^ **Directory structure setup**: We will organize all files and folders under a common top-level directory to simplify commands in this walkthrough. All paths mentioned in this walkthrough will be relative to this top-level directory. For example, /home/user/project_directory/example_case_coupled/ will be referred to as example_case_coupled/. The following steps walk you through how to setup your project directory. 1. Open a terminal window 2. Create a top-level directory that will hold all subdirectories and files used for this walkthrough. Hereafter referred to as the ‘project directory’. 3. Git clone WRF-Hydro, WRF, and WPS into project directory created in step 2. Here are examples of possible commands to use, modify as needed: .. code-block:: console git clone https://github.com/NCAR/wrf_hydro_nwm_public.git git clone --recurse-submodule --branch v4.7.1 https://github.com/wrf-model/WRF.git git clone --branch v4.6.0 https://github.com/wrf-model/WPS.git 4. Download and extract testcase and geographic data. .. code-block:: console # download and extract files wget https://github.com/NCAR/wrf_hydro_nwm_public/releases/download/v5.4.0/front_range_CO_example_testcase_coupled.tar.gz tar zxf front_range_CO_example_testcase_coupled.tar.gz # Note this geog data is currently broken, Derecho users should skip this # step and in namelists.wps set # geog_data_path = '/glade/work/wrfhelp/WPS_GEOG/', wget http://www2.mmm.ucar.edu/wrf/src/wps_files/geog_high_res_mandatory.tar.gz tar zxf geog_high_res_mandatory.tar.gz 5. Move the newly extracted geographic data into the WPS directory. .. code-block:: console # create directory and move geopgraphic data mkdir -p run/WPS mv WPS_GEOG/ run/WPS/geog 6. Your project directory structure will look like the following: .. code-block:: console project_directory/ ├──run/ │ ├──WPS/ │ └──WRF/ ├──wrf_hydro_nwm_public*/ │ └──src/ ├──WRF/ ├──WPS/ │ ├──geogrid/ │ ├──metgrid/ │ ├──ungrib/ │ └──geog/ └──example_case_coupled/ ├──WRF_FORCING/ └──DOMAIN/ Compiling the Code ^^^^^^^^^^^^^^^^^^ This section will walk you through compiling the coupled WRF | WRF-Hydro modeling system and the WRF Preprocessing System (WPS) utilities **Compiling the coupled WRF | WRF-Hydro modeling system** 1. Navigate to the WRF source code directory at WRF .. code-block:: console cd WRF 2. Remove the old WRF-Hydro source code contained within this directory and replace it with the updated version you just downloaded .. code-block:: console rm -r hydro cp -r ../wrf_hydro*/src hydro 3. Load appropriate modules on Derecho, the following is an example for GNU compilers. .. code-block:: console module purge module load ncarenv gcc ncarcompilers cray-mpich craype netcdf cmake 4. Configure and compile WRF .. warning:: **On Derecho, use the legacy configure method. CMake has known issues with the coupled case.** **Use the legacy configure method for building both WRF and WPS** 4a. Configure and compile WRF: CMake .. code-block:: console # CMake option to turn on WRF-Hydro nudging `-DWRF_HYDRO_NUDGING=1` ./configure_new -x -p gfortran/gcc -- -DWRF_CORE=ARW -DWRF_NESTING=BASIC -DENABLE_HYDRO=ON -DWRF_CASE=EM_REAL ./compile_new -j4 4b. Configure and compile WRF: Old Method .. code-block:: console # Load environement variables from WRF directory source hydro/template/setEnvar.sh # Export paths necessary for WRF to find the right libraries on Derecho export Jasper_ROOT=/glade/u/home/wrfhelp/UNGRIB_LIBRARIES/ # Configure WRF # On Derecho, # For GNU (dmpar) and basic nesting # 1. enter `printf '34\n1\n' | ./configure` or option 34 and 1 # For IFX (dmpar) and basic nesting # 1. enter `printf '78\n1\n' | ./configure` or option 78 and 1 # 2. Login node does not have enough memory to compile succesfully with ifx. # User can use interactive node with extra memory, mem=50GB works ./configure ./compile -j 4 em_real &> compile.log # the binaries will be in the run directory **Compiling the WRF Preprocessing System (WPS)** 1. Navigate to the WPS source code directory at WPS 2. Configure and compile the WPS. Note that grib2 data is used in the example and the Jasper environmental variables need to be set. 2a. Configure and compile WPS: CMake Note: CMakeLists.txt line 164 in the top directory of WPS will need to be changed to .. code-block:: console add_compile_definitions( ${WPS_DEFINITIONS_LIST} ${WPS_UNDEFINITIONS_LIST} USE_JPEG2000 USE_PNG ) Now configure with .. code-block:: console ./configure_new -x -p gfortran -- -DBUILD_EXTERNALS=ON ./compile_new -j 4 &> compile.log 2b. Configure and compile WPS: old Method .. code-block:: console # Select option 2 and --build-grib2-libs. Option 2 is Linux x86_64, gfortran # (dmpar) or select th dmpar option for compiler of choice # The user can also enter printf '2\n' | ./configure --build-grib2-libs to pass the arguments export Jasper_ROOT=/glade/u/home/wrfhelp/UNGRIB_LIBRARIES/ ./configure --build-grib2-libs ./compile geogrid -j 4 ./compile ungrib -j 4 ./compile metgrid -j 4 check the compile log for errors. Running the WRF Preprocessing System (WPS) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. figure:: media/wps_program_flow.png :align: center Image from `WPS Userguide `_. In this section we will use the compiled WRF Preprocessing System (WPS) utilities along with a namelist file ( namelist.wps ) and meteorological forcing data from the coupled test case to generate geogrid and metgrid files for the two model domains (note that the inner nest, or domain 2, is where WRF-Hydro will run). **Running the geogrid utility** 1. Create a run directory for WPS within your project directory .. code-block:: console mkdir -p run/WPS cd run/WPS 2. Now copy the required files for the WPS geogrid utility into your ``run/WPS`` directory .. code-block:: console cp ../../WPS/geogrid/GEOGRID.TBL . cp ../../example_case_coupled/namelist.wps . # for new CMake install method cp ../../WPS/install/bin/geogrid.exe . # or if the older method was used to build cp ../../WPS/geogrid.exe . Edit the paths within this namelist as appropriate for your system 3. Edit the path to geographic data in your ``namelist.wps`` file so that ``geog_data_path`` points to the correct path. .. code-block:: console geog_data_path = '/glade/work/wrfhelp/WPS_GEOG/', # or geog, note though this is currently not working geog_data_path = 'geog', 4. Run the geogrid utility .. code-block:: console mpiexec -np 2 ./geogrid.exe &> geogrid.log **Running the ungrib utility** The ungrib utility takes meteorological forcing data to be used for simulation initial and boundary conditions and converts the files to an intermediate file format used by the metgrid utility. Make sure modules are loaded from previous steps. 1. Now copy the additional required files for the WPS ungrib utility into your ``run/WPS`` directory .. code-block:: console cd run/WPS cp ../../WPS/link_grib.csh . # for new cmake build method cp ../../WPS/install/bin/ungrib.exe . # or if the older method was used to build cp ../../WPS/ungrib.exe . 2. Next copy over the necessary variable table for your forcing data .. code-block:: console cp ../../WPS/ungrib/Variable_Tables/Vtable.NAM Vtable 3. Then link your forcing data from the test case to the run directory (this script will also rename the files to those expected for the ungrib utility) .. code-block:: console ./link_grib.csh ../../example_case_coupled/WRF_FORCING/* 4. Next run the ungrib utility .. code-block:: console mpiexec -np 2 ./ungrib.exe &> ungrib.log **Running the metgrid utility** The metgrid utility does some interpolation of meteorological forcing data to the model domain creating metgrid files to be used as input to the WRF real utility. 1. Now copy additional the required files for the WPS metgrid utility into your ``run/WPS`` directory .. code-block:: console cp ../../WPS/metgrid/METGRID.TBL . # for newer CMake build method cp ../../WPS/install/bin/metgrid.exe . # or if the older method was used to build cp ../../WPS/metgrid.exe . 2. Next run the metgrid utility .. code-block:: console mpiexec -np 2 ./metgrid.exe &> metgrid.log Running a coupled WRF | WRF-Hydro simulation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In this section we will use our compiled coupled WRF | WRF-Hydro model to run a simulation. This walkthrough uses the Front Range coupled example test case. Details on the domain and time period of the simulation are provided in the example_case_coupled/README.txt file. **Setting up your run directory** First we will create a run directory and copy over or link the required files. 1. Create a run directory for WRF by copying over the run directory from where it was compiled .. code-block:: console cd project_directory # run directory should exist at this point cp -RL WRF/run run/WRF cd run/WRF 2. Copy over parameter tables for WRF-Hydro .. code-block:: console cp ../../WRF/hydro/template/HYDRO/*TBL . # cp ../../WRF/hydro/template/NoahMP/run/*.TBL . # cp ../../WRF/install/test/em_real/*.TBL . 3. Copy over the namelists for real / wrf (namelist.input) and the hydro components (hydro.namelist) from the example case .. code-block:: console cp ../../example_case_coupled/namelist.input . cp ../../example_case_coupled/hydro.namelist . cp ../../WRF/hydro/template/NoahMP/namelist.hrldas . cp -r ../../example_case_coupled/DOMAIN/ . cp ../../WRF/run/CAMtr_volume_mixing_ratio . cp ../../WRF/phys/noahmp/parameters/MPTABLE.TBL . 4. Link the geogrid and metgrid files we just generated from the WPS utilities .. code-block:: console ln -sf ../WPS/met_em* . ln -sf ../WPS/geo_em* . ln -sf ../../WRF/run/RRTM_DATA . 4. Copy executable files .. code-block:: console # location for the CMake build, older method will have these files in the WRF/run directory cp ../../WRF/install/bin/real real.exe cp ../../WRF/install/bin/wrf wrf.exe **Running the real utility** The WRF real utility creates the wrfinput* and wrfbdy* initial and boundary condition files to be used as input for the coupled simulation. 1. Execute real using the proper syntax for your system (example below) and pipe the output to a log file. .. code-block:: console mpirun -np 2 ./real.exe &> real.log 2. Next review the rsl.out.* and rsl.error.* files for possible errors and check to make sure the wrfinput* and wrfbdy* files have been created. .. code-block:: console tail rsl.error.* -n 1 **Running the coupled model** Now we will run the coupled model (all included in the wrf binary) using the wrfinput* and wrfbdy* files as initial and boundary conditions and the model physics and other options selected in the namelist.input and hydro.namelist files. 1. Execute wrf using the proper syntax for your system (example below) and pipe the output to a log file. .. code-block:: console mpirun -np 2 ./wrf.exe &> wrf.log 2. If your simulation ran successfully, there should now be a large number of output files. Descriptions of the output files can be found in the WRF-Hydro V5 Technical Description at ( https://ral.ucar.edu/projects/wrf_hydro ) and the WRF User’s Guide found here ( http://www2.mmm.ucar.edu/wrf/users/docs/user_guide_v4/contents.html ). You will also want to review the rsl.out.* and rsl.error.* files for possible error messages. .. _section-a3: A3. Exceptions for Running WRF-Hydro with the Noah LSM ------------------------------------------------------ Support for the Noah Land Surface Model (LSM) within WRF-Hydro is currently frozen at Noah version 3.6, development to use the `refactored NoahMP `_ as a submodule is under way. Since the Noah LSM is not under active development by the community, WRF-Hydro is continuing to support Noah in deprecated mode only. Some new model features, such as the improved output routines, have not been setup to be backward compatible with Noah. Noah users should follow the guidelines below for adapting the WRF-Hydro workflow to work with Noah: - **LSM initialization:** The simple wrfinput.nc initialization file created by the create_Wrfinput.R script does not currently include all of the fields required by the Noah LSM. Therefore, Noah users should use the WRF real utility to create a wrfinput_d0x file. Refer to the WRF documentation and user guides for information on how to do this. - **Time-varying vegetation specifications:** While the Noah LSM will be properly initialized with green vegetation fraction from the wrfinput file, there is currently no automated method to update this field over time (e.g., seasonally based on climatology). Therefore, Noah users will need to provide these time-varying fields in the model input forcing files (e.g., LDASIN). - **Spatially varying parameters**: Spatially varying soil and vegetation parameters (e.g., soil_properties.nc) are not supported in Noah. - **Model outputs:** The updated output routines have not been adapted to work with Noah. Therefore, Noah users should always use io_form_outputs = 0 to activate the deprecated output routines. Scale/offset and compression options, CF compliance, augmented spatial metadata, etc. are not available in this deprecated mode. .. _section-a4: A4. Noah `namelist.hrldas` File with Description of Options ----------------------------------------------------------- Below is an annotated namelist.hrldas file for running with the Noah land surface model. Notes and descriptions are indicated with <-- .. code-block:: fortran &NOAHLSM_OFFLINE HRLDAS_CONSTANTS_FILE = "./DOMAIN/wrfinput_d01" !!<-- Path to wrfinput file containing initialization data ! for the LSM. This is required even for a warm start ! where a restart file is provided. INDIR = "./FORCING" !<-- Path to atmospheric forcing data directory. OUTDIR = "./" !<-- Generally leave this as-is (output goes to base run directory); ! redirected output only applies to LSM output files and can cause ! issues when running coupled to WRF-Hydro. START_YEAR = 2013 !<-- Simulation start year START_MONTH = 09 !<-- Simulation start month START_DAY = 01 !<-- Simulation start day START_HOUR = 00 !<-- Simulation start hour START_MIN = 00 !<-- Simulation start min RESTART_FILENAME_REQUESTED = "RESTART.2013090100_DOMAIN1" !<-- Path to LSM restart file if using; this contains a ! "warm" model state from a previous model run. ! Comment out if not a restart simulation. ! Specification of simulation length in days hours KHOUR = 24 !<-- Number of hours for simulation; ! Timesteps in units of seconds FORCING_TIMESTEP = 3600 !<-- Timestep for forcing input data (in seconds) NOAH_TIMESTEP = 3600 !<-- Timestep the LSM to cycle (in seconds) OUTPUT_TIMESTEP = 86400 !<-- Timestep for LSM outputs, LDASOUT (in seconds) ! Land surface model restart file write frequency RESTART_FREQUENCY_HOURS = 6 !<-- Timestep for LSM restart files to be generated (in hours). A value of -99999 ! will simply output restarts on the start of each month, useful for longer ! model runs. Restart files are generally quite large, so be cognizant of ! storage space and runtime impacts when specifying. ! Split output after split_output_count output times. SPLIT_OUTPUT_COUNT = 1 !<-- Number of timesteps to put in a single output file. This option ! must be 1 for NWM output configurations. ! Soil layer specification NSOIL=4 !<-- Number of soil layers ZSOIL(1) = 0.10 !<-- Thickness of top soil layer (m) ZSOIL(2) = 0.30 !<-- Thickness of second soil layer (m) ZSOIL(3) = 0.60 !<-- Thickness of third soil layer (m) ZSOIL(4) = 1.00 !<-- Thickness of bottom soil layer (m) ! Forcing data measurement heights ZLVL = 2.0 !<-- Height of input temperature and humidity measurement/estimate ZLVL_WIND = 10.0 !<-- Height of input wind speed measurement/estimate IZ0TLND = 0 !<-- Switch to control land thermal roughness length. Option 0 is the default, ! non-vegetation dependent value and option 1 introduces a vegetation dependence. SFCDIF_OPTION = 0 !<-- Option to use the newer, option 1, or older, option 0, SFCDIF routine. The default value is 0. UPDATE_SNOW_FROM_FORCING = .FALSE. !<-- Option to activate or deactivate updating the snow­cover ! fields from available analyses. The default option is true. ! -------- Section: Select atmospheric forcing input file format, FORC_TYP -------- ! ! Specification of forcing data: 1=HRLDAS-hr format, 2=HRLDAS-min format, ! 3=WRF,4=Idealized, 5=Ideal w/ Spec.Precip., ! 6=HRLDAS-hrly fomat w/ Spec. Precip, 7=WRF w/ Spec. Precip FORC_TYP = 3 / .. _section-a5: A5. Noah-MP `namelist.hrldas` File with Description of Options -------------------------------------------------------------- Below is an annotated namelist.hrldas file for running with the Noah-MP land surface model. Do note that the file says ``&NOAHLSM_OFFLINE`` however it is for use with the Noah-MP LSM. This namelist statement happens to be hardcoded and thus not easily changed. Notes and descriptions are indicated with <-- after sections being described. See the official HRLDAS namelist description here: https://github.com/NCAR/hrldas-release/blob/release/HRLDAS/run/README.namelist .. code-block:: fortran &NOAHLSM_OFFLINE HRLDAS_SETUP_FILE = "./DOMAIN/wrfinput_d01" !<-- Path to wrfinput file containing initialization ! data for the LSM. This is required even for a warm ! start where a restart file is provided. INDIR = "./FORCING" !<-- Path to atmospheric forcing data directory. SPATIAL_FILENAME = "./DOMAIN/soil_properties.nc" !<-- Path to optional 2d/3d soil and vegetation ! parameter file. If you are using this option, ! you must also use a binary compiled with ! SPATIAL_SOIL=1. If using the traditional ! parameter lookup tables, compile with ! SPATIAL_SOIL=0 and comment out this option. OUTDIR = "./" !<-- Generally leave this as-is (output goes to base run directory); redirected ! output only applies to LSM output files ! and can cause issues when running coupled to WRF-Hydro. START_YEAR = 2013 !<-- Simulation start year START_MONTH = 09 !<-- Simulation start month START_DAY = 12 !<-- Simulation start day START_HOUR = 04 !<-- Simulation start hour START_MIN = 00 !<-- Simulation start min RESTART_FILENAME_REQUESTED = "RESTART.2013091204_DOMAIN1" !<-- Path to LSM restart file if using; ! this contains a "warm" model state ! from a previous model run. Comment out ! if not a restart simulation. ! Specification of simulation length in days OR hours KHOUR = 24 !<-- Number of hours for simulation ! -------- Following Section: Noah-MP physics options -------- ! ! Physics options (see the documentation for details) DYNAMIC_VEG_OPTION = 4 !<-- options for dynamic vegetation: ! 1 -> off (use table LAI; use FVEG = SHDFAC from input) ! 2 -> on (together with OPT_CRS = 1) ! 3 -> off (use table LAI; calculate FVEG) ! **4 -> off (use table LAI; use maximum vegetation fraction) ! **5 -> on (use maximum vegetation fraction) ! 6 -> on (use FVEG = SHDFAC from input) ! 7 -> off (use input LAI; use FVEG = SHDFAC from input) ! 8 -> off (use input LAI; calculate FVEG) ! 9 -> off (use input LAI; use maximum vegetation fraction) CANOPY_STOMATAL_RESISTANCE_OPTION = 1 !<-- options for canopy stomatal resistance ! **1 -> Ball-Berry ! 2 -> Jarvis BTR_OPTION = 1 !<-- options for soil moisture factor for stomatal resistance ! **1 -> Noah (soil moisture) ! 2 -> CLM (matric potential) ! 3 -> SSiB (matric potential) RUNOFF_OPTION = 3 !<-- options for runoff and groundwater ! 1 -> TOPMODEL with groundwater (Niu et al. 2007 JGR) ! 2 -> TOPMODEL with an equilibrium water table (Niu et al. 2005 JGR) ! **3 -> original surface and subsurface runoff (free drainage) ! 4 -> BATS surface and subsurface runoff (free drainage) ! 5 -> Miguez-Macho&Fan groundwater scheme (Miguez-Macho et al. 2007 JGR; ! Fan et al. 2007 JGR) [NOT YET SUPPORTED WITH WRF-HYDRO] ! 7 -> Xinanjiang runoff scheme SURFACE_DRAG_OPTION = 1 !<-- options for surface layer drag coeff (CH & CM) ! **1 -> M-O ! 2 -> original Noah (Chen97) FROZEN_SOIL_OPTION = 1 !<-- options for frozen soil permeability ! **1 -> linear effects, more permeable (Niu and Yang, 2006, JHM) ! 2 -> nonlinear effects, less permeable (old) SUPERCOOLED_WATER_OPTION = 1 !<-- options for supercooled liquid water (or ice fraction) ! **1 -> no iteration (Niu and Yang, 2006 JHM) ! 2 -> Koren's iteration RADIATIVE_TRANSFER_OPTION = 3 !<-- options for radiation transfer ! 1 -> modified two-stream (gap = F(solar angle, 3D structure ...)<1-FVEG) ! 2 -> two-stream applied to grid-cell (gap = 0) ! **3 -> two-stream applied to vegetated fraction (gap=1-FVEG) SNOW_ALBEDO_OPTION = 1 !<-- options for ground snow surface albedo ! **1 -> BATS ! 2 -> CLASS PCP_PARTITION_OPTION = 1 !<-- options for partitioning precipitation into rainfall & snowfall ! **1 -> Jordan (1991) ! 2 -> BATS: when SFCTMP SFCTMP < TFRZ ! 4 -> Use WRF microphysics output TBOT_OPTION = 2 !<-- options for lower boundary condition of soil temperature ! 1 -> zero heat flux from bottom (ZBOT and TBOT not used) ! **2 -> TBOT at ZBOT (8m) read from a file (original Noah) TEMP_TIME_SCHEME_OPTION = 3 !<-- options for snow/soil temperature time scheme (only layer 1) ! 1 -> semi-implicit; flux top boundary condition ! 2 -> full implicit (original Noah); temperature top boundary condition ! **3 -> same as 1, but FSNO for TS calculation (generally improves snow; v3.7) GLACIER_OPTION = 2 !<-- options for glacier treatment ! 1 -> include phase change of ice ! **2 -> ice treatment more like original Noah (slab) SURFACE_RESISTANCE_OPTION = 4 !<-- options for surface resistent to evaporation/sublimation ! 1 -> Sakaguchi and Zeng, 2009 ! 2 -> Sellers (1992) ! 3 -> adjusted Sellers to decrease RSURF for wet soil ! **4 -> option 1 for non-snow; rsurf = rsurf_snow for snow (set in MPTABLE); AD v3.8 IMPERV_OPTION = 9 !<-- options for impervious adjustment for surface runoff partitioning ! 0 -> none ! 1 -> adjust based on impervious fraction ! 2 -> adjust based on effective impervious fraction from Alley & Veenhuis ! **9 -> original formulation (varies based on runoff option) ! Timesteps in units of seconds FORCING_TIMESTEP = 3600 !<-- Timestep for forcing input data (in seconds) NOAH_TIMESTEP = 3600 !<-- Timestep the LSM to cycle (in seconds) OUTPUT_TIMESTEP = 86400 !<-- Timestep for LSM outputs, LDASOUT (in seconds) ! Land surface model restart file write frequency RESTART_FREQUENCY_HOURS = 2 !<-- Timestep for LSM restart files to be generated (in hours). ! A value of -99999 will simply output restarts on the start of ! each month, useful for longer model runs. Restart files are ! generally quite large, so be cognizant of storage space and ! runtime impacts when specifying. ! Split output after split_output_count output times. SPLIT_OUTPUT_COUNT = 1 !<-- Number of timesteps to put in a single output file. This option must be 1 for NWM output configurations. ! Soil layer specification NSOIL=4 !<-- Number of soil layers soil_thick_input(1) = 0.10 !<-- Thickness of top soil layer (m) soil_thick_input(2) = 0.30 !<-- Thickness of second soil layer (m) soil_thick_input(3) = 0.60 !<-- Thickness of third soil layer (m) soil_thick_input(4) = 1.00 !<-- Thickness of bottom soil layer (m) ! Forcing data measurement height for winds, temp, humidity ZLVL = 10.0 !<-- Height of input wind speed ! -------- Following Section: Restart IO file formats -------- ! ! Options to specify whether restart files (both read in and output) ! should be in binary or netCDF format. Generally recommend using ! netCDF format (option 0) for both. ! Restart file format options rst_bi_in = 0 !<-- 0: use netcdf input restart file 1: use parallel io for reading multiple ! restart files (1 per core) rst_bi_out = 0 !<-- 0: use netcdf output restart file 1: use parallel io for outputting multiple ! restart files (1 per core) ! -------- Optional forcing variable names -------- ! ! These can be left out of the namelist and will default to the values below, ! so only need to be specified if using alternative names. ! Forcing input variable names forcing_name_T = "T2D" !<-- variable name for air temperature forcing_name_Q = "Q2D" !<-- variable name for humidity forcing_name_U = "U2D" !<-- variable name for u-component of wind speed forcing_name_V = "V2D" !<-- variable name for v-component of wind speed forcing_name_P = "PSFC" !<-- variable name for surface pressure forcing_name_LW = "LWDOWN" !<-- variable name for downward longwave radiation forcing_name_SW = "SWDOWN" !<-- variable name for downward shortwave radiation forcing_name_PR = "RAINRATE" !<-- variable name for precipitation rate ! Optional way to supply liquid or snow fraction of precipitation, e.g., if provided ! by an atmospheric model. Otherwise the land model will estimate this. ! NOTE: You can provide either frozen fraction or liquid fraction (no need to provide both). forcing_name_SN = "" !<-- variable name for frozen fraction of precipitation forcing_name_LF = "LQFRAC" !<-- variable name for liquid fraction of precipitation / &WRF_HYDRO_OFFLINE ! Specification of forcing data: 1=HRLDAS-hr format, 2=HRLDAS-min format, ! 3=WRF, 4=Idealized, 5=Ideal w/ Spec.Precip., ! 6=HRLDAS-hrly fomat w/ Spec. Precip, 7=WRF w/ Spec.Precip FORC_TYP = 1 / ! -------- Optional settings for the Crocus snow model -------- ! ! These options can be excluded if not using the Crocus snow/glacier model. &CROCUS_nlist crocus_opt = 0 !<-- 0 means the Crocus model is off (default) ! 1 means the Crocus model is on act_lev = 40 !<-- Specify the number of layers the Crocus snow model will resolve. ! More layers will require more memory and may slow performance. ! 20-40 normal range, 1-50 acceptable / .. _section-a6: A6. WRF-Hydro `hydro.namelist` File with Description of Options --------------------------------------------------------------- Below is an annotated hydro.namelist file. Annotations follow what is being described, indicated with <-- and blue text. Note that annotations describing options are meant to accompany the commented description in the namelist which precedes the option. .. _hydro-namelist: .. code-block:: fortran &HYDRO_nlist !!!! --------------- SYSTEM COUPLING -------------- !!!! ! Specify what is being coupled: 1=HRLDAS (offline Noah-LSM), ! 2=WRF, 3=NASA/LIS, 4=CLM sys_cpl = 1 !<-- For offline runs, including Noah and Noah-MP, this will be option 1. !!!! ----------- MODEL INPUT DATA FILES ----------- !!!! ! Specify land surface model gridded input data file (e.g.: "geo_em.d01.nc") GEO_STATIC_FLNM = "./DOMAIN/geo_em.d01.nc" !<-- Path to the “GEOGRID” file which contains base ! information on the LSM grid (this file is generally ! created via WPS in the model preprocessing steps). ! Specify the high-resolution routing terrain input data file (e.g.: "Fulldom_hires.nc") GEO_FINEGRID_FLNM = "./DOMAIN/Fulldom_hires.nc" !<-- Path to the “routing stack” which contains ! base information on the high-resolution routing ! grid. This file is generally created via the ! GIS pre-processing tools. ! Specify the spatial hydro parameters file (e.g.: "hydro2dtbl.nc") ! If you specify a filename and the file does not exist, it will ! be created for you. HYDROTBL_F = "./DOMAIN/hydro2dtbl.nc" !<-- Path to the 2d hydro parameters file. If this file ! does not exist, it will be created for you based on ! HYDRO.TBL and the soil and land class grids found in the ! GEOGRID netCDF file ! Specify spatial metadata file for land surface grid. (e.g.: "GEOGRID_LDASOUT_Spatial_Metadata.nc") LAND_SPATIAL_META_FLNM = "./DOMAIN/GEOGRID_LDASOUT_Spatial_Metadata.nc" !<-- Path to the geospatial ! metadata file for your domain. This file is required ! if using any of the io_form_outputs options (i.e., ! io_form_outputs > 0). This file is generally created ! via the GIS pre-processing tools. ! Specify the name of the restart file if starting from restart...comment out with '!' if not... RESTART_FILE = 'HYDRO_RST.2013-09-12_04:00_DOMAIN3' !<-- Path to hydro restart file; this contains ! a "warm" model state from a previous model run. !!!! ------------- MODEL SETUP OPTIONS ------------ !!!! ! Specify the domain or nest number identifier...(integer) IGRID = 1 !<-- Domain ID number. This comes from the WRF coupling framework and is intended to ! specify which nested domain you are running. For standalone runs, this is not relevant ! HOWEVER this ID must match the number specified after DOMAIN in your forcing file names ! (e.g., the "1" in "2013091200.LDASIN_DOMAIN1"). ! Specify the restart file write frequency in minutes ! A value of -99999 will output restarts on the first day of the month only. rst_dt = 120 !<-- Specify how often hydro restart files should be generated, in minutes. This should ! generally track your LSM restart file frequency (as specified in namelist.hrldas). ! A value of -99999 will simply output restarts on the start of each month, useful for ! longer model runs. Hydro restart files are generally quite large, so be cognizant of ! storage space and runtime impacts. ! Reset the LSM soil states from the high-res routing restart file (1=overwrite, 0=no overwrite) ! NOTE: Only turn this option on if overland or subsurface routing is active! rst_typ = 1 !<-- Specify whether or not to use the soil conditions (soil moisture and ponded water) ! from the high-resolution hydro restart file, if "warm" starting the model with a ! provided HYDRO_RST file. If this option is 0, the LSM restart states will be used ! instead. IMPORTANT: If you are NOT running with terrain routing turned on, do not set ! this option to 1 as it may bring in invalid values. ! Restart file format control !<-- Options to whether restart files (input and output separately) ! should be in binary or netCDF format. Generally recommend to use ! netCDF format (option 0) for both. rst_bi_in = 0 !0: use netCDF input restart file (default) 1: use parallel io for reading multiple ! restart files, 1 per core rst_bi_out = 0 !0: use netCDF output restart file (default) 1: use parallel io for outputting multiple ! restart files, 1 per core ! Restart switch to set restart accumulation variables to 0 (0=no reset, 1=yes reset to 0.0) RSTRT_SWC = 0 !<-- Specify whether or not to reset any accumulated output variables to 0 (option 1) ! or to continue accumulating from the values in the hydro restart file (option 0). ! Note that this only applies to the hydrologic model outputs; the LSM outputs will ! always continue to accumulate from the LSM restart file. ! Specify baseflow/bucket model initialization (0=cold start from table, 1=restart file) GW_RESTART = 1 !<-- Specify whether to initialize the groundwater bucket states from the hydro ! restart file (option 1) or "cold" start the bucket states from the parameter ! table, GWBUCKPARM.nc. !!!! ------------ MODEL OUTPUT CONTROL ------------ !!!! ! Specify the output file write frequency...(minutes) out_dt = 60 !<-- Timestep for hydro model outputs, in minutes. This covers all output options ! listed below (CHRTOUT, GWOUT, RTOUT, LAKEOUT, etc.) so be cognizant of impacts ! on disk space and runtime when specifying. ! Specify the number of output times to be contained within each output history file...(integer) ! Currently only 1 and 0 are valid options. 1 will output a single file per timestep. ! 0 will output the CHANOBS file only as a single file over the run duration; other ! files will be one file per timestep. SPLIT_OUTPUT_COUNT = 1 !<-- Number of timesteps to put in a single output file. ! 1 = one file per timestep ! 0 = same as option 1 but there will be one file for the ! full run duration for CHANOBS only ! Specify the minimum stream order to output to netCDF point file (integer) ! Note: lower value of stream order produces more output. order_to_write = 4 !<-- Lowest stream order to include in output files. Selecting 1 gives ! you output for every reach/channel cell, selecting a higher order number ! gives you fewer channel output elements. ! Flag to turn on/off new I/O routines: ! 0 = deprecated output routines (only use when running with the Noah LSM), ! 1 = with scale/offset/compression, ! 2 = with scale/offset/NO compression, ! 3 = compression only, ! 4 = no scale/offset/compression (default) io_form_outputs = 1 !<-- Specify which output option to use (NOTE: option 0 is the only ! supported option when running with the original Noah LSM) ! Realtime run configuration option: ! 0=all (default), 1=analysis, 2=short-range, 3=medium-range, ! 4=long-range, 5=retrospective, ! 6=diagnostic (includes all of 1-4 outputs combined) io_config_outputs = 1 !<-- Specify which configuration of output variables to generate ! (NOTE: not active when io_form_outputs=0) ! Option to write output files at time 0 (restart cold start time): 0=no, 1=yes (default) t0OutputFlag = 1 !<-- Select whether or not to create outputs at the initial timestep. ! Options to output channel & bucket influxes. Only active for UDMP_OPT=1. ! Nonzero choice requires that out_dt above matches NOAH_TIMESTEP in namelist.hrldas. ! 0=None (default), 1=channel influxes (qSfcLatRunoff, qBucket) ! 2=channel+bucket fluxes (qSfcLatRunoff, qBucket, qBtmVertRunoff_toBucket) ! 3=channel accumulations (accSfcLatRunoff, accBucket) *NOT TESTED* output_channelBucket_influx = 0 !<-- Select which additional channel and groundwater bucket ! outputs will be generated. These additional variables can ! be used to drive the channel-only model. ! Output netCDF file control - specify which outputs to generate for the run. CHRTOUT_DOMAIN = 1 !<-- Channel output variables (streamflow, velocity, head, etc.) as a netCDF ! point timeseries output at all channel points (1d) 0 = no output, 1 = output CHANOBS_DOMAIN = 0 !<-- NetCDF point timeseries at forecast points or gage points (defined in ! Route_Link.nc) 0 = no output, 1 = output CHRTOUT_GRID = 0 !<-- NetCDF grid of channel streamflow values (2d) 0 = no output, 1 = output ! NOTE: Not available with reach-based routing LSMOUT_DOMAIN = 0 !<-- NetCDF grid of variables passed between LSM and routing components (2d) ! (generally used for diagnostics only) ! 0 = no output, 1 = output NOTE: No scale_factor/add_offset available RTOUT_DOMAIN = 1 !<-- NetCDF grid of terrain routing variables on routing grid (2d) ! 0 = no output, 1 = output output_gw = 1 !<-- NetCDF groundwater output, 0 = no output, 1 = output ! Groundwater bucket outputs [level, inflow, outflow] outlake = 1 !<-- NetCDF grid of lake values (1d) 0 = no output, 1 = output ! ! Lake output variables (if lakes are included in the domain) [level, inflow, outflow] frxst_pts_out = 0 !<-- ASCII text file of streamflow at forecast points or gage points ! (defined in Route_Link.nc), 0 = no output, 1 = output !!!! ---- PHYSICS OPTIONS AND RELATED SETTINGS ---- !!!! ! Specify the number of soil layers (integer) and the depth of the bottom of each layer... (meters) ! Notes: In the current version of WRF-Hydro these must be the same as in the namelist.input file. ! Future versions may permit this to be different. NSOIL=4 !<-- Number of soil layers ZSOIL8(1) = -0.10 !<-- Depth of bottom boundary of top soil layer in meters ZSOIL8(2) = -0.40 !<-- Depth of bottom of second soil layer in meters (note that this is specified ! differently than the namelist.hrldas; this is total depth from the surface instead of thickness) ZSOIL8(3) = -1.00 !<-- Depth of bottom of third soil layer in meters (note that this is specified ! differently than the namelist.hrldas; this is total depth from the surface instead of thickness) ZSOIL8(4) = -2.00 !<-- Depth of bottom of fourth (last) soil layer in meters (note that this is ! specified differently than the namelist.hrldas; this is total depth from the surface instead of thickness) ! Specify the grid spacing of the terrain routing grid (meters) DXRT = 100.0 !<-- Resolution of the high-res routing grid ! Specify the integer multiple between the land model grid and the terrain routing grid (integer) AGGFACTRT = 10 !<-- Aggregation factor between the high-res routing grid and the LSM grid; ! e.g., a 100-m routing grid resolution and a 1km LSM grid resolution would ! be AGGFACTRT = 10. ! Specify the channel routing model timestep (seconds) DTRT_CH = 10 !<-- Timestep for the channel routing module to cycle, in seconds; model runtime ! will be sensitive to this timestep, so choose something appropriate for your ! domain resolution (finer resolutions generally require finer timesteps). ! Specify the terrain routing model timestep (seconds) DTRT_TER = 10 !<-- Timestep for the terrain routing module to cycle, in seconds; model runtime ! will be sensitive to this timestep, so choose something appropriate for your ! domain resolution (finer resolutions generally require finer timesteps). ! Switch to activate subsurface routing...(0=no, 1=yes) SUBRTSWCRT = 1 !<-- Turn on/off subsurface routing module. ! Switch to activate surface overland flow routing...(0=no, 1=yes) OVRTSWCRT = 1 !<-- Turn on/off overland routing module. ! Specify overland flow routing option: ! 1=Seepest Descent (D8) 2=CASC2D (not active) ! NOTE: Currently subsurface flow is only steepest descent rt_option = 1 !<-- For both terrain routing modules, specify whether flow should follow the ! steepest path (option 1) or multi-directional (option 2). ! Option 2 is currently unsupported. ! Specify whether to adjust overland flow parameters based on imperviousness imperv_adj = 0 !<-- When overland routing is active and an imperviousness grid is ! provided in Fulldom_hires.nc, you can use this option to reduce ! the overland roughness and maximum retention depth based on the ! impervious fraction. ! 0 = no adjustment, 1 = activate parameter adjustments ! Switch to activate channel routing...(0=no, 1=yes) CHANRTSWCRT = 1 !<-- Turn on/off channel routing module. ! Specify channel routing option: ! 1=Muskingam-reach, 2=Musk.-Cunge-reach, 3=Diff.Wave-gridded channel_option = 3 !<-- If channel routing module is active, select which physics option to use. ! Specify the reach file for reach-based routing options (e.g.: "Route_Link.nc") route_link_f = "./DOMAIN/Route_Link.nc" !<-- If using one of the reach-based channel routing ! options (channel_option = 1 or 2), specify the path ! to the Route_Link.nc file, which provides the ! channel-reach parameters. ! If using channel_option=2, activate the compound channel formulation? (Default=.FALSE.) ! This option is currently only supported if using reach-basedrouting with UDMP=1. compound_channel = .FALSE. !<-- Turn on or off the compound channel formulation. ! This option only works with Muskingum-Cunge reach-based ! routing with UDMP=1. This option also requires additional ! parameters in the routelink file. ! Switch to activate channel-loss option (0=no, 1=yes) [Requires Kchan in RouteLink] ! channel_loss_option = 0 !<-- Turn on or off channel loss. Note that the channel loss ! scheme currently only works for Muskingum-Cunge reach-based ! channel routing. Also note that activating channel loss will ! create a sink in the model, so the water budget will not close. ! By default this option is off. ! Lake / Reservoir options (0=lakes off, 1=level pool (typical default), ! 2=passthrough, 3=reservoir DA [see &reservoir_nlist below]) lake_option = 1 !<-- Set the lake/reservoir option. Note that different options may ! require different domain/parameter/input files. Option 0 (lakes off) ! will not generate reasonable results for gridded channel routing ! domains where lake cells mask out channel cells. ! Specify the lake parameter file (e.g.: "LAKEPARM.nc"). Note: REQUIRED if lakes are on. route_lake_f = "./DOMAIN/LAKEPARM.nc" !<-- If lakes are active, specify the path to the lake ! parameter file, which provides the lake parameters. ! Switch to activate baseflow bucket model...(0=none, 1=exp. bucket, 2=pass-through, ! 4=exp. bucket with area normalized parameters) ! Option 4 is currently only supported if using reach-based routing with UDMP=1. GWBASESWCRT = 1 !<-- Turn on/off the ground water bucket module. Option 1 activates the ! exponential bucket model, Option 2 bypasses the bucket model and dumps all ! flow from the bottom of the soil column directly into the channel, and ! Option 4 is a variation of the exponential bucket model (option 1) where ! the coefficient is scaled by catchment area and only works for UDMP=1. ! Option 0 creates a sink at the bottom of the soil column (water draining from ! the bottom of the soil column leaves the system, so note that this option will ! not have water balance closure). ! Groundwater/baseflow 2d mask specified on land surface model grid (e.g.: "GWBASINS.nc"). ! NOTE: Only required if baseflow model is active (1 or 2) and UDMP_OPT=0. gwbasmskfil = "./DOMAIN/GWBASINS.nc" !<-- For configurations where the bucket or pass-through ! groundwater modules are active, provide the path to the ! 2d netCDF file (LSM grid resolution) that maps the ! groundwater basin IDs. Bucket parameters will be specified ! through the GWBUCKPARM.nc file, whose IDs should match ! those in the groundwater basin mask file. ! Groundwater bucket parameter file (e.g.: "GWBUCKPARM.nc") GWBUCKPARM_file = "./DOMAIN/GWBUCKPARM.nc" !<-- For configurations where the groundwater bucket ! model is active, specify the path to the bucket ! parameter file, which provides bucket parameters ! by catchment. ! User defined mapping, such NHDPlus: 0=no (default), 1=yes UDMP_OPT = 0 !<-- If 1, this tells the model to use a "user-defined mapping" scheme to translate ! between terrain and groundwater flow and reaches, e.g., NHDPlus. ! If user-define mapping is on, specify the user-defined mapping file (e.g.: "spatialweights.nc") !udmap_file = "./DOMAIN/spatialweights.nc" !<-- If UDMP_OPT=1 (user defined mapping is active), ! provide the path to the required spatial weights ! file, which maps between grid cells and catchments. / !<-- End of hydro namelist HYDRO_nlist &NUDGING_nlist !<-- Start of separate namelist for nudging, only used if the model is compiled ! with the compile-time option WRF_HYDRO_NUDGING=1. Ignored otherwise. ! Path to the "timeslice" observation files. timeSlicePath = "./nudgingTimeSliceObs/" !<-- Path to a directory containing nuding “time slice” ! observation files. There are no requirements on the ! existence of files in the directory, but the directory ! itself must exist if specified. nudgingParamFile = "DOMAIN/nudgingParams.nc" !<-- Path to the required nudging parameter file. ! Nudging restart file. nudgingLastObsFile defaults to '', which will look for ! nudgingLastObs.YYYY-mm-dd_HH:MM:SS.nc *AT THE INITALIZATION TIME OF THE RUN*. Set to a missing ! file to use no restart. !nudgingLastObsFile = '/a/nonexistent/file/gives/nudging/cold/start' !<-- Optional path to an ! optional nudging restart ! file. See comments above. ! Parallel input of nudging timeslice observation files? readTimesliceParallel = .TRUE. !<-- Can read the observation files in parallel (on different cores) ! for quicker run speeds. ! temporalPersistence defaults to true, only runs if necessary params present. temporalPersistence = .FALSE. !<-- This option uses the expCoeff ! parameter for persisting observations ! The total number of last (obs, modeled) pairs to save in nudgingLastObs for removal of bias. ! This is the maximum array length. (This option is active when persistBias=FALSE) ! (Default=960=10days @15min obs resolution, if all the obs are present and longer if not.) nLastObs = 960 !<-- The maximum trailing window size for calculating bias correction. ! If using temporalPersistence the last observation persists by default. This option instead ! persists the bias after the last observation. persistBias = .FALSE. !<-- Apply bias correction as observations move into the past? ! AnA (FALSE) vs Forecast (TRUE) bias persistence. ! If persistBias: Does the window for calculating the bias end at model init time (=t0)? ! FALSE = window ends at model time (moving), ! TRUE = window ends at init=t0(fcst) time. ! (If commented out, Default=FALSE) ! Note: Perfect restart tests require this option to be .FALSE. biasWindowBeforeT0 = .FALSE. !<-- Is the bias window shifting with ! model integration? ! If persistBias: Only use this many last (obs, modeled) pairs. ! (If Commented out, Default=-1*nLastObs) ! > 0: apply an age-based filter, units=hours. ! = 0: apply no additional filter, use all available/usable obs. ! < 0: apply an count-based filter, units=count maxAgePairsBiasPersist = -960 ! If persistBias: The minimum number of last (obs, modeled) pairs, with age less ! than maxAgePairsBiasPersist, required to apply a bias correction. (default=8) minNumPairsBiasPersist = 8 ! If persistBias: give more weight to observations closer in time? (default=FALSE) invDistTimeWeightBias = .TRUE. !<-- The exact form of this ! weighting is currently hard-coded. ! If persistBias: "No constructive interference in bias correction?", reduce the bias ! adjustment when the model and the bias adjustment have the same sign relative to the ! modeled flow at t0? (default=FALSE) ! Note: Perfect restart tests require this option to be .FALSE. noConstInterfBias = .FALSE. !<-- Tactical response to phase errors. / .. _section-a7: A7. Static input files for WRF-Hydro ------------------------------------- The WRF-Hydro model requires several static input files to define the spatial domain and its parameters. These include two files in common with the WRF Model, :file:`geo_em.d01.nc` and :file:`wrfinput.d01.nc`, as well as the WRF-Hydro routing domain file :file:`Fulldom_hires.nc`. The variables in these netCDF files are listed in the tables below: .. csv-table:: :file:`geo_em.d{X}.nc` `\qquad` *geo_em* :file: input-tables/geo_em.tsv :delim: tab :header-rows: 1 \ .. csv-table:: :file:`wrfinput.d{X}.nc` `\qquad` *WRFINPUT* :file: input-tables/wrfinput.tsv :delim: tab :header-rows: 1 \ .. csv-table:: :file:`Fulldom_hires.nc` `\qquad` *Fulldom_Hires* :file: input-tables/Fulldom_hires.tsv :delim: tab :header-rows: 1 .. _section-a8: A8. Noah land surface model parameter tables -------------------------------------------- The Noah land surface model requires three parameter table files denoted by the file suffix TBL. The variables contained within these files are described in the tables below. Please refer to the Noah land surface model documentation (https://ral.ucar.edu/sites/default/files/public/product-tool/unified-noah-lsm/Noah_LSM_USERGUIDE_2.7.1.pdf) for additional information. `GENPARM.TBL` - This file contains global parameters for the Noah land surface model. .. table:: :width: 90% :align: center +--------------------+-------------------------------------------------+ | **Variable name** | **Description** | +====================+=================================================+ | SLOPE_DATA | Linear reservoir coefficient | +--------------------+-------------------------------------------------+ | SBETA_DATA | Parameter used to calculate vegetation effect | | | on soil heat | +--------------------+-------------------------------------------------+ | FXEXP_DAT | Soil evaporation exponent used in DEVAP | +--------------------+-------------------------------------------------+ | CSOIL_DATA | Soil heat capacity [:math:`J/m^3/K`] | +--------------------+-------------------------------------------------+ | SALP_DATA | Shape parameter of distribution function of | | | snow cover | +--------------------+-------------------------------------------------+ | REFDK_DATA | Parameter in the surface runoff | | | parameterization | +--------------------+-------------------------------------------------+ | REFKDT_DATA | Parameter in the surface runoff | | | parameterization | +--------------------+-------------------------------------------------+ | FRZK_DATA | Frozen ground parameter | +--------------------+-------------------------------------------------+ | ZBOT_DATA | Depth of lower boundary soil temperature | | | [:math:`m`] | +--------------------+-------------------------------------------------+ | CZIL_DATA | Parameter used in the calculation of the | | | roughness length for heat | +--------------------+-------------------------------------------------+ | SMLOW_DATA | Soil moisture wilt, soil moisture reference | | | parameter | +--------------------+-------------------------------------------------+ | SMHIGH_DATA | Soil moisture wilt, soil moisture reference | | | parameter | +--------------------+-------------------------------------------------+ | LVCOEF_DATA | Parameter in the snow albedo formulation | +--------------------+-------------------------------------------------+ | `SOILPARM.TBL` - This file contains parameters that are assigned based upon soil classification. | *All parameters are a function of soil class.* .. table:: :width: 90% :align: center +-------------+--------------------------------------------------------+ | **Variable | **Description** | | name** | | +=============+========================================================+ | BB | B parameter | +-------------+--------------------------------------------------------+ | DRYSMC | Dry soil moisture threshold at which direct | | | evaporation from top soil layer ends | +-------------+--------------------------------------------------------+ | F11 | Soil thermal diffusivity/conductivity coefficient | +-------------+--------------------------------------------------------+ | MAXSMC | Saturation soil moisture content (i.e. porosity) | +-------------+--------------------------------------------------------+ | REFSMC | Reference soil moisture (field capacity), where | | | transpiration begins to stress | +-------------+--------------------------------------------------------+ | SATPSI | Saturation soil matric potential | +-------------+--------------------------------------------------------+ | SATDK | Saturation soil conductivity | +-------------+--------------------------------------------------------+ | SATDW | Saturation soil diffusivity | +-------------+--------------------------------------------------------+ | WLTSMC | Wilting point soil moisture | +-------------+--------------------------------------------------------+ | QTZ | Soil quartz content | +-------------+--------------------------------------------------------+ | `VEGPARM.TBL` - This file contains parameters that a function of land cover type. | *All parameters are a function of land cover type.* .. table:: :width: 90% :align: center +-------------------+---------------------------------------------------------+ | **Variable name** | **Description** | +===================+=========================================================+ | SHDFAC | Green vegetation fraction | +-------------------+---------------------------------------------------------+ | NROOT | Number of soil layers (from the top) reached by | | | vegetation roots | +-------------------+---------------------------------------------------------+ | RS | Minimum stomatal resistance [`s/m`] | +-------------------+---------------------------------------------------------+ | RGL | Parameter used in radiation stress function | +-------------------+---------------------------------------------------------+ | HS | Parameter used in vapor pressure deficit function | +-------------------+---------------------------------------------------------+ | SNUP | Threshold water-equivalent snow depth [m] that implies | | | 100% snow cover | +-------------------+---------------------------------------------------------+ | MAXALB | Upper bound on maximum albedo over deep snow [`\%`] | +-------------------+---------------------------------------------------------+ | LAIMIN | Minimum leaf area index through the year | | | [dimensionless] | +-------------------+---------------------------------------------------------+ | LAIMAX | Maximum leaf area index through the year | | | [dimensionless] | +-------------------+---------------------------------------------------------+ | EMISSMIN | Minimum background emissivity through the year | | | [fraction 0.0 to 1.0] | +-------------------+---------------------------------------------------------+ | EMISSMAX | Maximum background emissivity through the year | | | [fraction 0.0 to 1.0] | +-------------------+---------------------------------------------------------+ | ALBEDOMIN | Minimum background albedo through the year [fraction | | | 0.0 to 1.0] | +-------------------+---------------------------------------------------------+ | ALBEDOMAX | Maximum background albedo through the year [fraction | | | 0.0 to 1.0] | +-------------------+---------------------------------------------------------+ | Z0MIN | Minimum background roughness length through the year | | | [`m`] | +-------------------+---------------------------------------------------------+ | Z0MAX | Maximum background roughness length through the year | | | [`m`] | +-------------------+---------------------------------------------------------+ | TOPT_DATA | Optimum transpiration air temperature [`K`] | +-------------------+---------------------------------------------------------+ | CMCMAX_DATA | Maximum canopy water capacity [volumetric fraction] | | | | +-------------------+---------------------------------------------------------+ | CFACTR_DATA | Parameter used in the canopy interception calculation | | | [dimensionless] | +-------------------+---------------------------------------------------------+ | RSMAX_DATA | Maximal stomatal resistance [`s/m`] | +-------------------+---------------------------------------------------------+ | BARE | The land-use category representing bare ground (used to | | | set the vegetation fraction to zero) [land-use category | | | index] | +-------------------+---------------------------------------------------------+ | NATURAL | The land-use category representative of the non-urban | | | portion of urban land-use points [land-use category | | | index] | +-------------------+---------------------------------------------------------+ .. _section-a9: A9. Noah-MP land surface model parameter tables ----------------------------------------------- The Noah-MP land surface model requires three parameter table files denoted by the file suffix TBL. The variables contained within these files are described in the tables below. As part of the work conducted for the National Water Model implementation, the ability to specify a number of these land surface model parameters spatially on a two or three dimensional grid was introduced. This is done through the use of the compile time option ``SPATIAL_SOIL`` and the specification of a netCDF format parameter file with the default filename soil_properties.nc. A list of the variables contained in this file is included in a table below as well. `GENPARM.TBL` This file contains global parameters for the Noah-MP land surface model. .. table:: :width: 90% :align: center +---------------+------------------------------------------------------+ | **Variable | **Description** | | name** | | +===============+======================================================+ | SLOPE_DATA | Linear reservoir coefficient | +---------------+------------------------------------------------------+ | SBETA_DATA | Parameter used to calculate vegetation effect on | | | soil heat | +---------------+------------------------------------------------------+ | FXEXP_DAT | Soil evaporation exponent used in DEVAP | +---------------+------------------------------------------------------+ | CSOIL_DATA | Soil heat capacity [:math:`J/m^3/K`] | +---------------+------------------------------------------------------+ | SALP_DATA | Shape parameter of distribution function of snow | | | cover | +---------------+------------------------------------------------------+ | REFDK_DATA | Parameter in the surface runoff parameterization | +---------------+------------------------------------------------------+ | REFKDT_DATA | Parameter in the surface runoff parameterization | +---------------+------------------------------------------------------+ | FRZK_DATA | Frozen ground parameter | +---------------+------------------------------------------------------+ | ZBOT_DATA | Depth of lower boundary soil temperature [:math:`m`] | +---------------+------------------------------------------------------+ | CZIL_DATA | Parameter used in the calculation of the roughness | | | length for heat | +---------------+------------------------------------------------------+ | SMLOW_DATA | Soil moisture wilt, soil moisture reference | | | parameter | +---------------+------------------------------------------------------+ | SMHIGH_DATA | Soil moisture wilt, soil moisture reference | | | parameter | +---------------+------------------------------------------------------+ | LVCOEF_DATA | Parameter in the snow albedo formulation | +---------------+------------------------------------------------------+ `SOILPARM.TBL` - This file contains parameters that are assigned based on soil classification. .. table:: :width: 90% :align: center +--------------+-------------------------------------------------------+ | **Variable | **Description** | | name** | | +==============+=======================================================+ | BB | B parameter | +--------------+-------------------------------------------------------+ | DRYSMC | Dry soil moisture threshold at which direct | | | evaporation from top soil layer ends | +--------------+-------------------------------------------------------+ | F11 | Soil thermal diffusivity/conductivity coefficient | +--------------+-------------------------------------------------------+ | MAXSMC | Saturation soil moisture content (i.e. porosity) | +--------------+-------------------------------------------------------+ | REFSMC | Reference soil moisture (field capacity), where | | | transpiration begins to stress | +--------------+-------------------------------------------------------+ | SATPSI | Saturation soil matric potential | +--------------+-------------------------------------------------------+ | SATDK | Saturation soil conductivity | +--------------+-------------------------------------------------------+ | SATDW | Saturation soil diffusivity | +--------------+-------------------------------------------------------+ | WLTSMC | Wilting point soil moisture | +--------------+-------------------------------------------------------+ | QTZ | Soil quartz content | +--------------+-------------------------------------------------------+ | AXAJ | Tension water distribution inflection parameter | +--------------+-------------------------------------------------------+ | BXAJ | Tension water distribution shape parameter | +--------------+-------------------------------------------------------+ | XXAJ | Free water distribution shape parameter | +--------------+-------------------------------------------------------+ `MPTABLE.TBL` - This file contains parameters that are a function of land cover type. .. table:: :width: 90% :align: center +-------------------------+--------------------------------------------+ | **Variable name** | **Description** | +=========================+============================================+ | VEG_DATASET_DESCRIPTION | Land cover classification dataset | +-------------------------+--------------------------------------------+ | NVEG | Number of land cover categories | +-------------------------+--------------------------------------------+ | ISURBAN | Land cover category for urban | +-------------------------+--------------------------------------------+ | ISWATER | Land cover category for water | +-------------------------+--------------------------------------------+ | ISBARREN | Land cover category for barren | +-------------------------+--------------------------------------------+ | ISICE | Land cover category for ice | +-------------------------+--------------------------------------------+ | EBLFOREST | Land cover category for evergreen | | | broadleaf forest | +-------------------------+--------------------------------------------+ | .. centered:: *Parameters below are a function of land cover type* | +-------------------------+--------------------------------------------+ | CH2OP | Maximum intercepted H\ :sub:`2`\O per unit | | | LAI + SAI [:math:`mm`] | +-------------------------+--------------------------------------------+ | DLEAF | Characteristic leaf dimension [:math:`m`] | +-------------------------+--------------------------------------------+ | Z0MVT | Momentum roughness length [:math:`m`] | +-------------------------+--------------------------------------------+ | HVT | Top of canopy [:math:`m`] | +-------------------------+--------------------------------------------+ | HVB | Bottom of canopy [:math:`m`] | +-------------------------+--------------------------------------------+ | DEN | Tree density [:math:`trunks/m^2`\] | +-------------------------+--------------------------------------------+ | RC | Tree crown radius [:math:`m`] | +-------------------------+--------------------------------------------+ | MFSNO | Snowmelt m parameter | +-------------------------+--------------------------------------------+ | RHOS_VIS | Monthly stem area index (SAI), one-sided | +-------------------------+--------------------------------------------+ | RHOS_NIR | Monthly leaf area index (LAI), one-sided | +-------------------------+--------------------------------------------+ | TAUL_VIS | Leaf transmittance, visible | +-------------------------+--------------------------------------------+ | TAUL_NIR | Leaf transmittance, near infrared | +-------------------------+--------------------------------------------+ | TAUS_VIS | Stem transmittance, visible | +-------------------------+--------------------------------------------+ | TAUS_NIR | Stem transmittance, near infrared | +-------------------------+--------------------------------------------+ | XL | Leaf / stem orientation index | +-------------------------+--------------------------------------------+ | CWPVT | Canopy wind parameter | +-------------------------+--------------------------------------------+ | C3PSN | Photosynthetic pathway [c4 = 0. \| c3 = | | | 1.] | +-------------------------+--------------------------------------------+ | KC25 | CO2 Michaelis-Menten constant | | | at 25°C [:math:`Pa`] | +-------------------------+--------------------------------------------+ | AKC | Q10 for KC25 | +-------------------------+--------------------------------------------+ | KO25 | O2 Michaelis-Menten constant | | | at 25°C [:math:`Pa`] | +-------------------------+--------------------------------------------+ | AKO | Q10 for KO25 | +-------------------------+--------------------------------------------+ | AVCMX | Q10 for VCMX25 | +-------------------------+--------------------------------------------+ | AQE | Q10 for QE25 | +-------------------------+--------------------------------------------+ | LTOVRC | Leaf turnover [:math:`1/s`] | +-------------------------+--------------------------------------------+ | DILEFC | Coefficient for leaf stress death | | | [:math:`1/s`] | +-------------------------+--------------------------------------------+ | DILEFW | Coefficient for leaf stress death | | | [:math:`1/s`] | +-------------------------+--------------------------------------------+ | RMF25 | Leaf maintenance respiration at 25°C | | | [:math:`umol\ CO_{2}/m^2/s`] | +-------------------------+--------------------------------------------+ | SLA | Single-side leaf area [:math:`m2/kg`] | +-------------------------+--------------------------------------------+ | FRAGR | Fraction of growth respiration | +-------------------------+--------------------------------------------+ | TMIN | Minimum temperature for photosynthesis | | | [:math:`K`] | +-------------------------+--------------------------------------------+ | VCMX25 | maximum rate of carboxylation at 25°C | | | [:math:`umol\ CO_{2}/m^2/s`] | +-------------------------+--------------------------------------------+ | TDLEF | Characteristic temperature for leaf | | | freezing [:math:`K`] | +-------------------------+--------------------------------------------+ | BP | Minimum leaf conductance | | | [:math:`umol\ /m^2/s`] | +-------------------------+--------------------------------------------+ | MP | Slope of conductance to photosynthesis | | | relationship | +-------------------------+--------------------------------------------+ | QE25 | Quantum efficiency at 25°C | | | [:math:`umol\ CO_{2} / umol\ photon`] | +-------------------------+--------------------------------------------+ | RMS25 | Stem maintenance respiration at 25°C | | | [:math:`umol\ CO_{2}/kg_{bio}/s`] | +-------------------------+--------------------------------------------+ | RMR25 | Root maintenance respiration at 25°C | | | [:math:`umol\ CO_{2}/kg_{bio}/s`] | +-------------------------+--------------------------------------------+ | ARM | Q10 for maintenance respiration | +-------------------------+--------------------------------------------+ | FOLNMX | Foliage nitrogen concentration when | | | :math:`f(n)=1` [:math:`\%`] | +-------------------------+--------------------------------------------+ | WRRAT | Wood to non-wood ratio | +-------------------------+--------------------------------------------+ | MRP | Microbial respiration parameter | | | [:math:`umol\ CO_{2}/kg_{C}/s`] | +-------------------------+--------------------------------------------+ | NROOT | Number of soil layers with root present | +-------------------------+--------------------------------------------+ | RGL | Parameter used in radiation stress | | | function | +-------------------------+--------------------------------------------+ | RS | Stomatal resistance [:math:`s/m`] | +-------------------------+--------------------------------------------+ | HS | Parameter used in vapor pressure deficit | | | function | +-------------------------+--------------------------------------------+ | TOPT | Optimum transpiration air temperature [K] | +-------------------------+--------------------------------------------+ | RSMAX | Maximal stomatal resistance | | | [:math:`s m-1`] | +-------------------------+--------------------------------------------+ | SAI | Steam area index | +-------------------------+--------------------------------------------+ | LAI | Leaf area index | +-------------------------+--------------------------------------------+ | SLAREA | (not used in Noah-MP as configured in | | | WRF-Hydro) | +-------------------------+--------------------------------------------+ | EPS1 | (not used in Noah-MP as configured in | | | WRF-Hydro) | +-------------------------+--------------------------------------------+ | EPS2 | (not used in Noah-MP as configured in | | | WRF-Hydro) | +-------------------------+--------------------------------------------+ | EPS3 | (not used in Noah-MP as configured in | | | WRF-Hydro) | +-------------------------+--------------------------------------------+ | EPS4 | (not used in Noah-MP as configured in | | | WRF-Hydro) | +-------------------------+--------------------------------------------+ | EPS5 | (not used in Noah-MP as configured in | | | WRF-Hydro) | +-------------------------+--------------------------------------------+ | .. centered:: *Parameters below are a function of soil color index* | +-------------------------+--------------------------------------------+ | ALBSAT_VIS | Saturated soil albedos for visible | +-------------------------+--------------------------------------------+ | ALBSAT_NIR | Saturated soil albedos for near infrared | +-------------------------+--------------------------------------------+ | ALBDRY_VIS | Dry soil albedos for visible | +-------------------------+--------------------------------------------+ | ALBDRY_NIR | Dry soil albedos for near infrared | +-------------------------+--------------------------------------------+ | .. centered:: *Parameters below are global* | +-------------------------+--------------------------------------------+ | ALBICE | Albedo land ice (visible and near | | | infrared) | +-------------------------+--------------------------------------------+ | ALBLAK | Albedo frozen lakes (visible and near | | | infrared) | +-------------------------+--------------------------------------------+ | OMEGAS | Two-stream parameter for snow | +-------------------------+--------------------------------------------+ | BETADS | Two-stream parameter for snow | +-------------------------+--------------------------------------------+ | BETAIS | Two-stream parameter for snow | +-------------------------+--------------------------------------------+ | EG | Emissivity soil surface (soil and lake) | +-------------------------+--------------------------------------------+ | CO2 | CO\ :sub:`2` partial pressure | +-------------------------+--------------------------------------------+ | O2 | O\ :sub:`2` partial pressure | +-------------------------+--------------------------------------------+ | TIMEAN | Grid cell mean topographic index [global | | | mean] | +-------------------------+--------------------------------------------+ | FSATMX | Maximum surface saturated fraction [global | | | mean] | +-------------------------+--------------------------------------------+ | Z0SNO | Snow surface roughness length [:math:`m`] | +-------------------------+--------------------------------------------+ | SSI | Liquid water holding capacity for snowpack | | | [:math:`m^3/m^3`] | +-------------------------+--------------------------------------------+ | SWEMX | New snow mass to fully cover old snow | | | [:math:`mm`] | +-------------------------+--------------------------------------------+ | TAU0 | Tau0 from Yang97 eqn. 10a | +-------------------------+--------------------------------------------+ | GRAIN_GROWTH | Growth from vapor diffusion Yang97 | | | eqn. 10b | +-------------------------+--------------------------------------------+ | EXTRA_GROWTH | Extra growth near freezing Yang97 | | | eqn. 10c | +-------------------------+--------------------------------------------+ | DIRT_SOOT | Dirt and soot term Yang97 eqn. 10d | +-------------------------+--------------------------------------------+ | BATS_COSZ | Zenith angle snow albedo | | | adjustment; b in Yang97 eqn. 15 | +-------------------------+--------------------------------------------+ | BATS_VIS_NEW | New snow visible albedo | +-------------------------+--------------------------------------------+ | BATS_NIR_NEW | New snow NIR albedo | +-------------------------+--------------------------------------------+ | BATS_VIS_AGE | Age factor for diffuse visible snow | | | albedo Yang97 eqn. 17 | +-------------------------+--------------------------------------------+ | BATS_NIR_AGE | Age factor for diffuse NIR snow | | | albedo Yang97 eqn. 18 | +-------------------------+--------------------------------------------+ | BATS_VIS_DIR | Cosz factor for direct visible snow | | | albedo Yang97 eqn. 15 | +-------------------------+--------------------------------------------+ | BATS_NIR_DIR | Cosz factor for direct NIR snow | | | albedo Yang97 eqn. 16 | +-------------------------+--------------------------------------------+ | RSURF_SNOW | Surface resistance for snow [:math:`s/m`] | +-------------------------+--------------------------------------------+ | RSURF_EXP | Exponent in the shape parameter for | | | soil resistance option 1 | +-------------------------+--------------------------------------------+ | IMPERV_URBAN | impervious fraction to use for urban | | | type cells [0-1] | +-------------------------+--------------------------------------------+ | SCAMAX | maximum fractional snow covered area [0-1] | +-------------------------+--------------------------------------------+ | SWE_LIMIT | maximum SWE limit [mm] | +-------------------------+--------------------------------------------+ `soil\_properties.nc` [optional] .. table:: :width: 90% :align: center +------------+----------------------------------------------------------+ | **Variable | **Description** | | name** | | +============+==========================================================+ | bexp | Beta parameter | +------------+----------------------------------------------------------+ | cwpvt | Empirical canopy wind parameter | +------------+----------------------------------------------------------+ | dksat | Saturated soil hydraulic conductivity | +------------+----------------------------------------------------------+ | dwsat | Saturated soil hydraulic diffusivity | +------------+----------------------------------------------------------+ | hvt | Top of vegetation canopy [:math:`m`] | +------------+----------------------------------------------------------+ | mfsno | Snowmelt m parameter | +------------+----------------------------------------------------------+ | mp | Slope of conductance to photosynthesis relationship | +------------+----------------------------------------------------------+ | psisat | Saturated soil matric potential | +------------+----------------------------------------------------------+ | quartz | Soil quartz content | +------------+----------------------------------------------------------+ | refdk | Parameter in the surface runoff parameterization | +------------+----------------------------------------------------------+ | refkdt | Parameter in the surface runoff parameterization | +------------+----------------------------------------------------------+ | rsurf_exp | Exponent in the shape parameter for soil | | | resistance option 1 | +------------+----------------------------------------------------------+ | slope | Slope index | +------------+----------------------------------------------------------+ | smcdry | Dry soil moisture threshold where direction evaporation | | | from the top layer ends | +------------+----------------------------------------------------------+ | smcmax | Saturated value of soil moisture [volumetric] | +------------+----------------------------------------------------------+ | smcref | Reference soil moisture (field capacity) [volumetric] | +------------+----------------------------------------------------------+ | smcwlt | Wilting point soil moisture [volumetric] | +------------+----------------------------------------------------------+ | vcmx25 | Maximum rate of carboxylation at 25°C | | | [:math:`umol\ CO_{2}/m^2/s`] | +------------+----------------------------------------------------------+ | AXAJ | Tension water distribution inflection parameter | +------------+----------------------------------------------------------+ | BXAJ | Tension water distribution shape parameter | +------------+----------------------------------------------------------+ | XXAJ | Free water distribution shape parameter | +------------+----------------------------------------------------------+ | rsurfsnow | Surface resistance for snow [s/m] | +------------+----------------------------------------------------------+ | scamax | Maximum fractional snow covered area [0-1] | +------------+----------------------------------------------------------+ | snowretfac | Snowpack water release timescale factor [1/s] | +------------+----------------------------------------------------------+ | ssi | Liquid water holding capacity for snowpack | | | [:math:`m^3/m^3`] | +------------+----------------------------------------------------------+ | tau0 | Snow albedo decay timescale parameter [s] | +------------+----------------------------------------------------------+ | imperv | Impervious fraction (optional) [0-1] | +------------+----------------------------------------------------------+ .. _section-a10: A10. Terrain routing parameter files ------------------------------------ Parameters for the lateral routing component of WRF-Hydro are specified via either the `HYDRO.TBL` file or the `hydro2dtbl.nc` file. Variables within these files are described in the tables below. `HYDRO.TBL` .. table:: :width: 90% :align: center +--------------------+------------------------------------------------------+ | **Variable name** | **Description** | +====================+======================================================+ | .. centered:: *The parameter below is a function of land cover type* | +--------------------+------------------------------------------------------+ | SFC_ROUGH | Overland flow roughness coefficient | +--------------------+------------------------------------------------------+ | .. centered:: *The parameters below are a function of soil class* | +--------------------+------------------------------------------------------+ | SATDK | Saturated soil hydraulic conductivity [:math:`m/s`] | +--------------------+------------------------------------------------------+ | MAXSMC | Maximum volumetric soil moisture | | | [:math:`m^3/m^3`] | +--------------------+------------------------------------------------------+ | REFSMC | Reference volumetric soil moisture | | | [:math:`m^3/m^3`] | +--------------------+------------------------------------------------------+ | WLTSMC | Wilting point volumetric soil moisture | | | [:math:`m^3/m^3`] | +--------------------+------------------------------------------------------+ | QTZ | Quartz fraction of the soil | +--------------------+------------------------------------------------------+ `hydro2dtbl.nc` .. table:: :width: 90% :align: center +-----------------------+----------------------------------------------+ | **Variable name** | **Description** | +=======================+==============================================+ | SMCMAX1 | Maximum volumetric soil moisture | | | [:math:`m^3/m^3`] | +-----------------------+----------------------------------------------+ | SMCREF1 | Reference volumetric soil moisture | | | [:math:`m^3/m^3`] | +-----------------------+----------------------------------------------+ | SMCWLT1 | Wilting point volumetric soil moisture | | | [:math:`m^3/m^3`] | +-----------------------+----------------------------------------------+ | OV_ROUGH2D | Overland flow roughness coefficient | +-----------------------+----------------------------------------------+ | LKSAT | Lateral saturated soil hydraulic | | | conductivity [:math:`m/s`] | +-----------------------+----------------------------------------------+ | NEXP | Exponent in the decay function for lateral | | | Ksat over depth | +-----------------------+----------------------------------------------+ .. _section-a11: A11. Channel routing parameter tables (`CHANPARM.TBL` and `Route\_Link.nc`) --------------------------------------------------------------------------- Variables of the the channel routing parameter tables are described in the tables below. | `CHANPARM.TBL` | *All parameters are a function of Strahler stream order* .. table:: :width: 90% :align: center +----------------------+---------------------------------------------------+ | **Variable name** | **Description** | +======================+===================================================+ | Bw | Channel bottom width [:math:`m`] | +----------------------+---------------------------------------------------+ | HLINK | Initial depth of water in the channel [:math:`m`] | +----------------------+---------------------------------------------------+ | ChSSlp | Channel side slope [:math:`m/m`] | +----------------------+---------------------------------------------------+ | MannN | Manning’s roughness coefficient | +----------------------+---------------------------------------------------+ | `Route\_Link.nc` | *All parameters are specified per stream specified per stream segment (i.e. link)* .. table:: :width: 90% :align: center +----------------------+-----------------------------------------------+ | **Variable name** | **Description** | +======================+===============================================+ | BtmWdth | Channel bottom width [:math:`m`] | +----------------------+-----------------------------------------------+ | ChSlp | Channel side slope [:math:`m/m`] | +----------------------+-----------------------------------------------+ | Kchan | Channel conductivity [:math:`mm/hr`] | +----------------------+-----------------------------------------------+ | Length | Stream segment length [:math:`m`] | +----------------------+-----------------------------------------------+ | MusK | Muskingum routing time [:math:`s`] | +----------------------+-----------------------------------------------+ | MusX | Muskingum weighting coefficient | +----------------------+-----------------------------------------------+ | NHDWaterbodyComID | ComID of an associated water body if any | +----------------------+-----------------------------------------------+ | Qi | Initial flow in link [:math:`m^3/s`] | +----------------------+-----------------------------------------------+ | So | Slope [:math:`m/m`] | +----------------------+-----------------------------------------------+ | alt | Elevation from the NAD88 datum at start node | | | [:math:`m`] | +----------------------+-----------------------------------------------+ | ascendingIndex | Index to user for sorting IDs - *only in NWM | | | files* | +----------------------+-----------------------------------------------+ | from | From Link ID | +----------------------+-----------------------------------------------+ | gages | Identifier for stream gage at this location | +----------------------+-----------------------------------------------+ | lat | Latitude of the segment midpoint *[degrees | | | north]* | +----------------------+-----------------------------------------------+ | link | Link ID | +----------------------+-----------------------------------------------+ | lon | Longitude of the segment midpoint *[degrees | | | east]* | +----------------------+-----------------------------------------------+ | n | Manning's roughness | +----------------------+-----------------------------------------------+ | nCC | Compound Channel Manning's roughness | +----------------------+-----------------------------------------------+ | order | Strahler stream order | +----------------------+-----------------------------------------------+ | to | To Link ID | +----------------------+-----------------------------------------------+ | time | Time of measurement | +----------------------+-----------------------------------------------+ | TopWdth | Top Width [m] | +----------------------+-----------------------------------------------+ | TopWdthCC | Compound Channel Top Width [m] | +----------------------+-----------------------------------------------+ .. _section-a12: A12. Groundwater input and parameter files ------------------------------------------ The contents of the groundwater input and parameter files are described in the tables below. `GWBASINS.nc` .. table:: :width: 90% :align: center +----------------------+-----------------------------------------------+ | **Variable name** | **Description** | +======================+===============================================+ | y | projection y coordinate | +----------------------+-----------------------------------------------+ | x | projection x coordinate | +----------------------+-----------------------------------------------+ | crs | coordinate reference system definition | +----------------------+-----------------------------------------------+ | BASIN | groundwater basin ID | +----------------------+-----------------------------------------------+ `GWBUCKPARM.nc` .. table:: :width: 90% :align: center +-----------------------+----------------------------------------------+ | **Variable name** | **Description** | +=======================+==============================================+ | Basin | Basin monotonic ID (1...n) | +-----------------------+----------------------------------------------+ | Coeff | Coefficient | +-----------------------+----------------------------------------------+ | Expon | Exponent | +-----------------------+----------------------------------------------+ | Zmax | Zmax | +-----------------------+----------------------------------------------+ | Zinit | Zinit | +-----------------------+----------------------------------------------+ | Area_sqkm | Basin area [:math:`km^2`] | +-----------------------+----------------------------------------------+ | ComID | NHDCatchment FEATUREID (NHDFlowline ComID) | +-----------------------+----------------------------------------------+ | Loss | Fraction of bucket output lost | +-----------------------+----------------------------------------------+ .. _section-a13: A13. Spatial weights input file variable description ---------------------------------------------------- The contents of the `spatialweights.nc` file is described in the table below. .. table:: :width: 90% :align: center +--------------+---------------------------------------------+---------------+ | **Variable | **Description** | **Dimension** | | name** | | | +==============+=============================================+===============+ | polyid | ID of polygon | polyid | +--------------+---------------------------------------------+---------------+ | IDmask | Polygon ID (polyid) associated with each | data | | | record) | | +--------------+---------------------------------------------+---------------+ | overlaps | Number of intersecting polygons | polyid | +--------------+---------------------------------------------+---------------+ | weight | Fraction of intersecting polygon(polyid) | data | | | intersected by poly2 | | +--------------+---------------------------------------------+---------------+ | regridweight | Fraction of intersecting | data | | | polyid(overlapper) intersected by | | | | polygon(polyid) | | +--------------+---------------------------------------------+---------------+ | i_index | Index in the x dimension of the raster | data | | | grid *(starting with 1,1 in the LL corner)* | | +--------------+---------------------------------------------+---------------+ | j_index | Index in the y dimension of the raster | data | | | grid *(starting with 1,1 in the LL corner)* | | +--------------+---------------------------------------------+---------------+ .. _section-a14: A14. Lake and reservoir parameter tables (`LAKEPARM.nc`) -------------------------------------------------------- Variables within the `LAKEPARM.nc` file are described in the tables below. .. table:: :width: 90% :align: center +--------------------+-------------------------------------------------+ | **Variable name** | **Description** | +====================+=================================================+ | lake_id | Lake index (consecutively from 1 to n # of | | | lakes) | +--------------------+-------------------------------------------------+ | LkArea | Area [:math:`m^2`] | +--------------------+-------------------------------------------------+ | LkMxE | Elevation of maximum lake height [:math:`m`, | | | AMSL] | +--------------------+-------------------------------------------------+ | WeirC | Weir coefficient (ranges from zero to one) | +--------------------+-------------------------------------------------+ | WeirL | Weir length [:math:`m`] | +--------------------+-------------------------------------------------+ | WeirE | Weir elevation [:math:`m`, AMSL] | +--------------------+-------------------------------------------------+ | OrificeC | Orifice coefficient (ranges from zero to one) | +--------------------+-------------------------------------------------+ | OrificeA | Orifice area [:math:`m^2`] | +--------------------+-------------------------------------------------+ | OrificeE | Orifice elevation [:math:`m`, AMSL] | +--------------------+-------------------------------------------------+ | Dam_Length | Dam length as a multiplier on WeirL [multiplier]| +--------------------+-------------------------------------------------+ | lat | Latitude *[decimal degrees north]* | +--------------------+-------------------------------------------------+ | lon | Longitude *[decimal degrees east]* | +--------------------+-------------------------------------------------+ | time | time | +--------------------+-------------------------------------------------+ | ascendingIndex | Index to use for sorting IDs (ascending) | +--------------------+-------------------------------------------------+ | ifd | Initial fraction water depth | +--------------------+-------------------------------------------------+ | crs | CRS definition | +--------------------+-------------------------------------------------+ .. _section-a15: A15. Restart Files Overview --------------------------- **Cold start versus warm start model simulations:** When one start the model as a `cold start` (meaning that it is starting with the default values at the very beginning), it takes time for the model to warm up and reach an equilibrium state. For example, consider simulating streamflow values for a stream which has a base flow of at least 10 cms during the year, and you have a `cold start`. The default values of the streamflow might be zeros at the start of the modeling. It then takes time for the simulated streamflow within the model to reach the 10 cms. In contrast, a `warm start` is when the model simulation begins with the simulated values of a given time step (starting time step) from a previous run. This eliminates the processing time the model would take to reach an equilibrium state. Depending on which variable of the model you are looking at, the time required to reach to the warm state may differ. For example, groundwater requires a longer time period to reach to equilibrium. **How to do a warm start simulations with WRF-Hydro?** WRF-Hydro model outputs two set of model restart files (:file:`RESTART.YYYYmmddHH_DOMAIN` and :file:`HYDRO_RST.YYYY-mm-dd_HH:MM_DOMAIN1`) which store the model states at a specified time and could be used to start the model from that point in time. :file:`RESTART.YYYYmmddHH_DOMAIN` stores the state variables reqiured for restarting LSM and :file:`HYDRO_RST.YYYY-mm-dd_HH:MM_DOMAIN` stores the state variables required to resume the hydro components of the WRF-Hydro model. To warm start the LSM part of the model, specify path to the restart file in the :file:`namelist.hrldas` using `RESTART\_FILENAME\_REQUESTED` option. To warm start the HYDRO part of the model, specify the path to the `HYDRO\_RST` file in the :file:`hydro.namelist` using the option `RESTART\_FILE`, and also set the `gw\_restart` option to 1. If the path to the files are left empty or commented out, it means the model simulation is cold started. One could control the frequency of outputting restart files using the options `RESTART\_FREQUENCY\_HOURS` and `rst\_dt` in the :file:`namelist.hrldas` and :file:`hydro.namelist`, respectively. If these options are set to -9999, model outputs restart files once a month. Restart files are large in size, and therefore user needs to be cautious of how frequently it outputs the restart files. .. figure:: media/restarts.png :align: center **Figure A15.** Overview of restart files for the various model physics components. A15.1 RESTART_MP File Variable Table ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: Noah-MP restarts are written in ``subroutine lsm_restart()`` in :file:`module_NoahMP_hrldas_driver.F`. Noah-MP variables are defined in ``subroutine noahmplsm()`` in :file:`module_sf_noahmpdrv.F` `RESTART\_MP` file variable descriptions .. table:: :width: 90% :align: center +-------------+-------------------------------------------+------------------+ | **Variable | **Description** | **Units** | | name** | | | +=============+===========================================+==================+ | ACCPRCP | Accumulated precipitation | :math:`mm` | +-------------+-------------------------------------------+------------------+ | ACCECAN | Accumulated canopy evaporation | :math:`mm` | +-------------+-------------------------------------------+------------------+ | ACCEDIR | Accumulated direct soil evaporation | :math:`mm` | +-------------+-------------------------------------------+------------------+ | ACCETRAN | Accumulated transpiration | :math:`mm` | +-------------+-------------------------------------------+------------------+ | ACMELT | accumulated melting water out of snow | :math:`mm` | | | bottom | | +-------------+-------------------------------------------+------------------+ | ACSNOW | accumulated snowfall on grid | :math:`mm` | +-------------+-------------------------------------------+------------------+ | ALBOLD | snow albedo at last time step (-) | | +-------------+-------------------------------------------+------------------+ | AREAXY | (in the file but not used by the model) | | +-------------+-------------------------------------------+------------------+ | CANICE | Canopy ice water content / | :math:`mm` | | | canopy-intercepted ice | | +-------------+-------------------------------------------+------------------+ | CANLIQ | Canopy liquid water content / | :math:`mm` | | | canopy-intercepted liquid water | | +-------------+-------------------------------------------+------------------+ | CH | Sensible heat exchange coefficient | | +-------------+-------------------------------------------+------------------+ | CM | Momentum drag coefficient | | +-------------+-------------------------------------------+------------------+ | DEEPRECHXY | soil moisture below the bottom of the | :math:`m^3/m^3` | | | column | | +-------------+-------------------------------------------+------------------+ | EAH | canopy air vapor pressure | :math:`Pa` | +-------------+-------------------------------------------+------------------+ | EQZWT | (in the file but not used by the model) | | +-------------+-------------------------------------------+------------------+ | FASTCP | short-lived carbon in shallow soil | :math:`g/m^2` | +-------------+-------------------------------------------+------------------+ | FDEPTHXY | (in the file but not used by the model) | | +-------------+-------------------------------------------+------------------+ | FWET | Wetted or snowed fraction of canopy | :math:`fraction` | +-------------+-------------------------------------------+------------------+ | GVFMAX | annual maximum in vegetation fraction | | +-------------+-------------------------------------------+------------------+ | GVFMIN | annual minimum in vegetation fraction | | +-------------+-------------------------------------------+------------------+ | ISNOW | Number of snow layers | :math:`count` | +-------------+-------------------------------------------+------------------+ | LAI | leaf area index | | +-------------+-------------------------------------------+------------------+ | LFMASS | Leaf mass | :math:`g/m^2` | +-------------+-------------------------------------------+------------------+ | PEXPXY | (in the file but not used by the model) | | +-------------+-------------------------------------------+------------------+ | QRFSXY | Stem mass | :math:`g/m^2` | +-------------+-------------------------------------------+------------------+ | QRFXY | (in the file but not used by the model) | | +-------------+-------------------------------------------+------------------+ | QSFC | bulk surface specific humidity | | +-------------+-------------------------------------------+------------------+ | QSLATXY | Stable carbon in deep soil | :math:`g/m^2` | +-------------+-------------------------------------------+------------------+ | QSNOW | snowfall rate on the ground | :math:`mm/s` | +-------------+-------------------------------------------+------------------+ | QSPRINGSXY | Mass of wood and woody roots | :math:`g/m^2` | +-------------+-------------------------------------------+------------------+ | QSPRINGXY | (in the file by not used by the model) | | +-------------+-------------------------------------------+------------------+ | RECHXY | recharge to the water table (diagnostic) | :math:`m^3/m^3` | +-------------+-------------------------------------------+------------------+ | RIVERBEDXY | (in the file but not used by the model) | | +-------------+-------------------------------------------+------------------+ | RIVERCONDXY | (in the file but not used by the model) | | +-------------+-------------------------------------------+------------------+ | RTMASS | mass of fine roots | :math:`g/m^2` | +-------------+-------------------------------------------+------------------+ | SAI | stem area index | | +-------------+-------------------------------------------+------------------+ | SFCRUNOFF | Accumulatetd surface runoff | :math:`mm` | +-------------+-------------------------------------------+------------------+ | SH2O | volumetric liquid soil moisture | :math:`m^3/m^3` | +-------------+-------------------------------------------+------------------+ | SMC | Volumetric Soil Moisture | :math:`m^3/m^3` | +-------------+-------------------------------------------+------------------+ | SMCWTDXY | soil moisture below the bottom of the | :math:`m^3/m^3` | | | column | | +-------------+-------------------------------------------+------------------+ | SMOISEQ | volumetric soil moisture | :math:`m^3/m^3` | +-------------+-------------------------------------------+------------------+ | SNEQV | Snow water equivalent | :math:`kg/m^2` | +-------------+-------------------------------------------+------------------+ | SNEQVO | snow mass at last time step | :math:`mm` | +-------------+-------------------------------------------+------------------+ | SNICE | snow layer ice | :math:`mm` | +-------------+-------------------------------------------+------------------+ | SNLIQ | Snow layer liquid water | :math:`mm` | +-------------+-------------------------------------------+------------------+ | SNOWH | Snow depth | :math:`m` | +-------------+-------------------------------------------+------------------+ | SNOW_T | snow temperature | :math:`K` | +-------------+-------------------------------------------+------------------+ | SOIL_T | Soil Temperature on NSOIL layers | :math:`K` | +-------------+-------------------------------------------+------------------+ | STBLCP | Stable carbon in deep soil | :math:`g/m^2` | +-------------+-------------------------------------------+------------------+ | STMASS | stem mass | :math:`g/m^2` | +-------------+-------------------------------------------+------------------+ | TAH | Canopy Air Temperature | :math:`K` | +-------------+-------------------------------------------+------------------+ | TAUSS | snow age factor | | +-------------+-------------------------------------------+------------------+ | TG | Ground Temperature | :math:`K` | +-------------+-------------------------------------------+------------------+ | TV | Canopy Temperature | :math:`K` | +-------------+-------------------------------------------+------------------+ | UDRUNOFF | Accumulated underground runoff" | :math:`mm` | +-------------+-------------------------------------------+------------------+ | WA | Water in aquifer relative to reference | :math:`kg/m^2` | | | level | | +-------------+-------------------------------------------+------------------+ | WOOD | Mass of wood and woody roots | :math:`g/m^2` | +-------------+-------------------------------------------+------------------+ | WSLAKE | lake water storage | :math:`mm` | +-------------+-------------------------------------------+------------------+ | WT | Water in aquifer and saturated soil | :math:`kg/m^2` | +-------------+-------------------------------------------+------------------+ | ZSNSO | Snow layer depths from snow surface | :math:`m` | +-------------+-------------------------------------------+------------------+ | ZWT | water table depth | :math:`m` | +-------------+-------------------------------------------+------------------+ | VEGFRA | Vegetation fraction | | +-------------+-------------------------------------------+------------------+ .. _section-a15.2: A15.2 HYDRO_RST File Variable Table ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: The variables are written to the `HYDRO\_RST` file in the subroutine of ``RESTART_OUT_nc`` in the :file:`Routing/module_HYDRO_io.F90`. The tables below contain all the information on the dimensions and variables in the Hydro RESTART file (`HYDRO\_RST`). .. table:: :width: 90% :align: center +---------------+-----------------------------+---------------------------+ | **Dimension** | **Description** | **It is written** | +===============+=============================+===========================+ | depth | Number of soil layers | | +---------------+-----------------------------+---------------------------+ | ix | Number of columns in the | | | | coarse grid (LSM) | | +---------------+-----------------------------+---------------------------+ | iy | Number of rows in the | | | | coarse grid (LSM) | | +---------------+-----------------------------+---------------------------+ | ixrt | Number of columns in the | | | | fine grid (hydro) | | +---------------+-----------------------------+---------------------------+ | iyrt | Number of rows in the fine | | | | grid (hydro) | | +---------------+-----------------------------+---------------------------+ | links | Number of links/reaches | | +---------------+-----------------------------+---------------------------+ | basns | Number of basins for the | Only if ``GWBASESWCRT=1`` | | | groundwater/baseflow | in the `hydro.namelist` | | | modeling | | +---------------+-----------------------------+---------------------------+ | lakes | Number of lakes | Only if the lake | | | | routing is turned on | +---------------+-----------------------------+---------------------------+ .. table:: :width: 90% :align: center +--------------+-------------------------------+----------------+----------------+-----------------+ | **Variable | **Description** | **# Dimensions | **Resolution** | **Units** | | name** | | (not | | | | | | including | | | | | | time)** | | | +==============+===============================+================+================+=================+ | cvol | volume of stream in cell | 1 | fine/link | :math:`m^3` | +--------------+-------------------------------+----------------+----------------+-----------------+ | hlink | stream stage | 1 | fine/link | :math:`m` | +--------------+-------------------------------+----------------+----------------+-----------------+ | infxsrt | infiltration excess water | 2 | coarse | :math:`mm` | +--------------+-------------------------------+----------------+----------------+-----------------+ | infxswgt | weights for disaggregation of | 2 | fine | \- | | | infxsrt | | | | +--------------+-------------------------------+----------------+----------------+-----------------+ | qbdryrt | accumulated value of the | 2 | fine | :math:`mm` | | | boundary flux | | | | +--------------+-------------------------------+----------------+----------------+-----------------+ | qlink1 | stream flow in to cell/reach | 1 | fine/link | :math:`m^3/s` | +--------------+-------------------------------+----------------+----------------+-----------------+ | qlink2 | stream flow out of cell/reach | 1 | fine/link | :math:`m^3/s` | +--------------+-------------------------------+----------------+----------------+-----------------+ | qstrmvolrt | Accumulated depth of stream | 2 | fine | :math:`mm` | | | channel inflow | | | | +--------------+-------------------------------+----------------+----------------+-----------------+ | sfcheadrt | surface head on the coarse | 2 | coarse | :math:`mm` | | | grid | | | | +--------------+-------------------------------+----------------+----------------+-----------------+ | sfcheadsubrt | surface head on the routing | 2 | fine | :math:`mm` | | | grid | | | | +--------------+-------------------------------+----------------+----------------+-----------------+ | sh2owgt | weights for disaggregation of | 3 | fine | \- | | | total soil moisture (smc) | | | | +--------------+-------------------------------+----------------+----------------+-----------------+ | sh2ox | liquid soil moisture | 3 | coarse | :math:`m^3/m^3` | +--------------+-------------------------------+----------------+----------------+-----------------+ | smc | total liq+ice soil moisture. | 3 | coarse | :math:`m^3/m^3` | +--------------+-------------------------------+----------------+----------------+-----------------+ | soldrain | soil drainage | 2 | coarse | :math:`mm` | +--------------+-------------------------------+----------------+----------------+-----------------+ | stc | soil temperature | 3 | coarse | :math:`K` | +--------------+-------------------------------+----------------+----------------+-----------------+ | lake_inflort | lake inflow | 2 | fine | :math:`mm` | +--------------+-------------------------------+----------------+----------------+-----------------+ | resht | water surface elevation | 1 | link | :math:`m` | +--------------+-------------------------------+----------------+----------------+-----------------+ | qlakeo | outflow from lake used in | 1 | link | :math:`m^3/s` | | | diffusion scheme | | | | +--------------+-------------------------------+----------------+----------------+-----------------+ | qlakei | lake inflow | numLakes | link | :math:`m^3/s` | +--------------+-------------------------------+----------------+----------------+-----------------+ | z_gwsubbas | depth in ground water bucket | 1 | link | :math:`m` | +--------------+-------------------------------+----------------+----------------+-----------------+ .. _section-a16: A16. Streamflow Nudging ----------------------- Below is an example netCDF header nudging time slice observation file containing 2 gages. The command :program:`ncdump -h` was used to produce this header information. :: netcdf 2013-06-01_21:45:00.15min.usgsTimeSlice { dimensions: stationIdStrLen = 15 ; stationIdInd = UNLIMITED ; // (2 currently) timeStrLen = 19 ; variables: char stationId(stationIdInd, stationIdStrLen) ; stationId:long_name = "USGS station identifier of length 15" ; char time(stationIdInd, timeStrLen) ; time:units = "UTC" ; time:long_name = "YYYY-MM-DD_HH:mm:ss UTC" ; float discharge(stationIdInd) ; discharge:units = "m^3/s" ; discharge:long_name = "Discharge.cubic_meters_per_second" ; short discharge_quality(stationIdInd) ; discharge_quality:units = "-" ; discharge_quality:long_name = "Discharge quality 0 to 100 to be scaled by 100." ; float queryTime(stationIdInd) ; queryTime:units = "seconds since 1970-01-01 00:00:00 local TZ" ; // global attributes: :fileUpdateTimeUTC = "2017-08-25_17:24:22" ; :sliceCenterTimeUTC = "2013-06-01_21:45:00" ; :sliceTimeResolutionMinutes = "15" ; } Below is an example `nudgingParams.nc` file containing parameters for 3 gages. The command :program:`ncdump -h` was used to create this header information. :: netcdf nudgingParams { dimensions: stationIdInd = UNLIMITED ; // (3 currently) monthInd = 12 ; threshCatInd = 2 ; threshInd = 1 ; stationIdStrLen = 15 ; variables: float G(stationIdInd) ; G:units = "-" ; G:long_name = "Amplitude of nudging" ; float R(stationIdInd) ; R:units = "meters" ; R:long_name = "Radius of influence in meters" ; float expCoeff(stationIdInd, monthInd, threshCatInd) ; expCoeff:units = "minutes" ; expCoeff:long_name = "Coefficient b in denominator e^(-dt/b)" ; float qThresh(stationIdInd, monthInd, threshInd) ; qThresh:units = "m^3/s" ; qThresh:long_name = "Discharge threshold category" ; char stationId(stationIdInd, stationIdStrLen) ; stationId:units = "-" ; stationId:long_name = "USGS station identifer" ; float tau(stationIdInd) ; tau:units = "minutes" ; tau:long_name = "Time tapering parameter half window size in minutes" ; } .. _section-a17: A17. National Water Model (NWM) Configuration --------------------------------------------- The community WRF-Hydro modeling system is currently the underlying modeling architecture for the NOAA National Water Model. This means that the community WRF-Hydro model code is configurable into the National Water Model configurations that run in operations at the National Center for Environmental Prediction (NCEP). .. pull-quote:: “\ *The NWM is an hourly cycling uncoupled analysis and forecast system that provides streamflow for 2.7 million river reaches and other hydrologic information on 1km and 250m grids. The model provides complementary hydrologic guidance at current NWS River Forecast Center (RFC) river forecast locations and significantly expanded guidance coverage and type in underserved locations.* *The NWM ingests forcing from a variety of sources including Multi-Radar Multi-Sensor (MRMS) radar-gauge observed precipitation data and High-Resolution Rapid Refresh (HRRR), Rapid Refresh (RAP), Global Forecast System (GFS) and Climate Forecast System (CFS) Numerical Weather Prediction (NWP) forecast data. USGS real-time streamflow observations are assimilated and all NWM configurations benefit from the inclusion of ~5500 reservoirs. The core of the NWM system is the National Center for Atmospheric Research (NCAR)-supported community Weather Research and Forecasting (WRF)-Hydro hydrologic model. WRF-Hydro is configured to use the Noah Multi-Parameterization (Noah-MP) Land Surface Model (LSM) to simulate land surface processes. Separate water routing modules perform diffusive wave surface routing and saturated subsurface flow routing on a 250m grid, and Muskingum-Cunge channel routing down NHDPlusV2 stream reaches. River analyses and forecasts are provided across a domain encompassing the continental U.S. and hydrologically-contributing areas, while land surface output is available on a larger domain that extends beyond the continental U.S. into Canada and Mexico (roughly from latitude 19N to 58N). In addition, NWM forcing datasets are provided on this domain at a resolution of 1km.*\ ” .. centered:: *Excerpt from NOUS41 KWBC 061735 PNSWSH NWS Office of Science and Technology Integration* Newer versions of the National Water Model were extended to Hawaii, Puerto Rico and the U.S. Virgin Islands, and South-Central Alaska. A17.1 Operational NWM ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For more information regarding the operational configuration, input, and output data of the National Water Model see the Office of Water Prediction website: http://water.noaa.gov/about/nwm and the Open Commons Consortium Environmental Data Commons website: http://edc.occ-data.org/nwm/. There are different NWM configurations that run operationally. The full list of the configurations and their specifics can be found at - https://water.noaa.gov/about/nwm The latest NWM configuration and files can be found on the NOAA NCEP site: - https://www.nco.ncep.noaa.gov/pmb/codes/nwprod/ (scroll to the nwm.vX folder) Namelists for different operational configurations can be found on the NOAA NCEP site, for example: - NWMv3.0 CONUS Analysis & Assimilation cycle: https://www.nco.ncep.noaa.gov/pmb/codes/nwprod/nwm.v3.0.12/parm/analysis_assim/ - NWMv3.0 South-Central Alaska Medium-Range Forecast cycle: https://www.nco.ncep.noaa.gov/pmb/codes/nwprod/nwm.v3.0.12/parm/ak_medium_range/ - NWMv3.0 Hawaii Short-Range Forecast cycle: https://www.nco.ncep.noaa.gov/pmb/codes/nwprod/nwm.v3.0.12/parm/hi_short_range/ - NWMv3.0 Puerto Rico & U.S. Virgin Islands Short-Range Forecast cycle: https://www.nco.ncep.noaa.gov/pmb/codes/nwprod/nwm.v3.0.12/parm/pr_short_range/ An archive of National Water Model operational outputs can be found on Google Cloud: - https://console.cloud.google.com/storage/browser/national-water-model/ A17.2 NWM Retrospectives ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In addition to the operational model outputs, we also produce long-term (20-40 year) retrospectives for most versions of the National Water Model. The National Water Model Retrospectives can be found on AWS and Google Cloud: - https://registry.opendata.aws/nwm-archive/ - https://console.cloud.google.com/storage/browser/national-water-model-v3-0 .. _section-a18: A18. The Crocus Glacier Model ----------------------------- Crocus is an energy and mass transfer snowpack model, initially developed for avalanche forecasting (*Brun et al., 1989, 1992*). The version that was implemented into the French SURFEX model V8.0 (*Vionnet et al., 2012*) is being used here. This version has several updates from older versions of Crocus, such as the impacts of wind drift. The Crocus snowpack model is a multilayered, physically based snow model that explicitly calculates snow grain properties in each snow layer and how these properties change over time. The grain properties of dendricity, sphericity and size are prognosed in Crocus through metamorphism, compaction and impacts of wind drift. Furthermore, the snow albedo is calculated based on the snow grain properties from the top 3cm of the snowpack (*Vionnet et al., 2012*) and is calculated in three spectral bands (0.3-0.8, 0.8-1.5 and 1.5-2.5 `\mu m`). Impurities in aging snow are parameterized in the UV and visible spectral band (0.3-0.8 `\mu m`) from the age of the snow, with a time constant of 60 days. See *Vionnet et al. (2012)* for a detailed description of the albedo calculations. The albedo over ice is constant in all spectral bands and is 0.38, 0.23 and 0.08 for the spectral bands 0.3-0.8, 0.8-1.5 and 1.5-2.5 `\mu m`. The sensible and latent heat are parameterized with an effective roughness length over snow and ice (see *Vionnet et al. (2012)* for further details). In the Crocus model, it is possible to divide the snow into a user-defined maximum numbers of dynamically evolving layers. As new snow is accumulated, a new active layer is added. As different snow layers become similar (based upon the number of user-set layers, the thickness of the snow layers and the snow grain characteristics), these snow layers will merge into single snow layers. The Crocus module is added to the Noah-MP land surface model in WRF-Hydro to act as a glacier mass balance model (*Eidhammer et al. 2021*). Over designated glacier grid points, the Crocus snow model represents both snow and ice, while outside of the designated glacier grid points, the regular three-layer snow model in Noah-MP is used. Since the current Crocus implementation in WRF-Hydro only acts over designated glacier grid points, we follow *Gerbaux et al. (2005)* and assume that the temperatures at the bottom of the glacier and the ground below are both at `0^\circ C`. Note that we have not yet incorporated fluxes between the glacier and the ground below; thus, there is a constant temperature boundary condition. Both Crocus and Noah-MP (for the non-glacier grid points) output runoff from snowmelt (and precipitation). This runoff is provided to the terrain routing models in WRF-Hydro. Note that the implementation of Crocus as a glacier mass balance model does not address glacier movement (i.e., plastic flow) nor lateral wind (re)distribution of snow. However, there are two options for including impacts on the snow due to wind. One of the options impacts the snow density during blowing snow events (*Brun et al., 1997*). This option is important in polar environments (*Brun et al., 1997*). The other option is the sublimation due to snow drift, which was implemented by *Vionnet et al. (2012)* and which is in the Crocus version that is used in this study. As implemented, if the glacier completely melts over a user-defined glacier grid point, the original Noah-MP module is used from this point on. Therefore, as currently implemented, the glacier cannot grow horizontally in extent; it can only decrease in extent, as no dynamic response of the ice mass is included in the model. Over short model time periods, the lack of increase in glacier extent might impact a few grid points at the edges of the glacier. However, given the expected increase in temperature in the future, we do not expect that limiting glacier horizontal growth will have a major impact over most studied glaciers as most are likely to decrease in mass and extent. .. rubric:: Running WRF-Hydro / Glacier Below is a description on how to run with Crocus as a glacier model. There are only a few namelist options that needs to be added in :file:`namelist.hrldas`: .. code-block:: fortran &CROCUS_nlist crocus_opt = 1 ! 0 model is off, 1 model is on act_lev = 40 ! 1-50, 20-40 normal options / The initialization file wrfinput needs two additional fields to be defined: | ``glacier`` | ``glacier_thickness`` The field ``glacier`` should have the value of 1 over glacier gridpoints. The ``glacier`` field can be provided by the user, or the user can use the glacier category from ``IVGTYP``. Here is an example how to generate initial glacier fields for an “ideal” simulation, with homogeneous glacier thickness layer. In this case, ``IVGTYP=24`` represents glaciers: .. code-block:: bash ncap2 -O -s 'glacier=IVGTYP' wrfinput.nc wrfinput.nc ncap2 -O -s 'where(glacier!=24) glacier=0' wrfinput.nc wrfinput.nc ncap2 -O -s 'where(glacier==24) glacier=1' wrfinput.nc wrfinput.nc To create a 300 m thick glacier: .. code-block:: bash ncap2 -O -s 'glacier_thickness=glacier*300' wrfinput.nc wrfinput.nc At initialization, it is assumed that the glacier consists of only ice, and the density is that of pure ice (`900 \frac{kg}{m^3}`). Within the user-defined maximum layers (``act_lev``) the glacier is initialized with all the layers having the same assumed density and snow grain properties. As new snow accumulates during the simulations, the layers representing the glacier will start to merge since all layers contain the initialized ice. .. rubric:: Crocus outputs .. table:: :width: 90% :align: center :name: table-a16 +--------------+-----------+----------------------------------------------+--------------------+ | | Dimension | Explanation | Units | +==============+===========+==============================================+====================+ | PSNOWSWE | 3D | Snow water equivalent | `kg/m^2` | +--------------+-----------+----------------------------------------------+--------------------+ | PSNOWTEMP | 3D | Glacier temperature | `K` | +--------------+-----------+----------------------------------------------+--------------------+ | PSNOWALB | 2D | Albedo | `-` | +--------------+-----------+----------------------------------------------+--------------------+ | PSNOWTHRUFAL | 2D | Accumulated surface runoff | `kg/m^2` | +--------------+-----------+----------------------------------------------+--------------------+ | PSNOWHEIGHT | 2D | Total glacier thickness | `m` | +--------------+-----------+----------------------------------------------+--------------------+ | PSNOWTOTSWE | 2D | Total glacier snow water equivalent | `kg/m^2` | +--------------+-----------+----------------------------------------------+--------------------+ | PSNOWGRAN1 | 3D | Snow grain parameter 1 | `-` | +--------------+-----------+----------------------------------------------+--------------------+ | PSNOWGRAN2 | 3D | Snow grain parameter 2 | `-` | +--------------+-----------+----------------------------------------------+--------------------+ | PSNOWDZ | 3D | Thickness of snow/ice layers | `m` | +--------------+-----------+----------------------------------------------+--------------------+ | PSNOWHIST | 3D | Snow grain historical parameter | `-` | +--------------+-----------+----------------------------------------------+--------------------+ | PSNOWLIQ | 3D | Liquid content | `kg/m^2` | +--------------+-----------+----------------------------------------------+--------------------+ | PSNOWRHO | 3D | Snow/ice density | `kg/m^3` | +--------------+-----------+----------------------------------------------+--------------------+ | FLOW_ICE | 2D | Accumulated surface runoff from ice surface | `kg/m^2` (or `mm`) | +--------------+-----------+----------------------------------------------+--------------------+ | FLOW_SNOW | 2D | Accumulated surface runoff from snow surface | `kg/m^2` (or `mm`) | +--------------+-----------+----------------------------------------------+--------------------+ .. note:: Note on other WRF-Hydro outputs: The following outputs are informed from both Noah-MP and Crocus. Over glacier gridpoints, the outputs are informed from Crocus: ``ACCET``, ``ALBEDO``, ``SNOWEQV``, ``SNOWH`` and ``ACSNOWM``. Currently there are no namelist options to change parameter values. Several important parameters that can be modified can be found in: :file:`src/Land_models/NoahMP/phys/surfex/modd_snow_par.F90` Surface runoff is assigned to ``FLOW_ICE`` when the top active layer at the specific grid point has a density of 850 kg/m3, while surface runoff is assigned to ``FLOW_SNOW`` when the top active layer has a density equal to or less than 850 kg/m3. The sum of ``FLOW_ICE`` and ``FLOW_SNOW`` is equal to ``PSNOWTHRUFAL``. Note that runoff from precipitation is included in surface runoff, thus ``FLOW_SNOW`` and ``FLOW_ICE`` cannot be used directly as indication if melt is from the ice part of the glacier or snow part of the glacier. .. _section-a19: A19. Model Output Variables --------------------------------------------- A19.1. Land surface model output variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :file:`{YYYYMMDDHHMM}.LDASOUT_DOMAIN{X}` .. csv-table:: LDASOUT :file: output-tables/LDASOUT_DOMAIN.csv :header-rows: 1 A19.2. Land surface diagnostic output variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :file:`{YYYYMMDDHHMM}.LSMOUT_DOMAIN{X}` .. csv-table:: LSMOUT :file: output-tables/LSMOUT.csv :header-rows: 1 A19.3. Streamflow output variables at all channel reaches/cells ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :file:`{YYYYMMDDHHMM}.CHRTOUT_DOMAIN{X}` .. csv-table:: CHRTOUT :file: output-tables/CHRTOUT_DOMAIN.csv :header-rows: 1 A19.4. Streamflow output variables at forecast points or gage reaches/cells ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :file:`{YYYYMMDDHHMM}.CHANOBS_DOMAIN{X}` .. csv-table:: CHANOBS_DOMAIN :file: output-tables/CHANOBS_DOMAIN.csv :header-rows: 1 A19.5. Streamflow output variables on the 2D high resolution routing grid ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :file:`{YYYYMMDDHHMM}.CHRTOUT_GRID{X}` .. csv-table:: CHRTOUT_GRID :file: output-tables/CHRTOUT_GRID.csv :header-rows: 1 A19.6. Terrain routing variables on the 2D high resolution routing grid ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :file:`{YYYYMMDDHHMM}.RTOUT_DOMAIN{X}` .. csv-table:: RTOUT :file: output-tables/RTOUT_DOMAIN.csv :header-rows: 1 A19.7. Lake output variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :file:`{YYYYMMDDHHMM}.LAKEOUT_DOMAIN{X}` .. csv-table:: LAKEOUT :file: output-tables/LAKEOUT_DOMAIN.csv :header-rows: 1 A19.8. Ground water output variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :file:`{YYYYMMDDHHMM}.GWOUT_DOMAIN{X}` .. csv-table:: GWOUT :file: output-tables/GWOUT_DOMAIN.csv :header-rows: 1 ================================================ FILE: docs/userguide/conf.py ================================================ project = 'WRF-Hydro Modeling System' author = 'WRF-Hydro Team' copyright = '2024, '+author version = 'v5.4.0' release = '5.4.0' try: import sphinx_rtd_theme extensions = [ 'sphinx_rtd_theme', ] # html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] html_theme = 'sphinx_rtd_theme' html_theme_options = { 'navigation_depth': -1 } except: print("Warning: sphinx_rtd_theme not installed, using default theme") pass html_static_path = ['_static'] html_css_files = ['ug_theme.css'] numfig_secnum_depth = 2 #these are enforced by rstdoc, but keep them for sphinx-build numfig = 0 smartquotes = 0 source_suffix = '.rest' templates_path = [] language = 'en' highlight_language = "none" default_role = 'math' pygments_style = 'sphinx' exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] master_doc = 'index' ================================================ FILE: docs/userguide/index.rest ================================================ .. vim: syntax=rst .. include:: meta.rest .. image:: media/wrfhydro-banner.png :align: center ========================================================= The NCAR WRF-Hydro® Modeling System Technical Description ========================================================= .. rst-class:: center | Version |version_long| | | Originally Created: | April 14, 2013 | | Updated: | January 17, 2025 Until further notice, please cite the WRF-Hydro® modeling system as follows: Gochis, D.J., M. Barlage, R. Cabell, M. Casali, E. Dougherty, A. Dugger, T. Eidhammer, T. Enzminger, K. FitzGerald, F. Felfelani, A. Gaydos, L. Karsten, A. Mazrooei, M. McAllister, J. McCreight, A. McCluskey, N. Omani, A. RafieeiNasab, S. Rasmussen, L. Read, K. Sampson, I. Srivastava, D. Yates, W. Yu, and Y. Zhang (2025). *The WRF-Hydro® Modeling System Technical Description,* (Version 5.4). doi:`10.5281/zenodo.15040873` NCAR Technical Note. Available online at: https://wrf-hydro.readthedocs.io/en/latest/ .. rubric:: Links: - `Project Website `_ - `GitHub Repository `_ .. rubric:: FORWARD This Technical Description describes the WRF-Hydro® model coupling architecture and physics options, released in Version 5.4 in January 2025. As the WRF-Hydro® modeling system is developed further, this document will be continuously enhanced and updated. Please send feedback to wrfhydro@ucar.edu. .. rubric:: Prepared by: David Gochis, Michael Barlage, Ryan Cabell, Matt Casali, Erin Dougherty, Aubrey Dugger, Trude Eidhammer, Tom Enzminger, Katelyn FitzGerald, Farshid Felfelani, Andy Gaydos, Amir Mazrooei, Molly McAllister, James McCreight, Alyssa McCluskey, Nina Omani, Arezoo RafieeiNasab, Soren Rasmussen, Laura Read, Kevin Sampson, Ishita Srivastava, David Yates, and Yongxin Zhang .. rubric:: Special Acknowledgments: Development of the NCAR WRF-Hydro system has been significantly enhanced through numerous collaborations. The following persons are graciously thanked for their contributions to this effort: - John McHenry and Carlie Coats, Baron Advanced Meteorological Services - Martyn Clark, Fei Chen, Cenlin He, Prasanth Valayamkunnath, Dan Rosen, Rocky Dunlap, Alessandro Fanfarillo, National Center for Atmospheric Research - Zong-Liang Yang, Cedric David, Peirong Lin and David Maidment of the University of Texas at Austin - Harald Kunstmann, Benjamin Fersch and Thomas Rummler of Karlsruhe Institute of Technology, Garmisch-Partenkirchen, Germany - Alfonso Senatore, University of Calabria, Cosenza, Italy - Brian Cosgrove, Ed Clark, Fernando Salas, Trey Flowers, Zhengtao Cui, Xia Feng, Nels Frazier, James Halgren, Don Johnson, Yuqiong Liu, Dave Mattern, Fred Ogden, Cham Phan, Mehdi Rezaeianzadeh, and Tom Graziano of the National Oceanic and Atmospheric Administration Office of Water Prediction - Ismail Yucel, Middle East Technical University, Ankara, Turkey - Erick Fredj, The Jerusalem College of Technology, Jerusalem, Israel - Amir Givati, Surface water and Hydrometeorology Department, Israeli Hydrological Service, Jerusalem. - Antonio Parodi, Fondazione CIMA - Centro Internazionale in Monitoraggio Ambientale, Savona, Italy - Blair Greimann, Sedimentation and Hydraulics section, U.S. Bureau of Reclamation - Z George Xue and Dongxiao Yin, Louisiana State University - Tim Lahmers and Sujay Kumar, NASA Goddard Space Flight Center Funding support for the development and application of the WRF-Hydro® modeling system has been provided by: - The National Science Foundation National Center for Atmospheric Research - The U.S. National Weather Service - The Colorado Water Conservation Board - Baron Advanced Meteorological Services - National Aeronautics and Space Administration (NASA) - National Oceanic and Atmospheric Administration (NOAA) Office of Water Prediction (OWP) - U.S. Geological Survey (USGS) Water Mission Area .. toctree:: :hidden: Preface / Acknowledgements introduction model-code-config model-physics nudging model-inputs-preproc model-outputs references appendices ================================================ FILE: docs/userguide/input-tables/Fulldom_hires.tsv ================================================ VariableName Dimensions Description Units Notes TOPOGRAPHY Routing grid Terrain grid or Digital Elevation Model (DEM). m FLOWDIRECTION Routing grid Flow direction grid, which explicitly defines flow directions along the channel network in gridded routing. This variable dictates where water flows into channels from the land surface as well as in the channel. categorical FLOWACC Routing grid Number of upstream cells that drain into each cell. count CHANNELGRID Routing grid Channel network grid identifying the location of stream channel grid cells (-9999=no channel, -1=deactivated channel, 0=active channel) categorical STREAMORDER Routing grid Strahler stream order grid identifying the stream order for all channel pixels within the channel network. categorical LKSATFAC Routing grid Multiplier on saturated hydraulic conductivity in lateral flow direction. dimensionless RETDEPRTFAC Routing grid Multiplier on maximum retention depth before flow is routed as overland flow. dimensionless OVROUGHRTFAC Routing grid Multiplier on Manning's roughness for overland flow. dimensionless frxst_pts Routing grid Prescribed forecast points index basn_msk Routing grid Prescribed basin masks index LAKEGRID Routing grid Prescribed lakes index landuse Routing grid Land use from geogrid regridded to the high-res routing grid categorical ================================================ FILE: docs/userguide/input-tables/geo_em.tsv ================================================ VariableName Dimensions Description Units Notes LU_INDEX LSM grid Land cover type Categorical Hydro routing code uses this variable to define land cover type. The classification scheme is determined by the global attribute MMINLU and ISURBAN, ISWATER, and ISOILWATER are used to define special types. See MPTABLE.TBL for NoahMP-supported land cover classification schemes. SCT_DOM LSM grid Dominant top layer soil texture class Categorical Hydro routing code uses this variable to define soil type (texture class). Currently there is only one texture class defined per cell (not variable with depth). See SOILPARM.TBL for the supported texture classes. HGT_M LSM grid Elevation m Not used by the model but useful for reference. ================================================ FILE: docs/userguide/input-tables/wrfinput.tsv ================================================ VariableName Dimensions Description Units Notes SMOIS LSM grid, soil layers Initial volumetric soil moisture content m3/m3 TSLB LSM grid, soil layers Initial soil temperature K SNOW LSM grid Initial snow water equivalent mm (kg/m2) CANWAT LSM grid Initial canopy water storage mm (kg/m2) TSK LSM grid Initial surface temperature K Used to initialize model temperatures other than soil, e.g., canopy leaf and air temperature LAI LSM grid Initial leaf area index m2/m2 Only used by certain NoahMP settings IVGTYP LSM grid Land cover type Categorical LSM uses this variable to define land cover type. The classification scheme is determined by the global attribute MMINLU and ISURBAN, ISWATER, and ISICE are used to define special types. See MPTABLE.TBL for NoahMP-supported land cover classification schemes. ISLTYP LSM grid Soil texture class Categorical LSM uses this variable to define soil type (texture class). Currently there is only one texture class defined per cell (not variable with depth). See SOILPARM.TBL for the supported texture classes. TMN LSM grid Constant deep ­soil temperature K Used as fixed lower boundary temperature for TBOT_OPTION=2 SHDMAX LSM grid Maximum annual vegetation fraction % (0-100) Only used by certain NoahMP settings SHDMIN LSM grid Minimum annual vegetation fraction % (0-100) Only used by certain NoahMP settings SEAICE LSM grid Presence of sea ice fraction Set to 0; if >0, model will skip execution XLAND LSM grid Land/water mask (1=land, 2=water) categorical Set to 1 for land points; if =2, model will skip execution HGT LSM grid Elevation m Not used by the model but useful for reference. ================================================ FILE: docs/userguide/introduction.rest ================================================ .. vim: syntax=rst .. include:: meta.rest 1. Introduction =============== The purpose of this technical note is to describe the physical parameterizations, numerical implementation, coding conventions and software architecture for the NCAR Weather Research and Forecasting model (WRF) hydrological modeling system, hereafter referred to as WRF-Hydro. The system is intended to be flexible and extensible and users are encouraged to develop, add and improve components to meet their application needs. It is critical to understand that like the WRF atmospheric modeling system, the WRF-Hydro modeling system is not a singular 'model' per se but instead it is a modeling architecture that facilitates coupling of multiple alternative hydrological process representations. There are numerous (over 100) different configuration permutations possible in WRF-Hydro Version |version_short|. Users need to become familiar with the concepts behind the processes within the various model options in order to optimally tailor the system for their particular research and application activities. 1.1 Brief History ----------------- The WRF-Hydro modeling system provides a means to couple hydrological model components to atmospheric models and other Earth System modeling architectures. The system is intended to be extensible and is built upon a modular Modern Fortran architecture. The code has also been parallelized for distributed memory parallel computing applications. Numerous options for terrestrial hydrologic routing physics are contained within Version |version_short| of WRF-Hydro but users are encouraged to add additional components to meet their research and application needs. The initial version of WRF-Hydro (originally called 'Noah-distributed' in 2003) included a distributed, 3-dimensional, variably-saturated surface and subsurface flow model previously referred to as 'Noah-distributed' for the underlying land surface model upon which the original code was based. Initially, the implementation of terrain routing and, subsequently, channel and reservoir routing functions into the 1-dimensional Noah land surface model was motivated by the need to account for increased complexity in land surface states and fluxes and to provide physically-consistent land surface flux and stream channel discharge information for hydrometeorological applications. The original implementation of the surface overland flow and subsurface saturated flow modules into the Noah land surface model are described by Gochis and Chen (2003). In that work, a simple subgrid disaggregation-aggregation procedure was employed as a means of mapping land surface hydrological conditions from a “coarsely” resolved land surface model grid to a much more finely resolved terrain routing grid capable of adequately resolving the dominant local landscape gradient features responsible for the gravitational redistribution of terrestrial moisture. Since then numerous improvements to the Noah-distributed model have occurred including optional selection for 2-dimensional (in `x` and `y`) or 1-dimensional (“steepest descent” or so-called “D8” methodologies) terrain routing, a 1-dimensional, grid-based, hydraulic routing model, a reservoir routing model, 2 reach-based hydrologic channel routing models, and a simple empirical baseflow estimation routine. In 2004, the entire modeling system, then referred to as the NCAR WRF-Hydro hydrological modeling extension package was coupled to the Weather Research and Forecasting (WRF) mesoscale meteorological model (*Skamarock et al., 2005*) thereby permitting a physics-based, fully coupled land surface hydrology-regional atmospheric modeling capability for use in hydrometeorological and hydroclimatological research and applications. The code has since been fully parallelized for high-performance computing applications. During late 2011 and 2012, the WRF-Hydro code underwent a major reconfiguration of its coding structures to facilitate greater and easier extensibility and upgradability with respect to the WRF model, other hydrological modeling components, and other Earth system modeling frameworks. Additional changes to the directory structure occurred during 2014-2015 to accommodate the coupling with the new Noah-MP land modeling system. Between 2015-2018, new capabilities were added to permit more generalized, user-defined mapping onto irregular objects, such as catchments or hydrologic response units. During 2018-2022, some of the modules underwent a code refactoring and automated testing capabilities were added. In 2024, the directory structure was again updated for consistency with modern software design practices and this user guide was ported to an interactive online format. As additional changes and enhancements to WRF-Hydro occur they will be documented in future versions of this document. 1.2 Model Description ------------------------ WRF-Hydro has been developed to facilitate improved representations of terrestrial hydrologic processes related to the spatial redistribution of surface, subsurface and channel waters across the land surface and to facilitate coupling of hydrologic models with atmospheric models. Switch-activated modules in WRF-Hydro enable treatment of terrestrial hydrological physics, which have either been created or have been adapted from existing distributed hydrological models. The conceptual architecture for WRF-Hydro is shown in Figures 1.1 and 1.2 where WRF-Hydro exists as a coupling architecture (blue box) or “middle-ware” layer between weather and climate models and terrestrial hydrologic models and land data assimilation systems. WRF-Hydro can also operate in a standalone mode as a traditional land surface hydrologic modeling system. .. _figure-1.1: .. figure:: media/conceptual_diagram_wrfhydro.png :align: center :scale: 80% **Figure 1.1.** Generalized conceptual schematic of the WRF-Hydro architecture showing various categories of model components. .. figure:: media/coupling_schematic.png :align: center :scale: 80% **Figure 1.2.** Model schematic illustrating where many existing atmosphere, land surface and hydrological model components *could* fit into the WRF-Hydro architecture. NOTE: Not all of these models are currently coupled into WRF-Hydro at this time. This schematic is meant to be illustrative. Components which are coupled have an asterisk (\*) by their name. WRF-Hydro is designed to enable improved simulation of land surface hydrology and energy states and fluxes at a fairly high spatial resolution (typically 1 km or less) using a variety of physics-based and conceptual approaches. As such, it is intended to be used as either a land surface model in both standalone (“uncoupled” or “offline”) mode and fully-coupled (to an atmospheric model) mode. Both time-evolving “forcing” and static input datasets are required for model operation. The exact specification of both forcing and static data depends greatly on the selection of model physics and component options to be used. The principal model physics options in WRF-Hydro include: - 1-dimensional (vertical) land surface parameterization - surface overland flow - saturated subsurface flow - channel routing - reservoir routing - conceptual/empirical baseflow Both the Noah land surface and Noah-MP land surface model options are available for use in the current version of the WRF-Hydro. The rest of this document will focus on their implementation. Future versions will include other land surface model options. Like nearly all current land surface models, the Noah and Noah-MP land surface parameterizations require a few basic meteorological forcing variables. Required meteorological forcing variables are listed in Table 1.1. .. table:: **Table 1.1** Required input meteorological forcing variables for the Noah and Noah-MP LSMs :width: 90% :align: center +----------------------------------------+-----------+ | **Variable** | **Units** | +========================================+===========+ | Incoming shortwave radiation | `W/m^2` | +----------------------------------------+-----------+ | Incoming longwave radiation | `W/m^2` | +----------------------------------------+-----------+ | Specific humidity | `kg/kg` | +----------------------------------------+-----------+ | Air temperature | `K` | +----------------------------------------+-----------+ | Surface pressure | `Pa` | +----------------------------------------+-----------+ | Near surface wind in the u - component | `m/s` | +----------------------------------------+-----------+ | Near surface wind in the v-component | `m/s` | +----------------------------------------+-----------+ | Liquid water precipitation rate | `mm/s` | +----------------------------------------+-----------+ *[Different land surface models may require other or additional forcing variables or the specification of forcing variables in different units.]* When coupled to the WRF regional atmospheric model the meteorological forcing data is provided by the atmospheric model with a frequency dictated by the land surface model time-step specified in WRF. When run in a standalone mode, meteorological forcing data must be provided as gridded input time series. Further details on the preparation of forcing data for standalone WRF-Hydro execution is provided in :ref:`section-5.7` External, third party, Geographic Information System (GIS) tools are used to delineate a stream channel network, open water (i.e., lake, reservoir, and ocean) grid cells and groundwater/baseflow basins. Water features are mapped onto the high-resolution terrain-routing grid and post-hoc consistency checks are performed to ensure consistency between the coarse-resolution Noah/Noah-MP land model grid and the fine-resolution terrain and channel routing grid. The WRF-Hydro model components calculate fluxes of energy and moisture either back to the atmosphere or also, in the case of moisture fluxes, to stream and river channels and through reservoirs. Depending on the physics options selected, the primary output variables include but are not limited to those in the table below. Output variables and options are discussed in detail in :ref:`section-6.0` .. table:: **Table 1.2** Primary Output data from WRF-Hydro :width: 90% :align: center +-----------------------------------------------------------+------------+ | **Variable** | **Units** | +===========================================================+============+ | Surface latent heat flux | `W/m^2` | +-----------------------------------------------------------+------------+ | Surface sensible heat flux | `W/m^2` | +-----------------------------------------------------------+------------+ | Ground heat flux | `W/m^2` | +-----------------------------------------------------------+------------+ | Ground surface and/or canopy skin temperature | `K` | +-----------------------------------------------------------+------------+ | Surface evaporation components (soil evaporation, | `kg/m^2/s` | | transpiration, canopy water evaporation, snow sublimation | | | and ponded water evaporation) | | +-----------------------------------------------------------+------------+ | Soil moisture | `m^3/m^3` | +-----------------------------------------------------------+------------+ | Soil temperature | `K` | +-----------------------------------------------------------+------------+ | Deep soil drainage | `mm` | +-----------------------------------------------------------+------------+ | Surface runoff | `mm` | +-----------------------------------------------------------+------------+ | Canopy moisture content | `mm` | +-----------------------------------------------------------+------------+ | Snow depth | `m` | +-----------------------------------------------------------+------------+ | Snow liquid water equivalent | `mm` | +-----------------------------------------------------------+------------+ | Stream channel inflow (optional with terrain routing) | `mm` | +-----------------------------------------------------------+------------+ | Channel flow rate (optional with channel routing) | `m^3/s` | +-----------------------------------------------------------+------------+ | Channel flow depth (optional with channel routing) | `mm` | +-----------------------------------------------------------+------------+ | Reservoir height and discharge (optional with channel and | `m` and | | reservoir routing) | `m^3/s` | +-----------------------------------------------------------+------------+ WRF-Hydro has been developed for Linux-based operating systems including small local clusters and high-performance computing systems. Additionally, the model code has also been ported to a selection of virtual machine environments (e.g. "containers") to enable the use of small domain cases on many common desktop computing platforms (e.g. Windows and MacOS) and in the cloud. The parallel computing schema is provided in :ref:`section-2.3`. WRF-Hydro utilizes a combination of netCDF and flat ASCII file formats. The majority of input and output is handled using the netCDF data format and the netCDF library is a requirement for running the model. Details on the software requirements are available online on the FAQs page of the website as well as in the *How To Build & Run WRF-Hydro V5 in Standalone Mode* document also available from https://ral.ucar.edu/projects/wrf_hydro. WRF-Hydro is typically set up as a computationally-intensive modeling system. Simple small domains (e.g. 16 `km^2`) can be configured to run on a desktop platform. Large-domain model runs can require hundreds or thousands of processors. We recommend beginning with an example “test case” we supply at the WRF-Hydro website https://ral.ucar.edu/projects/wrf_hydro before moving to your region of interest, particularly if your region or domain is reasonably large. ================================================ FILE: docs/userguide/meta.rest ================================================ .. |version_short| replace:: 5.4 .. |version_long| replace:: 5.4.0 .. role:: center :class: center .. role:: underline :class: underline .. role:: file :class: filename .. role:: program :class: program .. role:: output :class: filename ================================================ FILE: docs/userguide/model-code-config.rest ================================================ .. vim: syntax=rst .. include:: meta.rest 2. Model Code and Configuration Description =========================================== This chapter presents the technical description of the WRF-Hydro model code. The chapter is divided into the following sections: 2.1 Brief Code Overview ----------------------- WRF-Hydro is written in a modularized, modern Fortran coding structure whose routing physics modules are switch-activated through a model namelist file called :ref:`hydro.namelist `. The code has been parallelized for execution on high-performance, parallel computing architectures including Linux operating system commodity clusters and multi-processor desktops as well as multiple supercomputers. More detailed model requirements depend on the choice of model driver, described in the next section. 2.2 Driver Level Description ---------------------------- WRF-Hydro is essentially a group of modules and functions which handle the communication of information between atmosphere components (such as WRF, CESM or prescribed meteorological analyses) and sets of land surface hydrology components. From a coding perspective the WRF-hydro system can be called from an existing architecture such as the WRF model, the CESM, NASA LIS, etc. or can run in a standalone mode with its own driver which has adapted part of the NCAR High Resolution Land Data Assimilation System (HRLDAS). Each new coupling effort requires some basic modifications to a general set of functions to manage the coupling. In WRF-Hydro, each new system that WRF-Hydro is coupled into gets assigned to a directory indicating the name of the coupling component WRF-Hydro is coupled to. For instance, the code which handles the coupling to the WRF model is contained in the :file:`WRF_cpl/` directory in the WRF-Hydro system. Similarly, the code which handles the coupling to the offline Noah land surface modeling system is contained within the :file:`Noah_cpl/` directory and so on. Description of each directory is provided in :ref:`section-2.4`. The coupling structure is illustrated here, briefly, in terms of the coupling of WRF-Hydro into the WRF model. A similar approach is used for coupling the WRF-Hydro extension package into other modeling systems or for coupling other modeling systems into WRF-Hydro. *Example:* For coupled WRF/WRF-Hydro runs the WRF-Hydro components are compiled as a single library function call with the WRF system. As such, a single executable is created upon compilation (:program:`wrf`). As illustrated in :ref:`Figure 2.1 `, WRF-hydro is called directly from WRF in the WRF surface driver module (:file:`phys/module_surface_driver.F90`). The code that manages the communication is the :file:`WRF_drv_Hydro.F90` interface module that is contained within the :file:`WRF_cpl/` directory. The :file:`WRF_drv_Hydro.F90` interface module is the specific instance of a 'General WRF-Hydro Coupling Interface' for the WRF model which passes data, grid and time information between WRF and WRF-Hydro. Components within WRF-Hydro then manage the dynamic regridding “data mapping” and sub-component routing functions (e.g. surface, subsurface and/or channel routing) within WRF-Hydro (see :ref:`Fig. 1.1 ` for an illustration of components contained within WRF-Hydro). Upon completion of the user-specified routing functions, WRF-Hydro will remap the data back to the WRF model grid and then pass the necessary variables back to the WRF model through the :file:`WRF_drv_Hydro.F90` interface module. Therefore, the key component of the WRF-Hydro system is the proper construction of the :file:`WRF_cpl_Hydro` interface module (or more generally :file:`{XXX}_cpl_Hydro`). Users wishing to couple new modules to WRF-Hydro will need to create a unique “General WRF-Hydro Coupling Interface” for their components. Some additional examples of this interface module are available upon request for users to build new coupling components. This simple coupling interface is similar in structure to other general model coupling interfaces such as those within the Earth System Modeling Framework (ESMF) or the Community Surface Dynamics Modeling System (CSDMS). .. _figure2.1: .. figure:: media/wrf_coupling.png :align: center **Figure 2.1** Schematic illustrating the coupling and calling structure of WRF-Hydro from the WRF Model. The model code has been compiled using the Intel :program:`ifort` compiler and the freely-available GNU Fortran compiler :program:`gfortran` for use with Unix-type operating systems on desktops, clusters, and supercomputing systems. Because the WRF-Hydro modeling system relies on netCDF input and output file conventions, netCDF Fortran libraries must be installed and properly compiled on the system upon which WRF-Hydro is to be executed. Not doing so will result in numerous error messages such as :code:`*…undefined reference to netCDF library …*` or similar messages upon compilation. For further installation requirements see the FAQs page of the website as well asin the *How To Build & Run WRF-Hydro v5 in Standalone Mode* document also available from https://ral.ucar.edu/projects/wrf_hydro. .. _section-2.3: 2.3 Parallelization strategy ---------------------------- Parallelization of the WRF-Hydro code utilizes geographic domain decomposition and 'halo' array passing structures similar to those used in the WRF atmospheric model (:ref:`Figures 2.2 ` and :ref:`2.3 `). Message passing between processors is accomplished using MPI protocols. Therefore the relevant MPI libraries must be installed and properly compiled on the system upon which WRF-Hydro is to be executed in parallel mode. Currently sequential compile is not supported so MPI libraries are required even if running over a single core. .. figure:: media/gridded_decomp.png :align: center :name: figure2.2 **Figure 2.2** Schematic of parallel domain decomposition scheme in WRF-Hydro. Boundary or 'halo' arrays in which memory is shared between processors (P1 and P2) are shaded in purple. .. figure:: media/channel_decomp.png :align: center :name: figure2.3 **Figure 2.3** Schematic of parallel domain decomposition scheme in WRF-Hydro as applied to channel routing. Channel elements (stars) are communicated at boundaries via ‘halo’ arrays in which memory is shared between processors (P1 and P2). Black and red stars indicate overlapping channel elements used in the diffusive wave solver. .. _section-2.4: 2.4 Directory Structures ------------------------ The top-level directory structure of the code is provided below as nested under the :file:`wrf_hydro_nwm_public` root directory and the subdirectory structures are described thereafter. The tables below provide brief descriptions of the file contents of each directory where the model code resides. .. default-role:: file .. table:: **Table 2.1** Description of the file contents of each directory where the model *code* resides :align: center :width: 90% :name: table-2.1 +-------------------------+--------------------------------------------------+ | **File/directory name** | **Description** | | | | +=========================+==================================================+ | Main code files and directories (under version control in | | a GitHub repository): | +-------------------------+--------------------------------------------------+ | :underline:`Top-Level Files and Directories:` | +-------------------------+--------------------------------------------------+ | `CMakeLists.txt` | Top-level CMake build script used to compile | | | the WRF-Hydro model | +-------------------------+--------------------------------------------------+ | `docs/` | Pointer to location of full documentation (i.e. | | | this document). | +-------------------------+--------------------------------------------------+ | `tests/` | Scripts and data used to test the model | +-------------------------+--------------------------------------------------+ | `src/` | WRF-Hydro Model source code | +-------------------------+--------------------------------------------------+ | :underline:`Source code directories under \`src/\`:` | +-------------------------+--------------------------------------------------+ | `CPL/Noah_cpl/` | Contains the WRF-Hydro coupling interface for | | | coupling WRF-Hydro components with the | | | standalone (offline) Noah land surface model | | | data assimilation and forecasting system | +-------------------------+--------------------------------------------------+ | `CPL/NoahMP_cpl/` | Contains the WRF-Hydro coupling interface for | | | coupling WRF-Hydro components with the | | | standalone (offline) Noah-MP land surface model | | | data assimilation and forecasting system | +-------------------------+--------------------------------------------------+ | `CPL/WRF_cpl/` | Contains the WRF-Hydro coupling interface for | | | coupling WRF-Hydro components with the WRF | | | system | +-------------------------+--------------------------------------------------+ | `CPL/CLM_cpl/` , | Work in progress for ongoing coupling work. | | `CPL/LIS_cpl/` , | Only NUOPC is actively supported. | | `CPL/NUOPC_cpl/` | | +-------------------------+--------------------------------------------------+ | `Data_Rec/` | Contains some data declaration modules | +-------------------------+--------------------------------------------------+ | `Debug_Utilities/` | Utilities for debugging | +-------------------------+--------------------------------------------------+ | `deprecated/` | Contains files not currently used | +-------------------------+--------------------------------------------------+ | `HYDRO_drv/` | Contains the high-level WRF-Hydro component | | | driver: `module_HYDRO_drv.F90` | +-------------------------+--------------------------------------------------+ | `Land_models/Noah/` | Contains the Noah land surface model driver for | | | standalone or uncoupled applications | +-------------------------+--------------------------------------------------+ | `Land_models/NoahMP/` | Contains the Noah-MP land surface model driver | | | for standalone or uncoupled applications | +-------------------------+--------------------------------------------------+ | `MPP/` | Contains MPI parallelization routines and | | | functions | +-------------------------+--------------------------------------------------+ | `nudging/` | Contains nudging data assimilation routines and | | | functions | +-------------------------+--------------------------------------------------+ | `Rapid_routing/` | Contains the files necessary for RAPID routing | | | model coupling. Unsupported as version of RAPID | | | is out of date. | +-------------------------+--------------------------------------------------+ | `Routing/` | Contains modules and drivers related to specific | | | routing processes in WRF-Hydro | +-------------------------+--------------------------------------------------+ | `template/` | Contains example namelist files for Noah, | | | Noah-MP and the WRF-Hydro modules (HYDRO). | | | Default and example parameter tables are also | | | included for HYDRO. Note: Parameter tables for | | | Noah and Noah-MP are stored within the | | | :file:`Land_models` directory. | +-------------------------+--------------------------------------------------+ | `utils/` | internal model versioning | +-------------------------+--------------------------------------------------+ | :underline:`Files:` | +-------------------------+--------------------------------------------------+ | `docs/BUILD.md` | WRF-Hydro build instructions for the standalone | | | model | +-------------------------+--------------------------------------------------+ | `wrf_hydro_config` | Configure script for coupled WRF \| WRF-Hydro | | | configuration | +-------------------------+--------------------------------------------------+ | `\*.json` | JSON files used for testing | +-------------------------+--------------------------------------------------+ | Local files and directories created by CMake in the build directory | | (not part of the version controlled repository): | +-------------------------+--------------------------------------------------+ | :underline:`Directories:` | +-------------------------+--------------------------------------------------+ | `lib/` | Directory where compiled libraries are written | +-------------------------+--------------------------------------------------+ | `mods/` | Directory where compiled `.mod`` files are | | | written upon compilation | +-------------------------+--------------------------------------------------+ | `Run/` | Directory where model executable, example | | | parameter tables, and example namelist files | | | for the compiled model configuration will be | | | populated. These files will be overwritten on | | | compile. It is recommended the user copy the | | | contents of this directory into an alternate | | | location, separate from the code, to execute | | | model runs. | +-------------------------+--------------------------------------------------+ .. table:: **Table 2.2** Modules within the :file:`Routing/` directory which relate to routing processes in WRF-Hydro :width: 90% :align: center :name: table-2.2 +--------------------------------------+-------------------------------------------------+ | **File/directory name** | **Description** | | | | +======================================+=================================================+ | `Overland/` | Directory containing overland routing modules | +--------------------------------------+-------------------------------------------------+ | `Makefile` | Makefile for WRF-Hydro component | +--------------------------------------+-------------------------------------------------+ | `module_channel_routing.F90` | Module containing WRF-Hydro channel routing | | | components | +--------------------------------------+-------------------------------------------------+ | `module_date_utilities_rt.F90` | Module containing various date/time utilities | | | for routing routines | +--------------------------------------+-------------------------------------------------+ | `module_GW_baseflow.F90` | Module containing model physics for simple | | | baseflow model | +--------------------------------------+-------------------------------------------------+ | `module_HYDRO_io.F90` | Module containing WRF-Hydro input and (some) | | | output functions | +--------------------------------------+-------------------------------------------------+ | `module_HYDRO_utils.F90` | Module containing several WRF-Hydro utilities | | | | +--------------------------------------+-------------------------------------------------+ | `module_lsm_forcing.F90` | Module containing the options for reading in | | | different forcing data types | +--------------------------------------+-------------------------------------------------+ | `module_noah_chan_param_init_rt.F90` | Module containing routines to initialize | | | WRF-Hydro routing grids | +--------------------------------------+-------------------------------------------------+ | `module_NWM_io.F90` | Module containing output routines to produce | | | CF-compliant desired output files. | +--------------------------------------+-------------------------------------------------+ | `module_NWM_io_dict.F90` | Dictionary to support CF-compliant output | | | routines. | +--------------------------------------+-------------------------------------------------+ | `module_RT.F90` | Module containing the calls to all the | | | WRF-Hydro routing initialization | +--------------------------------------+-------------------------------------------------+ | `module_UDMAP.F90` | Module for the user-defined mapping | | | capabilities, currently used for NWM | | | configuration (NHDPlus network) | +--------------------------------------+-------------------------------------------------+ | `Noah_distr_routing.F90` | Module containing overland flow and subsurface | | | physics routines and grid disaggregation | | | routine | +--------------------------------------+-------------------------------------------------+ | `module_gw_gw2d.F90` | Module containing routines for the experimental | | | 2D groundwater model | +--------------------------------------+-------------------------------------------------+ .. default-role:: 2.5 Model Sequence of Operations -------------------------------- The basic structure and sequencing of WRF-Hydro are diagrammatically illustrated in :ref:`Figure 2.4 ` management, initialization, I/O and model completion) is handled by the WRF-Hydro system unless WRF-Hydro is coupled into, and beneath, a different modeling architecture. The WRF-Hydro system can either call an independent land model driver such as the NCAR High Resolution Land Data Assimilation System (HRLDAS) for both Noah and Noah-MP land surface models to execute column land surface physics or be called by a different modeling architecture such as WRF, the NCAR CESM, or the NASA LIS. When run in a standalone or “uncoupled” mode, WRF-Hydro must read in the meteorological forcing data necessary to perform land surfac model calculations and it contains the necessary routines to do this. When run in a coupled mode with WRF or another larger architecture, WRF-Hydro receives meteorological forcing or land surface states and fluxes from the parent architecture. The basic execution process is as follows: 1. Upon initialization static land surface physiographic data are read into the WRF-Hydro system and the model domain and computational arrays are established. 2. Depending on whether or not WRF-Hydro is run offline as a standalone system or whether it is coupled into another architecture, either forcing data is read in or land surface states and fluxes are passed in. 3. For offline simulations which require land model execution, the gridded column land surface model is executed. 4. If routing is activated and there is a difference between the land model grid and the routing grid, land surface states and fluxes are then disaggregated to the high-resolution terrain routing grids. 5. If activated, sub-surface routing physics are executed. 6. If activated, surface routing physics are executed. 7. If activated, the conceptual base flow model is executed. 8. If activated, channel and reservoir routing components are executed. Streamflow nudging is currently available to be applied within the Muskingum-Cunge routing call. 9. Updated land surface states and fluxes are then aggregated from the high-resolution terrain routing grid to the land surface model grid (if routing is activated and there is a difference between the land model grid and the routing grid). 10. Results from these integrations are then written to the model output files and restart files or, in the case of a coupled WRF/WRF-Hydro simulation, passed back to the WRF model. As illustrated at the bottom of the :ref:`Figure 2.4 ` component with `NCAR’s DART `__ (https://www.image.ucar.edu/DAReS/DART/) has been developed. This currently only works with WRF-Hydro in standalone mode. DART updates WRF-Hydro states independently of model time integration. .. _figure2.4: .. figure:: media/modular_calling.png :align: center **Figure 2.4** Modular calling structure of WRF-Hydro. 2.6 WRF-Hydro compile-time options ---------------------------------- Compile time options are choices about the model structure which are determined when the model is compiled. Compile time choices select a WRF-Hydro instance from some of the options illustrated in :ref:`Figure 2.4. ` Compile time options fall into two categories: 1) the selected model driver, and 2) the compile options for the choice of driver. In this guide we limit the description of model drivers to WRF, Noah, and Noah-MP. Configuring, compiling, and running WRF-Hydro in standalone mode is described in detail in the *How To Build & Run WRF-Hydro V5 in Standalone Mode* document available from https://ral.ucar.edu/projects/wrf_hydro. Compile-time options are listed during the CMake build configuration process. These options are passed to CMake as environment variables using ``-D[OPTION]=[0|1]`` syntax. Those options/variables are listed below along with a description of what each option does: .. parsed-literal:: =================================================================== -- Start of WRF-Hydro Env VARIABLES WRF_HYDRO = 1 *Always set to 1 for WRF-Hydro* HYDRO_D = 0 *Set to 1 for enhanced diagnostic output* SPATIAL_SOIL = 1 *Set to 1 to allow NoahMP LSM to use* *spatially distributed parameter* *vs. a table based on soil class and* *land use categories* WRFIO_NCD_LARGE_FILE_SUPPORT = 0 *Set to 1 if using a* *WRF/WRF-Hydro coupled build* NCEP_WCOSS = 0 *Set to 1 if compile for NOAA WCOSS* NWM_META = 0 *Set to 1 if using NWM-style metadata in output* WRF_HYDRO_NUDGING = 0 *Set to 1 if using streamflow nudging* PRECIP_DOUBLE = 0 *Set to 1 to double all incoming* *precipitation (for debug purposes only)* WRF_HYDRO_NUOPC = 0 *Set to 1 when using NUOPC coupling* =================================================================== .. _section-2.7: 2.7 WRF-Hydro run time options ------------------------------------ There are two namelist files that users must edit in order to successfully execute the WRF-Hydro system in a standalone mode or “uncoupled” to WRF. One of these namelist files is the hydro.namelist file and in it are the various settings for operating all of the routing components of the WRF-Hydro system. The hydro.namelist file is internally commented so that it should be clear as to what is needed for each setting. A full annotated example of the hydro.namelist file is provided in :ref:`section-a6`. The second namelist is the namelist which specifies the land surface model options to be used. This namelist can change depending on which land model is to be used in conjunction with the WRF-Hydro routing components. For example, a user would use one namelist when running the Noah land surface model coupled to WRF-Hydro but that user would need to use a different namelist file when running the CLM model, the Noah-MP model or NASA LIS model coupled to WRF-Hydro. The reason for this is WRF-Hydro is intended to be *minimally-invasive* to other land surface models or land model driver structures and not require significant changes to those systems. This minimal invasiveness facilitates easier coupling with new systems and helps facilitate easy supportability and version control with those systems. When the standalone WRF-Hydro model is compiled the appropriate namelist.hrldas template file is copied over to the Run directory based upon the specified land surface model. In WRF-Hydro v\ |version_short|, Noah and Noah-MP land surface models are the main land surface model options when WRF-Hydro is run in standalone mode. Both Noah and Noah-MP use a namelist file called namelist.hrldas, which, as noted above, will contain different settings for the two different land surface models. For a run where WRF-Hydro is coupled to the WRF model, the WRF model input file namelist.input becomes the second namelist file. Full annotated example namelist.hrldas files for Noah and Noah-MP are provided in :ref:`section-a4` and :ref:`section-a5`. .. _section-2.8: 2.8 Build Instructions ------------------------------------ .. include:: ../BUILD.rst :start-line: 2 ================================================ FILE: docs/userguide/model-inputs-preproc.rest ================================================ .. vim: syntax=rst .. include:: meta.rest 5. Model inputs and preprocessing ================================= This chapter describes WRF-Hydro input and parameter file requirements and the preprocessing tools used to generate them. 5.1 Overview of model inputs ---------------------------- .. _figure-5.1: .. figure:: media/physics-inputs.png :align: center :figwidth: 90% **Figure 5.1** WRF-Hydro input and parameter files organized by model physics component. See the Key for files specific to a certain land model or channel configuration. WRF-Hydro requires a number of input files describing the model domain, parameters, initial conditions, and when run in a standalone configuration meteorological forcing files. A full list of these files broken up by model physics component is shown in :ref:`Figure 5.1 `. Note that the set of files required to run WRF-Hydro varies depending upon model configuration. For example, different land surface models and model physics components may require different parameter and input files. While some parameter files and templates are included with the model source code, most must be generated by the user. We provide a number of scripts and preprocessing utilities on the WRF-Hydro website (https://ral.ucar.edu/projects/wrf_hydro/pre-processing-tools) in order to aid in this process. These include NCAR Command Language (NCL) scripts to regrid forcing data from commonly used data sources, R scripts to generate parameter and model initialization files, and a set of Python based ArcGIS pre-processing tools. The specific utilities used to generate different files are listed in :ref:`Table 5.1 `. Users should be aware that these tools do not support all potential datasets and use cases and that the use of default parameters will often result in suboptimal model performance. More details regarding the pre-processing utilities, file requirements, and descriptions follow. In addition to the ArcGIS pre-processing tools, the WRF-Hydro group has also developed a set of open-source, Python-based preprocessing tools. These tools replicate existing capabilities and operate within the same software environments as WRF-Hydro. Built with Python 3 and libraries such as Whitebox Tools, NumPy, and GDAL, users can configure their environments using Anaconda, Miniconda, or custom setups. This initiative responds to user demand for an open-source option, ensuring portability and multi-platform support while offering efficient, parallelized geoprocessing. All underlying libraries are open-source, eliminating proprietary licensing restrictions. For more information, please visit: https://ral.ucar.edu/dataset/open-source-wrf-hydro-gis-pre-processing-tools-beta. 5.2 Domain processing and description of surface physiographic input files -------------------------------------------------------------------------- This subsection describes the process of defining the WRF-Hydro model domain, generating model initial conditions, and deriving geospatial input and parameter files via the WRF-Hydro GIS pre-processing tools. As noted in the previous section a number of scripts and utilities have been developed to facilitate the creation of these files. Additionally, we rely on a utility within the Weather Research and Forecasting (WRF) model preprocessing system (WPS) called GEOGRID to define the land surface model grid and relevant geospatial data and produce the resulting :file:`geo_em.d0{x}.nc` file hereafter referred to as a “geogrid” file. This geogrid file is then used as input to the ArcGIS preprocessing tools, along with external datasets such as high resolution topographic data, which generate the high resolution routing grid and all surface physiographic input data files required by the model. The geogrid file is also passed to utilities in order to generate land surface model initial condition files. 5.2.1 Defining the model domain ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The data required to define the domain and geospatial attributes of a spatially-distributed, or gridded, 1-dimensional (vertical) land surface model (LSM) are specified in a geogrid (:file:`geo_em.d0{x}.nc`) netCDF file. This file is generated by the :program:`GEOGRID` utility in the `WRF preprocessing system (WPS) `_. WPS is a preprocessing system that prepares both land surface and atmospheric data for use in the model. The GEOGRID component of WPS automates the procedure of defining in space, georeferencing and attributing most of the land surface parameter data required to execute both the Noah and Noah-MP land surface models. GEOGRID interpolates land surface terrain, soils and vegetation data from standard, readily available data products. These data are distributed as a geographical input data package via the WRF website. Complete documentation and user instructions for use of the WPS system are provided online by NCAR and are updated regularly and, thus, are not discussed in great detail here. This :file:`geo_em.d0{x}.nc` file is also required as input to other WRF-Hydro preprocessing utilities. 5.2.2 Initial land surface conditions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Initial conditions for the land surface, such as soil moisture, soil temperature, and snow states, are prescribed via the :file:`wrfinput_d0x.nc` file. This netCDF file can be generated one of two ways, through the :program:`real.exe` program within WRF or via an R script (:file:`create_wrfinput.R`) distributed on the `WRF-Hydro website `_. When created using the real.exe program in WRF, initial conditions are pulled from existing reanalysis or realtime products (see WRF documentation for data and system requirements). This will typically result in more realistic initial model states. However, the process is somewhat involved and requires the user to obtain additional external datasets. The R script will create a simplified version of the :file:`wrfinput_d0x.nc` file including all necessary fields for the Noah-MP land surface model, but with spatially uniform initial conditions that are prescribed within the script and requires only the geogrid file :file:`geo_em.d0{x}.nc` as input. Step-wise instructions and detailed requirements are included in the documentation distributed with the script. Users should be aware that the model will likely require additional spin-up time when initialized from this file. 5.2.3 Generating hydrologic routing input files via the WRF-Hydro GIS pre-processing tools ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A suite of Python based utilities, the *WRF-Hydro GIS Pre-processing Toolkit*, have been developed to facilitate the process of deriving WRF-Hydro input and parameter files from commonly available geospatial data products, such as hydrologically processed digital elevation models. A large number of the hydro input and parameter files described in :ref:`Table 5.1 ` can be generated by these tools as well as a geospatial metadata file to support georeferencing of WRF-Hydro model output files and relevant shapefiles to aid in visualizing the model components. The WRF-Hydro GIS pre-processing tools are developed to function as an additional ArcToolbox within the Esri ArcGIS software. Specific operating system and software requirements are addressed in the full *WRF-Hydro GIS Pre-processing Toolkit* `documentation `_. The minimum input data requirements for the pre-processing tools are the geogrid file :file:`geo_em.d0x.nc` and a hydrologically conditioned digital elevation model covering the full extent of the domain of interest. From these datasets the terrain routing files (e.g. :file:`Fulldom_hires.nc`, :file:`hydro2dtbl.nc`) and channel routing files (e.g. :file:`Route_Link.nc`) can be created (see Appendices :ref:`A7 `, :ref:`A10 `, and :ref:`A11 `). A ``.txt`` or ``.csv`` file with stream gage locations can optionally be supplied, allowing the user to demarcate these locations in the model input files and optionally produce time series outputs (e.g. :file:`*CHANOBS_DOMAIN{x}`) for only these locations. This text file denoting the location of stream gages or "forecast points" can also be used to generate groundwater input files. Effectively groundwater basins are delineated above each of these locations and default parameters will be assigned to a parameter file that can also be generated using this tool. More details are available in the *WRF-Hydro GIS Pre-processing Toolkit* `documentation `_. Lake and reservoir component input files also require a supplementary input file. A shapefile containing polygons defining the extent of each lake must be provided as input. From this file and the processed digital elevation model a number of parameters are derived for each lake (however, note that other parameters are only assigned a global default value). More details about this process and the contents of the input and parameter files can be found in Appendix :ref:`A14 ` and the full *WRF-Hydro GIS Pre-processing Toolkit* `documentation `_. The *WRF-Hydro GIS Pre-processing Toolkit* will also produce a geospatial metadata file (e.g. :file:`GEOGRID_LDASOUT_Spatial_Metadata.nc`) for the land surface model grid (as defined by the geogrid file :file:`geo_em.d0{x}.nc`). This file contains projection and coordinate information for the land surface model grid. While this file is an optional input to WRF-Hydro, in combination with the new file output routines in version 5.0 of WRF-Hydro this file will allow for the creation of CF (Climate and Forecast metadata convention) compliant output files. This allows for files to be more easily viewed in GIS systems (e.g. ArcGIS and QGIS) as well as other visualization software. Additional documentation for this toolkit including step by step instructions and detailed requirements is provided on the WRF-Hydro website. Requirements for the hydro components of the model (i.e. those not directly associated with the land surface model or data assimilation) are described in the model physics :ref:`Section 3 ` and in :ref:`Table 5.1 `. .. table:: **Table 5.1** Input and parameter files for hydro components of WRF-Hydro. :width: 90% :align: center :name: table-5.1 +---------------------------+---------------------+----------------------------------+--------------+ | **Filename** | **Description** | **Source** | **Required** | +===========================+=====================+==================================+==============+ | :file:`Fulldom_hires.nc` | High resolution | WRF-Hydro GIS | Yes | | | full domain file. | pre-processing | | | | Includes all fields | toolkit | | | | specified on the | | | | | routing grid. | | | +---------------------------+---------------------+----------------------------------+--------------+ | :file:`Route_Link.nc` | Channel reach | WRF-Hydro GIS | When reach | | | parameters (ComID, | pre-processing | based | | | gage ID, bottom | toolkit | routing is | | | width, slope, | | used | | | roughness, order, | | (including | | | etc.) | | user defined | | | | | mapping) | +---------------------------+---------------------+----------------------------------+--------------+ | :file:`GWBASINS.nc` | 2D file defining | WRF-Hydro GIS | When the | | | the locations of | pre-processing | baseflow | | | groundwater basins | toolkit | bucket model | | | on a grid | | is turned on | | | | | and user | | | | | defined | | | | | mapping is | | | | | off | +---------------------------+---------------------+----------------------------------+--------------+ | :file:`GWBUCKPARM.nc` | Groundwater | WRF-Hydro GIS | When the | | | parameter table | pre-processing | baseflow | | | containing bucket | toolkit | bucket model | | | model parameters | | is turned on | | | for each basin | | | +---------------------------+---------------------+----------------------------------+--------------+ | :file:`LAKEPARM.nc` | Lake parameter | WRF-Hydro GIS | When lake | | | table containing | pre-processing | and | | | lake model | toolkit | reservoir | | | parameters for each | | routing is | | | catchment | | turned on | +---------------------------+---------------------+----------------------------------+--------------+ | :file:`hydro2dtbl.nc` | Spatially | :file:`create_SoilProperties.R` | When using | | | distributed netCDF | script | spatially | | | version of | | distributed | | | :file:`HYDRO.TBL` | (will also be automatically | terrain | | | | generated by WRF-Hydro) | routing | | | | | parameters | +---------------------------+---------------------+----------------------------------+--------------+ | :file:`HYDRO.TBL` | Parameter table for | :file:`template/HYDRO` | Yes | | | lateral flow | directory in the | | | | routing within | model code | | | | WRF-Hydro. In the | | | | | :file:`HYDRO.TBL` | | | | | file parameters are | | | | | specified by land | | | | | cover type or soil | | | | | category | | | +---------------------------+---------------------+----------------------------------+--------------+ | :file:`HYDRO_MODIS.TBL` | Version of | :file:`template/HYDRO` | Replacement | | | :file:`HYDRO.TBL` | directory in the | for | | | using MODIS land | model code | |HYDRO.TBL| | | | use categories | | when using | | | rather than USGS. | | MODIS land | | | (Change name to | | use | | | :file:`HYDRO.TBL` | | categories | | | for use.) | | | +---------------------------+---------------------+----------------------------------+--------------+ | :file:`CHANPARM.TBL` | Parameters for | :file:`template/HYDRO` | When gridded | | | gridded channel | directory in the | routing is | | | routing scheme. | model code | used | | | Parameters are | | | | | specified by | | | | | Strahler stream | | | | | order | | | +---------------------------+---------------------+----------------------------------+--------------+ | :file:`spatialweights.nc` | Spatial weight file | distributed with NWM domain | When using | | | used to map fluxes | files | user defined | | | to catchment | | mapping | | | objects | | | +---------------------------+---------------------+----------------------------------+--------------+ .. |HYDRO.TBL| replace:: :file:`HYDRO.TBL` .. _section-5.3: 5.3 Description of land surface model and lateral routing parameter files ------------------------------------------------------------------------- Parameters for the Noah and Noah-MP land surface models as well as for the lateral routing component are specified via a collection of text files (i.e. parameter tables) denoted by the file suffix ``.TBL``. Default parameter tables for the Noah and Noah-MP models are included in the WRF-Hydro source code within the directory structure for their respective land model and the appropriate files are automatically moved to the Run directory upon building the model. The Noah land surface model requires three parameter table files, outlined in :ref:`Table 5.2 `. The first of these is the general parameter table or :file:`GENPARM.TBL`. This file contains a number of global parameters for the Noah land surface model. The next is the vegetation parameter table or :file:`VEGPARM.TBL`. This file contains parameters that are a function of land cover type. The final table is the soil parameter table or :file:`SOILPARM.TBL`. This parameter table contains parameters that are assigned based upon the soil classification. The variables contained within these files are described in the Appendix :ref:`A8 `. .. table:: **Table 5.2** Parameter tables for the Noah land surface model. These parameter tables can be found within the land surface model source code :file:`Run/` directory and will be copied over the the WRF-Hydro Run directory when the compile script for this LSM is run. :align: center :width: 90% :name: table-5.2 .. default-role:: file +---------------+-------------------------------------------+----------------+ | **Filename** | **Description** | **Required** | +===============+===========================================+================+ | GENPARM.TBL | Miscellaneous model parameters that are | Yes | | | applied globally | | +---------------+-------------------------------------------+----------------+ | VEGPARM.TBL | Vegetation parameters indexed by land use | Yes | | | / land cover categories | | +---------------+-------------------------------------------+----------------+ | SOILPARM.TBL | Soil parameters indexed by soil texture | Yes | | | classes | | +---------------+-------------------------------------------+----------------+ .. default-role:: The Noah-MP land surface model also requires three parameter table files, outlined in :ref:`Table 5.3 `. The first of these is the general parameter table or :file:`GENPARM.TBL`. This file contains a number of global parameters for the Noah-MP land surface model. The next table is the :file:`MPTABLE.TBL`. This file contains parameters that are a function of land cover type. The last one is the soil parameter table or :file:`SOILPARM.TBL`. This parameter table contains parameters that are assigned based upon the soil classification. The variables contained within these files are described in Appendix :ref:`A9 `. As part of work conducted for the National Water Model implementation, the ability to specify a number of these land surface model parameters spatially on a two or three dimensional grid was introduced. This is done through the use of the compile time option ``SPATIAL_SOIL`` and the specification of a netCDF format parameter file with the default filename :file:`soil_properties.nc`. A list of the variables contained in this file is included in Appendix :ref:`A9 `. .. table:: **Table 5.3** Parameter tables for the Noah-MP land surface model. These parameter tables can be found within the land surface model source code Run directory and will be copied over to the WRF-Hydro Run directory when the compile script for this LSM is run. :name: table-5.3 :align: center :width: 90% .. default-role:: file +----------------------+---------------------------------------------+----------------+ | **Filename** | **Description** | **Required** | +======================+=============================================+================+ | `GENPARM.TBL` | Miscellaneous model parameters that are | Yes | | | applied globally | | +----------------------+---------------------------------------------+----------------+ | `MPTABLE.TBL` | Vegetation parameters indexed by land use / | Yes | | | land cover categories | | +----------------------+---------------------------------------------+----------------+ | `SOILPARM.TBL` | Soil parameters indexed by soil texture | Yes | | | classes | | +----------------------+---------------------------------------------+----------------+ | `soil_properties.nc` | NetCDF file with spatially distributed land | No | | | surface model parameters used when | | | | WRF-Hydro is compiled with SPATIAL_SOIL=1. | | | | This allows the user to specify parameters | | | | on the model grid rather than as a single | | | | value or function of soil or land cover | | | | type. | | | | | | | | This file is created by the | | | | :file:`create_SoilProperties.R` script | | +----------------------+---------------------------------------------+----------------+ .. default-role:: file Parameters for the lateral routing component of WRF-Hydro are specified in a similar way via the :file:`HYDRO.TBL` file or the :file:`hydro2dtbl.nc` file. This file is also distributed with the WRF-Hydro source code in the :file:`templates/HYDRO` directory and is copied over to the :file:`Run` directory upon building the model. There is also an additional :file:`HYDRO_MODIS.TBL` file for those using the MODIS land cover classification scheme. The :file:`HYDRO.TBL` parameter table file contains 2 parts. The first part contains the Manning's roughness coefficients for overland flow as a function of the USGS vegetation types as that data is used in the Noah land surface model. The roughness values are strictly indexed to the USGS vegetation classes so that if one wanted to use a different vegetation index dataset (e.g. the MODIS/IGBP option in the Noah land surface model) a user would need to remap these roughness values to those new vegetation indices. Users can alter the values of overland flow roughness here for a given vegetation type. However, users may also 'scale' these initial values of roughness by changing the gridded values of the overland flow roughness scaling factor (``OVROUGHRTFAC``) that are contained within the high resolution routing data netCDF file (e.g., :file:`Fulldom_hires{x}.nc`). Because hydrological models are often calibrated over a particular region or watershed as opposed to a specific vegetation type it is recommended that users modify the ``OVROUGHRTFAC`` scaling factor as opposed to altering the roughness values in :file:`HYDRO.TBL`. The second part of the :file:`HYDRO.TBL` parameter table contains several soil hydraulic parameters that are classified as functions of soil type. These soil parameters are copied from the :file:`SOILPARM.TBL` parameter table from the Noah land surface model. They are provided in :file:`HYDRO.TBL` to allow the user to modify those parameters as needed during model calibration activities without modifying the :file:`SOILPARM.TBL` file and thus is just done for convenience. In effect, when routing options in WRF-Hydro are activated the code will read the soil hydraulic parameters from :file:`HYDRO.TBL`. If the Noah land surface model is executed within WRF-Hydro without any of the routing options activated, the code will simply use the parameter values specified in :file:`HYDRO.TBL`. The file :file:`hydro2dtbl.nc` is a spatially distributed netCDF file version of the :file:`HYDRO.TBL` parameter table. This netCDF file can be created via the :file:`create_SoilProperties.R` script distributed on the WRF-Hydro website (https://ral.ucar.edu/projects/wrf_hydro) or will automatically be generated by the model from the :file:`HYDRO.TBL` if the filename specified in the :file:`hydro.namelist` does not already exist. See Appendix :ref:`A10 ` for further explanation of the variables in the :file:`HYDRO.TBL` and :file:`hydro2dtbl.nc` files. 5.3.1 Spatially distributed parameter files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ As of version 5.0 of WRF-Hydro we now allow for the specification of a number of spatially distributed land surface model and / or lateral routing parameters in netCDF input files :file:`soil_properties.nc` and :file:`hydro2dtbl.nc`. This option was implemented as part of work conducted for the National Water Model and allows the user to specify parameters on the model grid rather than as a single value or function of soil or land cover type. The files can be generated via an R script provided on our website (:file:`create_SoilProperties.R`) and are described in more detail in Appendices :ref:`A9 ` and :ref:`A10 `. In order for the model to read in the :file:`soil_properties.nc` file the ``SPATIAL_SOIL`` environment variable must be set to 1 at compile time. This option gives users more flexibility in the specification of land surface model parameters and is particularly useful in the context of calibration and parameter regionalization. .. _section-5.4: 5.4 Description of channel routing parameter files -------------------------------------------------- Channel parameters for WRF-Hydro are specified in one of two files. If the model is configured using gridded channel routing these parameters will be stored in :file:`CHANPARM.TBL`. If the model is configured using reach-based routing (including the NWM configuration) the parameters and channel geometry are specified within the :file:`Route_Link.nc` file generated by the *WRF-Hydro GIS Pre-processing Toolkit*. Variables of the :file:`CHANPARM.TBL` and :file:`Route_Link.nc` files are described in Appendix :ref:`A11 `. It is important to keep in mind that there is large uncertainty associated with these parameters. Therefore, model calibration is almost always warranted. Also, because fully-distributed estimates of flow depth (``HLINK`` in :file:`CHANPARM.TBL`) are not available for model initialization, it is almost always necessary to use a small initial value of ``HLINK`` and let the model come to its own equilibrium (i.e. “spin-up”) after several hours of integration. The necessary time required to spin up the channel network is a direct function of how dense and long your channel network is. Larger, more dense networks will take substantially longer to spin up. Estimates of total travel time from the furthest channel element to the basin outline are a reasonable initial approximation of the time it will take to spin up the channel elements. .. _section-5.5: 5.5 Description of groundwater input and parameter files -------------------------------------------------------- Depending upon the choice of channel configuration, groundwater input and parameter files are specified in slightly different ways. For the National Water Model (NWM) implementation of the model - where user defined mapping is active - the :file:`spatialweights.nc` file is used to map gridded fluxes to the appropriate catchments, the spatial unit of the NWM groundwater bucket model. In other configurations of the model where user defined mapping is not used, grid-based groundwater basins are defined in a :file:`GWBASINS.nc` netCDF file. The contents of these files are described in Appendix :ref:`A12 `. Groundwater bucket model parameters are assigned via the :file:`GWBUCKPARM.nc` file for all configurations. The contents of these files are also summarized in Appendix :ref:`A12 ` and like the groundwater basins files these files are produced by the *WRF-Hydro GIS Pre-processing Toolkit*. Note that global default parameters are prescribed when these files are generated so user adjustments and/or calibration are recommended. .. _section-5.6: 5.6 Description of lake and reservoir parameter tables ------------------------------------------------------ Lake parameter values are specified for each one of the lake objects. Typically, baseline parameters are derived within the high-resolution terrain preprocessing stages described above using tools such as ArcGIS (e.g. ``LkArea``, ``LkMxE`` in the file :file:`LAKEPARM.nc`). Values for the weir and orifice coefficients and sizes can be drawn from standard engineering hydraulics textbooks (e.g. *Chow et al., 1957*) and calibrated based on lake level performance. Weir parameters are specified for reservoir “overflow” or “spill” and orifice parameters are specified for design operations. The behavior of the reservoir to store and release water is highly dependent on these parameters and therefore it is highly recommended that the user modify this file with their own set of parameters beyond the default given in the *WRF-Hydro GIS Pre-processing Toolkit*. See Appendix :ref:`A14 ` for descriptions of the variables within the :file:`LAKEPARM.nc` file. .. _section-5.7: 5.7 Specification of meteorological forcing data ------------------------------------------------ Modern land surface hydrology models, including WRF-Hydro, require meteorological forcing data to simulate land-atmosphere exchanges and terrestrial hydrologic processes when uncoupled to atmospheric modeling systems. Most land models require a similar set of input variables with some variation in terms of the units, spectral bandwidths of radiation, handling of precipitation phase, etc. Most commonly these variables include: incoming short and longwave radiation, humidity, temperature, pressure, wind speed and precipitation rate and type. The required variables for the Noah and Noah-MP land surface models supported in version 5.x of WRF-Hydro are listed in :ref:`Table 5.4 `. These variables' names, units, and several of the forcing data file format options described below are borrowed from the High-Resolution Land Data Assimilation System (`HRLDAS `__), an offline driver for Noah land surface models. When WRF-Hydro is coupled into other modeling architectures such as the NASA Land Information System (LIS), these systems will set the requirements for the forcing data. .. table:: **Table 5.4** Input forcing data for the Noah and Noah-MP land surface models :width: 90% :align: center :name: table-5.4 +-----------------+------------------------------------+---------------+ | **Variable | **Description** | **Units** | | name** | | | +=================+====================================+===============+ | ``SWDOWN`` | Incoming shortwave radiation | `W/m^2` | +-----------------+------------------------------------+---------------+ | ``LWDOWN`` | Incoming longwave radiation | `W/m^2` | +-----------------+------------------------------------+---------------+ | ``Q2D`` | Specific humidity | `kg/kg` | +-----------------+------------------------------------+---------------+ | ``T2D`` | Air temperature | `K` | +-----------------+------------------------------------+---------------+ | ``PSFC`` | Surface pressure | `Pa` | +-----------------+------------------------------------+---------------+ | ``U2D`` | Near surface wind in the | `m/s` | | | `u`-component | | +-----------------+------------------------------------+---------------+ | ``V2D`` | Near surface wind in the | `m/s` | | | `v`-component | | +-----------------+------------------------------------+---------------+ | ``RAINRATE`` | Precipitation rate | `mm/s` *or* | | | | `kg/m^2` | +-----------------+------------------------------------+---------------+ | ``LQFRAC`` | Precipitation type | `unitless` | | (optional) | i.e., liquid water fraction (0-1) | | +-----------------+------------------------------------+---------------+ Here we simply describe the requirements and options that are available in the standalone version of WRF-Hydro. Presently, there are 9 forcing data input types in WRF-Hydro. Because it is untenable to support a large variety of input file formats and data types within the model, WRF-Hydro requires that most processing of forcing data be handled external to the model (i.e. as a “pre-process”) and that users put their forcing data into one of the required formats. This includes performing tasks like, gridding of station observations, making sure forcing data is gridded to match the domain grid and has the correct variable names and units (see :ref:`Table 5.4 `), reformatting data into the prescribed netCDF format, etc. Note that The WRF-Hydro code will not remap or spatially-subset the forcing data in any way. To facilitate these pre-processing activities we have developed `WRF-Hydro Forcing Engine `_ and numerous scripts which can be executed to help in the forcing data preparation process. These scripts along with sample data files are distributed on the WRF-Hydro website. The input forcing data type is specified in the land surface model namelist file :file:`namelist.hrldas` by modifying the ``FORC_TYP`` namelist option. Model forcing type namelist options are specified and described as follows, See Appendices :ref:`A4 ` and :ref:`A5 ` for more details. : # 1 = HRLDAS-hr format # 2 = HRLDAS-min format # 3 = WRF output # 4 = Idealized # 5 = Idealized with specified precipitation # 6 = HRLDAS-hr format with specified precipitation # 7 = WRF output with specified precipitation FORC_TYP = 1 .. rubric:: 1 - HRLDAS hourly format input files: This option requires meteorological forcing data to be provided in the HRLDAS hourly forcing data format. Scripts provided on the WRF-Hydro website will generate files in this format. Forcing files in this format can also be found in the example cases. In this format, gridded forcing data for all meteorological forcing variables with the names and units shown in :ref:`Table 5.4 ` are included in a single netCDF file for each time step. The forcing data grids must match the model grid specified in the :file:`geo_em.d0{x}.nc` “geogrid” file. Filenames must conform to the following convention: :file:`YYYYMMDDHH.LDASIN_DOMAIN{X}` .. rubric:: 2 - HRLDAS minute format input files: This option requires meteorological forcing data to be provided in the HRLDAS minute forcing data format. Like the HRLDAS hourly format, this standard is borrowed from the HRLDAS modeling system. However, this format allows for the specification of forcing data at more frequent time intervals (up to every minute as specified by the forcing time step in the :file:`namelist.hrldas` file). In this format, gridded forcing data for all meteorological forcing variables with the names and units shown in :ref:`Table 5.4 ` are included in a single netCDF file for each time step. The forcing data grids must match the model grid specified in the :file:`geo_em.d0{x}.nc` file. Filenames must conform to the following convention: :file:`YYYYMMDDHHmm.LDASIN_DOMAIN{X}` .. rubric:: 3 - WRF output files as input to WRF-Hydro: This option allows for meteorological forcing data to be read directly from a WRF model output file “wrfout” file so long as the WRF model grid is the same as that for WRF-Hydro. The WRF-Hydro code will not remap or spatially-subset the data in any way. All necessary fields are available in a default WRF output file but users should verify their existence if modifications have been made. These files must be written with only a single time step per file and retain the default filenames. The file naming convention for the wrfout file is :file:`wrfout_d0{x}_YYYY-MM-DD_HH:MM:SS`. .. rubric:: 4 - Idealized forcing: This option requires no input files. Instead a simple rainfall event is prescribed (i.e. “hardcoded”) in the model. This event is a spatially uniform 25.4 `mm/hr` (1 `in/hr`) for 1 hour duration over the first hour of the model simulation. The remainder of the forcing variables are set to have either constant values (in space and time) or, in the case of temperature and radiation variables, a fixed diurnal cycle (see :ref:`Table 5.5 `). This option is primarily used for simple testing of the model and is convenient for checking whether or not components besides the forcing data are properly being read into the model and working. Future versions of WRF-Hydro will allow the user to specify values for the precipitation event and the other meteorological variables. Note that this forcing type requires the user-specified ``FORCING_TIMESTEP`` namelist parameter to be set to 3600 (1 hr) in the :file:`namelist.hrldas` file. .. table:: **Table 5.5.** Description of idealized forcing :align: center :width: 90% :name: table-5.5 +--------------+--------------------------+------------------------------+ | **Variable | **Prescribed value or | **Timing** | | name** | range of values** | | +==============+==========================+==============================+ | ``SWDOWN`` | 0 - 900 [`W/m^2`] | Diurnal cycle | +--------------+--------------------------+------------------------------+ | ``LWDOWN`` | 375 - 425 | Diurnal cycle | | | [`W/m^2`] | | +--------------+--------------------------+------------------------------+ | ``Q2D`` | 0.01 [`kg/kg`] | Constant | +--------------+--------------------------+------------------------------+ | ``T2D`` | 287 - 293 [`K`] | Diurnal cycle | +--------------+--------------------------+------------------------------+ | ``PSFC`` | 100,000 [`Pa`] | Constant | +--------------+--------------------------+------------------------------+ | ``U2D`` | 1.0 [`m/s`] | Constant | +--------------+--------------------------+------------------------------+ | ``V2D`` | 1.0 [`m/s`] | Constant | +--------------+--------------------------+------------------------------+ | ``RAINRATE`` | 25.4 [`mm/s` or | For first hourly time step | | | `kg/m^2`] | and zero thereafter | +--------------+--------------------------+------------------------------+ .. rubric:: 5 - Idealized forcing with specified precipitation: This option is identical to forcing type 4 with the exception that the WRF-Hydro system will look for user provided supplementary precipitation files. These supplementary precipitation files are netCDF files containing a single gridded field with either the name ``precip`` and units of `mm` or ``precip_rate`` with unit a unit of `mm/s`. When using this forcing type, the WRF-Hydro system will look for a new precipitation input file based on the user-specified ``FORCING_TIMESTEP`` namelist option set in the :file:`namelist.hrldas` file. Scripts provided on the WRF-Hydro website will generate files in this format (specifically the MRMS regridding scripts). Forcing files in this format can also be found in the example test cases. Filenames for supplemental precipitation files must conform to this convention: :file:`{YYYYMMDDHHMM}.PRECIP_FORCING.nc`. .. rubric:: 6 - HRLDAS hourly format input files with specified precipitation: This option is identical to forcing type 1 with the exception that the WRF-Hydro system will also look for user provided supplementary precipitation files. These supplementary precipitation files are netCDF files containing a single gridded field with either the name ``precip`` and units of `mm` or ``precip_rate`` with unit a unit of `mm/s`. When using this forcing type, the WRF-Hydro system will look for a new precipitation input file based on the user-specified ``FORCING_TIMESTEP`` namelist option set in the :file:`namelist.hrldas` file. Scripts provided on the WRF-Hydro website will generate files in this format (specifically the MRMS regridding scripts). Forcing files in this format can also be found in the example test cases. Filenames for supplemental precipitation files must conform to this convention: :file:`{YYYYMMDDHHMM}.PRECIP_FORCING.nc`. This option is useful when combining atmospheric analyses from reanalysis products or other models with a separate analysis of precipitation (e.g. a gridded gauge product, radar QPE, nowcasts, satellite QPE, etc). The model reads in the meteorological forcing data fields on each hour and then holds those values constant for the entire hour. Precipitation can be read in more frequently based on the user-specified ``FORCING_TIMESTEP`` namelist parameter in the :file:`namelist.hrldas` file. For example, the user can have 'hourly' meteorology with '5-minute' precipitation analyses. .. rubric:: 7 - WRF output files as input to WRF-Hydro with specified precipitation: This option is identical to forcing type 3 with the exception that the WRF-Hydro system will also look for user provided supplementary precipitation files. These supplementary precipitation files are netCDF files containing a single gridded field with either the name ``precip`` and units of `mm` or ``precip_rate`` with unit a unit of `mm/s`. When using this forcing type, the WRF-Hydro system will look for a new precipitation input file based on the user-specified ``FORCING_TIMESTEP`` namelist option set in the :file:`namelist.hrldas` file. Scripts provided on the WRF-Hydro website will generate files in this format (e.g., MRMS regridding scripts). Forcing files in this format can also be found in the example test cases. Filenames for supplemental precipitation files must conform to this convention: :file:`{YYYYMMDDHHMM}.PRECIP_FORCING.nc`. This option is useful when combining forcing data from WRF with a separate analysis of precipitation (e.g. a gridded gauge product, radar QPE, nowcasts, satellite QPE, etc). The model reads in the meteorological forcing data fields from the WRF output file and then holds those values constant until the next file is available. Precipitation can be read in more frequently based on the user-specified ``FORCING_TIMESTEP`` namelist parameter in the :file:`namelist.hrldas` file. For example, the user can have 'hourly' meteorology with '5-minute' precipitation analyses. ================================================ FILE: docs/userguide/model-outputs.rest ================================================ .. vim: syntax=rst .. include:: meta.rest .. _section-6.0: 6. Description of Output Files from WRF-Hydro ============================================= This chapter describes the output files from Version 5.x of WRF-Hydro. The user has several options to allow flexibility when outputting from the WRF-Hydro modeling system. All of the options to control outputs are located in the hydro.namelist file that the user edits prior to running a simulation. Prior to turning specific file options on, there are a few high-level namelist options (flags) that help control the quantity of variables each file will produce, along with some flexibility on the level of compression files contain. .. rubric:: ``io_form_outputs``: This flag directs the output to utilize optional internal netCDF compression and the use of optional scale_factor/add_offset attributes to pack variables from floating point to integer. However, the user also has the flexibility to turn these optional features off. For additional information on these “packing” attributes, consult the netCDF documentation for a more in-depth explanation (http://www.unidata.ucar.edu/software/netcdf/docs/index.html). It should be noted that the use of internal compression adds time to output files being produced. This may become costly for large-scale modeling applications. Tests have indicated a cost of 15-25% additional time spent producing output variables when internal netCDF compression is utilized, depending on the number of output files being produced. However, without the use of compression, it is possible file sizes could become large depending on the application. It is also important to note that a value of ``0`` will result in the code deferring to old output routines used in version 3.0 of WRF-Hydro. For these outputs, the user is encouraged to read the documentation for that version of the code. The following values for the ``io_form_outputs`` option are available: ``0`` - Defer to old output routines for version 3.0 of WRF-Hydro (NOTE:this is the ONLY option that is supported when running with the Noah LSM) ``1`` - Utilize internal netCDF compression in conjunction with scale_factor/add_offset byte packing ``2`` - Utilize scale_factor/add_offset byte packing without internal netCDF compression ``3`` - Utilize internal netCDF compression without scale_factor/add_offset byte packing. ``4`` - No internal netCDF compression and no scale_factor/add_offset byte packing. .. rubric:: ``io_config_outputs``: This flag offers different sets of output variables for each file. This offers the user some flexibility to the number of output variables being produced. *NOTE*: This flag has no effect when ``io_form_outputs = 0``. .. rubric:: ``t0OutputFlag``: This flag controls if output files are produced on the initial timestep of the model simulation. It is important to note that some variables are initialized to missing values and may translate to missing values in the output files for the initial time step. However, these files may offer useful information to the user for diagnosing purposes. .. rubric:: ``output_channelBucket_influx``: This flag controls the creation of output variables specific to running a channel-only configuration of the model. These variables provide useful information on flow coming into channel links located in the simulation domain, which can be used for diagnosing purposes. *Note*: this value must be zero for running a gridded channel routing configuration of the model. An overview of available model output files is shown in :ref:`Figure 6.1 `. For a detailed table of each variable contained within each output file, see :ref:`A17 `. There is no optimal combination of namelist options to use for outputs. Flexibility was given to the user as end applications will vary from one user to another. While a combination of many output variables with compression may work for a one-time model simulation, having fewer variables with less time spent on compression may be more suitable for a user that is operations driven. Future code upgrades will allow further flexibility on the exact variables to output for each file. .. figure:: media/wrfhydro-outputs.png :name: figure-6.1 :figwidth: 90% :width: 90% :align: center **Figure 6.1** WRF-Hydro output files organized by model physics component. See the Key for files specific to a certain channel configuration. Please note a proper land spatial metadata file is highly encouraged when producing land surface output from the simulations. This file is specified by the ``LAND_SPATIAL_META_FLNM`` option in the hydro.namelist file. This file contains several geospatial variables and attributes which are translated to output files that meet CF compliance (http://cfconventions.org/). This file can be created using the *WRF-Hydro GIS Pre-processing Toolkit* associated with this release. For gridded output files, coordinate variable data and attributes are used from the spatial metadata file for the output variables. Additionally, geospatial attributes, which can help the user display data in GIS applications are located within the metadata file. These attributes translate to the output files during the output creation process. For the 2D high resolution routing output files (``RT_DOMAIN``, ``CHRTOUT_GRID``), geospatial attributes and coordinate variables are translated from the Fulldom_hires.nc file if they are detected. For point output files (``CHRTOUT_GRID``, ``CHANOBS_DOMAIN``, ``LAKEOUT_DOMAIN``), the geospatial attributes and coordinate variables have been hard-coded to be latitude and longitude for this version of the code. Each output file will potentially contain some set of attributes and variables that contain temporal and geospatial information useful to the user. Again, it is worth noting that the lack of a land spatial metadata file, or proper attributes in the :file:`Fulldom_hires.nc` file will result in a less comprehensive output file in terms of metadata. Each output file will contain a time dimension and variable that specifies the number of timesteps located in the output file, along with a numeric value for each timestep in the form of minutes since EPOCH. A ``reference_time`` dimension (usually 1 in dimension size) and variable exist. This variable will contain the model initialization in minutes since EPOCH. Gridded output files will contain an `x` and `y` coordinate dimension and variable that will contain the center-point coordinate values for either the routing grid, or land surface grid in the model projected space. For example, on a Lambert Conformal modeling domain, these values would be in meters. Gridded output files will also contain a ``CRS`` variable, which contains useful geospatial metadata attributes about the modeling domain. Output files for points, river channel links, or lakes will contain latitude, longitude, and elevation variables to offer metadata about each location in the output file. Additionally, output files at points will contain a feature_id variable that will list either a global ID value associated with that point, or a predefined ID value extracted from an input file. For example, with 2D gridded channel routing, each channel pixel cell has an ID value that ranges from `1-n` where `n` is the global number of channel pixel cells. However, with reach-based routing, each channel reach may have a predefined link ID value specified via the :file:`Route_Link.nc` file. All files contain ``model_initialization_time`` and ``model_output_valid_time`` character attributes to offer additional time information about the output file. For files that were produced with ``io_form_outputs`` options of ``1`` or ``2``, standard netCDF variable attributes ``scale_factor`` and ``add_offset`` are present to help users and netCDF APIs unpack integer data back to floating point for visualization and analysis. For a more in-depth description of netCDF CF compliant output, please visit http://cfconventions.org. Two output files that do not necessarily follow the above mentioned format will be the groundwater output (``GWOUT_DOMAIN``) file and :file:`frxst_pts_out.txt` text file. Groundwater output are representative of a spatial region, as opposed to points or fixed pixel cells. Future code upgrades will attempt to incorporate additional spatial information about groundwater buckets. The :file:`frxst_pts_out.txt` text file is a simple ASCII text file, not netCDF. The following output files are available to the user, depending on their run configuration: 1. Land surface model output 2. Land surface diagnostic output 3. Streamflow output at all channel reaches/cells 4. Streamflow output at forecast points or gage reaches/cells 5. Streamflow on the 2D high resolution routing grid (gridded channel routing only) 6. Terrain routing variables on the 2D high resolution routing grid 7. Lake output variables 8. Ground water output variables 9. A text file of streamflow output at either forecast points or gage locations (:file:`frxst_pts_out.txt`) The output files will be described below. File naming convention of output files: ``YYYY`` = year, ``MM`` = month, ``DD`` = day, ``HH`` = hour, ``MM`` = minutes, ``DOMAINX`` = the domain number that is specified in the hydro.namelist input file (also matches the domain number of the geogrid input file) .. rubric:: 1. Land surface model output \ :file:`{YYYYMMDDHHMM}.LDASOUT_DOMAIN{X}` For this output file, land surface model variables are written to a multi-dimensional netCDF file. Output is produced on the land surface grid, most variables coming directly from the land surface model. The `x` and `y` dimensions of the output file match those of the geogrid input file and the land spatial metadata file. The ``soil_layers_stag`` and ``snow_layers`` dimensions specify the number of soil and snow layers being produced by the land surface model. The names and definitions for each output variable in the LSM output file are generally consistent with those output from standard Noah or Noah-MP LSM coupled to WRF. The output frequency of this file is dictated ``OUTPUT_TIMESTEP`` specified in :file:`namelist.hrldas`. .. rubric:: 2. Land surface diagnostic output \ :file:`{YYYYMMDDHHMM}.LSMOUT_DOMAIN{X}` Variables for this output file will not change with varying values of ``io_config_outputs`` as there is a limited set of land surface states produced for this output file. In general, the user will not desire this output file as the regular land surface output files contain a larger amount of land surface output. However, for examining model state and flux passing between the LSM and the routing routines, this file could contain potentially valuable information that would assist in those efforts. Some of these states include soil moisture, soil temperature, infiltration excess, and surface head. Like the land surface output files, output variables in this output file will match the land surface grid. The output frequency of this file is dictated by ``OUTPUT_TIMESTEP`` specified in :file:`namelist.hrldas`. .. rubric:: 3. Streamflow output at all channel reaches/cells \ :file:`{YYYYMMDDHHMM}.CHRTOUT_DOMAIN{X}` The ``CHRTOUT_DOMAIN`` option in the :file:`hydro.namelist` is used to activate this output. This output file will produce a set of streamflow (and related) variables for each channel location in the modeling domain. For 2D gridded routing on the channel network, this is every pixel cell on the high-resolution modeling domain classified as a channel pixel cell. Forreach-based routing, this is every channel reach defined in the :file:`Route_Link.nc` file. If the user desires to limit the number of streamflow points, the ``order_to_write`` option in :file:`hydro.namelist` will reduce the number of points based on the Strahler order number. Otherwise, all points will be outputted to the file. Each file will contain a ``latitude``, ``longitude``, ``elevation``, and ``order`` variable to describe basic information on each channel point. The ``CRS`` projection variable has been hard-coded (as it is with all other point output files) as the coordinate variables for point files are in latitude/longitude. .. rubric:: 4. Streamflow output at forecast points or gage reaches/cells \ :file:`{YYYYMMDDHHMM}.CHANOBS_DOMAIN{X}` The ``CHANOBS_DOMAIN`` option in the hydro.namelist is used to activate this output. This output file is very similar to the regular streamflow output file format. The key difference is output only occurs at predefined forecast points or gage locations. For 2D gridded channel routing, the user defines forecast points during the setup of their modeling domain. Under this configuration, streamflow will be produced at those points. It is worth noting output points can be constrained by the ``order_to_write`` as they are in the regular streamflow output files. For reach-based routing, it is possible to create outputs at a set of predefined gage points in the :file:`Route_Link.nc` file. Within the :file:`Route_Link.nc` file, a variable called ``gages`` of type character will need to be created by the user containing a string for each channel reach that contains a gage. This variable is of length ``feature_id`` (see description of the Route_Link.nc file in Appendix :ref:`A9 `), and size 15. If a channel reach does not contain a gage, the string stays empty. For example, ``" "`` would represent a channel reach with no gage, and ``" 07124000"`` would contain a gage labeled “07124000”. It is up to the user to create this variable and populate it with character strings if there is a desire to connect gage locations to channel reaches. If no locations are found, the output code will simply bypass creating this output file. Like the other point files, similar geospatial information will be placed into the output files. .. rubric:: 5. Streamflow on the 2D high resolution routing grid \ :file:`{YYYYMMDDHHMM}.CHRTOUT_GRID{X}` The ``CHRTOUT_GRID`` option in the :file:`hydro.namelist` is used to activate this output. This output file is a 2D file created from streamflow with 2D gridded channel routing. Currently, this file is not available for reach-based routing as channel routing does not occur on the channel grid. Output occurs on the high resolution channel routing grid, which means file sizes may be large depending on the size of your domain. In addition to geospatial metadata and coordinate variables, an ``index`` variable is created on the 2D grid producing a global index value for each channel pixel cell on the grid. The main motivation behind creating this file is for easy spatial visualization of the streamflow occurring across the modeling domain. .. rubric:: 6. Terrain routing variables on the 2D high resolution routing grid \ :file:`{YYYYMMDDHHMM}.RTOUT_DOMAIN{X}` The ``RTOUT_DOMAIN`` option in the :file:`hydro.namelist` is used to activate this output. This output file is a 2D file created on the high resolution routing grid. The primary variables created for this file are overland and subsurface routing components that may be of interest to the user. The format is very similar to the 2D streamflow file. Due to the shear size of these data layers, care should be used in deciding when to output high-resolution terrain data. .. rubric:: 7. Lake output variables \ :file:`{YYYYMMDDHHMM}.LAKEOUT_DOMAIN{X}` The ``outlake`` option in the :file:`hydro.namelist` will activate this output. This file is a point output file containing lake/reservoir inflow, outflow and elevation values for each lake/reservoir object created in the modeling domain. The format follows that of the other point output files in terms of geospatial metadata. If no lake/reservoir objects were created in the modeling domain, no output will be created. .. rubric:: 8. Ground water output variables \ :file:`{YYYYMMDDHHMM}.GWOUT_DOMAIN{X}` The ``output_gw`` option in the :file:`hydro.namelist` will activate this output. When groundwater buckets are activated in the model simulations, it is possible to output bucket inflow/outflow/depth states via netCDF files. One important note to reiterate for these output files is that they will not contain the same geospatial metadata as other point files. Each element in the output array represents a spatial groundwater bucket that covers a region that is neither a single pixel cell or point on the modeling domain. For these reasons, this is the only netCDF output file that will not contain full geospatial metadata and coordinate variables. .. rubric:: 9. :file:`frxst_pts_out.txt` \ The ``frxst_pts_out`` option in the :file:`hydro.namelist` will activate this output. The forecast points text file is a unique output file that distills modeled streamflow and stage down to a simple text file with the following columns: - column 1 : time (in seconds) into simulation - column 2 : date and time as YYYY-MM-DD_HH:MM:SS - column 3 : station number index (same as ``feature_id`` in netCDF files) - column 4 : station longitude (in decimal degrees) - column 5 : station latitude (in decimal degrees) - column 6 : streamflow discharge (in cubic meters per second) - column 7 : streamflow discharge (in cubic feet per second) - column 8 : flow depth/river stage (in meters above channel bottom) *Note*: Column 8 is not active for reach-based routing. Each row in the text file is representative of a predefined forecast point (2D gridded channel routing only) or a gage point (reach-based routing). It is worth noting that the number of points will be reduced (as with CHANOBS and CHRTOUT) if the user specifies a higher ``order_to_write`` namelist option. Once output files are generated, the user should inspect the files using the :program:`ncdump` netCDF utility for displaying the contents of a netCDF file. With the exception of groundwater output files, the forecast points text file, and any files generated using ``io_form_outputs`` of 0, the user should see some baseline variables and attributes. A ``crs`` variable will be present indicating the projection coordinate system for the output files. If these files are missing in the 2D files, it is possible the Fulldom_hires.nc or land spatial metadata file does not contain the necessary ``crs`` variable. The same logic can be applied to the ``x`` and ``y`` coordinate variables in the 2D output files. The omission of these indicates they were not present in the input files prior to running the model. For additional help indicating potential issues with the output code, please inspect the standard output from the model. Specifically, look for any ":output:`WARNING`" messages that may indicate why files have not appeared or metadata is missing. For example, ":output:`WARNING: Unable to locate the crs variable. No crs variable or \ attributes will be created.`" would indicate the model was unable to locate the ``crs`` variable in one of the input files. .. note:: **Additional Notes:** - The output descriptions above may not be fully accurate when running with the Noah LSM, which is not actively in development and we therefore support only in a deprecated state. New and improved output routines (e.g., with CF compliance, scale/offset/compression options, augmented metadata) only work with the Noah-MP LSM, while the Noah LSM relies on deprecated output routines. See Appendix :ref:`A2 ` for more details on running with the Noah LSM. - For proper QGIS display of the 2D variables, the user will need to rename netCDF output files to include a “.nc” at the end as some versions of QGIS struggle to properly read in information from a netCDF file without this extension. Future upgrades will automatically add this file extension into the filenames. ================================================ FILE: docs/userguide/model-physics.rest ================================================ .. vim: syntax=rst .. include:: meta.rest .. _section-3: 3. Model Physics Description ============================ This chapter describes the physics behind each of the modules in Version |version_short| of WRF-Hydro and the associated namelist options which are specified at “run time”. 3.1 Physics Overview -------------------- .. _figure3.1: .. figure:: media/wrf-hydro-components.png :align: center **Figure 3.1.** Conceptual diagram of WRF-Hydro physics components and relative outputs. First, the 1-dimensional (1D) column land surface model calculates the vertical fluxes of energy (sensible and latent heat, net radiation) and moisture (canopy interception, infiltration, infiltration-excess, deep percolation) and soil thermal and moisture states. Infiltration excess, ponded water depth and soil moisture are subsequently disaggregated from the 1D LSM grid, typically of 1-4 km spatial resolution, to a high-resolution, typically 30-100 m, routing grid using a time-step weighted method *(Gochis and Chen, 2003)* and are passed to the subsurface and overland flow terrain-routing modules. In typical U.S. applications, land cover classifications for the 1D LSMs are provided by the USGS 24-type Land Use Land Cover product or MODIS Modified IGBP 20-category land cover product (see WRF/WPS documentation); soil classifications are provided by the 1-km STATSGO database *(Miller and White, 1998)*; and soil hydraulic parameters that are mapped to the STATSGO soil classes are specified by the soil analysis of *Cosby et al. (1984)*. Other land cover and soil type classification datasets can be used with WRF-Hydro but users are responsible for mapping those categories back to the same categories as used in the USGS or MODIS land cover and STATSGO soil type datasets. The WRF model pre-processing system (WPS) also provides a fairly comprehensive database of land surface data that can be used to set up the Noah and Noah-MP land surface models. It is possible to use other land cover and soils datasets, and more recently, data from the USGS National Land Cover Dataset (NLCD) and international soils datasets have been integrated into WRF-Hydro. Then, subsurface lateral flow in WRF-Hydro is calculated prior to the routing of overland flow to allow exfiltration from fully saturated grid cells to be added to the infiltration excess calculated by the LSM. The method used to calculate the lateral flux of the saturated portion of the soil column is that of *Wigmosta et al. (1994)* and *Wigmosta and Lettenmaier (1999)*, implemented in the Distributed Hydrology Soil Vegetation Model (DHSVM). It calculates a quasi-3D flow, which includes the effects of topography, saturated soil depth, and depth-varying saturated hydraulic conductivity values. Hydraulic gradients are approximated as the slope of the water table between adjacent grid cells in either the steepest descent or in both `x`- and `y`-directions. The flux of water from one cell to its down-gradient neighbor on each time-step is approximated as a steady-state solution. The subsurface flux occurs on the coarse grid of the LSM while overland flow occurs on the fine grid. Next, WRF-Hydro calculates the water table depth according to the depth of the top of the saturated soil layer that is nearest to the surface. Typically, a minimum of four soil layers are used in a 2-meter soil column used in WRF-Hydro but this is not a strict requirement. Additional discretization permits improved resolution of a time-varying water table height and users may vary the number and thickness of soil layers in the model namelist described in the Appendices :ref:`section-a3`, :ref:`section-a4`, and :ref:`section-a5`. Then, overland flow is defined. The fully unsteady, spatially explicit, diffusive wave formulation of *Julien et al. (1995-CASC2D)* with later modification by *Ogden (1997)* is the current option for representing overland flow, which is calculated when the depth of water on a model grid cell exceeds a specified retention depth. The diffusive wave equation accounts for backwater effects and allows for flow on adverse slopes *(Ogden, 1997)*. As in *Julien et al. (1995)*, the continuity equation for an overland flood wave is combined with the diffusive wave formulation of the momentum equation. Manning's equation is used as the resistance formulation for momentum and requires specification of an overland flow roughness parameter. Values of the overland flow roughness coefficient used in WRF-Hydro were obtained from *Vieux (2001)* and were mapped to the existing land cover classifications provided by the USGS 24-type land-cover product of *Loveland et al. (1995)* and the MODIS 20-type land cover product, which are the same land cover classification datasets used in the 1D Noah/Noah-MP LSMs. Additional modules have also been implemented to represent stream channel flow processes, lakes and reservoirs, and stream baseflow. In WRF-Hydro v\ |version_short| inflow into the stream network and lake and reservoir objects is a one-way process. Overland flow reaching grid cells identified as 'channel' grid cells pass a portion of the surface water in excess of the local ponded water retention depth to the channel model. This current formulation implies that stream and lake inflow from the land surface is always positive to the stream or lake element. There is an optional channel loss formulation *(Lahmers et al. 2019)* where water can seep from the channel; note that this water becomes a sink term and is not returned to the soil or baseflow. Currently there are no channel or lake loss functions where water can move from channels or lakes back to the landscape. Channel flow in WRF-Hydro is represented by one of a few different user-selected methodologies described below. Water passing into and through lakes and reservoirs is routed using a simple level pool routing scheme. Baseflow to the stream network is represented using a conceptual catchment storage-discharge bucket model formulation (discussed below) which obtains “drainage” flow from the spatially-distributed landscape. Discharge from buckets is input directly into the stream using an empirically-derived storage-discharge relationship. If overland flow is active, the only water flowing into the buckets comes from soil drainage. This is because the overland flow scheme will pass water directly to the channel model. If overland flow is switched off and channel routing is still active, then surface infiltration excess water from the land model is collected over the pre-defined catchment and passed into the bucket as well. Each of these process options are enabled through the specification of options in the model namelist file. 3.2 Land model description: The community Noah and Noah-MP land surface models ------------------------------------------------------------------------------- .. note:: As of this writing, only the Noah and Noah-MP land surface models are supported within WRF-Hydro. CLM coupling is currently out-of-date and is not formally supported but is in the process of being updated. The NASA Land Information System (LIS) has been coupled with WRF-Hydro through the NUOPC framework and is supported under the `NASA Land Coupler `_. 3.2.1 Noah Land Surface Model (deprecated support only) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Noah land surface model is a community, 1-dimensional land surface model that simulates soil moisture (both liquid and frozen), soil temperature, skin temperature, snowpack depth, snowpack water equivalent, canopy water content and the energy flux and water flux terms at the Earth's surface *(Mitchell et al., 2002; Ek et al., 2003)*. The model has a long heritage, with legacy versions extensively tested and validated, most notably within the Project for Intercomparison of Land surface Parameterizations (PILPS), the Global Soil Wetness Project *(Dirmeyer et al. 1999)*, and the Distributed Model Intercomparison Project *(Smith, 2002)*. *Mahrt and Pan (1984)* and *Pan and Mahrt (1987)* developed the earliest predecessor to Noah at Oregon State University (OSU) during the mid-1980's. The original OSU model calculated sensible and latent heat flux using a two-layer soil model and a simplified plant canopy model. Development and implementation of the Noah land model has been sustained through the community participation of various agency modeling groups and the university community (e.g. *Chen et al., 2005*). *Ek et al. (2003)* detail the numerous changes that have evolved since its inception including, a four layer soil representation (with soil layer thicknesses of 0.1, 0.3, 0.6 and 1.0 m), modifications to the canopy conductance formulation *(Chen et al., 1996)*, bare soil evaporation and vegetation phenology *(Betts et al., 1997)*, surface runoff and infiltration *(Schaake et al., 1996)*, thermal roughness length treatment in the surface layer exchange coefficients *(Chen et al., 1997a)* and frozen soil processes *(Koren et al., 1999)*. More recently refinements to the snow-surface energy budget calculation *(Ek et al., 2003)* and seasonal variability of the surface emissivity *(Tewari et al., 2005)* have been implemented. The Noah land surface model has been tested extensively in both offline (e.g., *Chen et al., 1996, 1997*; *Chen and Mitchell, 1999*; *Wood et al., 1998*; *Bowling et al., 2003*) and coupled (e.g. *Chen et el., 1997*, *Chen and Dudhia, 2001*, *Yucel et al., 1998*; *Angevine and Mitchell, 2001*; and *Marshall et al., 2002*) modes. The most recent version of Noah is currently one of the operational LSM's participating in the interagency NASA-NCEP real-time Land Data Assimilation System (LDAS, 2003, *Mitchell et al., 2004* for details). Gridded versions of the Noah model are currently coupled to real-time weather forecasting models such as the National Center for Environmental Prediction (NCEP) North American Model (NAM), and the community WRF model. Users are referred to *Ek et al. (2003)* and earlier works for more detailed descriptions of the 1-dimensional land surface model physics of the Noah LSM. .. note:: Support for the Noah Land Surface Model within WRF-Hydro is currently frozen at Noah version 3.6. Since the Noah LSM is not under active development by the community, WRF-Hydro is continuing to support Noah in deprecated mode only. Some new model features, such as the improved output routines, have not been setup to be backward compatible with Noah. Noah users should follow the guidelines in Appendix :ref:`A2 ` for adapting the WRF-Hydro workflow to work with Noah. 3.2.2 Noah-MP Land Surface Model (recommended) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Noah-MP is a land surface model (LSM) using multiple options for key land-atmosphere interaction processes (*Niu et al., 2011*). Noah-MP was developed to improve upon some of the limitations of the Noah LSM (*Koren et al., 1999; Ek et al., 2003*). Specifically, Noah-MP contains a separate vegetation canopy defined by a canopy top and bottom, crown radius, and leaves with prescribed dimensions, orientation, density, and radiometric properties. The canopy employs a two-stream radiation transfer approach along with shading effects necessary to achieve proper surface energy and water transfer processes including under-canopy snow processes (*Dickinson, 1983; Niu and Yang, 2004*). Noah-MP contains a multi-layer snow pack with liquid water storage and melt/refreeze capability and a snow-interception model describing loading/unloading, melt/refreeze capability, and sublimation of canopy-intercepted snow (*Yang and Niu 2003; Niu and Yang 2004*). Multiple options are available for surface water infiltration and runoff and groundwater transfer and storage including water table depth to an unconfined aquifer (*Niu et al., 2007*) as well as options for different snow processes such as snow albedo. The Noah-MP land surface model can be executed by prescribing both the horizontal and vertical density of vegetation using either ground- or satellite-based observations. Another available option is for prognostic vegetation growth that combines a Ball-Berry photosynthesis-based stomatal resistance (*Ball et al., 1987*) with a dynamic vegetation model (*Dickinson et al. 1998*) that allocates carbon to various parts of vegetation (leaf, stem, wood and root) and soil carbon pools (fast and slow). The model is capable of distinguishing between `C_3` and `C_4` photosynthesis pathways and defines vegetation-specific parameters for plant photosynthesis and respiration. In addition to the three-layer snow model in NoahMP, WRF-Hydro also supports optionally running the Crocus snowpack model within NoahMP for glacial representation. For details on using this option, please see :ref:`Appendix 16 `. The Noah-MP version in WRF-Hydro also includes an option for adjusting infiltration vs. surface runoff partitioning as a function of impervious surface cover. The default Noah-MP behavior is to set a very narrow range of soil water holding capacity for cells classified as urban. This has the effect of generating more runoff, but also results in very wet cells that may or may not be appropriate for your application. The new physics setting (``IMPERV_OPTION`` in :file:`namelist.hrldas`) includes 4 options: - Option 0 (no adjustment): Urban cells will be treated the same as all other cells and will use the provided soil and surface parameters to calculate partitoning between infiltration and surface runoff. - Option 1 (total): If spatially distributed parameters are active (``SPATIAL_SOIL=1`` on code compile), the model will expect an impervious fraction grid (``imperv``) to be included in the soil_properties.nc file. The model will use this fractional value to automatically partition that fraction (``imperv``) of effective precipitation reaching the surface to direct surface runoff. The rest (1-``imperv``) will be available for infiltration. If spatially distributed parameters are not active (``SPATIAL_SOIL=0`` on code compile), the model will use the ``IMPERV_URBAN`` value from :file:`MPTABLE.TBL` for impervious fraction for all urban cells. - Option 2 (Alley&Veenhuis): Similar to Option 1, with the modification that the provided impervious fraction will be adjusted to account for local capture of some runoff to adjacent green spaces. This adjustment uses an empirical formulation derived in Alley & Veenhuis (1983, https://doi.org/10.1061/(ASCE)0733-9429(1983)109:2(313) ). In the future we plan to test options that derive an adjustment factor based on impervious connectivity or other local (sub-grid) conditions. - Option 9 (original formulation): This reverts back to the original Noah-MP configuration where soil water holding capacity is adjusted for urban cells and impervious fraction is not used. .. note:: The Noah-MP code within WRF-Hydro has some additional features that were added specifically for WRF-Hydro hydrologic applications, such as spatially distributed parameters and impervious surface runoff treatment, so it does not exactly track the Noah-MP standalone code releases. Standalone Noah-MP model code was recently modernized for modularity and accessibility (*He et al. 2023*). Support for this refactored version of the Noah-MP model is currently in development and will be included in a future WRF-Hydro release. 3.3 Spatial Transformations --------------------------- The WRF-Hydro system has the ability to execute a number of physical process executions (e.g. column physics, routing processes, reservoir fluxes) on different spatial frameworks (e.g. regular grids, catchments, river channel vectors, reservoir polygons, etc). This means that spatial transformations between differing spatial elements has become a critical part of the overall modeling process. Starting in v5.0 of WRF-Hydro, increased support has been developed to aid in the mapping between differing spatial frameworks. Section 3.3.1 describes the spatial transformation process which relies on regular, rectilinear grid-to-grid mapping using a simplified integer linear multiple aggregation/disaggregation scheme. This basic scheme has been utilized in WRF-Hydro since its creation as it was described in *Gochis and Chen, 2003*. Section 3.3.2 describes new spatial transformation methods that have been developed and are currently supported in v5.0 and beyond and, more specifically, in the NOAA National Water Model (NWM). Those user-defined transformations rely on the pre-processing development and specification of interpolation or mapping weights which must be read into the model. As development continues future versions will provide more options and flexibility for spatial transformations using similar user-defined methodologies. .. _section-5: 3.3.1 Subgrid disaggregation-aggregation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This section details the implementation of a subgrid aggregation/disaggregation scheme in WRF-Hydro. The disaggregation-aggregation routines are activated when routing of either overland flow or subsurface flow is active and the specified routing grid increment is different from that of the land surface model grid. Routing in WRF-Hydro is “switch-activated” through the declaration of parameter options in the primary model namelist file hydro.namelist which are described in Appendix :ref:`section-a5` In WRF-Hydro subgrid aggregation/disaggregation is used to represent overland and subsurface flow processes on grid scales much finer than the native land surface model grid. Hence, only routing is represented within a subgrid framework. It is possible to run both the land surface model and the routing model components on the same grid. This effectively means that the aggregation factor between the grids has a value of 1.0. This following section describes the aggregation/disaggregation methodology in the context of a “subgrid” routing implementation. In WRF-Hydro the routing portions of the code have been structured so that it is simple to perform both surface and subsurface routing calculations on grid cells that potentially differ from the native land surface model grid sizes provided that each land surface model grid cell is divided into integer portions for routing. Hence routing calculations can be performed on comparatively high-resolution land surfaces (e.g., a 25 `m` digital elevation model) while the native land surface model can be run at much larger (e.g., 1 `km`) grid sizes. (In this example, the integer multiple of disaggregation in this example would be equal to 40.) This capability adds considerable flexibility in the implementation of WRF-Hydro. However, it is well recognized that surface hydrological responses exhibit strongly scale-dependent behavior such that simulations at different scales, run with the same model forcing, may yield quite different results. The aggregation/disaggregation routines are currently activated by specifying either the overland flow or subsurface flow routing options in the model namelist file and prescribing terrain grid domain file dimensions (``IXRT``, ``JXRT``) which differ from the land surface model domain file dimensions (``IX``, ``JX``). Additionally, the model sub-grid size (``DXRT``), the routing time-step (``DTRT``), and the integer divisor (``AGGFACTRT``), which determines how the aggregation/disaggregation routines will divide up a native model grid square, all need to be specified in the model `hydro.namelist` file. If ``IXRT=IX``, ``JXRT=JX`` and ``AGGFACTRT=1`` the aggregation/disaggregation schemes will be activated but will not yield any effective changes in the model resolution between the land surface model grid and the terrain routing grid. Specifying different values for ``IXRT``, ``JXRT`` and ``AGGFACTRT≠1`` will yield effective changes in model resolution between the land model and terrain routing grids. As described in the Surface Overland Flow Routing section `3.5 <#surface-overland-flow-routing>`__, ``DXRT`` and ``DTRT`` must always be specified in accordance with the routing grid even if they are the same as the native land surface model grid. The disaggregation/aggregation routines are implemented in WRF-Hydro as two separate spatial loops that are executed after the main land surface model loop. The disaggregation loop is run prior to routing of saturated subsurface and surface water. The main purpose of the disaggregation loop is to divide up specific hydrologic state variables from the land surface model grid square into integer portions as specified by ``AGGFACTRT``. An example disaggregation (where ``AGGFACTRT=4``) is given in Figure 3.2. .. _figure3.2: .. figure:: media/aggfactr.png :align: center :scale: 50% **Figure 3.2** Example of the routing sub-grid implementation within the regular land surface model grid for an aggregation factor = 4. Four model variables are required to be disaggregated for higher resolution routing calculations: `SMCMAX` - maximum soil moisture content for each soil type `SMCREF` - reference soil moisture content (field capacity) for each soil type `INFXS` - infiltration excess `LKSAT` - lateral saturated conductivity for each soil type `SMC` - soil moisture content for each soil layer In the model code, fine-grid values bearing the same name as these with an “RT” extension are created for each native land surface model grid cell (e.g. ``INFXSRT`` vs ``INFXS``). To preserve the structure of the spatial variability of soil moisture content on the sub-grid from one model time step to the next, simple, linear sub-grid weighting factors are assigned. These values indicate the fraction of the total land surface model grid value that is partitioned to each sub-grid pixel. After disaggregation, the routing schemes are executed using the fine-grid values. Following execution of the routing schemes the fine-grid values are aggregated back to the native land surface model grid. The aggregation procedure used is a simple linear average of the fine-grid components. For example the aggregation of surface head (``SFHEAD``) from the fine grid to the native land surface model grid would be: .. rst-class:: center :math:`{SFHEAD}_{i,j}\ = \ \frac{\Sigma\Sigma\ {SFHEADRT}_{irt,jrt}}{AGGFACTRT^2}` (3.0) where, `i_{rt}` and `j_{rt}` are the indices of all of the grid cells residing within the native land model grid cell `i`,\ `j`. The following variables are aggregated and, where applicable, update land surface model variable values: | SFHEAD - surface head (or, equivalently, depth of ponded water) | SMC - soil moisture content for each soil layer These updated values are then used on the next iteration of the land surface model. 3.3.2 User-Defined Mapping ~~~~~~~~~~~~~~~~~~~~~~~~~~ The emergence of hydrologic models, like WRF-Hydro, that are capable of running on gridded as well as vector-based processing units requires generic tools for processing input and output data as well as methods for transferring data between models. Such a spatial transformation is currently utilized when mapping between model grids and catchments in the WRF-Hydro/National Water Model (NWM) system. In the NWM, selected model fluxes are mapped from WRF-Hydro model grids onto the NHDPlus catchment polygon and river vector network framework. The GIS pre-processing framework described here allows for fairly generalized geometric relationships between features to be characterized and for parameters to be summarized for any discrete unit of geography. 3.3.3 Data Remapping for Hydrological Applications ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A common task in hydrologic modeling is to regrid or aggregate data from one unit of analysis to another. Frequently, atmospheric model data variables such as temperature and precipitation may be produced on a rectilinear model grid while the hydrologic unit of analysis may be a catchment Hydrologic Response Unit (cHRU), defined using a closed polygon and derived from a hydrography dataset or terrain processing application. Often, cHRU-level parameters must be derived from data on a grid. Depending on the difference between the scale of the gridded and feature data, simple interpolation schemes such as nearest neighbor may introduce significant error when estimating data at the cHRU scale. Other GIS analysis methods such as zonal statistics require resampling of the gridded and/or feature data and limited control over the common analysis grid resolution, which may also introduce significant error. Area-weighted grid statistics provide a robust and potentially conservative method for transferring data from one or multiple features to another. In the case of runoff calculated from a land surface model grid, the runoff should be conservatively transferred between the grid and the cHRU, such that the runoff volume is conserved. The correspondence between polygons and grid cells need only be generated once for any grid/polygon collection. The correspondence file that is output from the tool stores all necessary information for translating data between the datasets in either direction. There are a variety of useful regridding and spatial analysis tools available for use in the hydrologic and atmospheric sciences. Many regridding utilities exist that are able to either characterize and store the relationship between grid features and polygons or perform regridding from one grid to another. The Earth System Modeling Framework (ESMF) offers high performance computing (HPC) software for building and coupling weather, climate, and related models. ESMF provides the :program:`ESMF_RegridWeightGen` utility for parallel generation of interpolation weights between two grid files in netCDF format. These utilities will work for structured (rectilinear) and unstructured grids. The :program:`ESMF_RegridWeightGen` tool since can be accessed through python (through ESMPy) and the NCAR Command Language (NCL, deprecated). Another commonly used tool in the atmospheric sciences are the Climate Data Operators (CDO), which offer 1\ :sup:`st` and 2\ :sup:`nd`\- order conservative regridding (:program:`remapcon`, :program:`remapcon2`) and regrid weight generation (:program:`gencon`, :program:`gencon2`) based on the work of *Jones (1999)*. All of the above-mentioned utilities require SCRIP grid description files to perform the remapping. The SCRIP standard format for correspondence stores geometry information for regridding, while the tools mentioned here store just the spatial weights. Thus, WRF-Hydro spatial correspondence files are more generic, with compact file sizes, and may be used for non-gridded data. The WRF-Hydro geospatial pre-processing toolkit includes a script that quantifies the polygon to polygon correspondence between geometries in two separate features (grid cells represented by polygons and basins represented by polygons). This correspondence is stored in a netCDF format file that contains the spatial weights and identification of all polygons from one input shapefile that intersect each polygon in another input shapefile. The storage of correspondence information between one dataset and another allows for many types of regridding and spatial interpolation between the spatial datasets. This file needs only to be derived once between any two sets of polygons, and the correspondence file can be used to regrid variables between those spatial datasets. This is useful if multiple variables must be regridded, or a single variable across many timesteps. As long as the grids do not change in space or time, the relationship between all features will remain constant, and the correspondence file may be used to regrid data between them. There are uses for this utility that range outside of the hydrological sciences, and this utility may be of broader interest to the geospatial community. Although interpolation packages exist, this method allows for storage of the correspondence information for future use in a small-file size. Users wanting to create custom spatial weight interpolation files for WRF-Hydro need to refer to the *WRF-Hydro GIS Pre-processing Toolkit* and documentation. For reference, variable descriptions of the contents of the spatial weights file is located in :ref:`section-a13`. .. _figure3.3: .. figure:: media/user-defined-mapping.png :align: center :scale: 90% **Figure 3.3.** An illustration of implementing user-defined mapping to translate from gridded fluxes and states to aggregated catchment fluxes and states, which can be passed into, for example, vector-based channel routing modules. 3.4 Subsurface Routing ---------------------- Subsurface lateral flow is calculated prior to the routing of overland flow. This is because exfiltration from a supersaturated soil column is added to infiltration excess from the land surface model, which ultimately updates the value of surface head prior to routing of overland flow. A supersaturated soil column is defined as a soil column that possesses a positive subsurface moisture flux which when added to the existing soil water content is in excess of the total soil water holding capacity of the entire soil column. Figure 3.4 illustrates the lateral flux and exfiltration processes in WRF-Hydro. In the current default implementation of WRF-Hydro with the Noah and Noah-MP land surface models, there are four soil layers. The depth of the soil layers in WRF-Hydro can be manually specified in the model namelist file under the ``ZSOIL`` variable. Users must be aware that, in the present version of WRF-Hydro, total soil column depth and individual soil layer thicknesses are constant throughout the entire model domain. Future versions under development are relaxing this constraint. However, the model is capable of using a different distribution of soil column layer depths and these simply need to be specified in the model namelist file. Assuming a 2-m soil profile the default soil layer depths (and associated water table depths) are specified in Table 3.1. .. table:: **Table 3.1: Depths of 4 soil layers in WRF-Hydro** :align: center +-------------+-------------------------+-----------------------------+ | **Layer** | **Soil Thickness (mm)** | **Z (depth to top of layer) | | | | (mm)** | +=============+=========================+=============================+ | 1 | 100 | 0 | +-------------+-------------------------+-----------------------------+ | 2 | 300 | 100 | +-------------+-------------------------+-----------------------------+ | 3 | 600 | 400 | +-------------+-------------------------+-----------------------------+ | 4 | 1000 | 1000 | +-------------+-------------------------+-----------------------------+ .. _figure3.4: .. figure:: media/subsurface-flow.png :align: center :scale: 50% **Figure 3.4** Conceptualization of saturated subsurface flow components. The method used to calculate the lateral flow of saturated soil moisture employs a quasi three-dimensional flow representation, which include the effects of topography, saturated soil depth (in this case layers), and saturated hydraulic conductivity. Hydraulic gradients are approximated as the slope of the water table between adjacent grid cells in the x- and y-directions or in an eight direction (D8) steepest descent methodology that is specified by the user in the model namelist. In each cell, the flux of water from one cell to its down-gradient neighbor on each timestep is approximated as a steady-state solution. The looping structure through the model grid performs flux calculations separately in the x- and y-directions for the 2-dimensional routing option or simply along the steepest D8 pathway. Using Dupuit-Forchheimer assumptions the rate of saturated subsurface flow at time `t` can be calculated as: .. _eqn3.1: .. rst-class:: center .. math:: {q}_{i,j} &= - T_{i,j}\beta_{i,j}w_{i,j}\ when\ \beta_{i,j}\ < \ 0 \\ &= 0\ when\ \beta_{i,j} > = 0 (3.1) where, `q_{i,j}` is the flow rate from cell `(i,j)`, `T_{i,j}` is the transmissivity of cell `(i,j)`, `\beta_{i,j}` is the water table slope and `w_{i,j}` is the width of the cell which is fixed for a regular grid. `\beta_{i,j}` is calculated as the difference in water table depths between two adjacent grid cells divided by the grid spacing. The method by which the water table depth is determined is provided below. Transmissivity is a power law function of saturated hydraulic conductivity (`Ksat_{i,j}`) and soil thickness (`D_{i,j}`) given by: .. _eqn3.2: .. rst-class:: center .. math:: T_{i,j} &= \frac{{Ksat}_{i,j}D_{i,j}} {n_{i,j}} \left( 1 - \frac{z_{i,j}}{D_{i,j}} \right)^{n_{i,j}}\ when\ z_{i,j} < = D_{i,j} \\ &= 0\ when\ z_{i,j} > D_{i,j} (3.2) where, `z_{i,j}` is the depth to the water table. `n_{i,j}` in :ref:`Eq. (3.2) ` is defined as the local power law exponent and is a tunable parameter that dictates the rate of decay of `Ksat_{i,j}` with depth (`n_{i,j}` has a default value of 1.0 or can be specified as "NEXP" in hydro2dtbl.nc). When :ref:`Eq. (3.2) ` is substituted into :ref:`Eq. (3.1) ` the flow rate from cell `(i,j)` to its neighbor in the `x`-direction can be expressed as: .. _eqn3.3: .. rst-class:: center .. math:: q_{x(i,j)} = \gamma_{x(i,j)} h_{i,j}\ when\ \beta_{x(i,j)} < 0 (3.3) where, .. _eqn3.4: .. rst-class:: center .. math:: \gamma_{x(i,j)} = - \left( \frac{w_{i,j}{Ksat}_{i,j}D_{i,j}}{n_{i,j}} \right)\beta_{x(i,j)} (3.4) .. _eqn3.5: .. rst-class:: center .. math:: h_{i,j} = \left( 1-\frac{z_{i,j}}{D_{i,j}} \right) (3.5) This calculation is repeated for the y-direction when using the two-dimensional routing method. The net lateral flow of saturated subsurface moisture (`Q_{net}`) for cell `(i,j)` then becomes: .. _eqn3.6: .. rst-class:: center .. math:: Q_{net(i,j)} = h_{i,j} \sum_x{\gamma_{x(i,j)}} + h_{i,j} \sum_y{\gamma_{y(i,j)}} (3.6) The mass balance for each cell on a model time step (`\Delta t`) can then be calculated in terms of the change in depth to the water table (`\Delta z`): .. _eqn3.7: .. rst-class:: center .. math:: \Delta z = \frac{1}{\phi_{(i,j)}} \left[ \frac{Q_{net(i,j)}}{A} - R_{(i,j)} \right] \Delta t (3.7) where, `\phi` is the soil porosity, `R` is the soil column recharge rate from infiltration or deep subsurface injection and *A* is the grid cell area. In WRF-Hydro, `R`, is implicitly accounted for during the land surface model integration as infiltration and subsequent soil moisture increase. Assuming there is no deep soil injection of moisture (i.e. pressure driven flow from below the lowest soil layer), `R`, in WRF-Hydro is set equal to 0. The methodology outlined in Equations :ref:`3.2 ` thru :ref:`3.7 ` has no explicit information on soil layer structure, as the method treats the soil as a single homogeneous column (with an assumed exponential decay of saturated hydraulic conductivity). Therefore, changes in water table depth (`\Delta z`) need to be remapped to the land surface model soil layers. WRF-Hydro specifies the water table depth according to the depth of the top of the highest (i.e. nearest to the surface) saturated layer. The residual saturated water above the uppermost, saturated soil layer is then added to the overall soil water content of the overlying unsaturated layer. This computational structure requires accounting steps to be performed prior to calculating `Q_{net}`. Given the timescale for groundwater movement and limitations in the model structure there is significant uncertainty in the time it takes to properly spin-up groundwater systems. The main things to consider include 1) the specified depth of soil and number and thickness of the soil vertical layers and 2) the prescription of the model bottom boundary condition. Typically, for simulations with deep soil profiles (e.g. > 10 `m`) the bottom boundary condition is set to a ‘no-flow’ boundary (``SLOPE_DATA = 0.0`` in the :file:`GENPARM.TBL` parameter file or ``slope = 0.0`` in the :file:`soil_properties.nc` spatially distributed parameter file). See Appendices :ref:`section-a6` and :ref:`section-a7` for a description of :file:`GENPARM.TBL` and :file:`soil_properties.nc`. .. note:: Currently subsurface routing is only supported in the steepest slope (D8) formulation. The 2-dimensional solution will be reactivated in a future release. .. rubric:: Relevant code modules: :file:`Routing/Noah_distr_routing_subsurface.F90` .. rubric:: Relevant namelist options: :file:`hydro.namelist`: - ``SUBRTSWCRT`` - Switch to activate subsurface flow routing. - ``DXRT`` - Specification of the routing grid cell spacing - ``AGGFACTR`` - Subgrid aggregation factor, defined as the ratio of the subgrid resolution to the native land model resolution :file:`namelist.hrldas`: - ``NOAH_TIMESTEP`` - Subsurface routing operates on the LSM timestep .. rubric:: Relevant domain and parameter files/variables: - ``TOPOGRAPHY`` in :file:`Fulldom_hires.nc` - Terrain grid or Digital Elevation Model (DEM). Note: this grid may be provided at resolutions equal to or finer than the native land model resolution. - ``LKSATFAC`` in :file:`Fulldom_hires.nc` - Multiplier on saturated hydraulic conductivity in lateral flow direction. - ``SATDK``, ``SMCMAX``, ``SMCREF`` in :file:`HYDRO.TBL` or :file:`hydro2dtbl.nc` - Soil properties (saturated hydraulic conductivity, porosity, field capacity) used in lateral flow routing. - ``NEXP`` in :file:`hydro2dtbl.nc` - Local power law exponent that dictates the rate of decay of saturated hydraulic conductivity with depth. .. _section-3.5: 3.5 Surface Overland Flow Routing --------------------------------- Overland flow in WRF-Hydro is calculated using a fully-unsteady, explicit, finite-difference, diffusive wave formulation similar to that of *Julien et al. (1995)* and *Ogden et al. (1997)*. The diffusive wave equation, while slightly more complicated, is, under some conditions, superior to the simpler and more traditionally used kinematic wave equation, because it accounts for backwater effects and allows for flow on adverse slopes. The overland flow routine described below can be implemented in either a 2-dimensional (x and y direction) or 1-dimension (steepest descent or “D8”) method. While the 2-dimensional method may provide a more accurate depiction of water movement across some complex surfaces it is more expensive in terms of computational time compared with the 1-dimensional method. While the physics of both methods are identical we have presented the formulation of the flow in equation form below using the 2-dimensional methodology. .. figure:: media/overland-flow.png :align: center :scale: 50% **Figure 3.5:** Conceptual representation of terrain elements. Flow is routed across terrain elements until it intersects a “channel” grid cell indicated by the blue line where it becomes “in-flow” to the stream channel network. The diffusive wave formulation is a simplification of the more general St. Venant equations of continuity and momentum for a shallow water wave. The two-dimensional continuity equation for a flood wave flowing over the land surface is: .. _eqn3.8: .. rst-class:: center .. math:: \frac{\partial h}{\partial t} + \frac{\partial q_x}{\partial x} + \frac{\partial q_y}{\partial x} = i_e (3.8) where, `h` is the surface flow depth; `q_x` and `q_y` are the unit discharges in the `x`- and `y`-directions, respectively; and `i_e` is the infiltration excess. The momentum equation used in the diffusive wave formulation for the `x`-dimension is: .. _eqn3.9: .. rst-class:: center .. math:: S_{fx} = S_{ox} - \frac{\partial h}{\partial x} (3.9) where, `S_fx` is the friction slope (or slope of the energy grade line) in the x-direction, `S_ox` is the terrain slope in the `x`-direction and `\partial h/\partial x` is the change in depth of the water surface above the land surface in the `x`-direction. In the 2-dimensional option, flow across the terrain grid is calculated first in the `x`- then in the `y`-direction. In order to solve :ref:`Eq. 3.8 ` values for `q_x` and `q_y` are required. In most hydrological models they are typically calculated by the use of a resistance equation such as Manning's equation or the Chezy equation, which incorporates the expression for momentum losses given in :ref:`Eq. 3.9 `. In WRF-Hydro, a form of Manning's equation is implemented: .. _eqn3.10: .. rst-class:: center .. math:: q_x = \alpha_x h^\beta (3.10) where, .. _eqn3.11: .. rst-class:: center .. math:: \alpha_x = \frac{S_{fx}^{1/2}}{n_{OV}}; \qquad \beta = \frac{5}{3} (3.11) where, `n_{OV}` is the roughness coefficient of the land surface and is a tunable parameter and `\beta` is a unit-dependent coefficient expressed here for SI units. The overland flow formulation has been used effectively at fine terrain scales ranging from 30-300 `m`. There has not been rigorous testing to date, in WRF-Hydro, at larger length-scales (> 300 `m`). This is due to the fact that typical overland flood waves possess length scales much smaller than 1 `km`. Micro-topography can also influence the behavior of a flood wave. Correspondingly, at larger grid sizes (e.g. > 300 `m`) there will be poor resolution of the flood wave and the small-scale features that affect it. Also, at coarser resolutions, terrain slopes between grid cells are lower due to an effective smoothing of topography as grid size resolution is decreased. Each of these features will degrade the performance of dynamic flood wave models to accurately simulate overland flow processes. Hence, it is generally considered that finer resolutions yield superior results. The selected model time step is directly tied to the grid resolution. In order to prevent numerical diffusion of a simulated flood wave (where numerical diffusion is the artificial dissipation and dispersion of a flood wave) a proper time step must be selected to match the selected grid size. This match is dependent upon the assumed wave speed or celerity (`c`). The Courant Number, `C_n = c(\Delta t/\Delta x)`, should be close to 1.0 in order to prevent numerical diffusion. The value of the `C_n` also affects the stability of the routing routine such that values of `C_n` should always be less than 1.0. Therefore the following model time steps are suggested as a function of model grid size as shown in Table 3.2. .. table:: **Table 3.2:** Suggested routing time steps for various grid spacings :align: center :width: 50% +---------+---------+ | X (`m`) | T (`s`) | +=========+=========+ | 30 | 2 | +---------+---------+ | 100 | 6 | +---------+---------+ | 250 | 15 | +---------+---------+ | 500 | 30 | +---------+---------+ WRF-Hydro also includes an impervious surface adjustment option for overland routing. If this scheme is activated (``imperv_adj = 0`` in :file:`hydro.namelist`) then the overland roughness Manning's coefficient and maximum retention depth are adjusted based on the impervious fraction provided as ``IMPERVFRAC`` in :file:`Fulldom_hires.nc`. Specifically, maximum retention depth is multiplied by (1 - ``IMPERVFRAC``) (so smaller values for higher imperviousness). Manning's roughness for overland routing is scaled based on a linear weighting of smoothness (1/roughness, see Liong et al. 1989) and assuming a roughness of 0.02 for impervious and native cell roughness for pervious: OVROUGHRT = 1 / ((1/0.02)*impervfrac + (1/OVROUGHRT)*(1-impervfrac)) .. rubric:: Relevant code modules: :file:`Routing/Noah_distr_routing_overland.F90` .. rubric:: Relevant namelist options: `hydro.namelist`: - ``OVRTSWCRT`` - Switch to activate overland flow routing. - ``DXRT`` - Specification of the routing grid cell spacing - ``AGGFACTR`` - Subgrid aggregation factor, defined as the ratio of the subgrid resolution to the native land model resolution - ``DTRT_TER`` - Overland routing grid time step - ``rt_option`` - Overland flow routing option (steepest descent or 2-dimensional) .. rubric:: Relevant domain and parameter files/variables: - ``TOPOGRAPHY`` in :file:`Fulldom_hires.nc` - Terrain grid or Digital Elevation Model (DEM). Note: this grid may be provided at resolutions equal to or finer than the native land model resolution. - ``RETDEPRTFAC`` in :file:`Fulldom_hires.nc` - Multiplier on maximum retention depth before flow is routed as overland flow. - ``OVROUGHRTFAC`` in :file:`Fulldom_hires.nc` - Multiplier on Manning's roughness for overland flow. - ``OV_ROUGH`` in :file:`HYDRO.TBL` or ``OV_ROUGH2D`` in :file:`hydro2dtbl.nc` - Manning's roughness for overland flow (by default a function of land use type). .. _section-3.6: 3.6 Channel Routing ---------------------------- There are multiple channel routing algorithms available in version |version_short| of WRF-Hydro. These algorithms operate either on the resolution of the fine grid (gridded routing) or on a vectorized network of channel reaches (linked routing, also referred to as reach-based routing), which maps the fine grid to the vector network (:ref:`Figure 3.6 `). The following section describes the routing methods and their implementation in the WRF-Hydro model code. In general, inflow to the channel is based on a mass balance calculation, where the channel routes water when the ponded water depth (or surface head, `SFCHEADRT`) of the channel grid cells exceeds a predefined retention depth (`RETDEPRT`). As described in `Section 3.5 <#surface-overland-flow-routing>`__, the depth of surface head on any grid cell is a combination of the local infiltration excess, the amount of water flowing onto the grid cell from overland flow, and exfiltration from groundwater flow. The quantity of surface head in excess of the retention depth is accumulated as stream channel inflow and is effectively “discharged” to the channel routing routine (described below). In the current code, `RETDEPRT` is hard-coded to 5mm for channel pixels to encourage more local infiltration near the river channel leading to wetter soils that better emulate riparian conditions. Values of “channel inflow” are accumulated on the channel grid and can be output for visualization and analysis (see :ref:`Section 6 ` for a description of model outputs). .. _figure3.6: .. figure:: media/channel-routing-grid-link.png :align: center **Figure 3.6** Channel routing via the high resolution grid (left) or on a vector/link network (right). The channel routing module :file:`module_channel_routing.F90` allows for the one-dimensional, distributed routing of streamflow across the domain. An optional, switch-activated, level-pool lake/reservoir algorithm is also available and is described below in Sections :ref:`3.7 ` and :ref:`3.8 `. Within each channel grid cell there is an assumed channel reach of trapezoidal geometry as depicted in Figure 3.7. Channel parameters side slope (`z`), bottom width (`B_w`) and roughness (`n`) are currently prescribed as functions of Strahler stream order for defaults. Details on how each routing method reads these parameters are specified in the subsections below. .. _figure3.7: .. figure:: media/channel-terms.png :align: center :figwidth: image **Figure 3.7** Schematic of Channel Routing Terms .. table:: :align: center +---------------------------------+------------------+ | Channel Slope | `S_o` | +---------------------------------+------------------+ | Channel Length | `\Delta x` (`m`) | +---------------------------------+------------------+ | Channel side slope | `z` (`m`) | +---------------------------------+------------------+ | Constant bottom width | `B_w` (`m`) | +---------------------------------+------------------+ | Manning's roughness coefficient | (`n`) | +---------------------------------+------------------+ As discussed above, channel elements receive lateral inflow from overland flow. There is currently no overbank flow back to the fine-grid, so flow into the channel model is effectively one-way. Therefore, WRF-Hydro does not explicitly represent inundation areas from overbank flow from the channel back to the terrain. This will be an upcoming enhancement, though currently there are methods for post-processing an inundation surface. Uncertainties in channel geometry parameters and the lack of an overbank flow representation result in a measure of uncertainty for users wishing to compare model flood inundation versus those from observations. It is strongly recommended that users compare model versus observed streamflow discharge values and use observed stage-discharge relationships or “rating curves” when wishing to relate modeled/predicted streamflow values to actual river levels and potential inundation areas. .. rubric:: Relevant code modules: :file:`Routing/module_channel_routing.F90` .. rubric:: Relevant namelist options for gridded and reach-based routing: `hydro.namelist`: - ``CHANRTSWCRT`` - Switch to activate channel routing. - ``channel_option`` - Specification of the type of channel routing to activate - ``DTRT_CH`` - Channel routing time step, applies to both gridded and reach-based channel routing methods - ``route_link_f`` (optional) - a :file:`Route_Link.nc` file is required for reach-based routing methods. Example header in :ref:`Appendix A9 `. 3.6.1. Gridded Routing using Diffusive Wave ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Channel flow down through the gridded channel network is performed using an explicit, one-dimensional, variable time-stepping diffusive wave formulation. As mentioned above the diffusive wave formulation is a simplification of the more general St. Venant equations for shallow water wave flow. Similarly, for channel routing, the mass and momentum continuity equations are given as: Continuity: .. math:: \frac{\partial A}{\partial t} + \frac{\partial Q}{\partial x} = q_{lat} \qquad (3.12) \ Momentum: .. math:: \frac{\partial Q}{\partial t} + \frac{\partial(\beta Q^2 / A)}{\partial x} + gA\frac{\partial Z}{\partial x} = -gAS_f \qquad (3.13) Where `t` is the time, `x` is the streamwise coordinate, `A` is in the flow area of the cross section, and `q_{lat}` is the lateral inflow rate into the channel. In the momentum equation, `Q` is the flow rate, `\beta` is a momentum correction coefficient, `Z` is the water surface elevation, `g` is gravity and `S_f` is the friction slope which is computed as: .. math:: S_f = \left( \frac{Q}{K} \right)^2 \qquad (3.14) where `K` is the conveyance, computed from the Manning's equation: .. math:: K = \frac{C_m}{n} AR^{2/3} \qquad (3.15) where `n` is the Manning's roughness coefficient, `A` is the cross-sectional area, `R` is the hydraulic radius (`A/P`), `P` is the wetted perimeter, and `C_m` is dimensional constant (1.486 for English units or 1.0 for SI units). Ignoring the convective term, the second term in the momentum equation gives the diffusive wave approximation of open channel flow. The momentum equation then simplifies to: .. math:: Q = -SIGN \left( \frac{\partial Z}{\partial x} \right) K \sqrt{\left| \frac{\partial z}{\partial x}\right |} \qquad (3.16) where the substitution for friction slope has been made and the `SIGN` function is `1` for `\partial Z / \partial x > 0` and `-1` for `\partial Z / \partial x < 0`. The numerical solution is obtained by discretizing the continuity equation over a raster cell as: .. math:: A^{n+1} - A^n = \frac{\Delta t}{\Delta x} \left( Q^n_{i+\frac{1}{2}} - Q^n_{i-\frac{1}{2}} \right) + \Delta tq^n_{lat} \qquad (3.17) where `Q^n_{i+\frac{1}{2}}` is the flux across the cell face between point `i` and `i+1`, and is computed as: .. math:: Q^n_{i+\frac{1}{2}} = -SIGN\left(\Delta Z^n_{i+1}\right) K_{i+\frac{1}{2}} \sqrt{\frac{\left|\Delta Z^n_{i+1}\right|}{\Delta x}} \qquad (3.18) where: .. math:: \Delta Z^n_{i+1} = Z^n_{i+1} - Z^i &\qquad (3.19) \\ K^n_{i+\frac{1}{2}} = \frac{1}{2} \left( 1 + SIGN\left(\Delta Z^n_{i+1}\right)\right) K_i + \left( 1- SIGN\left( \Delta Z^n_{i+1} \right)\right) K_{i+1} &\qquad (3.20) A first-order, Newton-Raphson (N-R) solver is used to integrate the diffusive wave flow equations. Under certain streamflow conditions (e.g. typically low gradient channel reaches) the first-order solver method can produce some instabilities resulting in numerical oscillations in calculated streamflow values. To address this issue, higher order solver methods will be implemented in future versions of WRF-Hydro. Unlike typical overland flow flood waves which have very shallow flow depths, on the order of millimeters or less, channel flood waves have appreciably greater flow depths and wave amplitudes, which can potentially result in strong momentum gradients and strong accelerations of the propagating wave. To properly characterize the dynamic propagation of such highly variable flood waves it is often necessary to decrease model time-steps in order to satisfy Courant conditions. Therefore WRF-Hydro utilizes variable time-stepping in the diffusive wave channel routing module in order to satisfy Courant constraints and avoid numerical dispersion and instabilities in the solutions. The initial value of the channel routing time-step is set equal to ``DTRT_CH`` (which should be estimated based on the grid cell size, as for overland routing). If, during model integration the N-R convergence criteria for upstream-downstream streamflow discharge values is not met, the channel routing time-step is decreased by a factor of one-half and the N-R solver is called again. It is important to note that the use of variable time-stepping can affect model computational performance resulting in slower solution times for rapidly evolving streamflow conditions such as those occurring during significant flood events. Therefore, selection of the time-step decrease factor (default value set to 0.5) and the N-R convergence criteria can each affect model computational performance. Uncertainty in channel routing parameters can also impact the accuracy of the model solution which implies that model calibration is often required upon implementation in a new domain. Presently, all of the channel routing parameters are prescribed as functions of stream order in a channel routing parameter table :file:`CHANPARM.TBL`. The structure of this file is described in detail in Appendix :ref:`A9 `. It should be noted that prescription of channel flow parameters as functions of stream order is likely to be a valid assumption over relatively small catchments and not over large regions. .. _section-3.6.2: 3.6.2. Reach Routing using Muskingum and Muskingum-Cunge ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The gridded catchment and drainage network of the land surface model (Noah/Noah-MP LSM) are mapped to the one-dimensional vectorized channel network, with a unique set of channel properties defined as constant for each reach. The flow out of each channel reach is determined based on flow hydraulics, channel storage and the lateral inflow contribution from each grid cell that is mapped to the individual reach element. Since reach lengths are not constant, the number of contributing grid cells to the reach depend on the reach length (:ref:`Figure 3.6 `). Flow is assumed always upstream-to-downstream, and channel junctions accommodate the merging of flows through the reach network. The simultaneous transformation of the often complex drainage network, source areas, and channel flow hydrographs in these large, complex networks necessitates a practical and efficient solution to the routing problem (*Brunner and Gorbrecht, 1991*). On the reach network, WRF-Hydro makes use of a fairly standard implementation of the Muskingum-Cunge (MC) method of hydrograph routing which makes use of time varying parameter estimates. The scheme is a practical approach to characterize watershed runoff characteristics over large network, large watershed flow integration. But as a one-dimensional explicit scheme, it does not allow for backwater or localized effects. Channel flows are routed upstream to downstream in a cascade routing manner (*Gunner and Gorbetch, 1991*) with the assumption that there are negligible backwater effects. The MC routing scheme relates inflow and outflow using a storage relationship, where: .. math:: S = K[XI + (1-X) Q] \qquad (3.21) where X is a weighting factor with a range of` 0 ≤ X ≤ 0.5`, where `X` range from `0` for reservoir-type storage, while an advancing floodwave produces a wedge of storage and thus a value of `X` greater than `0` (*Chow et al., 1982*). The finite difference formulation of the storage relationship results in the Muskingum Equation, .. math:: Q_{d}^{c} = \ C1{\ Q}_{u}^{p}\ + \ C2\ Q_{u}^{c}\ + \ {C3Q}_{d}^{p}\ + \left( \frac{\ q_{l}\ dt}{D} \right) \qquad (3.22) where `D = K(1-X)+ dt/2` and is the wedge storage contribution from lateral inflow in the reach. The subscript are `u` and `d` are the upstream and downstream nodes of each reach, respectively; and the `p` and `c` superscript are the previous and current time step, respectively. .. _figure3.8: .. figure:: media/channel-props.svg :align: center :scale: 150% **Figure 3.8** Channel Properties Static hydraulic properties are used to describe the properties of each channel reach, with each being assumed trapezoidal and include bottom width (`B_w``), channel length (`dx`), channel top width before bankfull (`Tw`), Manning's roughness coefficient (`n`), channel side slope (`z`, in meters), and the longitudinal slope of the channel (`So`). If a user is running the model with reach-based routing (``channel_option`` = ``1`` or ``2``), the `B_w` , `n`, and `z` parameters can be modified through the :file:`Route_Link.nc` file. Note: the :file:`CHANPARM.TBL` file will not be used in this configuration. Simulated state variables include estimate of mean water depth in the channel (`h`), steady-state velocity (`v`) and flow rate (`q`) in the reach at the current timestep. An initial depth estimate is made based on the depth from the previous time step. Time varying properties include the hydraulic area, `Area = (B_w*h*z)*h; (3.23)`, the wetted perimeter `W_p= (B_w + 2 * \sqrt{1+z^2}); (3.24)`, and the hydraulic radius, `R=Area/W_p; (3.25)`. With an initial estimate of water depth in the channel, the wave celerity for the trapezoidal channel is estimated as: .. math:: Ck = \sqrt{\frac{So}{n}} \frac{5}{3}R^{\frac{2}{3}} - \frac{2}{3}R^{\frac{5}{3}}*\left(2*\sqrt{\frac{1+z^2}{B_w + 2hz}}\right) \qquad (3.26) Wave celerity is used to estimate the MC routing parameters, where *K=* *dx/c\ k* (3.27) is the time required for an incremental flood wave to propagate through the channel reach, and the storage shape weighting factor is given as, *X* = :math:`\frac{1}{2}\left( 1 - \frac{Q}{(Tw{\ c}_{k}\ So\ dx} \right)` , (3.28) where *Q* is the estimated discharge, *T\ w* is the water surface width, *S\ o* is the channel slope and *dx* is the channel length. .. rubric:: Relevant domain and parameter files/variables: - ``TOPOGRAPHY`` in :file:`Fulldom_hires.nc` - Terrain grid or Digital Elevation Model (DEM). Note: this grid may be provided at resolutions equal to or finer than the native land model resolution. - ``CHANNELGRID`` in :file:`Fulldom_hires.nc` - Channel network grid identifying the location of stream channel grid cells - ``STREAMORDER`` in :file:`Fulldom_hires.nc` - Strahler stream order grid identifying the stream order for all channel pixels within the channel network. - ``FLOWDIRECTION`` in :file:`Fulldom_hires.nc` - Flow direction grid, which explicitly defines flow directions along the channel network in gridded routing. This variable dictates where water flows into channels from the land surface as well as in the channel. This should not be modified independently because it is tied to the DEM. - ``frxst_pts`` (optional) in :file:`Fulldom_hires.nc` - Forecast point grid, which specified selected channel pixels for which channel discharge and flow depth are to be output within a netcdf point file (CHANOBS) and/or an ASCII timeseries file (frxstpts_out.txt). - :file:`CHANPARM.TBL` text or :file:`Route_Link.nc` netcdf file - Specifies channel parameters by stream order (:file:`CHANPARM.TBL`, for gridded channel routing) or individual reaches (``route_link_f``, for reach-based routing methods) .. note:: Reach-based routing is highly sensitive to time step. 3.6.3 Compound Channel (limited configuration) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In order to represent a simplification of the behavior of a flood wave when it exceeds the channel bank, a compound channel formulation was added to WRF-Hydro. This option is currently only available when ``channel_option=2`` and ``udmp=1`` (so using user-defined mapping with the Muskingum-Cunge reach-based channel routing scheme). A visual representation is shown in Figure 3.9. When the depth of the flow exceeds bankfull (`d > d_b`), then the wave celerity is given as the weighted celerity of the trapezoidal flow and the overbank portion of flow. This weighting is based on the cross-sectional area of each, and allows water to enter the conceptual compound channel, where the Manning's coefficient of the compound channel portion, `n_{cc}`, is assumed rougher than the channel `n` by an unknown factor, `n_{cc}`. Based on a set of sensitivity experiments described in *Read et al., (2023)*, the default value is `n_{cc}=2n`, such that the floodplain roughness is twice that of the channel. The introduction of compound channel requires values for three more parameters: bankfull depth (`d_b`), top widths of the trapezoid and the compound channel, `T_w` and `T_{w\_cc},` respectively. These parameters, in addition to `n_{cc}`, are defined in the Route_Link.nc file. The default values were determined using a published equation from *Blackburn-Lynch et al., 2017*, who gathered regional USGS estimations of channel parameters and developed coefficients to describe the relationship of drainage area (`DA`) to `T_w` and to channel area (`A`). The aggregated CONUS equation is: `T_w = 2.44(DA)^{0.34}` and `A = 0.75(DA)^{0.53}`. Given these, `d_b` is determined using the standard equation for a trapezoid. As a default value, `T_{w\_cc}` is a multiplier on `T_w`. Sensitivity experiments presented in *Read et al. (2023)* found that `T_{w\_cc}=3*T_w` yielded the best streamflow performance, all else being equal. .. _figure3.9: .. figure:: media/trapezoid-compound-channel.png :align: center :scale: 50% **Figure 3.9** Cross-sectional schematic of trapezoidal channel and compound channel in National Water Model, where the dashed lines represent roughness of the channel n, and of the compound channel, `n_{cc}` .. note:: The compound channel option is currently only available when ``channel_option=2`` and ``udmp=1`` (so using user-defined mapping with the Muskingum-Cunge reach-based channel routing scheme). .. _section-3.7: 3.7 Lake and Reservoir Routing Description ------------------------------------------ A simple mass balance, level-pool lake/reservoir routing module allows for an estimate of the inline impact of small and large reservoirs on hydrologic response. A lake/reservoir or series of lakes/reservoirs are identified in the channel routing network, and lake/reservoir storage and outflow are estimated using a level-pool routing scheme. The only conceptual difference between lakes and reservoirs as represented in WRF-Hydro is that reservoirs contain both orifice and weir outlets for reservoir discharge while lakes only contain weirs. Note that the user must adjust these parameters accordingly - the model makes no other distinction between a reservoir and a lake. Fluxes into a lake/reservoir object occur through the channel network and when surface overland flow intersects a lake object (in the gridded channel routing configuration only). Fluxes from lake/reservoir objects are made only through the channel network and no fluxes from lake/reservoir objects to the atmosphere or the land surface are currently represented (i.e. there is currently no lake evaporation or subsurface exchange between the land surface and lakes and reservoirs). The Level Pool scheme tracks water elevation changes over time, `h(t)` where water from the reservoir can exit either through weir overflow (`Q_w`) and/or a gate-controlled flow (`Q_o`), where these outflows are functions of the water elevation and spillway parameters. Weir flow is given as `Q_w(t) = C_wLh^{\frac{3}{2}}; (3.29)` when `h>h_{max}` or `Q_w(t) = 0.0` when `h≤h_{max}` where, `h_{max}` is the maximum height before the weir begins to spill (`m`), `C_w` is a weir coefficient, and `L` is the length of the weir (`m`). Orifice flow is given as `Q_o(t) = C_oO_a\sqrt{2gh}; (3.30)` where `C_o` is the orifice coefficient, `O_a` is the orifice area (`m^2`), and `g` is the acceleration of gravity (`m/s^2`). In addition, the level pool scheme is designed to track each reservoir's surface area, `S_a` (`km^2`) as a function of water depth and the area at full storage, `A_s` (`km^2`). Presently, a lake/reservoir object is assumed to have vertical side walls, such that the surface area is always constant. .. _figure-3.10: .. figure:: media/level-pool.png :align: center :scale: 40% .. rst-class:: center .. math:: S_a(t) &= f(h, A_s) \\ Q_t(t) &= f(h) .. rst-class:: center **Figure 3.10** Schematic of Level Pool Routing The lake/reservoir parameters listed below are required for level-pool routing and are defined in the :file:`LAKEPARM.nc` parameter file. The GIS pre-processing tool can make this file and the model will read it as specified in the :file:`hydro.namelist` file. - Weir and Orifice Coefficients, `Cw`, `Co` in equations above or ``WeirC``, ``OrificeC`` in :file:`LAKEPARM.nc` - Weir Length (`m`), `L` in equations above or ``WeirL`` in :file:`LAKEPARM.nc` - Weir Elevation (`m`), ``WeirE`` in :file:`LAKEPARM.nc` - Orifice Area (`m^2`), `O_a` in equations above or ``OrificeA`` in :file:`LAKEPARM.nc` - Orifice Elevation (`m`), ``OrificeE`` in :file:`LAKEPARM.nc` - Reservoir Area (`km^2`), `A_s` in equations above or ``LkArea`` in :file:`LAKEPARM.nc` - Maximum reservoir height at full storage (`m`), `h_{max}` in equations above or ``LkMxE`` in :file:`LAKEPARM.nc` - Dam length specified as a multiplier on weir length (`dimensionless`), `Dam_Length` in :file:`LAKEPARM.nc` For the gridded channel routing option, the lake/reservoir routing options require lake objects to be defined and properly indexed as a data field in the high resolution terrain routing :file:`Fulldom_hires.nc` file. If lake/reservoir objects are present in the lake grid (and also within the channel network) then level-pool routing through those objects will occur if ``CHANRTSWCRT = 1`` (channel is active), ``channel_option = 3`` (gridded routing), and ``lake_option = 1`` (level pool) in :file:`hydro.namelist`. For reach-based channel routing options, the lake/reservoir routing options require lake objects to be defined and properly indexed as waterbody objects in the :file:`Route_Link.nc` file. If lake/reservoir objects are present in the :file:`Route_Link.nc` file then level-pool routing through those objects will occur if ``CHANRTSWCRT = 1`` (channel is active), ``channel_option = 1 or 2`` (reach routing), and ``lake_option = 1`` (level pool) in :file:`hydro.namelist`. The ``lake_option`` in :file:`hydro.namelist` can also be used to turn off lake/reservoir routing completely (``lake_option = 0``), set the waterbodies to simply pass water through from inflow to outflow with no storage or delay (``lake_option = 2``), or activate data assimilation (specific to the NOAA National Water Model and not currently supported outside of that configuration). There are several special requirements for the lake and channel files when lakes/reservoirs are to be represented and these are discussed in Sections :ref:`5.4 ` and :ref:`5.6 `. .. rubric:: Relevant code modules: :file:`Routing/module_channel_routing.F90` :file:`Routing/Reservoirs/Level_Pool/module_levelpool.F90` .. rubric:: Relevant namelist options: :file:`hydro.namelist`: - ``lake_option`` - Option to specify lake/reservoir routing behavior (0=lakes off, 1=level pool, 2=passthrough, 3=reservoir DA). - ``route_lake_f`` - Path to lake parameter file to support level-pool reservoir routing methods. .. note:: As mentioned in the paragraph above, if in the GIS-Preprocessing the user created a “gridded” routing stack for ``channel_option = 3`` (i.e. did *not* select to create a Route_Link.nc file for ``channel_option=1`` or ``=2``) AND specified a lake file (user provided a reservoir/lake input file), then the :file:`Fulldom_hires.nc` file will populate the ``LAKEGRID`` variable. For this case, the user **must** specify the route_lake_f file. To turn lakes “off” with ``channel_option=3``, create another set of :file:`Fulldom_hires.nc` (“domain”) files without a reservoir input file specified. .. rubric:: Relevant domain and parameter files/variables: - ``CHANNELGRID`` in :file:`Fulldom_hires.nc` - Channel network grid identifying the location of stream channel grid cells - ``LAKEGRID`` in :file:`Fulldom_hires.nc` (optional) - Specifies lake locations on the channel grid (for gridded channel routing methods, i.e. ``channel_option=3``). - :file:`Route_Link.nc` netCDF file (optional) - Specifies lake associations with channel reaches. - :file:`LAKEPARM.nc` netCDF file - Specifies lake parameters for each lake object specified. .. _section-3.8: 3.8 Conceptual base flow model description ------------------------------------------ Aquifer processes contributing baseflow often operate at depths well below ground surface. As such, there are often conceptual shortcomings in current land surface models in their representation of groundwater processes. Because these processes contribute to streamflow (typically as “baseflow”) a parameterization is often used in order to simulate total streamflow values that are comparable with observed streamflow from gauging stations. Therefore, a switch-activated baseflow module :file:`Routing/module_GW_baseflow.F90` has been created which conceptually (i.e. *not* physically-explicit) represents baseflow contributions to streamflow. This model option is particularly useful when WRF-Hydro is used for long-term streamflow simulation/prediction and baseflow or “low flow” processes must be properly accounted for. Besides potential calibration of the land surface model parameters the conceptual baseflow model does not directly impact the performance of the land surface model scheme. The new baseflow module is linked to WRF-Hydro through the discharge of “deep drainage” from the land surface soil column (sometimes referred to as “underground runoff”). The baseflow parameterization in WRF-Hydro uses spatially-aggregated drainage from the soil profile as recharge to a conceptual groundwater reservoir (:ref:`Fig. 3.10 `). The unit of spatial aggregation is often taken to be that of a catchment or sub-basin within a watershed. Each sub-basin has a groundwater reservoir “bucket” with a conceptual depth and associated conceptual volumetric capacity. The reservoir operates as a simple bucket where outflow (= “baseflow” or “stream inflow”) is estimated using an empirically-derived function of recharge. The functional type and parameters are determined empirically from offline tests using an estimation of baseflow from stream gauge observations and model-derived estimates of bucket recharge provided by WRF-Hydro. Presently, WRF-Hydro uses either a direct output-equals-input ("pass-through") relationship or an exponential storage-discharge function for estimating the bucket discharge as a function of a conceptual depth of water in the bucket ("exponential bucket"). Note that, because this is a highly conceptualized formulation, the depth of water in the bucket in no way infers the actual depth of water in a real aquifer system. However, the volume of water that exists in the bucket needs to be tracked in order to maintain mass conservation. Estimated baseflow discharged from the bucket model is then combined with lateral inflow from overland routing (if active) and input directly into the stream network as channel inflow, as referred to above in Section :ref:`3.5 `. Presently, the total basin baseflow flux to the stream network is equally distributed among all channel pixels within a basin for gridded channel routing options or dumped into the top of the reach to be routed downstream for reach-based methods. Lacking more specific information on regional groundwater basins, the groundwater/baseflow basins in WRF-Hydro are often assumed to match those of the surface topography. However, this is not a strict requirement. Buckets can be derived in a number of ways such as where true aquifers are defined or from a third-party hydrographic dataset such as the USGS NHDPlus or Hydrosheds. .. _figure-3.11: .. figure:: media/groundwater.svg :align: center :width: 70% **Figure 3.11** Hypothetical map of groundwater/baseflow sub-basins within a watershed and conceptualization of baseflow “bucket” parameterization in WRF-Hydro. \ | `z = z_{previous} + \frac{Q_{in}*dt}{A}; \qquad (3.40)` | | **if** `z > z_{max}` : | `z_{spill} = z - z_{max}` | `z = z_{max}` | `Q_{spill} = \frac{A*z_{spill}}{dt}` | | **else** : | `Q_{spill} = 0` | | `Q_{exp} = C(e^{E\frac{z}{zmax}}-1)` | `Q_{out} = Q_{spill} + Q_{exp}` | `z = z - \frac{Q_{exp}*dt}{A}` | | **where** : | `Q_{in}` is the inflow to the bucket aggregated from the bottom of the LSM in `m^3/s` | `z` is the height of the water level in the bucket in `mm` | `z_{max}` is the total height of the bucket in `mm` | `A` is the area of the catchment or groundwater basin in `m^2` | `E` is a unitless parameter | `C` is a parameter with units of `m^3/s` A groundwater/baseflow bucket model parameter file (:file:`GWBUCKPARM.nc`) specifies the empirical parameters governing the behavior of the bucket model parameterization for each groundwater/baseflow basin specified within the model domain. These files are created by the WRF-Hydro GIS Preprocessing System and documented in :ref:`Appendix 10 `. The parameters include: the bucket model coefficient, the bucket model exponent, the initial depth of water in the bucket model, and the maximum storage in the bucket before "spilling" occurs. It is important to remember that a simple bucket model is a highly abstracted and conceptualized representation of groundwater processes and therefore the depth of water values in the bucket and the parameters themselves have no real physical basis. As mentioned above, initial values of the groundwater bucket model parameters are typically derived analytically or \'offline\' from WRF-Hydro and then are fine-tuned through model calibration. There are 4 options available for the conceptual baseflow model, as specified in ``GWBASESWCRT`` in :file:`hydro.namelist`. The conceptual baseflow model can be turned off (``GWBASESWCRT = 0``), which means water draining from the soil column in the land surface model will become a sink term (this water will not be returned to the channel and will be a loss from the system). The exponential bucket model can be activated (``GWBASESWCRT = 1``), as described above. Water draining from the land model soil column can be placed directly into the channel with no additional storage/attenuation (``GWBASESWCRT = 2``). For configurations using user-defined mapping to specify catchment boundaries (``UDMP_OPT = 1``), there is a modified version of the exponential bucket model (``GWBASESWCRT = 4``) that adjusts the `C` parameter above based on the area of the catchment. .. rubric:: Relevant code modules: :file:`Routing/module_GW_baseflow.F90` .. rubric:: Relevant namelist options: :file:`hydro.namelist`: - ``GWBASESWCRT`` - Switch to activate groundwater bucket module. - ``GWBUCKPARM_file`` - Path to groundwater bucket parameter file. - ``gwbasmskfil`` (optional) - Path to netcdf groundwater basin mask file if using an explicit groundwater basin 2d grid. - ``UDMP_OPT`` (optional) - Switch to activate user-defined mapping between land surface model grid and conceptual basins. - ``udmap_file`` (optional) - If user-defined mapping is active, path to spatial-weights file. .. rubric:: Relevant domain and parameter files/variables: - :file:`GWBUCKPARM.nc` netCDF file - Specifies the parameters for each groundwater bucket/basin. More information regarding the groundwater bucket model parameters is provided in :ref:`Section 5.5 ` and :ref:`Appendix 10 `. - :file:`GWBASINS.nc` netCDF file - The 2d grid of groundwater basin IDs. - :file:`spatialweights.nc` - netCDF file specifying the weights to map between the land surface grid and the pre-defined groundwater basin boundaries. ================================================ FILE: docs/userguide/nudging.rest ================================================ .. vim: syntax=rst .. include:: meta.rest 4. Streamflow Nudging Data Assimilation ======================================= This chapter describes streamflow nudging and data assimilation in Version 5.0 and beyond of WRF-Hydro. Streamflow nudging was introduced in v1.1 of the National Water Model (NWM). The community WRF-Hydro model source code and the NWM source code have merged as of Version 5.0 of WRF-Hydro. See Appendix :ref:`A14 ` for more information on the NWM. 4.1 Streamflow Nudging Data Assimilation Overview ------------------------------------------------- For the National Water Model (NWM), a simple nudging data assimilation (DA) scheme has been developed to correct modeled stream flows to (or towards) observed values. The capability is only currently supported under the NWM configuration, but could be extended to NCAR reach-based routing, and potentially other kinds of routing, in the future. Specifically, the nudging capability introduces an interface for stream discharge observations to be applied to the Muskingum-Cunge streamflow routing solution. .. _section-4.2: 4.2 Nudging Formulation ----------------------- There are several motivations for performing DA. For the NWM analysis and assimilation cycle, the motivation is to improve model simulation and forecast initial conditions. Nudging is a simple and computationally inexpensive method of data assimilation where an observed state is inserted into the model with some uncertainty. When the observed value is inserted into the model without uncertainty, the method is referred to as “direct insertion”. Nudging works well locally to observations, both in space and time. Away from observations, in space and time, the method has limited success. For example, our application applies nudging data assimilation on a channel network with the advantage that the corrections are propagated downstream with the network flow. However, if no spatial or temporal smoothing of the corrections are included with the nudging method, upstream errors soon propagate past observed points when in the forecast (away from the observations, into the future). Various assumptions can be made to smooth the nudge (or correction) in space and/or time but these are highly parameterized and require tuning. In the NWM we have avoided spatial smoothing and have opted to pursue a very limited temporal-interpolation approach. The basic nudging equation solves `e_j`, the nudge, `e`, on a spatial element `j`, .. _equation-4.1: .. rst-class:: center .. math:: e_{j} = \frac{\sum_{n=1}^{N_j} q_{n}*w_{n}^{2}(j,t)*(Q_{n} - {\widehat{Q}}_{n})}{\sum_{n=1}^{N_j} w_{n}^{2}(j,t)} \qquad (4.1) The numerator is the sum, over the `N_j` observations affecting element `j`, of the product of each observations' quality coefficient, `q_n`, the model error, :math:`Q_{n} - {\widehat{Q}}_{n}`, and the squared weights. The weights is where most of the action happens. The weights determine how the nudge is interpolated in both space and time (`j,t`). The weights term `w_n(j,t)` in the above equation is solved for observation `n` as a function of both space, `j`, and time, `t`. It is expressed as the product of separate spatial and temporal weight terms: .. _equation-4.2: .. rst-class:: center .. math:: w_{n}(j,t) = w_{n_{s}}(j)\ *\ w_{n_{t}}(t,j) \qquad (4.2) The temporal weight term takes the following piecewise form in our application: .. _equation-4.3: .. rst-class:: center .. math:: w_{n_t}(t,j) = \begin{cases} 10^{10} * (1/10)^{\frac{\left| t-\widehat{t} \right|}{tau_j / 10}} &:\text{if} \ \left| t-\widehat{t} \right| \leq tau_j \\ e^{-a_j*(t-\widehat{t})} &:\text{if} \ \left| t-\widehat{t} \right| \gt tau_j \end{cases} \qquad (4.3) The spatial weight term is of the following form: .. _equation-4.4: .. rst-class:: center .. math:: w_{n_s} = \begin{cases} \frac{R_{n}^2 - d_{jn}^{2}}{R_{n}^2 + d_{jn}^2} &: \text{if} R_n > d_{jn} \\ 0 &: \text{otherwise} \end{cases} \qquad (4.4) The parameters specified in version 1.2 of the NWM (equivalent to this WRF-Hydro version 5) are: .. rst-class:: center | *tau = 15 minutes* | *a = 120 minutes* | *R = 0.25 meters* for all gages (all `j`) in CONUS (the parameter files are discussed below). The very short `R` means that nudging is applied locally, only to the reach where the observation is associated. There is currently no spatial smoothing. This is partly because spatial smoothing is assumed to be computationally intensive and has not been completely implemented. The `tau = 15` means that within 15 minutes of an observation we are heavily weighting the observation and `a = 120` means that nudging to the observation relaxes with e-folding time of two hours moving away from the observation. The Muskingum-Cunge equation in :ref:`Section 3.6.2 ` has the form: .. _equation-4.5: .. rst-class:: center .. math:: Q_{d}^{c} = C1{\,Q}_{u}^{p} + C2\,Q_{u}^{c} + {C3\,Q}_{d}^{p} + \left( \frac{q_{l}\,dt}{D} \right) \qquad (4.5) In v1.0 of the NWM, nudging was applied into this equation in the following manner .. _equation-4.6: .. rst-class:: center .. math:: Q_{d}^{c} = C1{\,Q}_{u}^{p} + C2\,Q_{u}^{c} + {C3\,(Q}_{d}^{p} + N_{d}^{p}) + \left( \frac{q_{l}\,dt}{D} \right) \qquad (4.6) where the discharge solution (`Q`) at the current time (`c`) at the downstream (`d`) reach was solved by applying the nudge from the previous timestep (`N_{d}^{p}`) to adjust the discharge of downstream reach at the previous (`p`) time. Experiments indicated undesirable side effects of introducing a discontinuity (the previous nudge) in discharge between the upstream (`u`) link and the downstream (`d`) link in this solution. With v1.2 of the NWM (equivalent to v5.0 WRF-Hydro), the equation was modified to include the nudge in the upstream terms of the solution as well, at both the previous and current times: .. _equation-4.7: .. rst-class:: center .. math:: Q_{d}^{c} = C1{(Q}_{u}^{p} + N_{d}^{p}) + C2{(Q}_{u}^{c} + N_{d}^{p}) + {C3(Q}_{d}^{p} + N_{d}^{p}) + \left( \frac{q_{l}\,dt}{D} \right) \qquad (4.7) This is the form of the equation currently used for nudging which aims to reduce the discontinuity in space between the upstream and downstream reaches. Experiments revealed that this formulation, significantly reduced the difference between modeled and observed discharge and hence the nudging magnitudes (over long time series of assimilated observations). Note that the nudge is only applied to the upstream reach during the solution of the downstream reach and is not applied in the output values of the upstream reach. This change in the nudging formulation also promotes the previous downstream nudge to a prognostic variable. Whereas `Q_{d}^{p} + N_{d}^{p}` was simply the previous downstream streamflow value after the nudge (already a prognostic model variable), adding the previous downstream nudge to the upstream solutions requires having the previous nudge available. Therefore, the previous downstream nudge values gets written to the nudgingLastObs files (described in :ref:`Section 4.3 `), which are the restart files for the nudging routine. There are a variety of experimental nudging options and features in the nudging section of the :file:`hydro.namelist` which are incomplete or unused at this time. There are also nudging features used in a limited capacity by the NWM which are not described here. As development of these options evolves, they will be documented in future versions of WRF-Hydro. .. _section-4.3: 4.3 Nudging Workflow -------------------- Figure 4.1 provides an overview of the nuding workflow at the file level. Descriptions are provided for each of the files shown in the diagram. .. figure:: media/nudging-workflow.svg :align: center :scale: 125% **Figure 4.1:** The nudging workflow at the file level. 4.3.1 Input Files ~~~~~~~~~~~~~~~~~ .. rubric:: Discharge observations and :file:`nudgingTimeSliceObs/` : Discharge observations from the real world enter the WRF-Hydro system through the :file:`nugingTimeSliceObs/` directory. The individual observation files used for streamflow nudging are stored in this directory, each with the the following naming convention :file:`YYYY-mm-dd_HH:MM:SS.RRmin.usgsTimeSlice.ncdf`. The first part of the filename, ``YYYY-mm-dd_HH:MM:SS``, identifies the center of the “slice of time” in which observations are found (from year down to second). ``RR`` indicates the resolution, or total width of the time slice. Currently this resolution is a **hard-coded** parameter in the model. It is set to 15 minutes as this is the most common reporting frequency for USGS gages in the USA. The ``usgsTimeSlice`` part of the filename is fixed and is legacy of the fact that these files were originally designed for USGS observations. However, any discharge observations can be placed into this format. The format of a an example timeslice observation file is given by an :program:`ncdump -h` in :ref:`Appendix A14 `. Of the three-dimensional variables, two are character lengths and only the ``stationIdInd`` dimension is variable (unlimited). The ``stationIdInd`` variable has dimensions of the number of individual stream gages contained in the file by the fixed width of the strings (``stationIdStrLen=15``). The variable metadata describes the contents. The ``stationId`` variable is the “USGS station identifier of length 15”. While the character type of the variable and the length of 15 are both fixed, identifiers are not limited to those used by the USGS. Custom identifiers can be used and are described later in this section when the gages variable in the :file:`Route_Link.nc` file is described. The variable ``discharge_quality`` is simply a multiplier. This value is stored as a short integer for space concerns and only takes values from zero to one hundred. Internally in the model, this variable is scaled by 100 and used as a floating point variable between zero and one. The ``queryTime`` variable is not used by the model and is optional. It may be useful in situations when the files are updated in real-time. Similarly, the metadata field ``fileUpdateTimeUTC`` can be useful but is not required by the model. The remaining two metadata fields are both required by the model: ``sliceCenterTimeUTC`` and ``sliceTimeResolutionMinutes`` ensure that the file and the model are operating under the same time location and resolution assumptions. An example of generating timeslice files from USGS observations using the R language is given in the help for the rwrfhydro function :command:`WriteNcTimeSlice`. .. rubric:: :file:`hydro.namelist`: When WRF-Hydro is compiled with nudging on, the :file:`hydro.namelist` file is required to contain ``&NUDGING_nlist``. The nudging namelist is found at the bottom of the :file:`hydro.namelist` file either in the :file:`Run/` directory after compilation or in the :file:`template/HYDRO/` directory. The namelist governs the run-time options to the nudging code. These run-time options are detailed in :ref:`Section 4.5 ` below and in :ref:`Appendix A5 `. .. rubric:: :file:`Route_Link.nc`: Collocation of streamflow gages and reach elements is achieved by the gages field in the :file:`Route_Link.nc` file (see Sections :ref:`3.6 ` and :ref:`5.4 `). Each reach element may have a single gage identified with it as specific by a fixed-width 15 character string in the gages field. A blank entry indicates no gage is present on the reach. The gages field in :file:`Route_Link.nc` tells the nudging module where to apply the observed values to the stream network. Gages which appear in the observation files but not in the :file:`Route_Link.nc` file do not cause a problem, they are simply skipped and their identifiers collected and printed to the file :file:`NWIS_gages_not_in_RLAndParams.txt` file, described later. The number of non-blank routelink gages must match the number of gages supplied in the nudging parameters file, described next. .. rubric:: :file:`nudgingParams.nc`: Appendix :ref:`A14 ` shows the structure of the :file:`nudgingParams.nc` file for a small domain. Some of the parameters in the file are explained in detail in Section :ref:`4.2 ` and some are placeholders for capabilities which have not been developed. 4.3.2 Output Files ~~~~~~~~~~~~~~~~~~ When the code is compiled with the nudging compile-time option on (see next section), four types of output files contain nudging information. Some files are different than when compiled without nudging while other files are unique outputs for the nuding option. .. rubric:: :file:`YYYYmmddHHMM.CHRTOUT_DOMAIN1`: The nudging code affects the values written to the “CHRTOUT” files. If valid observations are available, the (modeled) streamflow variable is changed by the assimilated observations. When the model is compiled to enable nudging, the variable ``nudge`` also appears in the file. The nudge value is calculated as in Section :ref:`4.2 `. .. rubric:: :file:`nudgingLastObs.YYYY-mm-dd_HH:MM:SS.nc`: These files are unique to the nudging compile and are the restart files for the nudging component of the model. A restart file is not required, nudging can be run from a cold start. This file can contain multiple variables, only the ``nudge`` variable is described in this documentation. .. rubric:: :file:`NWIS_gages_not_in_RLAndParams.txt`: These files are unique to nudging and report the unique gages found in the observation time slice files which were not present in the :file:`Route_Link.nc` file. These are gages which may have the opportunity to be assimilated (provided they could be located in the domain). There is only one such file per run, written at the end of the run. .. rubric:: Standard output and :file:`hydro_diag.*` files: The nudging routines write various messages. The ultimate destination of these can be compiler dependent. The nudging code aims to preface all its messages with ``Ndg:`` and all its warnings with ``Ndg: WARNING:``. 4.4 Nudging compile-time option ------------------------------- The nuding capability is only available when the code is compiled with the environment variable set: ``WRF_HYDRO_NUDGING=1`` .. _section-4.5: 4.5 Nudging run-time options ---------------------------- :ref:`Appendix A5 ` presents an annotated :file:`hydro.namelist` file. There are two Fortran namelists contained within that file. The nudging run-time options are contained the ``NUDGING_nlist`` which is the second namelist in the document. Only some run time options listed in the namelist are documented at this time. +-----------------------------------+---------------------------------------+ | **Documented/Supported Options** | **Undocumented/Unsupported Options** | +===================================+=======================================+ | ``timeSlicePath`` | ``nLastObs`` | | | | | ``nudgingParamFile`` | ``persistBias`` | | | | | ``nudgingLastObsFile`` | ``biasWindowBeforeT0`` | | | | | ``readTimesliceParallel`` | ``maxAgePairsBiasPersist`` | | | | | ``temporalPersistence`` | ``minNumPairsBiasPersist`` | | | | | | ``invDistTimeWeightBias`` | | | | | | ``noConstInterfBias`` | +-----------------------------------+---------------------------------------+ Details on the meaning and usage of the options are given in :ref:`Appendix A5 `, in both the comments which are part of the namelist itself and by the blue annotations added to the namelists. The supported options are fairly straight forward in their usage. It is worth noting that the specfication of the :file:`nudgingLastObsFile` does not behave the same way as the specification of the LSM or hydro restart files. The unsupported nudging options have to do with mostly experimental methods for forecast bias correction which have been investigated. ================================================ FILE: docs/userguide/output-tables/CHANOBS_DOMAIN.csv ================================================ Variable Name,Long Name,Description,Units,IO_ConfigOutputs_0,IO_ConfigOutputs_1,IO_ConfigOutputs_2,IO_ConfigOutputs_3,IO_ConfigOutputs_4,IO_ConfigOutputs_5,IO_ConfigOutputs_6,Min,Max,Scale,Offset,Fill time,valid output time,Valid output time,minutes since 1970-01-01 00:00:00 UTC,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A reference_time,model initialization time,Model initialization time,minutes since 1970-01-01 00:00:00 UTC,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A feature_id,Reach ID,Unique reach or channel cell ID,-,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A latitude,Feature latitude,Station latitude,decimal degrees,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A longitude,Feature longitude,Station longitude,decimal degrees,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A order,Streamflow Order,Strahler stream order for output reach or cell,-,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A elevation,Feature Elevation,Elevation for output reach or cell,m,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A streamflow,River Flow,Streamflow,m3 s-1,Yes,Yes,Yes,Yes,Yes,Yes,Yes,0,500000,0.01,0,-9999 ================================================ FILE: docs/userguide/output-tables/CHRTOUT_DOMAIN.csv ================================================ Variable Name,Long Name,Description,Units,IO_ConfigOutputs_0,IO_ConfigOutputs_1,IO_ConfigOutputs_2,IO_ConfigOutputs_3,IO_ConfigOutputs_4,IO_ConfigOutputs_5,IO_ConfigOutputs_6,Min,Max,Scale,Offset,Fill,Special Notes time,valid output time,Valid output time,minutes since 1970-01-01 00:00:00 UTC,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A, reference_time,model initialization time,Model initialization time,minutes since 1970-01-01 00:00:00 UTC,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A, feature_id,Reach ID,Unique reach or channel cell ID,-,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A, latitude,Feature latitude,Station latitude,decimal degrees,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A, longitude,Feature Longitude,Station longitude,decimal degrees,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A, order,Streamflow order,Strahler stream order for output reach or cell,-,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A, elevation,Feature Elevation,Elevation for output reach or cell,m,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A, streamflow,River Flow,Streamflow,m3 s-1,Yes,Yes,Yes,Yes,Yes,Yes,Yes,0,500000,0.01,0,-9999, nudge,Amount of stream flow alteration,Streamflow nudge value (only if nudging DA is active),m3 s-1,No,No,No,No,No,No,No,-500000,500000,0.01,0,-9999,Values only when nudging DA is active q_lateral,Runoff into channel reach,Lateral flow into channel reach or cell,m3 s-1,Yes,No,No,No,No,Yes,Yes,0,500000,0.1,0,-9999, velocity,River Velocity,Channel velocity,m s-1,Yes,Yes,Yes,Yes,Yes,Yes,Yes,0,500000,0.01,0,-9999, head,River Stage,River stage (gridded channel only),m,Yes,No,No,No,No,No,No,0,500000,0.01,0,-9999, qSfcLatRunoff,Runoff from terrain routing,Flux from terrain routing,m3 s-1,No,No,No,No,No,No,No,0,500000,0.001,0,-9999,Only available for UDMP_OPT=1 qBucket,Flux from gw bucket,Flux from groundwater buckets,m3 s-1,No,No,No,No,No,No,No,0,500000,0.001,0,-9999,Only available for UDMP_OPT=1 qBtmVertRunoff,Runoff from bottom of soil to bucket,Flux from bottom of soil column into groundwater buckets,m3,No,No,No,No,No,No,No,0,500000,0.001,0,-9999,Only available for UDMP_OPT=1 AccSfcLatRunoff,Accumulated runoff from terrain routing,Accumulated flux from terrain routing,m3,No,No,No,No,No,No,No,0,500000,0.01,0,-9999,Only available for UDMP_OPT=1 accBucket,Accumulated runoff from gw bucket,Accumulated flux from groundwater buckets,m3,No,No,No,No,No,No,No,0,500000,0.01,0,-9999,Only available for UDMP_OPT=1 ================================================ FILE: docs/userguide/output-tables/CHRTOUT_GRID.csv ================================================ Variable Name,Long Name,Description,Units,IO_ConfigOutputs_0,IO_ConfigOutputs_1,IO_ConfigOutputs_2,IO_ConfigOutputs_3,IO_ConfigOutputs_4,IO_ConfigOutputs_5,IO_ConfigOutputs_6,Min,Max,Scale,Offset,Fill time,valid output time,Valid output time,minutes since 1970-01-01 00:00:00 UTC,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A reference_time,model initialization time,Model initialization time,minutes since 1970-01-01 00:00:00 UTC,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A x,x coordinate of projection,x coordinate (in native projection),native projection units,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A y,y coordinate of projection,y coordinate (in native projection),native projection units,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A Index,Stream cell index value,Stream cell index value,-,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A streamflow,River Flow,Streamflow,m3 s-1,Yes,Yes,Yes,Yes,Yes,Yes,Yes,0,500000,0.1,0,-9999 ================================================ FILE: docs/userguide/output-tables/GWOUT_DOMAIN.csv ================================================ Variable Name,Long Name,Description,Units,IO_ConfigOutputs_0,IO_ConfigOutputs_1,IO_ConfigOutputs_2,IO_ConfigOutputs_3,IO_ConfigOutputs_4,IO_ConfigOutputs_5,IO_ConfigOutputs_6,Min,Max,Scale,Offset,Fill time,valid output time,Valid output time,minutes since 1970-01-01 00:00:00 UTC,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A reference_time,model initialization time,Model initialization time,minutes since 1970-01-01 00:00:00 UTC,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A feature_id,Groundwater Bucket ID,Unique groundwater bucket ID,-,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A inflow,Bucket Inflow,Total groundwater bucket inflow,m3 s-1,Yes,Yes,Yes,Yes,Yes,Yes,Yes,-10000,10000,0.01,0,-9999 outflow,Bucket Outflow,Total groundwater bucket outflow,m3 s-1,Yes,Yes,Yes,Yes,Yes,Yes,Yes,-10000,10000,0.01,0,-9999 depth,Bucket Depth,Groundwater bucket water level,mm,Yes,Yes,Yes,Yes,Yes,Yes,Yes,-10000,10000,0.1,0,-9999 ================================================ FILE: docs/userguide/output-tables/LAKEOUT_DOMAIN.csv ================================================ Variable Name,Long Name,Description,Units,IO_ConfigOutputs_0,IO_ConfigOutputs_1,IO_ConfigOutputs_2,IO_ConfigOutputs_3,IO_ConfigOutputs_4,IO_ConfigOutputs_5,IO_ConfigOutputs_6,Min,Max,Scale,Offset,Fill time,valid output time,Valid output time,minutes since 1970-01-01 00:00:00 UTC,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A reference_time,model initialization time,Model initialization time,minutes since 1970-01-01 00:00:00 UTC,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A feature_id,Lake COMMON ID,Unique lake ID,-,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A latitude,Lake latitude,Lake latitude,decimal degrees,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A longitude,Lake longitude,Lake longitude,decimal degrees,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A water_sfc_elev,Water Surface Elevation,Water surface elevation above sea level,m,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A inflow,Lake Inflow,Total inflow into waterbody,m3 s-1,Yes,Yes,Yes,Yes,Yes,Yes,Yes,-10000,10000,0.01,0,-9999 outflow,Lake Outflow,Outflow from waterbody outlet,m3 s-1,Yes,Yes,Yes,Yes,Yes,Yes,Yes,-10000,10000,0.01,0,-9999 ================================================ FILE: docs/userguide/output-tables/LDASOUT_DOMAIN.csv ================================================ Variable Name,Long Name,Description,Units,IO_ConfigOutputs_0,IO_ConfigOutputs_1,IO_ConfigOutputs_2,IO_ConfigOutputs_3,IO_ConfigOutputs_4,IO_ConfigOutputs_5,IO_ConfigOutputs_6,Min,Max,Scale,Offset,Fill time,valid output time,Valid output time,minutes since 1970-01-01 00:00:00 UTC,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A reference_time,model initialization time,Model initialization time,minutes since 1970-01-01 00:00:00 UTC,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A x,x coordinate of projection,x coordinate (in native projection),native projection units,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A y,y coordinate of projection,x coordinate (in native projection),native projection units,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A IVGTYP,Dominant vegetation category,Dominant vegetation category,category,Yes,No,No,No,No,No,No,0,100,1,0,-9999 ISLTYP,Dominant soil category,Dominant soil category,category,Yes,No,No,No,No,No,No,0,100,1,0,-9999 FVEG,Green Vegetation Fraction,Fraction of surface covered by vegetation,fraction,Yes,No,No,No,No,No,No,0,1,0.01,0,-9999 LAI,Leaf area index,Leaf area index,m2 m-2,Yes,No,No,No,No,No,No,0,20,0.1,0,-9999 SAI,Stem area index,Stem area index,m2 m-2,Yes,No,No,No,No,No,No,0,20,0.1,0,-9999 SWFORC,Shortwave forcing,Shortwave radiation forcing,W m-2,Yes,No,No,No,No,No,No,-1000,3000,0.1,0,-9999 COSZ,Cosine of zenith angle,Cosine of zenith angle,-,Yes,No,No,No,No,No,No,-1,1,0.01,0,-9999 LWFORC,Longwave forcing,Longwave radiation forcing,W m-2,Yes,No,No,No,No,No,No,-1500,1500,0.1,0,-9999 RAINRATE,Precipitation rate,Precipitation in model timestep,mm s-1,Yes,No,No,No,No,No,No,0,100,0.000001,0,-9999 EMISS,Grid emissivity,Emissivity: grid-average,-,Yes,No,No,No,No,No,No,0,1,0.01,0,-9999 FSA,Total absorbed SW radiation,Total absorbed SW radiation,W m-2,Yes,No,No,Yes,No,Yes,Yes,-1500,1500,0.1,0,-9999 FIRA,Total net LW radiation to atmosphere,Total net LW radiation (+ to atmosphere),W m-2,Yes,No,No,Yes,No,Yes,Yes,-1500,1500,0.1,0,-9999 GRDFLX,Heat flux into the soil,Ground heat flux: grid-average (+ to soil),W m-2,Yes,No,No,Yes,No,No,Yes,-1500,1500,0.1,0,-9999 HFX,Total sensible heat to the atmosphere,Sensible heat flux: grid-average (+ to atmosphere),W m-2,Yes,No,No,Yes,No,Yes,Yes,-1500,1500,0.1,0,-9999 LH,Total latent heat to the atmosphere,Latent heat flux: grid-average (+ to atmosphere),W m-2,Yes,No,No,Yes,No,Yes,Yes,-1500,1500,0.1,0,-9999 ECAN,Canopy water evaporation rate,Canopy water evaporation rate,kg m-2 s-1,Yes,No,No,No,No,No,No,-100,100,0.000001,0,-9999 EDIR,Direct from soil evaporation rate,Direct soil evaporation rate,kg m-2 s-1,Yes,No,No,No,No,No,No,-100,100,0.000001,0,-9999 ALBEDO,Surface albedo,Total-grid surface albedo,-,Yes,No,No,No,No,No,No,0,1,0.01,0,-9999 ETRAN,Transpiration rate,Transpiration rate,kg m-2 s-1,Yes,No,No,No,No,No,No,-100,100,0.000001,0,-9999 UGDRNOFF,Accumulated underground runoff,Underground runoff: accumulated,mm,Yes,No,No,Yes,Yes,Yes,Yes,-100,100000,0.01,0,-9999 SFCRNOFF,Accumulated surface runoff,Surface runoff: accumulated,mm,Yes,No,No,No,Yes,Yes,Yes,0,100000,0.001,0,-9999 CANLIQ,Canopy liquid water content,Canopy liquid water content,mm,Yes,No,No,No,No,No,No,-5,30000,0.01,0,-9999 CANICE,Canopy ice water content,Canopy ice water content,mm,Yes,No,No,No,No,No,No,-5,30000,0.01,0,-9999 ZWT,Depth to the water table,Depth to water table,m,Yes,No,No,No,No,No,No,0,10,0.00001,0,-9999 WA,Water in aquifer,Water in aquifer relative to reference level,kg m-2,Yes,No,No,No,No,No,No,0,10000,0.01,0,-9999 WT,Water in aquifer and saturated soil,Water in aquifer and saturated soil,kg m-2,Yes,No,No,No,No,No,No,0,10000,0.01,0,-9999 ACCPRCP,Accumulated precip,Accumulated precipitation,mm,Yes,No,No,No,No,No,No,0,1000000,0.01,0,-9999 ACCECAN,Accumulated canopy water,Accumulated canopy evaporation,mm,Yes,No,No,Yes,No,No,Yes,-100,1000000,0.01,0,-9999 ACCEDIR,Accumulated direct soil evap,Accumulated direct soil evaporation,mm,Yes,No,No,Yes,No,No,Yes,-100,1000000,0.01,0,-9999 ACCETRAN,Accumulated transpiration,Accumulated transpiration,mm,Yes,No,No,Yes,No,No,Yes,-100,1000000,0.01,0,-9999 SAV,Solar radiative heat flux aborbed by vegetation,Solar radiation absorbed: vegetation canopy,W m-2,Yes,No,No,No,No,No,No,-1500,1500,0.1,0,-9999 TR,Transpiration heat,Transpiration heat flux,W m-2,Yes,No,No,No,No,No,No,-1500,1500,0.1,0,-9999 EVC,Canopy evap heat,Latent heat flux: leaf to canopy air,W m-2,Yes,No,No,No,No,No,No,-1500,1500,0.1,0,-9999 IRC,Canopy net LW rad,Net emitted LW radiation: canopy,W m-2,Yes,No,No,No,No,No,No,-1500,1500,0.1,0,-9999 SHC,Canopy sensible heat,Sensible heat flux: leaf to canopy air,W m-2,Yes,No,No,No,No,No,No,-1500,1500,0.1,0,-9999 IRG,Ground net LW rad,Net emitted LW radiation: below-canopy ground,W m-2,Yes,No,No,No,No,No,No,-1500,1500,0.1,0,-9999 SHG,Ground sensible heat,Sensible heat flux: below-canopy ground to canopy air,W m-2,Yes,No,No,No,No,No,No,-1500,1500,0.1,0,-9999 EVG,Ground evap heat,Latent heat flux: below-canopy ground to canopy air,W m-2,Yes,No,No,No,No,No,No,-1500,1500,0.1,0,-9999 GHV,Ground heat flux + to soil vegetated,Ground heat flux: vegetated fraction (+ to soil),W m-2,Yes,No,No,No,No,No,No,-1500,1500,0.1,0,-9999 SAG,Solar radiative heat flux absorved by ground,Solar radiation absorbed: ground surface,W m-2,Yes,No,No,No,No,No,No,-1500,1500,0.1,0,-9999 IRB,Net LW rad to atm bare,Net emitted LW radiation: bare ground,W m-2,Yes,No,No,No,No,No,No,-1500,1500,0.1,0,-9999 SHB,Sensible heat atm bare,Sensible heat flux: bare ground to atmosphere,W m-2,Yes,No,No,No,No,No,No,-1500,1500,0.1,0,-9999 EVB,Evaporation heat to atm bare,Latent heat flux: bare ground to atmosphere,W m-2,Yes,No,No,No,No,No,No,-1500,1500,0.1,0,-9999 GHB,Ground heat flux + to soil bare,Ground heat flux: bare ground fraction (+ to soil),W m-2,Yes,No,No,No,No,No,No,-1500,1500,0.1,0,-9999 TRAD,Surface radiative temperature,Surface radiative temperature: grid,K,Yes,No,No,Yes,No,Yes,Yes,0,400,0.1,0,-9999 TG,Ground temperature,Ground temperature: grid-average,K,Yes,No,No,No,No,No,No,0,400,0.1,0,-9999 TV,Vegetation temperature,Vegetation leaf temperature,K,Yes,No,No,No,No,No,No,0,400,0.1,0,-9999 TAH,Canopy air temperature,Canopy air temperature,K,Yes,No,No,No,No,No,No,0,400,0.1,0,-9999 TGV,Ground surface Temp vegetated,Ground temperature: vegetated ground,K,Yes,No,No,No,No,No,No,0,400,0.1,0,-9999 TGB,Ground surface Temp bare,Ground temperature: bare ground,K,Yes,No,No,No,No,No,No,0,400,0.1,0,-9999 T2MV,2m Air Temp vegetated,Air temperature @ 2m: vegetated ground,K,Yes,No,No,No,No,No,No,0,400,0.1,0,-9999 T2MB,2m Air Temp bare,Air temperature @ 2m: bare ground,K,Yes,No,No,No,No,No,No,0,400,0.1,0,-9999 Q2MV,2m mixing ratio vegetated,Mixing ratio @ 2m: vegetated ground,kg/kg,Yes,No,No,No,No,No,No,0,1,0.0001,0,-9999 Q2MB,2m mixing ratio bare,Mixing ratio @ 2m: bare ground,kg/kg,Yes,No,No,No,No,No,No,0,1,0.0001,0,-9999 EAH,Canopy air vapor pressure,Canopy air vapor pressure,Pa,Yes,No,No,No,No,No,No,-1000,100000,0.1,0,-9999 FWET,Wetted or snowed fraction of canopy,Fraction of canopy covered by liquid or frozen water,fraction,Yes,No,No,No,No,No,No,0,1,0.01,0,-9999 ZSNSO_SN,Snow layer depths from snow surface,Snow and soil interface depths (from snow surface),m,Yes,No,No,No,No,No,No,-100,100,0.00001,0,-9999 SNICE,Snow layer ice,Snow layer ice,mm,Yes,No,No,No,No,No,No,0,100000,0.01,0,-9999 SNLIQ,Snow layer liquid water,Snow layer liquid water,mm,Yes,No,No,Yes,No,No,Yes,0,100000,0.01,0,-9999 SOIL_T,soil temperature,Soil temperature,K,Yes,No,No,Yes,No,No,Yes,0,400,0.1,0,-9999 SOIL_W,liquid volumetric soil moisture,Volumetric soil moisture: liquid,m3 m-3,Yes,No,No,No,No,Yes,Yes,0,1,0.01,0,-9999 SNOW_T,snow temperature,Snow temperature,K,Yes,No,No,No,No,No,No,0,400,0.1,0,-9999 SOIL_M,volumetric soil moisture,Volumetric soil moisture,m3 m-3,Yes,No,No,Yes,No,Yes,Yes,0,1,0.01,0,-9999 SNOWH,Snow depth,Snow depth,m,Yes,Yes,Yes,Yes,No,Yes,Yes,0,100,0.0001,0,-9999 SNEQV,Snow water equivalent,Snow water equivalent,kg m-2,Yes,Yes,Yes,Yes,Yes,Yes,Yes,0,100000,0.1,0,-9999 QSNOW,Snowfall rate,Snowfall rate at ground surface,mm s-1,Yes,No,No,No,No,No,No,0,100,0.000001,0,-9999 ISNOW,Number of snow layers,Number of active snow layers,count,Yes,No,No,Yes,No,No,Yes,0,10,1,0,-9999 FSNO,Snow-cover fraction on the ground,Fraction of surface covered by snow,fraction,Yes,Yes,Yes,Yes,No,Yes,Yes,0,1,0.001,0,-9999 ACSNOW,accumulated snow fall,Accumulated snow fall,mm,Yes,No,No,No,No,No,No,0,100000,0.01,0,-9999 ACSNOM,accumulated melting water out of snow bottom,Accumulated melting water out of snow bottom,mm,Yes,No,No,Yes,Yes,No,Yes,0,100000,0.01,0,-9999 CM,Momentum drag coefficient,Exchange coefficient: grid-average,-,Yes,No,No,No,No,No,No,-5,5,0.00001,0,-9999 CH,Sensible heat exchange coefficient,Exchange coefficient: grid-average,-,Yes,No,No,No,No,No,No,-5,5,0.00001,0,-9999 CHV,Exchange coefficient vegetated,Exchange coefficient: vegetation-atmosphere,m s-1,Yes,No,No,No,No,No,No,-5,5,0.00001,0,-9999 CHB,Exchange coefficient bare,Exchange coefficient: bare ground,m s-1,Yes,No,No,No,No,No,No,-5,5,0.00001,0,-9999 CHLEAF,Exchange coefficient leaf,Exchange coefficient: leaf surface,m s-1,Yes,No,No,No,No,No,No,-5,5,0.00001,0,-9999 CHUC,Exchange coefficient bare,Exchange coefficient: below-canopy,m s-1,Yes,No,No,No,No,No,No,-5,5,0.00001,0,-9999 CHV2,Exchange coefficient 2-meter vegetated,Exchange coefficient: vegetation-atmosphere @ 2-meters,m s-1,Yes,No,No,No,No,No,No,-5,5,0.00001,0,-9999 CHB2,Exchange coefficient 2-meter bare,Exchange coefficient: bare ground @ 2-meters,m s-1,Yes,No,No,No,No,No,No,-5,5,0.00001,0,-9999 LFMASS,Leaf mass,Leaf carbon mass,g C m-2,Yes,No,No,No,No,No,No,0,1000,0.01,0,-9999 RTMASS,Mass of fine roots,Root carbon mass,g C m-2,Yes,No,No,No,No,No,No,0,1000,0.01,0,-9999 STMASS,Stem mass,Stem carbon mass,g C m-2,Yes,No,No,No,No,No,No,0,1000,0.01,0,-9999 WOOD,Mass of wood and woody roots,Wood and woody roots carbon mass,g C m-2,Yes,No,No,No,No,No,No,0,1000,0.01,0,-9999 STBLCP,Stable carbon in deep soil,Stable carbon in deep soil,g C m-2,Yes,No,No,No,No,No,No,0,5000,0.01,0,-9999 FASTCP,Short-lived carbon in shallow soil,Short-lived carbon in shallow soil,g C m-2,Yes,No,No,No,No,No,No,0,5000,0.01,0,-9999 NEE,Net ecosystem exchange,Net ecosystem exchange,g m-2 s-1 CO2,Yes,No,No,No,No,No,No,0,1000,0.01,0,-9999 GPP,Net instantaneous assimilation,Net instantaneous carbon assimilation,g m-2 s-1 C,Yes,No,No,No,No,No,No,0,1000,0.01,0,-9999 NPP,Net primary productivity,Net primary productivity,g m-2 s-1 C,Yes,No,No,No,No,No,No,0,1000,0.01,0,-9999 PSN,Total photosynthesis,Total photosynthesis,umol CO2 m-2 s-1,Yes,No,No,No,No,No,No,0,1000,0.01,0,-9999 APAR,Photosynthesis active energy by canopy,Absorbed photosynthetically active radiation,W m-2,Yes,No,No,No,No,No,No,0,1000,0.01,0,-9999 ACCET,Accumulated total ET,Accumulated total evapotranspiration,mm,Yes,Yes,Yes,Yes,Yes,Yes,Yes,-1000,1000000,0.01,0,-9999 CANWAT,Total canopy water (liquid + ice),Total canopy water (liquid + ice),mm,Yes,No,No,Yes,Yes,No,Yes,-5,30000,0.01,0,-9999 SOILICE,fraction of soil moisture that is ice,Fraction of soil moisture that is ice,fraction,Yes,No,No,Yes,No,No,Yes,0,1,0.01,0,-9999 SOILSAT_TOP,fraction of soil saturation (top 2 layers),Fraction of soil saturation (top 2 layers),fraction,Yes,Yes,Yes,Yes,Yes,No,Yes,0,1,0.001,0,-9999 SOILSAT,fraction of soil saturation (column integrated),Fraction of soil saturation (column integrated),fraction,Yes,No,No,No,Yes,No,Yes,0,1,0.001,0,-9999 SNOWT_AVG,average snow temperature (by layer mass),Average snow temperature (by layer mass),K,Yes,Yes,Yes,Yes,No,No,Yes,0,400,0.1,0,-9999 ALBSND,snowpack albedo (direct),Snowpack albedo (direct),-,Yes,No,No ,No,No,Yes,Yes,0,1,0.01,0,-9999 ALBSNI,snowpack albedo (diffuse),Snowpack albedo (diffuse),-,Yes,No,No,No,No ,Yes,Yes,0,1,0.01,0,-9999 ================================================ FILE: docs/userguide/output-tables/LSMOUT.csv ================================================ Variable Name,Long Name,Description,Units,IO_ConfigOutputs_0,IO_ConfigOutputs_1,IO_ConfigOutputs_2,IO_ConfigOutputs_3,IO_ConfigOutputs_4,IO_ConfigOutputs_5,IO_ConfigOutputs_6,, time,valid output time,Valid output time,minutes since 1970-01-01 00:00:00 UTC,Yes,Yes,Yes,Yes,Yes,Yes,Yes,, reference_time,model initialization time,Model initialization time,minutes since 1970-01-01 00:00:00 UTC,Yes,Yes,Yes,Yes,Yes,Yes,Yes,, x,x coordinate of projection,x coordinate (in native projection),native projection units,Yes,Yes,Yes,Yes,Yes,Yes,Yes,, y,y coordinate of projection,x coordinate (in native projection),native projection units,Yes,Yes,Yes,Yes,Yes,Yes,Yes,, stc1,Soil temperature in the top layer,Soil temperature in the top layer,K,Yes,Yes,Yes,Yes,Yes,Yes,Yes,, smc1,Soil moisture in the top layer,Volumetric soil moisture in the top layer,m3 m-3,Yes,Yes,Yes,Yes,Yes,Yes,Yes,, sh2ox1,Volumetric soil moisture in the top layer,Liquid water in the top layer,m3 m-3,Yes,Yes,Yes,Yes,Yes,Yes,Yes,, stc2,Soil temperature in the second layer,Soil temperature in the second layer,K,Yes,Yes,Yes,Yes,Yes,Yes,Yes,, smc2,Soil moisture in the second layer,Volumetric soil moisture in the second layer,m3 m-3,Yes,Yes,Yes,Yes,Yes,Yes,Yes,, sh2ox2,Volumetric soil moisture in the second layer,Liquid water in the second layer,m3 m-3,Yes,Yes,Yes,Yes,Yes,Yes,Yes,, stc3,Soil temperature in the third layer,Soil temperature in the third layer,K,Yes,Yes,Yes,Yes,Yes,Yes,Yes,, smc3,Soil moisture in the third layer,Volumetric soil moisture in the third layer,m3 m-3,Yes,Yes,Yes,Yes,Yes,Yes,Yes,, sh2ox3,Volumetric soil moisture in the third layer,Liquid water in the third layer,m3 m-3,Yes,Yes,Yes,Yes,Yes,Yes,Yes,, stc4,Soil temperature in the fourth layer,Soil temperature in the bottom layer,K,Yes,Yes,Yes,Yes,Yes,Yes,Yes,, smc4,Soil moisture content in the fourth layer,Volumetric soil moisture in the bottom layer,m3 m-3,Yes,Yes,Yes,Yes,Yes,Yes,Yes,, sh2ox4,Volumetric soil moisture in the fourth layer,Liquid water in the bottom layer,m3 m-3,Yes,Yes,Yes,Yes,Yes,Yes,Yes,, infxsrt,Infiltration excess,Infiltration excess (from LSM),mm,Yes,Yes,Yes,Yes,Yes,Yes,Yes,, sfcheadrt,Surface head,Surface head (from HYDRO),mm,Yes,Yes,Yes,Yes,Yes,Yes,Yes,, ================================================ FILE: docs/userguide/output-tables/RTOUT_DOMAIN.csv ================================================ Variable Name,Long Name,Description,Units,IO_ConfigOutputs_0,IO_ConfigOutputs_1,IO_ConfigOutputs_2,IO_ConfigOutputs_3,IO_ConfigOutputs_4,IO_ConfigOutputs_5,IO_ConfigOutputs_6,Min,Max,Scale,Offset,Fill time,valid output time,Valid output time,minutes since 1970-01-01 00:00:00 UTC,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A reference_time,model initialization time,Model initialization time,minutes since 1970-01-01 00:00:00 UTC,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A x,x coordinate of projection,x coordinate (in native projection),native projection units,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A y,y coordinate of projection,x coordinate (in native projection),native projection units,Yes,Yes,Yes,Yes,Yes,Yes,Yes,N/A,N/A,N/A,N/A,N/A SOIL_M,volumetric soil moisture,Volumetric soil moisture,m3 m-3,Yes,No,No,No,No,No,No,0,1,0.01,0,-9999 zwattablrt,water table depth,Depth to saturated layers (=2m when no saturation; =0 when fully saturated),m,Yes,Yes,Yes,Yes,Yes,Yes,Yes,0,10,0.1,0,-9999 sfcheadsubrt,surface head,Instantaneous value of depth of ponded water on surface,mm,Yes,Yes,Yes,Yes,Yes,Yes,Yes,0,1000000,1,0,-9999 QSTRMVOLRT,channel inflow,Accumulated depth of stream channel inflow,mm,Yes,No,No,No,No,No,No,0,1000,1,0,-9999 QBDRYRT,accumulated value of the boundary flux,Accumulated flow volume routed outside of the domain from the boundary cells,mm,Yes,No,No,No,No,No,No,0,1000,1,0,-9999 ================================================ FILE: docs/userguide/references.rest ================================================ .. vim: syntax=rst REFERENCES ========== Below are cited references in an alphabetical listing by author. Ball, J. T., I. E. Woodrow, and J. A. Berry (1987), A model predicting stomatal conductance and its contribution to the control of photosynthesis under different environmental conditions, in Process in Photosynthesis Research, vol. 1, edited by J. Biggins, pp. 221–234, Martinus Nijhoff, Dordrecht, Netherlands. Bowling, L.C., D.P. Lettenmaier, B. Nijssen, L.P. Graham and co-authors, 2003: Simulation of high latitude hydrological processes in the Torne-Kalix basin: PILPS Phase 2(c) 1: Experiment description and summary intercomparisons. Global and Planet. Change Brun, E., Martin, E., Simon, V., Gendre, C., and Coléou, C.: An energy and mass model of snow cover suitable for operational avalanche forecasting, J. Glaciol., 35, 333-342, https://doi.org/10.3189/S0022143000009254, 1989. Brun, E., David, P., Sudul, M., and Brunot, G.: A numer- ical model to simulate snow-cover stratigraphy for operational avalanche forecasting, J. Glaciol., 38, 13-22, https://doi.org/10.3189/S0022143000009552, 1992. Brun, E., Martin, E., and Spiridonov, V.: Coupling a multi- layered snow model with a GCM, Ann. Glaciol., 25, 66-72, https://doi.org/10.3189/S0260305500013811, 1997. Bryan, F. O., B. G. Kauffman, W. G. Large, and P. R. Gent (1996). The NCAR CSM flux coupler, NCAR Tech. Note 424, 50 pp. [Available from NCAR, Boulder, CO 80307] Chen, F., K.E. Mitchell, J. Schaake, Y. Xue, H.-L. Pan, V. Koren, Q.Y. Duan, M. Ek and A. Betts, 1996: Modeling of land-surface evaporation by four schemes and comparison with FIFE observations. J. Geophys. Res., 101, 7251-7268. Chen, F., Z. Janic and K.E. Mitchell, 1997: Impact of atmospheric surface-layer parameterizations in the new land-surface scheme of the NCEP mesoscale Eta model. Bound.-Layer Meteorol., 85, 391-421. Chen, F. and K.E. Mitchell, 1999: Using the GEWEX/ISLSCP forcing data to simulate global soil moisture fields and hydrological cycle for 1987-1988, J. Meteorol. Soc. Japan, 77, 167-182. Dickinson, R. E., M. Shaikh, R. Bryant, and L. Graumlich (1998), Interactive canopies for a climate model, J. Clim., 11, 2823-2836, doi:10.1175/1520-0442. Dirmeyer, P.A., A.J. Dolman, N. Sato, 1999: The pilot phase of the Global Soil Wetness Project. Bull. Am. Meteorol. Soc., 80(5), 851-878. Eidhammer, T., A. Booth, S. Decker, L. Li, M. Barlage., D. Gochis., R. Rasmussen, K. Melvold., A. Nesje and S Sobolowski (2021), Mass balance and hydrological modeling of the Hardangerjøkulen ice cap in south-central Norway, Hydrol. Earth Syst. Sci. 25, 4275-4297, https://doi.org/10.5194/hess-25-4275-2021. Ek, M.B., K.E. Mitchell, Y. Lin, E. Rogers, P. Grunmann, V. Koren, G. Gayno, and J.D. Tarpley, 2003: Implementation of Noah land surface model advances in the NCEP operational mesoscale Eta model. Submitted to J. Geophys. Res., Aug., 2003. Gerbaux, M., Genthon, C., Etchevers, P., Vincent, C., and Dedieu, J.: Surface mass balance of glacier in the French Alps: Dis- tributed modeling sensitivity to climate change, J. Glaciol., 175, 561-572, https://doi.org/10.3189/172756505781829133, 2005. Gochis, D.J. and F. Chen, 2003: Hydrological enhancements to the community Noah land surface model. NCAR Technical Note, NCAR/TN-454+STR, 68 pgs. Jones, P. W. (1999). First- and Second-Order Conservative Remapping Schemes for Grids in Spherical Coordinates, Monthly Weather Review, Volume 127, 2204-2210. Julien, P.Y., B. Saghafian and F.L. Ogden, 1995: Raster-based hydrological modeling of spatially-varied surface runoff. Water Resour. Bull., AWRA, 31(3), 523-536. Koren, V., J.C. Schaake, K.E. Mitchell, Q.Y. Duan, F. Chen and J. Baker, 1999: A parameterization of snowpack and frozen ground intended for NCEP weather and climate models. J. Geophys. Res., 104(D16), 19,569-19,585. LDAS, 2003: Land Data Assimilation Systems (LDAS). World Wide Web Homepage. Available online at: http://ldas.gsfc.nasa.gov/ Mahrt, L. and H.-L. Pan, 1984: A two-layer model of soil hydrology. Bound.-Layer Meteorol., 29, 1-20, 1984. Niu, G.-Y., et al. (2011), The community Noah land surface model with multiparameterization options (Noah-MP): 1. Model description and evaluation with local-scale measurements, J. Geophys. Res. 116, D12109, doi: 10.1029/2010JD015139. Niu, G.-Y., and Z.-L. Yang (2004), The effects of canopy processes on snow surface energy and mass balances, J. Geophys. Res., 109, D23111, doi:10.1029/2004JD004884. Niu, G.-Y., Z.-L. Yang, R. E. Dickinson, L. E. Gulden, and H. Su (2007), Development of a simple groundwater model for use in climate models and evaluation with Gravity Recovery and Climate Experiment data, J. Geophys. Res., 112, D07103, doi:10.1029/2006JD007522. Ogden, F.L., 1997: CASC2D Reference Manual. Dept. of Civil and Evniron. Eng. U-37, U. Connecticut, 106 pp. Pan, H.-L. and L. Mahrt, 1987: Interaction between soil hydrology and boundary-layer development, Bound.-Layer Meteorol., 38, 185-202. Skamarock, W. C., J. B. Klemp, J. Dudhia, D. O. Gill, D. M. Barker, W. Wang, and J. G. Powers, 2005: A Description of the Advanced Research WRF Version 2. NCAR Technical Note NCAR/TN-468+STR, doi:10.5065/D6DZ069T. Vionnet, V., Brun, E., Morin, S., Boone, A., Faroux, S., Le Moigne, P., Martin, E., and Willemet, J.-M.: The detailed snowpack scheme Crocus and its implementation in SURFEX v7.2, Geosci. Model Dev., 5, 773-791, https://doi.org/10.5194/gmd-5-773- 2012, 2012. Wigmosta, M.S. L.W. Vail and D.P. Lettenmaier, 1994: A distributed hydrology-vegetation model for complex terrain. Water Resour. Res., 30(6), 1665-1679. Wigmosta, M.S. and D.P. Lettenmaier, 1999: A comparison of simplified methods for routing topographically driven subsurface flow. Water Resour. Res., 35(1), 255-264. Wood, E.F., D.P. Lettenmaier, X. Kian, D. Lohmann, A. Boone, S. Chang, F.Chen, Y. Dai, R.E. Dickinson, Q. Duan, M. Ek, Y.M. Gusev, F. Habets, P. Irannejad, R. Koster, K.E. Mitchell, O.N. Nasonova, J. Noilhan, J. Schaake, A. Schlosser, Y. Shao, A.B. Shmakin, D. Verseghy, K. Warrach, P. Wetzel, Y. Xue, Z.-L. Yang, and Q.-C. Zeng, 1998: The project for intercomparison of land-surface parameterization schemes (PILPS) phase 2(c) Red-Arkansas river basin experiment: 1. Experiment description and summary intercomparisons, Global Planet. Change, 19, 115-135. Yang, Z.-L., and G.-Y. Niu (2003), The versatile integrator of surface and atmosphere processes (VISA) part I: Model description, Global Planet. Change, 38, 175–189, doi:10.1016/S0921-8181(03)00028-6. ESMF (Earth System Modeling Framework) https://www.earthsystemcog.org/projects/esmf/ USGS Global Land Cover Characterization https://www.usgs.gov/centers/eros/science/usgs-eros-archive-landcover-products-global-land-cover-characterization-glcc-0?qt-science_center_objects=0#qt-science_center_objectsTableLegend:Appendix3 https://edcftp.cr.usgs.gov/project/glcc/globdoc2_0.html#app3 IGBP_MODIS_BU+tundra Landcover Class Legend ftp://ftp.emc.ncep.noaa.gov/mmb/gcp/ldas/noahlsm/README NCL (NCAR Command Language) https://www.ncl.ucar.edu/ CDO (Climate Data Operators) https://code.mpimet.mpg.de/projects/cdo/ ================================================ FILE: src/.nwm_version ================================================ v3.1 ================================================ FILE: src/.version ================================================ v5.4.0 ================================================ FILE: src/CMakeLists.txt ================================================ if(${PROJECT_NAME} STREQUAL "WRF") # additions that WRF-Hydro's top CMakeLists.txt handles add_compile_options( "${PROJECT_COMPILE_OPTIONS}" ) add_compile_definitions( "${PROJECT_COMPILE_DEFINITIONS}" ) set(CMAKE_Fortran_MODULE_DIRECTORY ${PROJECT_BINARY_DIR}/hydro/mods) add_definitions(-DMPP_LAND) if (WRF_HYDRO_NUDGING STREQUAL "1") add_definitions(-DWRF_HYDRO_NUDGING=1) endif() endif() # build the various sup-projects add_subdirectory("MPP") add_subdirectory("utils") add_subdirectory("IO") add_subdirectory("OrchestratorLayer") add_subdirectory("Debug_Utilities") add_subdirectory("Routing/Overland") add_subdirectory("Routing/Subsurface") add_subdirectory("Routing/Reservoirs") add_subdirectory("Routing/Diversions") add_subdirectory("Data_Rec") add_subdirectory("Routing") add_subdirectory("HYDRO_drv") if(${PROJECT_NAME} STREQUAL "WRF") add_subdirectory("CPL/WRF_cpl") endif() if (WRF_HYDRO_NUDGING_IO STREQUAL "1" OR WRF_HYDRO_NUDGING STREQUAL "1") add_subdirectory("nudging/io") add_dependencies(hydro_routing hydro_nudging_io) endif() if (WRF_HYDRO_NUDGING STREQUAL "1") add_subdirectory("nudging") add_dependencies(hydro_routing hydro_nudging) add_dependencies(hydro_driver hydro_nudging) endif() if (WRF_HYDRO_NUOPC STREQUAL "1") add_subdirectory("CPL/NUOPC_cpl") endif() # add module dependencies add_dependencies(hydro_debug_utils hydro_mpp) add_dependencies(hydro_utils hydro_mpp) add_dependencies(hydro_orchestrator hydro_netcdf_layer) add_dependencies(hydro_routing hydro_mpp hydro_routing_overland hydro_routing_subsurface hydro_routing_reservoirs hydro_routing_reservoirs_levelpool hydro_routing_reservoirs_hybrid hydro_utils ) add_dependencies(hydro_routing_reservoirs_hybrid hydro_routing_reservoirs_levelpool) add_dependencies(hydro_routing_overland hydro_mpp) # currently unused Routing/Groundwater directory # add_subdirectory("Routing/Groundwater") # add_dependencies(hydro_routing # hydro_routing_groundwater # hydro_routing_groundwater_bucket # hydro_routing_groundwater_nhd # hydro_routing_groundwater_simple # ) # add_dependencies(hydro_routing_groundwater hydro_mpp) # add_dependencies(hydro_routing_groundwater_bucket hydro_routing_groundwater) # add_dependencies(hydro_routing_groundwater_simple # hydro_routing_groundwater # hydro_routing_groundwater_bucket # ) # add_dependencies(hydro_routing_groundwater_nhd # hydro_routing_groundwater # hydro_routing_groundwater_bucket # ) add_dependencies(hydro_driver hydro_routing hydro_debug_utils ) add_dependencies(hydro_data_rec hydro_routing_overland hydro_routing_subsurface hydro_routing_reservoirs ) if (HYDRO_LSM MATCHES "NoahMP") message("-- Building NoahMP LSM") add_subdirectory("Land_models/NoahMP") add_subdirectory("CPL/NoahMP_cpl") add_dependencies(hydro_noahmp_cpl hydro_routing) add_dependencies(hydro_noahmp_cpl hydro_mpp ) add_dependencies(hydro_noahmp_cpl hydro_driver ) add_executable(wrfhydro Land_models/NoahMP/IO_code/main_hrldas_driver.F Land_models/NoahMP/IO_code/module_hrldas_netcdf_io.F Land_models/NoahMP/IO_code/module_NoahMP_hrldas_driver.F ) target_include_directories(wrfhydro BEFORE PUBLIC ${PROJECT_BINARY_DIR}/mods) target_link_libraries(wrfhydro hydro_utils hydro_mpp hydro_debug_utils hydro_routing_overland hydro_routing_subsurface hydro_data_rec hydro_routing hydro_routing_reservoirs_levelpool hydro_routing_reservoirs_hybrid hydro_routing_reservoirs_rfc hydro_routing_reservoirs hydro_driver noahmp_util noahmp_phys noahmp_data hydro_noahmp_cpl ${NETCDF_LIBRARIES} # hydro_routing_groundwater # hydro_routing_groundwater_bucket # hydro_routing_groundwater_nhd # hydro_routing_groundwater_simple ) if (WRF_HYDRO_NUDGING_IO STREQUAL "1") target_link_libraries(wrfhydro hydro_nudging_io) add_dependencies(wrfhydro hydro_nudging_io) endif() if (WRF_HYDRO_NUDGING STREQUAL "1") target_link_libraries(wrfhydro hydro_nudging) target_link_libraries(wrfhydro hydro_routing_diversions) add_dependencies(wrfhydro hydro_nudging) add_dependencies(wrfhydro hydro_routing_diversions) endif() # bash commands to copy namelists to the Run directory set(BASH_CP_HRLDAS_NML "if [[ ! -f ${CMAKE_BINARY_DIR}/Run/namelist.hrldas ]]\; then cp ${PROJECT_SOURCE_DIR}/src/template/NoahMP/namelist.hrldas ${CMAKE_BINARY_DIR}/Run \; fi\;") set(BASH_CP_HYDRO_NML "if [[ ! -f ${CMAKE_BINARY_DIR}/Run/hydro.namelist ]]\; then cp ${PROJECT_SOURCE_DIR}/src/template/HYDRO/hydro.namelist ${CMAKE_BINARY_DIR}/Run \; fi\;") add_custom_command(TARGET wrfhydro POST_BUILD COMMAND mkdir -p ${CMAKE_BINARY_DIR}/Run COMMAND cp ${PROJECT_SOURCE_DIR}/tests/ctests/run_dir_makefile.mk ${CMAKE_BINARY_DIR}/Run/Makefile # copy tables COMMAND cp ${PROJECT_SOURCE_DIR}/src/template/HYDRO/CHANPARM.TBL ${CMAKE_BINARY_DIR}/Run COMMAND cp ${PROJECT_SOURCE_DIR}/src/template/HYDRO/HYDRO.TBL ${CMAKE_BINARY_DIR}/Run COMMAND cp ${PROJECT_SOURCE_DIR}/src/Land_models/NoahMP/run/*.TBL ${CMAKE_BINARY_DIR}/Run # copy namelists COMMAND bash -c "${BASH_CP_HRLDAS_NML}" COMMAND bash -c "${BASH_CP_HYDRO_NML}" # copy and setup executables COMMAND rm -f ${CMAKE_BINARY_DIR}/Run/wrf_hydro COMMAND rm -f ${CMAKE_BINARY_DIR}/Run/wrf_hydro_NoahMP COMMAND cp ${PROJECT_BINARY_DIR}/src/wrfhydro ${CMAKE_BINARY_DIR}/Run/wrf_hydro COMMAND ln -sf ${CMAKE_BINARY_DIR}/Run/wrf_hydro ${CMAKE_BINARY_DIR}/Run/wrf_hydro_NoahMP COMMAND rm ${PROJECT_BINARY_DIR}/src/wrfhydro ) if(WRF_HYDRO_CREATE_EXE_SYMLINK) add_custom_command(TARGET wrfhydro POST_BUILD COMMAND ${CMAKE_COMMAND} -E create_symlink ${CMAKE_BINARY_DIR}/Run/wrf_hydro ${CMAKE_BINARY_DIR}/Run/wrf_hydro.exe ) endif() elseif (HYDRO_LSM MATCHES "Noah") message("-- Building Noah LSM") add_subdirectory("Land_models/Noah") add_subdirectory("CPL/Noah_cpl") add_dependencies(hydro_noah_cpl hydro_routing) add_dependencies(hydro_noah_cpl hydro_mpp ) add_dependencies(hydro_noah_cpl hydro_driver ) add_executable(wrfhydro Land_models/Noah/IO_code/module_hrldas_netcdf_io.F Land_models/Noah/IO_code/Noah_hrldas_driver.F ) target_include_directories(wrfhydro BEFORE PUBLIC ${PROJECT_BINARY_DIR}/mods) target_link_libraries(wrfhydro hydro_utils hydro_mpp hydro_debug_utils hydro_routing_overland hydro_routing_subsurface hydro_data_rec hydro_routing hydro_driver hydro_routing_reservoirs_levelpool hydro_routing_reservoirs_hybrid hydro_routing_reservoirs_rfc hydro_routing_reservoirs noah_util noah hydro_noah_cpl ${NETCDF_LIBRARIES} ${MPI_Fortran_LIBRARIES} # hydro_routing_groundwater # hydro_routing_groundwater_bucket # hydro_routing_groundwater_nhd # hydro_routing_groundwater_simple ) if (WRF_HYDRO_NUDGING STREQUAL "1") target_link_libraries(wrfhydro hydro_nudging) add_dependencies(wrfhydro hydro_nudging) endif() add_custom_command(TARGET wrfhydro POST_BUILD COMMAND mkdir -p ${CMAKE_BINARY_DIR}/Run COMMAND rm -f ${CMAKE_BINARY_DIR}/Run/* COMMAND cp ${PROJECT_BINARY_DIR}/src/wrfhydro ${CMAKE_BINARY_DIR}/Run/wrf_hydro_Noah COMMAND cp ${PROJECT_SOURCE_DIR}/src/template/Noah/* ${CMAKE_BINARY_DIR}/Run COMMAND cp ${PROJECT_SOURCE_DIR}/src/template/HYDRO/CHANPARM.TBL ${CMAKE_BINARY_DIR}/Run COMMAND cp ${PROJECT_SOURCE_DIR}/src/template/HYDRO/hydro.namelist ${CMAKE_BINARY_DIR}/Run COMMAND cp ${PROJECT_SOURCE_DIR}/src/template/HYDRO/HYDRO.TBL ${CMAKE_BINARY_DIR}/Run COMMAND cp ${PROJECT_SOURCE_DIR}/src/Land_models/Noah/Run/*.TBL ${CMAKE_BINARY_DIR}/Run COMMAND ln -sf ${CMAKE_BINARY_DIR}/Run/wrf_hydro_Noah ${CMAKE_BINARY_DIR}/Run/wrf_hydro COMMAND ln -sf ${CMAKE_BINARY_DIR}/Run/wrf_hydro_Noah ${CMAKE_BINARY_DIR}/Run/wrf_hydro.exe COMMAND rm ${PROJECT_BINARY_DIR}/src/wrfhydro ) elseif(${PROJECT_NAME} STREQUAL "WRF") add_library(wrfhydro INTERFACE) target_link_libraries(wrfhydro INTERFACE hydro_utils hydro_mpp hydro_debug_utils hydro_routing_overland hydro_routing_subsurface hydro_data_rec hydro_routing hydro_routing_reservoirs_levelpool hydro_routing_reservoirs_hybrid hydro_routing_reservoirs_rfc hydro_routing_reservoirs hydro_wrf_cpl hydro_orchestrator hydro_netcdf_layer hydro_driver ) else() message("Unknown land surface model:" ${HYDRO_LSM} ) endif() ================================================ FILE: src/CPL/CLM_cpl/Makefile ================================================ # Makefile # .SUFFIXES: .SUFFIXES: .o .F CLMOBJPATH = /d1/weiyu/scratch/merra_boulder CLM_MOD = -I $(CLMOBJPATH)/lnd/obj -I $(CLMOBJPATH)/lib/include include ../../macros MODFLAG = -I./ -I ../../MPP -I ../../mod OBJS = \ module_clm_HYDRO.o \ clm_drv_HYDRO.o all: $(OBJS) .F.o: @echo "" $(COMPILER90) $(CPPINVOKE) $(CPPFLAGS) -I$(NETCDFINC) -o $(@) $(F90FLAGS) $(MODFLAG) -I ../../mod $(CLM_MOD) $(*).F @echo "" ar -r ../../lib/libHYDRO.a $(@) # # Dependencies: # clean: rm -f *.o *.mod *.stb *~ cd ../..; make -f Makefile.comm clean ================================================ FILE: src/CPL/CLM_cpl/Makefile.cpl ================================================ # Makefile all: (cd ../../; make -f Makefile.comm) (make) clean: (cd ../../; make -f Makefile.comm clean) ================================================ FILE: src/CPL/CLM_cpl/bat2.csh ================================================ #!/bin/csh -f make -f Makefile.cpl rm -f /d1/weiyu/scratch/merra_boulder/run/ccsm.exe cd /d1/weiyu/scratch/merra_boulder/ccsm/obj mpif90 -o /d1/weiyu/scratch/merra_boulder/run/ccsm.exe ccsm_comp_mod.o ccsm_driver.o map_atmatm_mct.o map_atmice_mct.o map_atmlnd_mct.o map_atmocn_mct.o map_glcglc_mct.o map_iceice_mct.o map_iceocn_mct.o map_lndlnd_mct.o map_ocnocn_mct.o map_rofocn_mct.o map_rofrof_mct.o map_snoglc_mct.o map_snosno_mct.o mrg_x2a_mct.o mrg_x2g_mct.o mrg_x2i_mct.o mrg_x2l_mct.o mrg_x2o_mct.o mrg_x2s_mct.o seq_avdata_mod.o seq_diag_mct.o seq_domain_mct.o seq_flux_mct.o seq_frac_mct.o seq_hist_mod.o seq_rearr_mod.o seq_rest_mod.o -L/d1/weiyu/scratch/merra_boulder/lib -latm -llnd -lice -locn -lglc -L/d1/weiyu/scratch/merra_boulder/lib -lcsm_share -lmct -lmpeu -lpio -L/home/weiyu/netcdf/lib -lnetcdf -lnetcdff -L /raid/weiyu/LIS_trunk2/p61_NDHMS/routing/ndhms_wrf_hydro/src/lib -lHYDRO ================================================ FILE: src/CPL/CLM_cpl/cesm_cpl_compiling.csh ================================================ #!/bin/csh -f cd /raid/weiyu/scratch/clm4_ndhms/ccsm/obj mpif90 -o /d1/weiyu/scratch/clm4_ndhms/run/ccsm.exe ccsm_comp_mod.o ccsm_driver.o map_atmatm_mct.o map_atmice_mct.o map_atmlnd_mct.o map_atmocn_mct.o map_glcglc_mct.o map_iceice_mct.o map_iceocn_mct.o map_lndlnd_mct.o map_ocnocn_mct.o map_rofocn_mct.o map_rofrof_mct.o map_snoglc_mct.o map_snosno_mct.o mrg_x2a_mct.o mrg_x2g_mct.o mrg_x2i_mct.o mrg_x2l_mct.o mrg_x2o_mct.o mrg_x2s_mct.o seq_avdata_mod.o seq_diag_mct.o seq_domain_mct.o seq_flux_mct.o seq_frac_mct.o seq_hist_mod.o seq_rearr_mod.o seq_rest_mod.o -L/d1/weiyu/scratch/clm4_ndhms/lib -latm -llnd -lice -locn -lglc -L/d1/weiyu/scratch/clm4_ndhms/lib -lcsm_share -lmct -lmpeu -lpio -L/home/weiyu/netcdf/lib -lnetcdf -lnetcdff -L /d1/weiyu/LISv6.1/src/routing/NCAR_router/lib -lland -lNDHMS ================================================ FILE: src/CPL/CLM_cpl/clm_drv_HYDRO.F ================================================ subroutine clm_drv_HYDRO() use module_clm_HYDRO, only: clm_cpl_HYDRO implicit none call clm_cpl_HYDRO() end subroutine clm_drv_HYDRO ================================================ FILE: src/CPL/CLM_cpl/module_clm_HYDRO.F ================================================ module module_CLM_HYDRO use domainMod , only : ldomain use clmtype , only : clm3 use clm_varpar , only : nlevgrnd use decompMod , only : get_proc_bounds, get_proc_global use clm_varcon , only : zsoi use subgridAveMod, only: l2g_1d use subgridAveMod, only: c2g_1d, c2g_2d ! NDHMS module use module_mpp_land, only: global_nx, global_ny, decompose_data_real, & write_io_real, my_id use module_hydro_stop, only: HYDRO_stop use module_HYDRO_drv, only: HYDRO_ini, HYDRO_exe implicit none integer begg, endg integer :: numg, numl, numc, nump INTEGER, PARAMETER :: double=8 real(kind=double), pointer :: r2p(:,:) , r1p(:) integer :: begl, endl, begc, endc, begp, endp real(kind=double), allocatable, dimension(:) :: clm_g1d real(kind=double), allocatable, dimension(:,:) :: clm_g2d real, allocatable, dimension(:,:) :: vg_test CONTAINS subroutine clm_cpl_HYDRO() use module_rt_data, only: rt_domain use module_CPL_LAND, only: CPL_LAND_INIT, cpl_outdate use module_mpp_land use config_base, only: nlst implicit none integer k, ix,jx, nn integer :: did integer ntime, wrf_ix,wrf_jx real cpl_land_dt integer :: i,j integer clm_lev !output flux and state variable did = 1 call get_cpl_date(cpl_land_dt) #ifdef HYDRO_D write(6,*) "cpl_land_dt = ",cpl_land_dt #endif ntime = 1 if(.not. RT_DOMAIN(did)%initialized) then call HYDRO_ini(ntime,did,1,1) if(nlst(did)%sys_cpl .ne. 4) then write(6,*) "FATAL ERROR: sys_cpl should be 4." call hydro_stop("In module_clm_HYDRO.F clm_cpl_HYDRO() - "// & "sys_cpl should be 4. Check hydro.namelist file") endif RT_DOMAIN(did)%initialized = .true. nlst(did)%dt = cpl_land_dt nlst(did)%startdate(1:19) = cpl_outdate(1:19) nlst(did)%olddate(1:19) = cpl_outdate(1:19) endif if(nlst(did)%rtFlag .eq. 0) return ix = rt_domain(did)%ix jx = rt_domain(did)%jx ! get the initial data from CLM call get_proc_global(numg, numl, numc, nump) call get_proc_bounds(begg, endg, begl, endl, begc, endc, begp, endp) #ifdef HYDRO_D write(6,*) "begg, endg, ", begg, endg write(6,*) "begl, endl, ", begl, endl write(6,*) "begc, endc, ", begc, endc write(6,*) "begp, endp, ", begp, endp #endif ! call get_proc_bounds( begg=begg, endg=endg ) nn = endg - begg + 1 allocate(clm_g1d(endg-begg + 1)) allocate(clm_g2d(endg-begg+1, nlevgrnd) ) r1p => clm3%g%l%c%cwf%qflx_surf call c2g_1d(begc, endc, begl, endl, begg, endg, r1p(begc:endc), clm_g1d, & 'urbanf', 'unity') call clm2ND2d(clm_g1d,nn,RT_DOMAIN(did)%INFXSRT,ix,jx) #ifdef HYDRO_D write(6,*) "finish qflx_surf" #endif r1p => clm3%g%l%c%cwf%qflx_drain call c2g_1d(begc, endc, begl, endl, begg, endg, r1p(begc:endc), clm_g1d, & 'urbanf', 'unity') call clm2ND2d(clm_g1d,nn,RT_DOMAIN(did)%SOLDRAIN,ix,jx) #ifdef HYDRO_D write(6,*) "finish qflx_drain " #endif r2p =>clm3%g%l%c%ces%t_soisno call c2g_2d(begc, endc, begl, endl, begg, endg, nlevgrnd, r2p(begc:endc,1:nlevgrnd), clm_g2d, & 'urbanh', 'unity') call clm2ND3d (clm_g2d,nn,nlevgrnd,zsoi(1:nlevgrnd), & ix,jx, nlst(did)%nsoil,abs(rt_domain(did)%subsurface%properties%zsoil(1:nlst(did)%nsoil)),& RT_DOMAIN(did)%STC) #ifdef HYDRO_D write(6,*) "finish t_soisno " #endif r2p => clm3%g%l%c%cws%h2osoi_vol call c2g_2d(begc, endc, begl, endl, begg, endg, nlevgrnd, r2p(begc:endc,1:nlevgrnd), clm_g2d, & 'urbanh', 'unity') call clm2ND3d (clm_g2d,nn,nlevgrnd,zsoi(1:nlevgrnd), & ix,jx, nlst(did)%nsoil,abs(rt_domain(did)%subsurface%properties%zsoil(1:nlst(did)%nsoil)),& RT_DOMAIN(did)%SMC) #ifdef HYDRO_D write(6,*) "finish h2osoi_vol " #endif r2p => clm3%g%l%c%cws%h2osoi_liq call c2g_2d(begc, endc, begl, endl, begg, endg, nlevgrnd, r2p(begc:endc,1:nlevgrnd), clm_g2d, & 'urbanh', 'unity') call clm2ND3d (clm_g2d, nn,nlevgrnd,zsoi(1:nlevgrnd), & ix,jx, nlst(did)%nsoil,abs(rt_domain(did)%subsurface%properties%zsoil(1:nlst(did)%nsoil)),& RT_DOMAIN(did)%SH2OX) RT_DOMAIN(did)%SH2OX = RT_DOMAIN(did)%SH2OX /1000. #ifdef HYDRO_D write(6,*) "finish h2osoi_liq " write(6,*) "before call HYDRO_exe" #endif call HYDRO_exe(did) #ifdef HYDRO_D write(6,*) "after call HYDRO_exe" #endif ! add for update the CLM state variable. clm_lev = 10 r2p =>clm3%g%l%c%ces%t_soisno call Toclm3d (clm_g2d,nn,clm_lev,zsoi(1:clm_lev), & ix,jx, nlst(did)%nsoil,abs(rt_domain(did)%subsurface%properties%zsoil(1:nlst(did)%nsoil)),& RT_DOMAIN(did)%STC) call g2c_2d(begc, endc, begl, endl, begg, endg,clm_lev,r2p(begc:endc,1:clm_lev), clm_g2d, & 'urbanh', 'unity') r2p => clm3%g%l%c%cws%h2osoi_vol call Toclm3d (clm_g2d,nn,clm_lev,zsoi(1:clm_lev), & ix,jx, nlst(did)%nsoil,abs(rt_domain(did)%subsurface%properties%zsoil(1:nlst(did)%nsoil)), & RT_DOMAIN(did)%SMC) call g2c_2d_tmp(begc, endc, begl, endl, begg, endg,clm_lev,r2p(begc:endc,1:clm_lev), clm_g2d, & 'urbanh', 'unity', 0.01, 10.) r2p => clm3%g%l%c%cws%h2osoi_liq call Toclm3d(clm_g2d,nn,clm_lev,zsoi(1:clm_lev), & ix,jx, nlst(did)%nsoil,abs(rt_domain(did)%subsurface%properties%zsoil(1:nlst(did)%nsoil)),& RT_DOMAIN(did)%SH2OX*1000) call g2c_2d_tmp(begc, endc, begl, endl, begg, endg,clm_lev,r2p(begc:endc,1:clm_lev), clm_g2d, & 'urbanh', 'unity',0.01, 10.) ! 2d variable ! t_soisno ! 3 d variable deallocate(clm_g1d) deallocate(clm_g2d) #ifdef HYDRO_D write(6,*) "end of drive ndhms" #endif end subroutine clm_cpl_HYDRO subroutine Toclm3d (v1d_out,nn,kk1,z1_in,ix,jx,kk2,z2,v2_in) implicit none integer :: nn,ix,jx, kk2, kk1 integer :: k real:: v2_in(ix,jx,kk2) real:: v1(ix,jx,kk1) real, dimension(kk2) :: z2 REAL (KIND=double),dimension(nn,kk1):: v1d_out REAL (KIND=double),dimension(kk1):: z1_in REAL ,dimension(kk1):: z1 z1 = z1_in ! v1 is the out from interp3D call Interp3D (z2,v2_in,kk2,z1,v1,ix,jx,kk1) do k = 1, kk1 call Toclm2d(v1(:,:,k),ix,jx,v1d_out(:,k),nn) end do end subroutine Toclm3d subroutine Toclm2d(v1,ix,jx,v1d_out,nn) use module_mpp_land, only: my_id,IO_id,mpp_land_bcast_real implicit none integer ix,jx, nn real v1(ix,jx) REAL (KIND=double),dimension(nn) :: v1d_out real, dimension(global_nx*global_ny)::vg real, dimension(global_nx,global_ny)::vg2d call write_io_real(v1,vg2d) vg = 0.0 if(my_id .eq. IO_id) then call TO1d(vg2d,vg,global_nx,global_ny) end if #ifdef HYDRO_D write(6,*) "before scatter_1d_r" #endif call scatter_1d_r(v1d_out,nn,vg,global_nx*global_ny) #ifdef HYDRO_D write(6,*) "after scatter_1d_r" #endif end subroutine Toclm2d subroutine TO1d(vg2d,v1d,nx,ny) implicit none integer nx,ny, n, i,j real vg2d(nx,ny) real v1d(nx*ny) do j = 1,ny do i = 1,nx n = (j-1)*nx + i v1d(n) = vg2d(i,j) enddo enddo end subroutine TO1d subroutine clm2ND3d (v1d_in,nn,kk1,z1_in,ix,jx,kk2,z2,vout) implicit none integer :: nn,kk1,ix,jx,kk2 integer :: k real:: vout(ix,jx,kk2) real:: v1(ix,jx,kk1) real(kind=double),dimension(nn,kk1):: v1d_in real(kind=double), dimension(kk1) :: z1_in real, dimension(kk1) :: z1 real, dimension(kk2) :: z2 z1 = z1_in do k = 1, kk1 call clm2ND2d(v1d_in(:,k),nn,v1(:,:,k),ix,jx) end do call Interp3D (z1(1:kk1),v1,kk1,z2(1:kk2),vout,ix,jx,kk2) end subroutine clm2ND3d subroutine clm2ND2d (v1d_in,nn,vout,ix,jx) use clmtype, only: grlnd use module_mpp_land, only: my_id,IO_id,mpp_land_bcast_real implicit none integer :: ix,jx,nn, n real vout(ix,jx) integer :: i,j,gni,gnj ! ! real, allocatable, dimension(:) :: g1d real(kind=double), dimension(global_nx*global_ny) :: g1d real v2d_g(global_nx,global_ny) real(kind=double),dimension(nn) :: v1d_in gni = global_nx gnj = global_ny ! gather 1d global array if(endg .gt. gni*gnj) then write(6,*) "WARNING: endg > gni*gnj", endg, gni*gnj ! need to stop endif call gather_1d_real(v1d_in,nn,g1d,gni*gnj) ! transfer 1d to 2d if(my_id.eq.IO_id) then do j = 1,gnj do i = 1,gni n = (j-1)*gni + i v2d_g(i,j) = g1d(n) enddo enddo endif ! if(my_id .eq. 0) then ! call output_nc(v2d_g,gni,gnj, "test", "test.nc") ! endif ! domain decomposition call decompose_data_real(v2d_g,vout) end subroutine clm2ND2d subroutine Interp3D (z1,v1,kk1,z,vout,ix,jx,kk) ! input: z1,v1,kk1,z,ix,jx,kk ! output: vout ! interpolate based on soil layer: z1 and z ! z : soil layer of output variable. ! z1: array of soil layers of input variable. implicit none integer:: i,j,k integer:: kk1, ix,jx,kk real :: z1(kk1), z(kk), v1(ix,jx,kk1),vout(ix,jx,kk) ! write(6,*) "k, kk1 ", k, kk1 ! write(6,*) "z1(kk1), z(k) ", z1(kk1), z(k) do j = 1, jx do i = 1, ix do k = 1, kk ! call interpLayer(abs(Z1),v1(i,j,1:kk1),kk1,abs( Z(k) ),vout(i,j,k)) call interpLayer(Z1(1:kk1),v1(i,j,1:kk1),kk1,Z(k),vout(i,j,k)) end do end do end do end subroutine Interp3D subroutine interpLayer(inZ,inV,inK,outZ,outV) implicit none integer:: k, k1, k2 integer :: inK real:: inV(inK),inZ(inK) real:: outV, outZ, w1, w2 if(outZ .le. inZ(1)) then if(inZ(2) .eq. inZ(1)) then write(6,*) "FATAL ERROR: inZ(2)=inZ(1) ", inZ(2),inZ(1) !stop 99 stop("In module_clm_HYDRO.F interpLayer() - inZ(2)=inZ(1)") end if w1 = (inZ(2)-outZ)/(inZ(2)-inZ(1)) w2 = (inZ(1)-outZ)/(inZ(2)-inZ(1)) outV = inV(1)*w1-inV(2)*w2 return elseif(outZ .ge. inZ(inK)) then if(inZ(inK-1) .eq. inZ(inK)) then write(6,*) "FATAL ERROR: inZ(inK-1)=inZ(inK) ", inZ(inK-1),inZ(inK) !stop 99 stop("FATAL ERROR: In module_clm_HYDRO.F interpLayer() - inZ(inK-1)=inZ(inK)") end if w1 = (outZ-inZ(inK-1))/(inZ(inK)-inZ(inK-1)) w2 = (outZ-inZ(inK)) /(inZ(inK)-inZ(inK-1)) outV = inV(inK)*w1 -inV(inK-1)* w2 return else do k = 2, inK if((inZ(k) .ge. outZ).and.(inZ(k-1) .le. outZ) ) then k1 = k-1 k2 = k if(inZ(k1) .eq. inZ(k2)) then write(6,*) "FATAL ERROR: inZ(k1)=inZ(k2) ", inZ(k1),inZ(k2) !stop 99 stop("FATAL ERROR: In module_clm_HYDRO.F interpLayer()- inZ(k1)=inZ(k2)") end if w1 = (outZ-inZ(k1))/(inZ(k2)-inZ(k1)) w2 = (inZ(k2)-outZ)/(inZ(k2)-inZ(k1)) outV = inV(k2)*w1 + inV(k1)*w2 return end if end do endif end subroutine interpLayer subroutine get_cpl_date(cpl_land_dt) use clm_time_manager, only : get_step_size, get_curr_date use module_CPL_LAND, only: cpl_outdate implicit none integer :: yr, mo, da, hr, mn, ss , sec real :: cpl_land_dt integer cmdate cpl_land_dt = 1.0* get_step_size() call get_curr_date(yr, mo, da, sec) hr = sec/3600 sec = mod(sec,3600) mn = sec/60 ss = mod(sec,60) if(yr .lt. 1000) yr = 2000+yr write(cpl_outdate(1:4),'(I4)') yr if(mo .lt. 10 ) then write(cpl_outdate(5:7),'("-0",I1)') mo else write(cpl_outdate(5:7),'("-",I2)') mo endif if(da .lt. 10 ) then write(cpl_outdate(8:10),'("-0",I1)') da else write(cpl_outdate(8:10),'("-",I2)') da endif if(hr .lt. 10 ) then write(cpl_outdate(11:13),'("_0",I1)') hr else write(cpl_outdate(11:13),'("_",I2)') hr endif if(mn .lt. 10 ) then write(cpl_outdate(14:16),'(":0",I1)') mn else write(cpl_outdate(14:16),'(":",I2)') mn endif if(ss .lt. 10 ) then write(cpl_outdate(17:19),'(":0",I1)') ss else write(cpl_outdate(17:19),'(":",I2)') ss endif ! write(cpl_outdate,'(I4,"-",I2,"-",I2,"_",I2,":",I2,":",I2)' ) & ! yr, mo, da, hr, mn, ss #ifdef HYDRO_D write(6,*) "cpl_outdate = ",cpl_outdate #endif end subroutine get_cpl_date ! transfer the grid column to gridcell. subroutine g2c_1d(lbc, ubc, lbl, ubl, lbg, ubg, carr, garr, & c2l_scale_type, l2g_scale_type) ! ! !DESCRIPTION: ! Perfrom subgrid-average from columns to gridcells. ! Averaging is only done for points that are not equal to "spval". ! ! !ARGUMENTS: use clm_varcon, only : spval, isturb, icol_roof, icol_sunwall, icol_shadewall, & icol_road_perv, icol_road_imperv use clm_varctl, only : iulog implicit none integer , intent(in) :: lbc, ubc ! beginning and ending column indices integer , intent(in) :: lbl, ubl ! beginning and ending landunit indices integer , intent(in) :: lbg, ubg ! beginning and ending landunit indices real(kind=double), intent(out) :: carr(lbc:ubc) ! output column array real(kind=double), intent(in) :: garr(lbg:ubg) ! input gridcell array character(len=*), intent(in) :: c2l_scale_type ! scale factor type for averaging character(len=*), intent(in) :: l2g_scale_type ! scale factor type for averaging ! ! !REVISION HISTORY: ! Created by Mariana Vertenstein 12/03 ! ! ! !LOCAL VARIABLES: !EOP integer :: ci,c,l,g,index ! indices integer :: max_col_per_gcell ! max columns per gridcell; on the fly logical :: found ! temporary for error check real(kind=double) :: scale_c2l(lbc:ubc) ! scale factor real(kind=double) :: scale_l2g(lbl:ubl) ! scale factor real(kind=double) :: sumwt(lbg:ubg) ! sum of weights real(kind=double), pointer :: wtgcell(:) ! weight of columns relative to gridcells integer , pointer :: clandunit(:) ! landunit of corresponding column integer , pointer :: cgridcell(:) ! gridcell of corresponding column integer , pointer :: ncolumns(:) ! number of columns in gridcell integer , pointer :: coli(:) ! initial column index in gridcell integer , pointer :: ctype(:) ! column type integer , pointer :: ltype(:) ! landunit type real(kind=double), pointer :: canyon_hwr(:) ! urban canyon height to width ratio integer :: gcount(lbg:ubg) !------------------------------------------------------------------------ ctype => clm3%g%l%c%itype ltype => clm3%g%l%itype canyon_hwr => clm3%g%l%canyon_hwr wtgcell => clm3%g%l%c%wtgcell clandunit => clm3%g%l%c%landunit cgridcell => clm3%g%l%c%gridcell ncolumns => clm3%g%ncolumns coli => clm3%g%coli if (l2g_scale_type == 'unity') then do l = lbl,ubl scale_l2g(l) = 1.0 end do end if if (c2l_scale_type == 'unity') then do c = lbc,ubc scale_c2l(c) = 1.0 end do else if (c2l_scale_type == 'urbanf') then do c = lbc,ubc l = clandunit(c) if (ltype(l) == isturb) then if (ctype(c) == icol_sunwall) then scale_c2l(c) = 3.0 * canyon_hwr(l) else if (ctype(c) == icol_shadewall) then scale_c2l(c) = 3.0 * canyon_hwr(l) else if (ctype(c) == icol_road_perv .or. ctype(c) == icol_road_imperv) then scale_c2l(c) = 3.0 else if (ctype(c) == icol_roof) then scale_c2l(c) = 1.0 end if else scale_c2l(c) = 1.0 end if end do else if (c2l_scale_type == 'urbans') then do c = lbc,ubc l = clandunit(c) if (ltype(l) == isturb) then if (ctype(c) == icol_sunwall) then scale_c2l(c) = (3.0 * canyon_hwr(l)) / (2.*canyon_hwr(l) + 1.) else if (ctype(c) == icol_shadewall) then scale_c2l(c) = (3.0 * canyon_hwr(l)) / (2.*canyon_hwr(l) + 1.) else if (ctype(c) == icol_road_perv .or. ctype(c) == icol_road_imperv) then scale_c2l(c) = 3.0 / (2.*canyon_hwr(l) + 1.) else if (ctype(c) == icol_roof) then scale_c2l(c) = 1.0 end if else scale_c2l(c) = 1.0 end if end do else if (c2l_scale_type == 'urbanh') then do c = lbc,ubc l = clandunit(c) if (ltype(l) == isturb) then if (ctype(c) == icol_sunwall) then scale_c2l(c) = spval else if (ctype(c) == icol_shadewall) then scale_c2l(c) = spval else if (ctype(c) == icol_road_perv .or. ctype(c) == icol_road_imperv) then scale_c2l(c) = spval else if (ctype(c) == icol_roof) then scale_c2l(c) = spval end if else scale_c2l(c) = 1.0 end if end do end if sumwt(:) = 0. gcount(:) = 0 do c = lbc,ubc if (carr(c) /= spval .and. scale_c2l(c) /= spval) then l = clandunit(c) g = cgridcell(c) if(wtgcell(c) .ne. 0) then carr(c) = garr(g) endif end if end do end subroutine g2c_1d subroutine gather_1d_real(l1d,lnn,g1d,gnn) use spmdGathScatMod use clmtype , only : grlnd, nameg implicit none integer lnn, gnn real(kind=double),dimension(lnn) :: l1d real(kind=double),dimension(gnn) :: g1d real(kind=double), pointer :: lp_yw(:), gp_yw(:) allocate(lp_yw(lnn) ) allocate(gp_yw(gnn) ) lp_yw = l1d call gather_data_to_master(lp_yw,gp_yw,grlnd) g1d = gp_yw deallocate(lp_yw) deallocate(gp_yw) end subroutine gather_1d_real subroutine scatter_1d_r(l1d,lnn,g1d,gnn) use spmdGathScatMod, only: scatter_1darray_real use clmtype , only : grlnd, nameg implicit none integer lnn, gnn real(kind=double),dimension(lnn) :: l1d real,dimension(gnn) :: g1d real(kind=double), pointer :: lp_yw(:), gp_yw(:) allocate(lp_yw(begg:endg) ) allocate(gp_yw(gnn) ) gp_yw(:) = g1d(:) ! call scatter_data_from_master(lp, gp, grlnd) call scatter_1darray_real(lp_yw, gp_yw, grlnd) l1d = lp_yw(begg:endg) deallocate(lp_yw) deallocate(gp_yw) end subroutine scatter_1d_r subroutine output_nc(array,idim,jdim, var_name, file_name) implicit none #include integer idim,jdim real array(idim,jdim) integer dim(2) character(len=*) file_name,var_name integer iret,ncid,varid,idim_id,jdim_id integer i,j iret = nf_create(trim(file_name), 0, ncid) iret = nf_def_dim(ncid, "idim", idim,idim_id) iret = nf_def_dim(ncid, "jdim", jdim,jdim_id) dim(1)=idim_id dim(2)=jdim_id iret = nf_put_att_real(ncid, NF_GLOBAL, & "missing_value", NF_FLOAT, 1, -1.E33) iret = nf_def_var(ncid,var_name,NF_FLOAT,2,dim,varid) iret = nf_enddef(ncid) ! output iret = nf_inq_varid(ncid,var_name,varid) iret = nf_put_var_real(ncid,varid,array) iret=nf_close(ncid) end subroutine output_nc subroutine g2c_2d(lbc, ubc, lbl, ubl, lbg, ubg, num2d, carr, garr, & c2l_scale_type, l2g_scale_type) ! ! !DESCRIPTION: ! Perfrom subgrid-average from columns to gridcells. ! Averaging is only done for points that are not equal to "spval". ! use clm_varcon, only : spval, isturb, icol_roof, icol_sunwall, icol_shadewall, & icol_road_perv, icol_road_imperv use clm_varctl, only : iulog ! !ARGUMENTS: implicit none integer , intent(in) :: lbc, ubc ! beginning and ending column indices integer , intent(in) :: lbl, ubl ! beginning and ending landunit indices integer , intent(in) :: lbg, ubg ! beginning and ending gridcell indices integer , intent(in) :: num2d ! size of second dimension real(kind=double), intent(inout) :: carr(lbc:ubc,num2d) ! input column array real(kind=double), intent(in) :: garr(lbg:ubg,num2d) ! output gridcell array character(len=*), intent(in) :: c2l_scale_type ! scale factor type for averaging character(len=*), intent(in) :: l2g_scale_type ! scale factor type for averaging real(kind=double) :: yw_r ! ! !REVISION HISTORY: ! Created by Mariana Vertenstein 12/03 ! ! ! !LOCAL VARIABLES: !EOP integer :: j,ci,c,g,l,index ! indices integer :: max_col_per_gcell ! max columns per gridcell; on the fly logical :: found ! temporary for error check real(kind=double) :: scale_c2l(lbc:ubc) ! scale factor real(kind=double) :: scale_l2g(lbl:ubl) ! scale factor real(kind=double) :: sumwt(lbg:ubg) ! sum of weights real(kind=double), pointer :: wtgcell(:) ! weight of columns relative to gridcells integer , pointer :: clandunit(:) ! landunit of corresponding column integer , pointer :: cgridcell(:) ! gridcell of corresponding column integer , pointer :: ncolumns(:) ! number of columns in gridcell integer , pointer :: coli(:) ! initial column index in gridcell integer , pointer :: ctype(:) ! column type integer , pointer :: ltype(:) ! landunit type real(kind=double), pointer :: canyon_hwr(:) ! urban canyon height to width ratio real :: w_yw !------------------------------------------------------------------------ ctype => clm3%g%l%c%itype ltype => clm3%g%l%itype canyon_hwr => clm3%g%l%canyon_hwr wtgcell => clm3%g%l%c%wtgcell clandunit => clm3%g%l%c%landunit cgridcell => clm3%g%l%c%gridcell ncolumns => clm3%g%ncolumns coli => clm3%g%coli if (l2g_scale_type == 'unity') then do l = lbl,ubl scale_l2g(l) = 1.0 end do else write(iulog,*)'WARNING: In module_clm_HYDRO.F c2g_2d() - '// & 'scale type ',l2g_scale_type,' not supported' end if if (c2l_scale_type == 'unity') then do c = lbc,ubc scale_c2l(c) = 1.0 end do else if (c2l_scale_type == 'urbanf') then do c = lbc,ubc l = clandunit(c) if (ltype(l) == isturb) then if (ctype(c) == icol_sunwall) then scale_c2l(c) = 3.0 * canyon_hwr(l) else if (ctype(c) == icol_shadewall) then scale_c2l(c) = 3.0 * canyon_hwr(l) else if (ctype(c) == icol_road_perv .or. ctype(c) == icol_road_imperv) then scale_c2l(c) = 3.0 else if (ctype(c) == icol_roof) then scale_c2l(c) = 1.0 end if else scale_c2l(c) = 1.0 end if end do else if (c2l_scale_type == 'urbans') then do c = lbc,ubc l = clandunit(c) if (ltype(l) == isturb) then if (ctype(c) == icol_sunwall) then scale_c2l(c) = (3.0 * canyon_hwr(l)) / (2.*canyon_hwr(l) + 1.) else if (ctype(c) == icol_shadewall) then scale_c2l(c) = (3.0 * canyon_hwr(l)) / (2.*canyon_hwr(l) + 1.) else if (ctype(c) == icol_road_perv .or. ctype(c) == icol_road_imperv) then scale_c2l(c) = 3.0 / (2.*canyon_hwr(l) + 1.) else if (ctype(c) == icol_roof) then scale_c2l(c) = 1.0 end if else scale_c2l(c) = 1.0 end if end do else if (c2l_scale_type == 'urbanh') then do c = lbc,ubc l = clandunit(c) if (ltype(l) == isturb) then if (ctype(c) == icol_sunwall) then scale_c2l(c) = spval else if (ctype(c) == icol_shadewall) then scale_c2l(c) = spval else if (ctype(c) == icol_road_perv .or. ctype(c) == icol_road_imperv) then scale_c2l(c) = spval else if (ctype(c) == icol_roof) then scale_c2l(c) = spval end if else scale_c2l(c) = 1.0 end if end do else write(iulog,*) 'WARNING: In module_clm_HYDRO.F c2g_2d()- '// & 'scale type ',c2l_scale_type,' not supported' end if do j = 1,num2d sumwt(:) = 0. do c = lbc,ubc if (wtgcell(c) /= 0) then if (carr(c,j) /= spval .and. scale_c2l(c) /= spval) then l = clandunit(c) g = cgridcell(c) sumwt(g) = sumwt(g) + wtgcell(c) end if end if end do do c = lbc,ubc if (wtgcell(c) /= 0) then if (carr(c,j) /= spval .and. scale_c2l(c) /= spval) then l = clandunit(c) g = cgridcell(c) !garr(g,j) = garr(g,j) + carr(c,j) * scale_c2l(c) * scale_l2g(l) * wtgcell(c) !w_yw = scale_c2l(c) * scale_l2g(l) * wtgcell(c) w_yw = scale_c2l(c) * scale_l2g(l) if(w_yw .ne. 0) then ! carr(c,j) = garr(g,j) / w_yw *sumwt(g) yw_r = garr(g,j) / w_yw if(abs(yw_r - carr(c,j)) .lt. 400 .and. yw_r .ne. 0 ) then carr(c,j) = garr(g,j) / w_yw endif endif end if end if end do end do end subroutine g2c_2d subroutine g2c_2d_tmp(lbc, ubc, lbl, ubl, lbg, ubg, num2d, carr, garr, & c2l_scale_type, l2g_scale_type, minv, maxv) ! ! !DESCRIPTION: ! Perfrom subgrid-average from columns to gridcells. ! Averaging is only done for points that are not equal to "spval". ! use clm_varcon, only : spval, isturb, icol_roof, icol_sunwall, icol_shadewall, & icol_road_perv, icol_road_imperv use clm_varctl, only : iulog ! !ARGUMENTS: implicit none integer , intent(in) :: lbc, ubc ! beginning and ending column indices integer , intent(in) :: lbl, ubl ! beginning and ending landunit indices integer , intent(in) :: lbg, ubg ! beginning and ending gridcell indices integer , intent(in) :: num2d ! size of second dimension real(kind=double), intent(inout) :: carr(lbc:ubc,num2d) ! input column array real(kind=double), intent(in) :: garr(lbg:ubg,num2d) ! output gridcell array character(len=*), intent(in) :: c2l_scale_type ! scale factor type for averaging character(len=*), intent(in) :: l2g_scale_type ! scale factor type for averaging real(kind=double) :: yw_r real :: minv, maxv ! ! !REVISION HISTORY: ! Created by Mariana Vertenstein 12/03 ! ! ! !LOCAL VARIABLES: !EOP integer :: j,ci,c,g,l,index ! indices integer :: max_col_per_gcell ! max columns per gridcell; on the fly logical :: found ! temporary for error check real(kind=double) :: scale_c2l(lbc:ubc) ! scale factor real(kind=double) :: scale_l2g(lbl:ubl) ! scale factor real(kind=double) :: sumwt(lbg:ubg) ! sum of weights real(kind=double), pointer :: wtgcell(:) ! weight of columns relative to gridcells integer , pointer :: clandunit(:) ! landunit of corresponding column integer , pointer :: cgridcell(:) ! gridcell of corresponding column integer , pointer :: ncolumns(:) ! number of columns in gridcell integer , pointer :: coli(:) ! initial column index in gridcell integer , pointer :: ctype(:) ! column type integer , pointer :: ltype(:) ! landunit type real(kind=double), pointer :: canyon_hwr(:) ! urban canyon height to width ratio real :: w_yw !------------------------------------------------------------------------ ctype => clm3%g%l%c%itype ltype => clm3%g%l%itype canyon_hwr => clm3%g%l%canyon_hwr wtgcell => clm3%g%l%c%wtgcell clandunit => clm3%g%l%c%landunit cgridcell => clm3%g%l%c%gridcell ncolumns => clm3%g%ncolumns coli => clm3%g%coli if (l2g_scale_type == 'unity') then do l = lbl,ubl scale_l2g(l) = 1.0 end do else write(iulog,*) 'WARNING: In module_clm_HYDRO.F g2c_2d_tmp - '// & 'scale type ',l2g_scale_type,' not supported' end if if (c2l_scale_type == 'unity') then do c = lbc,ubc scale_c2l(c) = 1.0 end do else if (c2l_scale_type == 'urbanf') then do c = lbc,ubc l = clandunit(c) if (ltype(l) == isturb) then if (ctype(c) == icol_sunwall) then scale_c2l(c) = 3.0 * canyon_hwr(l) else if (ctype(c) == icol_shadewall) then scale_c2l(c) = 3.0 * canyon_hwr(l) else if (ctype(c) == icol_road_perv .or. ctype(c) == icol_road_imperv) then scale_c2l(c) = 3.0 else if (ctype(c) == icol_roof) then scale_c2l(c) = 1.0 end if else scale_c2l(c) = 1.0 end if end do else if (c2l_scale_type == 'urbans') then do c = lbc,ubc l = clandunit(c) if (ltype(l) == isturb) then if (ctype(c) == icol_sunwall) then scale_c2l(c) = (3.0 * canyon_hwr(l)) / (2.*canyon_hwr(l) + 1.) else if (ctype(c) == icol_shadewall) then scale_c2l(c) = (3.0 * canyon_hwr(l)) / (2.*canyon_hwr(l) + 1.) else if (ctype(c) == icol_road_perv .or. ctype(c) == icol_road_imperv) then scale_c2l(c) = 3.0 / (2.*canyon_hwr(l) + 1.) else if (ctype(c) == icol_roof) then scale_c2l(c) = 1.0 end if else scale_c2l(c) = 1.0 end if end do else if (c2l_scale_type == 'urbanh') then do c = lbc,ubc l = clandunit(c) if (ltype(l) == isturb) then if (ctype(c) == icol_sunwall) then scale_c2l(c) = spval else if (ctype(c) == icol_shadewall) then scale_c2l(c) = spval else if (ctype(c) == icol_road_perv .or. ctype(c) == icol_road_imperv) then scale_c2l(c) = spval else if (ctype(c) == icol_roof) then scale_c2l(c) = spval end if else scale_c2l(c) = 1.0 end if end do else write(iulog,*) 'WARNING: In module_clm_HYDRO.F g2c_2d_tmp() - '// & 'scale type ',c2l_scale_type,' not supported' end if do j = 1,num2d sumwt(:) = 0. do c = lbc,ubc if (wtgcell(c) /= 0) then if (carr(c,j) /= spval .and. scale_c2l(c) /= spval) then l = clandunit(c) g = cgridcell(c) sumwt(g) = sumwt(g) + wtgcell(c) end if end if end do do c = lbc,ubc if (wtgcell(c) /= 0) then if (carr(c,j) /= spval .and. scale_c2l(c) /= spval) then l = clandunit(c) g = cgridcell(c) !garr(g,j) = garr(g,j) + carr(c,j) * scale_c2l(c) * scale_l2g(l) * wtgcell(c) !w_yw = scale_c2l(c) * scale_l2g(l) * wtgcell(c) w_yw = scale_c2l(c) * scale_l2g(l) if(w_yw .ne. 0) then if(abs(garr(g,j)) .gt. minv .and. abs(garr(g,j)) .lt. maxv) then ! carr(c,j) = garr(g,j) / w_yw *sumwt(g) yw_r = garr(g,j) / w_yw if(yw_r .gt. 0) then carr(c,j) = garr(g,j) / w_yw endif endif endif end if end if end do end do end subroutine g2c_2d_tmp end module module_clm_HYDRO ================================================ FILE: src/CPL/LIS_cpl/Makefile ================================================ # Makefile # .SUFFIXES: .SUFFIXES: .o .F LIS_ROOT = ../../../.. LIS_MOD = -I ../../mod -I$(LIS_ROOT)/make include $(LIS_ROOT)/make/configure.lis include ../../macros MODFLAG = -I./ -I ../../MPP -I ../../mod OBJS = \ module_lis_HYDRO.o\ lis_drv_HYDRO.o all: $(OBJS) .F.o: @echo "" $(COMPILER90) $(CPPINVOKE) $(CPPFLAGS) -I$(NETCDFINC) -o $(@) $(F90FLAGS) $(MODFLAG) -I../../mod $(LIS_MOD) -I$(MOD_ESMF) $(*).F @echo "" ar -r ../../lib/libHYDRO.a $(@) # # Dependencies: # clean: rm -f *.o *.mod *.stb *~ ================================================ FILE: src/CPL/LIS_cpl/Makefile.cpl ================================================ # Makefile all: (cd ../../; make -f Makefile.comm) (make) clean: (make clean) (cd ../../; make -f Makefile.comm clean) ================================================ FILE: src/CPL/LIS_cpl/lis_drv_HYDRO.F ================================================ !2345678 subroutine lis_drv_HYDRO(n) use module_lis_HYDRO, only: lis_cpl_HYDRO implicit none integer n #ifdef HYDRO_D write(6,*) "calling lis_cpl_HYDRO " #endif ! stop 888 call lis_cpl_HYDRO(n) end subroutine lis_drv_HYDRO ================================================ FILE: src/CPL/LIS_cpl/module_lis_HYDRO.F ================================================ module module_lis_HYDRO use noah271_lsmMod, only : noah271_struc ! use LIS_coreMod, only : LIS_rc, LIS_domain, LIS_masterproc, & ! LIS_ews_ind, LIS_ewe_ind, LIS_nss_ind, LIS_nse_ind use LIS_coreMod ! use LIS_historyMod, only: LIS_gather_gridded_output, lis_gather_tiled_vector_output ! use HYDRO module use module_hydro_stop, only: HYDRO_stop use module_rt_data, only: rt_domain use module_CPL_LAND, only: CPL_LAND_INIT, cpl_outdate use module_mpp_land use config_base, only : nlst use module_HYDRO_drv, only: HYDRO_ini, HYDRO_exe !!! temp use use module_yw, only: SFHEAD1RT,INFXS1RT, soldrain contains subroutine lis_cpl_HYDRO(n) implicit none integer n, k, ix,jx integer :: did, its,ite,jts,jte, ierr integer ntime, wrf_ix,wrf_jx logical mpi_inited !output flux and state variable integer :: i,j, kz did = 1 ntime = 1 ! write(6,*) "yyyywww step 2, n =", n ! write(6,*) "npesx, npesy",LIS_rc%npesx, LIS_rc%npesy if(.not. RT_DOMAIN(did)%initialized) then !!! get soil layers from lis !!! ++++++++++++++ nlst(did)%nsoil = noah271_struc(n)%nslay #ifdef MPP_LAND call mpp_land_bcast_int1(nlst(did)%nsoil) #endif if(nlst(did)%nsoil < 1) then write(6,*) "FATAL ERROR: nsoil is less than 1" call hydro_stop("In module_lis_HYDRO.F module_lis_HYDRO() - nsoil is less than 1") endif allocate(nlst(did)%zsoil8(nlst(did)%nsoil)) nlst(did)%zsoil8(1) = -noah271_struc(n)%lyrthk(1) DO KZ = 2,nlst(did)%nsoil nlst(did)%zsoil8(KZ) = -noah271_struc(n)%lyrthk(KZ)+nlst(did)%zsoil8(KZ-1) END DO !!! ---------- #ifdef HYDRO_D write(6,*) "zsoil8 = ",nlst(did)%zsoil8 #endif call MPI_Initialized( mpi_inited, ierr ) if ( .NOT. mpi_inited ) then call MPI_Init( ierr ) ! stand alone land model. if (ierr /= MPI_SUCCESS) stop "MPI_INIT" call MPI_Comm_dup(MPI_COMM_WORLD, HYDRO_COMM_WORLD, ierr) if (ierr /= MPI_SUCCESS) stop "MPI_COMM_DUP" endif call MPI_Comm_rank( HYDRO_COMM_WORLD, my_id, ierr ) call MPI_Comm_size( HYDRO_COMM_WORLD, numprocs, ierr ) endif if(nlst(did)%rtFlag .eq. 0) return write(cpl_outdate(1:5),'(I4,"-")') LIS_rc%yr if(LIS_rc%mo .lt. 10) then write(cpl_outdate(6:8),'("0",I1,"-")') LIS_rc%mo else write(cpl_outdate(6:8),'(I2,"-")') LIS_rc%mo endif if(LIS_rc%da .lt. 10) then write(cpl_outdate(9:11),'("0",I1,"_")') LIS_rc%da else write(cpl_outdate(9:11),'(I2,"_")') LIS_rc%da endif if(LIS_rc%hr .lt. 10) then write(cpl_outdate(12:14),'("0",I1,":")') LIS_rc%hr else write(cpl_outdate(12:14),'(I2,":")') LIS_rc%hr endif if(LIS_rc%mn .lt. 10) then write(cpl_outdate(15:17),'("0",I1,":")') LIS_rc%mn else write(cpl_outdate(15:17),'(I2,":")') LIS_rc%mn endif if(LIS_rc%ss .lt. 10) then write(cpl_outdate(18:19),'("0",I1)') LIS_rc%ss else write(cpl_outdate(18:19),'(I2)') LIS_rc%ss endif nlst(did)%olddate(1:19) = cpl_outdate(1:19) jx = LIS_rc%lnr(n) ix = LIS_rc%lnc(n) its = LIS_ews_ind(LIS_rc%nnest,my_id+1) ite = LIS_ewe_ind(LIS_rc%nnest,my_id+1) jts = LIS_nss_ind(LIS_rc%nnest,my_id+1) jte = LIS_nse_ind(LIS_rc%nnest,my_id+1) ! write(6,*) "LIS_ews_ind",LIS_ews_ind ! write(6,*) "LIS_ewe_ind",LIS_ewe_ind ! write(6,*) "LIS_nss_ind",LIS_nss_ind ! write(6,*) "LIS_nse_ind",LIS_nse_ind if(.not. RT_DOMAIN(did)%initialized) then ! write(6,*) "yyyywww step 3" #ifdef HYDRO_D write(6,*) "ix,jx, cpl_land_dt",ix,jx, LIS_rc%ts ! write(6,*) "yyyywww step 4 before HYDRO_ini= " write(6,*) "its,ite,jts,jte", its,ite,jts,jte write(6,*) "noah271_struc(n)%nslay=", noah271_struc(n)%nslay write(6,*) "noah271_struc(n)%lyrthk=", noah271_struc(n)%lyrthk #endif nlst(did)%startdate(1:19) = cpl_outdate(1:19) call CPL_LAND_INIT(its,ite,jts,jte) ! write(6,*) "yyyywww step 4 before HYDRO_ini= " ! write(6,*) "its,ite,jts,jte", its,ite,jts,jte call HYDRO_ini(ntime,did=did,ix0=1,jx0=1) if(nlst(did)%sys_cpl .ne. 3) then write(6,*) "FATAL ERROR: sys_cpl should be 3." call hydro_stop("In module_lis_HYDRO.F lis_cpl_HYDRO() - "// & "sys_cpl should be 3. Check hydro.namelist file") endif ! write(6,*) "yyyywww step 5 my_id= ", my_id nlst(did)%dt = LIS_rc%ts ! write(6,*) "LIS_rc%gnc(n),LIS_rc%gnr(n),LIS_rc%glbnch_red(n)", & ! LIS_rc%gnc(n),LIS_rc%gnr(n),LIS_rc%glbnch_red(n) ! write(6,*) "LIS_rc%nch =", LIS_rc%nch(n) ! write(6,*) "size(noah271_struc(n)%noah%cmc)" , size(noah271_struc(n)%noah%cmc) ! write(6,*) "LIS_nss_halo_ind,LIS_nse_halo_ind", LIS_nss_halo_ind,LIS_nse_halo_ind ! write(6,*) "LIS_ews_halo_ind,LIS_ewe_halo_ind",LIS_ews_halo_ind,LIS_ewe_halo_ind ! nlst(did)%startdate(1:19) = cpl_outdate(1:19) RT_DOMAIN(did)%initialized = .true. endif ! write(6,*) "before call lis2HYDRO" ! write(6,*) "size(noah271_struc(n)%noah%smc(1)),n,ix,jx" , size(noah271_struc(n)%noah%smc(1)),n,ix,jx ! write(6,*) "nlst(did)%nsoil = ", nlst(did)%nsoil ! get the initial data from LIS do k = 1 , nlst(did)%nsoil call lis2HYDRO(RT_DOMAIN(did)%SMC(:,:,k),noah271_struc(n)%noah%smc(k),size(noah271_struc(n)%noah%smc(k)),n,ix,jx) call lis2HYDRO(RT_DOMAIN(did)%stc(:,:,k),noah271_struc(n)%noah%stc(k),size(noah271_struc(n)%noah%stc(k)), n,ix,jx) call lis2HYDRO(RT_DOMAIN(did)%SH2OX(:,:,k),noah271_struc(n)%noah%sh2o(k),size(noah271_struc(n)%noah%sh2o(k)),n,ix,jx) enddo #ifdef HYDRO_D write(6,*) "NDHMS lis date ", LIS_rc%yr, LIS_rc%mo, LIS_rc%da, LIS_rc%hr, LIS_rc%mn, LIS_rc%ss #endif ! write(11,*) "RT_DOMAIN(did)%stc",RT_DOMAIN(did)%stc(:,:,1) ! write(12,*) "noah271_struc(n)%noah%stc(1)",noah271_struc(n)%noah%stc(1) ! call land_finish() call lis2HYDRO(RT_DOMAIN(did)%infxsrt(:,:),INFXS1RT,size(INFXS1RT),n,ix,jx) call lis2HYDRO(RT_DOMAIN(did)%soldrain(:,:),SOLDRAIN,size(SOLDRAIN),n,ix,jx) call HYDRO_exe(did) ! add for update the land surface model state variable. ! 3 d variable do k = 1 , nlst(did)%nsoil call HYDRO2lis_2d(RT_DOMAIN(did)%SMC(:,:,k),noah271_struc(n)%noah%smc(k),size(noah271_struc(n)%noah%smc(k)),n,ix,jx) call HYDRO2lis_2d(RT_DOMAIN(did)%stc(:,:,k),noah271_struc(n)%noah%stc(k),size(noah271_struc(n)%noah%stc(k)),n,ix,jx) call HYDRO2lis_2d(RT_DOMAIN(did)%SH2OX(:,:,k),noah271_struc(n)%noah%sh2o(k),size(noah271_struc(n)%noah%sh2o(k)),n,ix,jx) end do call HYDRO2lis_2d(rt_domain(did)%overland%control%surface_water_head_lsm(:,:),SFHEAD1RT,size(SFHEAD1RT),n,ix,jx) return end subroutine lis_cpl_HYDRO subroutine HYDRO2lis_2d(var,v1d,size1,n,ix,jx) implicit none integer :: n, ix, jx, i, r,c, size1 real, dimension(ix,jx) :: var real, dimension(jx,ix) :: tmpVar real :: v1d (size1) ! call LIS_gather_gridded_output(n, p1,tmpVar) do r=1,jx do c=1,ix if(LIS_domain(n)%gindex(c,r).ne.-1) then v1d(LIS_domain(n)%gindex(c,r)) = var(c,r) endif enddo enddo end subroutine HYDRO2lis_2d subroutine lis2HYDRO(var,v1d,size1,n,ix,jx) implicit none integer n, ix,jx, r,c, size1 real, dimension(ix,jx) :: var ! real, dimension(jx,ix) :: tmpVar real :: v1d (size1) ! do i = 1, ix ! tmpVar(:,i) = Var(i,:) ! end do ! call LIS_gather_tiled_vector_output(n,v1d,tmpVar) do r=1,jx do c=1,ix if(LIS_domain(n)%gindex(c,r).ne.-1) then var(c,r) = v1d(LIS_domain(n)%gindex(c,r)) endif enddo enddo end subroutine lis2HYDRO end module module_lis_HYDRO ================================================ FILE: src/CPL/NUOPC_cpl/.gitignore ================================================ *.a *.mk *.mod *.o VERSION ================================================ FILE: src/CPL/NUOPC_cpl/CMakeLists.txt ================================================ ### Library Prerequisites if (NOT TARGET esmf) find_package(ESMF MODULE REQUIRED) endif (NOT TARGET esmf) ### Library Files list(APPEND wrfhydro_nuopc_files WRFHydro_NUOPC_Cap.F90 WRFHydro_NUOPC_Gluecode.F90 WRFHydro_NUOPC_Fields.F90 WRFHydro_NUOPC_Flags.F90 WRFHydro_ESMF_Extensions.F90 ) ### Library Dependencies list(APPEND wrfhydro_nuopc_deps hydro_routing hydro_mpp hydro_driver hydro_orchestrator ) list(APPEND wrfhydro_nuopc_linklibs hydro_utils hydro_mpp hydro_debug_utils hydro_routing_overland hydro_routing_subsurface hydro_data_rec hydro_routing hydro_routing_diversions fortglob hydro_routing_reservoirs_levelpool hydro_routing_reservoirs_hybrid hydro_routing_reservoirs_rfc hydro_routing_reservoirs hydro_driver hydro_orchestrator hydro_netcdf_layer ) if (WRF_HYDRO_NUDGING STREQUAL "1") list(APPEND wrfhydro_nuopc_linklibs hydro_nudging ) endif (WRF_HYDRO_NUDGING STREQUAL "1") ### New Library: wrfhydro_nuopc add_library(wrfhydro_nuopc STATIC ${wrfhydro_nuopc_files}) add_dependencies(wrfhydro_nuopc ${wrfhydro_nuopc_deps}) target_link_libraries(wrfhydro_nuopc PUBLIC ${wrfhydro_nuopc_linklibs}) target_link_libraries(wrfhydro_nuopc PUBLIC esmf) target_link_libraries(wrfhydro_nuopc PUBLIC ${NETCDF_LIBRARIES}) ### Library Installation install(TARGETS wrfhydro_nuopc ${wrfhydro_nuopc_linklibs} EXPORT wrfhydro-config LIBRARY DESTINATION lib ) install(DIRECTORY ${CMAKE_Fortran_MODULE_DIRECTORY} DESTINATION ${CMAKE_INSTALL_PREFIX}/WRFHYDRO ) install(EXPORT wrfhydro-config DESTINATION lib/cmake ) ================================================ FILE: src/CPL/NUOPC_cpl/Doxyfile ================================================ # Doxyfile 1.8.12 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. # # All text after a double hash (##) is considered a comment and is placed in # front of the TAG it is preceding. # # All text after a single hash (#) is considered a comment and will be ignored. # The format is: # TAG = value [value, ...] # For lists, items can also be appended using: # TAG += value [value, ...] # Values that contain spaces should be placed between quotes (\" \"). #--------------------------------------------------------------------------- # Project related configuration options #--------------------------------------------------------------------------- # This tag specifies the encoding used for all characters in the config file # that follow. The default is UTF-8 which is also the encoding used for all text # before the first occurrence of this tag. Doxygen uses libiconv (or the iconv # built into libc) for the transcoding. See http://www.gnu.org/software/libiconv # for the list of possible encodings. # The default value is: UTF-8. DOXYFILE_ENCODING = UTF-8 # The PROJECT_NAME tag is a single word (or a sequence of words surrounded by # double-quotes, unless you are using Doxywizard) that should identify the # project for which the documentation is generated. This name is used in the # title of most generated pages and in a few other places. # The default value is: My Project. PROJECT_NAME = "WRF-Hydro NUOPC Cap" # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version # control system is used. PROJECT_NUMBER = # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. PROJECT_BRIEF = # With the PROJECT_LOGO tag one can specify a logo or an icon that is included # in the documentation. The maximum height of the logo should not exceed 55 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy # the logo to the output directory. PROJECT_LOGO = # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path # into which the generated documentation will be written. If a relative path is # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. OUTPUT_DIRECTORY = docs # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and # will distribute the generated files over these directories. Enabling this # option can be useful when feeding doxygen a huge amount of source files, where # putting all generated files in the same directory would otherwise causes # performance problems for the file system. # The default value is: NO. CREATE_SUBDIRS = NO # If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII # characters to appear in the names of generated files. If set to NO, non-ASCII # characters will be escaped, for example _xE3_x81_x84 will be used for Unicode # U+3044. # The default value is: NO. ALLOW_UNICODE_NAMES = NO # The OUTPUT_LANGUAGE tag is used to specify the language in which all # documentation generated by doxygen is written. Doxygen will use this # information to generate all constant output in the proper language. # Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese, # Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States), # Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian, # Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages), # Korean, Korean-en (Korean with English messages), Latvian, Lithuanian, # Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian, # Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish, # Ukrainian and Vietnamese. # The default value is: English. OUTPUT_LANGUAGE = English # If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member # descriptions after the members that are listed in the file and class # documentation (similar to Javadoc). Set to NO to disable this. # The default value is: YES. BRIEF_MEMBER_DESC = YES # If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief # description of a member or function before the detailed description # # Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the # brief descriptions will be completely suppressed. # The default value is: YES. REPEAT_BRIEF = YES # This tag implements a quasi-intelligent brief description abbreviator that is # used to form the text in various listings. Each string in this list, if found # as the leading text of the brief description, will be stripped from the text # and the result, after processing the whole list, is used as the annotated # text. Otherwise, the brief description is used as-is. If left blank, the # following values are used ($name is automatically replaced with the name of # the entity):The $name class, The $name widget, The $name file, is, provides, # specifies, contains, represents, a, an and the. ABBREVIATE_BRIEF = "The $name class" \ "The $name widget" \ "The $name file" \ is \ provides \ specifies \ contains \ represents \ a \ an \ the # If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then # doxygen will generate a detailed section even if there is only a brief # description. # The default value is: NO. ALWAYS_DETAILED_SEC = NO # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all # inherited members of a class in the documentation of that class as if those # members were ordinary class members. Constructors, destructors and assignment # operators of the base classes will not be shown. # The default value is: NO. INLINE_INHERITED_MEMB = NO # If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path # before files name in the file list and in the header files. If set to NO the # shortest path that makes the file name unique will be used # The default value is: YES. FULL_PATH_NAMES = YES # The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. # Stripping is only done if one of the specified strings matches the left-hand # part of the path. The tag can be used to show relative paths in the file list. # If left blank the directory from which doxygen is run is used as the path to # strip. # # Note that you can specify absolute paths here, but also relative paths, which # will be relative from the directory where doxygen is started. # This tag requires that the tag FULL_PATH_NAMES is set to YES. STRIP_FROM_PATH = # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the # path mentioned in the documentation of a class, which tells the reader which # header file to include in order to use a class. If left blank only the name of # the header file containing the class definition is used. Otherwise one should # specify the list of include paths that are normally passed to the compiler # using the -I flag. STRIP_FROM_INC_PATH = # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but # less readable) file names. This can be useful is your file systems doesn't # support long names like on DOS, Mac, or CD-ROM. # The default value is: NO. SHORT_NAMES = NO # If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the # first line (until the first dot) of a Javadoc-style comment as the brief # description. If set to NO, the Javadoc-style will behave just like regular Qt- # style comments (thus requiring an explicit @brief command for a brief # description.) # The default value is: NO. JAVADOC_AUTOBRIEF = NO # If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first # line (until the first dot) of a Qt-style comment as the brief description. If # set to NO, the Qt-style will behave just like regular Qt-style comments (thus # requiring an explicit \brief command for a brief description.) # The default value is: NO. QT_AUTOBRIEF = NO # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a # multi-line C++ special comment block (i.e. a block of //! or /// comments) as # a brief description. This used to be the default behavior. The new default is # to treat a multi-line C++ comment block as a detailed description. Set this # tag to YES if you prefer the old behavior instead. # # Note that setting this tag to YES also means that rational rose comments are # not recognized any more. # The default value is: NO. MULTILINE_CPP_IS_BRIEF = NO # If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the # documentation from any documented member that it re-implements. # The default value is: YES. INHERIT_DOCS = YES # If the SEPARATE_MEMBER_PAGES tag is set to YES then doxygen will produce a new # page for each member. If set to NO, the documentation of a member will be part # of the file/class/namespace that contains it. # The default value is: NO. SEPARATE_MEMBER_PAGES = NO # The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen # uses this value to replace tabs by spaces in code fragments. # Minimum value: 1, maximum value: 16, default value: 4. TAB_SIZE = 4 # This tag can be used to specify a number of aliases that act as commands in # the documentation. An alias has the form: # name=value # For example adding # "sideeffect=@par Side Effects:\n" # will allow you to put the command \sideeffect (or @sideeffect) in the # documentation, which will result in a user-defined paragraph with heading # "Side Effects:". You can put \n's in the value part of an alias to insert # newlines. ALIASES = # This tag can be used to specify a number of word-keyword mappings (TCL only). # A mapping has the form "name=value". For example adding "class=itcl::class" # will allow you to use the command class in the itcl::class meaning. TCL_SUBST = # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For # instance, some of the names that are used will be different. The list of all # members will be omitted, etc. # The default value is: NO. OPTIMIZE_OUTPUT_FOR_C = NO # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or # Python sources only. Doxygen will then generate output that is more tailored # for that language. For instance, namespaces will be presented as packages, # qualified scopes will look different, etc. # The default value is: NO. OPTIMIZE_OUTPUT_JAVA = NO # Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran # sources. Doxygen will then generate output that is tailored for Fortran. # The default value is: NO. OPTIMIZE_FOR_FORTRAN = YES # Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL # sources. Doxygen will then generate output that is tailored for VHDL. # The default value is: NO. OPTIMIZE_OUTPUT_VHDL = NO # Doxygen selects the parser to use depending on the extension of the files it # parses. With this tag you can assign which parser to use for a given # extension. Doxygen has a built-in mapping, but you can override or extend it # using this tag. The format is ext=language, where ext is a file extension, and # language is one of the parsers supported by doxygen: IDL, Java, Javascript, # C#, C, C++, D, PHP, Objective-C, Python, Fortran (fixed format Fortran: # FortranFixed, free formatted Fortran: FortranFree, unknown formatted Fortran: # Fortran. In the later case the parser tries to guess whether the code is fixed # or free formatted code, this is the default for Fortran type files), VHDL. For # instance to make doxygen treat .inc files as Fortran files (default is PHP), # and .f files as C (default is Fortran), use: inc=Fortran f=C. # # Note: For files without extension you can use no_extension as a placeholder. # # Note that for custom extensions you also need to set FILE_PATTERNS otherwise # the files are not read by doxygen. EXTENSION_MAPPING = # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments # according to the Markdown format, which allows for more readable # documentation. See http://daringfireball.net/projects/markdown/ for details. # The output of markdown processing is further processed by doxygen, so you can # mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in # case of backward compatibilities issues. # The default value is: YES. MARKDOWN_SUPPORT = YES # When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up # to that level are automatically included in the table of contents, even if # they do not have an id attribute. # Note: This feature currently applies only to Markdown headings. # Minimum value: 0, maximum value: 99, default value: 0. # This tag requires that the tag MARKDOWN_SUPPORT is set to YES. TOC_INCLUDE_HEADINGS = 0 # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can # be prevented in individual cases by putting a % sign in front of the word or # globally by setting AUTOLINK_SUPPORT to NO. # The default value is: YES. AUTOLINK_SUPPORT = YES # If you use STL classes (i.e. std::string, std::vector, etc.) but do not want # to include (a tag file for) the STL sources as input, then you should set this # tag to YES in order to let doxygen match functions declarations and # definitions whose arguments contain STL classes (e.g. func(std::string); # versus func(std::string) {}). This also make the inheritance and collaboration # diagrams that involve STL classes more complete and accurate. # The default value is: NO. BUILTIN_STL_SUPPORT = NO # If you use Microsoft's C++/CLI language, you should set this option to YES to # enable parsing support. # The default value is: NO. CPP_CLI_SUPPORT = NO # Set the SIP_SUPPORT tag to YES if your project consists of sip (see: # http://www.riverbankcomputing.co.uk/software/sip/intro) sources only. Doxygen # will parse them like normal C++ but will assume all classes use public instead # of private inheritance when no explicit protection keyword is present. # The default value is: NO. SIP_SUPPORT = NO # For Microsoft's IDL there are propget and propput attributes to indicate # getter and setter methods for a property. Setting this option to YES will make # doxygen to replace the get and set methods by a property in the documentation. # This will only work if the methods are indeed getting or setting a simple # type. If this is not the case, or you want to show the methods anyway, you # should set this option to NO. # The default value is: YES. IDL_PROPERTY_SUPPORT = YES # If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC # tag is set to YES then doxygen will reuse the documentation of the first # member in the group (if any) for the other members of the group. By default # all members of a group must be documented explicitly. # The default value is: NO. DISTRIBUTE_GROUP_DOC = NO # If one adds a struct or class to a group and this option is enabled, then also # any nested class or struct is added to the same group. By default this option # is disabled and one has to add nested compounds explicitly via \ingroup. # The default value is: NO. GROUP_NESTED_COMPOUNDS = NO # Set the SUBGROUPING tag to YES to allow class member groups of the same type # (for instance a group of public functions) to be put as a subgroup of that # type (e.g. under the Public Functions section). Set it to NO to prevent # subgrouping. Alternatively, this can be done per class using the # \nosubgrouping command. # The default value is: YES. SUBGROUPING = YES # When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions # are shown inside the group in which they are included (e.g. using \ingroup) # instead of on a separate page (for HTML and Man pages) or section (for LaTeX # and RTF). # # Note that this feature does not work in combination with # SEPARATE_MEMBER_PAGES. # The default value is: NO. INLINE_GROUPED_CLASSES = NO # When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions # with only public data fields or simple typedef fields will be shown inline in # the documentation of the scope in which they are defined (i.e. file, # namespace, or group documentation), provided this scope is documented. If set # to NO, structs, classes, and unions are shown on a separate page (for HTML and # Man pages) or section (for LaTeX and RTF). # The default value is: NO. INLINE_SIMPLE_STRUCTS = NO # When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or # enum is documented as struct, union, or enum with the name of the typedef. So # typedef struct TypeS {} TypeT, will appear in the documentation as a struct # with name TypeT. When disabled the typedef will appear as a member of a file, # namespace, or class. And the struct will be named TypeS. This can typically be # useful for C code in case the coding convention dictates that all compound # types are typedef'ed and only the typedef is referenced, never the tag name. # The default value is: NO. TYPEDEF_HIDES_STRUCT = NO # The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This # cache is used to resolve symbols given their name and scope. Since this can be # an expensive process and often the same symbol appears multiple times in the # code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small # doxygen will become slower. If the cache is too large, memory is wasted. The # cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range # is 0..9, the default is 0, corresponding to a cache size of 2^16=65536 # symbols. At the end of a run doxygen will report the cache usage and suggest # the optimal cache size from a speed point of view. # Minimum value: 0, maximum value: 9, default value: 0. LOOKUP_CACHE_SIZE = 0 #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- # If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in # documentation are documented, even if no documentation was available. Private # class members and static file members will be hidden unless the # EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES. # Note: This will also disable the warnings about undocumented members that are # normally produced when WARNINGS is set to YES. # The default value is: NO. EXTRACT_ALL = YES # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will # be included in the documentation. # The default value is: NO. EXTRACT_PRIVATE = YES # If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal # scope will be included in the documentation. # The default value is: NO. EXTRACT_PACKAGE = YES # If the EXTRACT_STATIC tag is set to YES, all static members of a file will be # included in the documentation. # The default value is: NO. EXTRACT_STATIC = NO # If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined # locally in source files will be included in the documentation. If set to NO, # only classes defined in header files are included. Does not have any effect # for Java sources. # The default value is: YES. EXTRACT_LOCAL_CLASSES = YES # This flag is only useful for Objective-C code. If set to YES, local methods, # which are defined in the implementation section but not in the interface are # included in the documentation. If set to NO, only methods in the interface are # included. # The default value is: NO. EXTRACT_LOCAL_METHODS = NO # If this flag is set to YES, the members of anonymous namespaces will be # extracted and appear in the documentation as a namespace called # 'anonymous_namespace{file}', where file will be replaced with the base name of # the file that contains the anonymous namespace. By default anonymous namespace # are hidden. # The default value is: NO. EXTRACT_ANON_NSPACES = NO # If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all # undocumented members inside documented classes or files. If set to NO these # members will be included in the various overviews, but no documentation # section is generated. This option has no effect if EXTRACT_ALL is enabled. # The default value is: NO. HIDE_UNDOC_MEMBERS = NO # If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all # undocumented classes that are normally visible in the class hierarchy. If set # to NO, these classes will be included in the various overviews. This option # has no effect if EXTRACT_ALL is enabled. # The default value is: NO. HIDE_UNDOC_CLASSES = NO # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend # (class|struct|union) declarations. If set to NO, these declarations will be # included in the documentation. # The default value is: NO. HIDE_FRIEND_COMPOUNDS = NO # If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any # documentation blocks found inside the body of a function. If set to NO, these # blocks will be appended to the function's detailed documentation block. # The default value is: NO. HIDE_IN_BODY_DOCS = NO # The INTERNAL_DOCS tag determines if documentation that is typed after a # \internal command is included. If the tag is set to NO then the documentation # will be excluded. Set it to YES to include the internal documentation. # The default value is: NO. INTERNAL_DOCS = NO # If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file # names in lower-case letters. If set to YES, upper-case letters are also # allowed. This is useful if you have classes or files whose names only differ # in case and if your file system supports case sensitive file names. Windows # and Mac users are advised to set this option to NO. # The default value is: system dependent. CASE_SENSE_NAMES = YES # If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with # their full class and namespace scopes in the documentation. If set to YES, the # scope will be hidden. # The default value is: NO. HIDE_SCOPE_NAMES = NO # If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will # append additional text to a page's title, such as Class Reference. If set to # YES the compound reference will be hidden. # The default value is: NO. HIDE_COMPOUND_REFERENCE= NO # If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of # the files that are included by a file in the documentation of that file. # The default value is: YES. SHOW_INCLUDE_FILES = YES # If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each # grouped member an include statement to the documentation, telling the reader # which file to include in order to use the member. # The default value is: NO. SHOW_GROUPED_MEMB_INC = NO # If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include # files with double quotes in the documentation rather than with sharp brackets. # The default value is: NO. FORCE_LOCAL_INCLUDES = NO # If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the # documentation for inline members. # The default value is: YES. INLINE_INFO = YES # If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the # (detailed) documentation of file and class members alphabetically by member # name. If set to NO, the members will appear in declaration order. # The default value is: YES. SORT_MEMBER_DOCS = YES # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief # descriptions of file, namespace and class members alphabetically by member # name. If set to NO, the members will appear in declaration order. Note that # this will also influence the order of the classes in the class list. # The default value is: NO. SORT_BRIEF_DOCS = NO # If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the # (brief and detailed) documentation of class members so that constructors and # destructors are listed first. If set to NO the constructors will appear in the # respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS. # Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief # member documentation. # Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting # detailed member documentation. # The default value is: NO. SORT_MEMBERS_CTORS_1ST = NO # If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy # of group names into alphabetical order. If set to NO the group names will # appear in their defined order. # The default value is: NO. SORT_GROUP_NAMES = NO # If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by # fully-qualified names, including namespaces. If set to NO, the class list will # be sorted only by class name, not including the namespace part. # Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. # Note: This option applies only to the class list, not to the alphabetical # list. # The default value is: NO. SORT_BY_SCOPE_NAME = NO # If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper # type resolution of all parameters of a function it will reject a match between # the prototype and the implementation of a member function even if there is # only one candidate or it is obvious which candidate to choose by doing a # simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still # accept a match between prototype and implementation in such cases. # The default value is: NO. STRICT_PROTO_MATCHING = NO # The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo # list. This list is created by putting \todo commands in the documentation. # The default value is: YES. GENERATE_TODOLIST = YES # The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test # list. This list is created by putting \test commands in the documentation. # The default value is: YES. GENERATE_TESTLIST = YES # The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug # list. This list is created by putting \bug commands in the documentation. # The default value is: YES. GENERATE_BUGLIST = YES # The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO) # the deprecated list. This list is created by putting \deprecated commands in # the documentation. # The default value is: YES. GENERATE_DEPRECATEDLIST= YES # The ENABLED_SECTIONS tag can be used to enable conditional documentation # sections, marked by \if ... \endif and \cond # ... \endcond blocks. ENABLED_SECTIONS = # The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the # initial value of a variable or macro / define can have for it to appear in the # documentation. If the initializer consists of more lines than specified here # it will be hidden. Use a value of 0 to hide initializers completely. The # appearance of the value of individual variables and macros / defines can be # controlled using \showinitializer or \hideinitializer command in the # documentation regardless of this setting. # Minimum value: 0, maximum value: 10000, default value: 30. MAX_INITIALIZER_LINES = 30 # Set the SHOW_USED_FILES tag to NO to disable the list of files generated at # the bottom of the documentation of classes and structs. If set to YES, the # list will mention the files that were used to generate the documentation. # The default value is: YES. SHOW_USED_FILES = YES # Set the SHOW_FILES tag to NO to disable the generation of the Files page. This # will remove the Files entry from the Quick Index and from the Folder Tree View # (if specified). # The default value is: YES. SHOW_FILES = YES # Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces # page. This will remove the Namespaces entry from the Quick Index and from the # Folder Tree View (if specified). # The default value is: YES. SHOW_NAMESPACES = YES # The FILE_VERSION_FILTER tag can be used to specify a program or script that # doxygen should invoke to get the current version for each file (typically from # the version control system). Doxygen will invoke the program by executing (via # popen()) the command command input-file, where command is the value of the # FILE_VERSION_FILTER tag, and input-file is the name of an input file provided # by doxygen. Whatever the program writes to standard output is used as the file # version. For an example see the documentation. FILE_VERSION_FILTER = # The LAYOUT_FILE tag can be used to specify a layout file which will be parsed # by doxygen. The layout file controls the global structure of the generated # output files in an output format independent way. To create the layout file # that represents doxygen's defaults, run doxygen with the -l option. You can # optionally specify a file name after the option, if omitted DoxygenLayout.xml # will be used as the name of the layout file. # # Note that if you run doxygen from a directory containing a file called # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE # tag is left empty. LAYOUT_FILE = # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib # extension is automatically appended if omitted. This requires the bibtex tool # to be installed. See also http://en.wikipedia.org/wiki/BibTeX for more info. # For LaTeX the style of the bibliography can be controlled using # LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the # search path. See also \cite for info how to create references. CITE_BIB_FILES = #--------------------------------------------------------------------------- # Configuration options related to warning and progress messages #--------------------------------------------------------------------------- # The QUIET tag can be used to turn on/off the messages that are generated to # standard output by doxygen. If QUIET is set to YES this implies that the # messages are off. # The default value is: NO. QUIET = NO # The WARNINGS tag can be used to turn on/off the warning messages that are # generated to standard error (stderr) by doxygen. If WARNINGS is set to YES # this implies that the warnings are on. # # Tip: Turn warnings on while writing the documentation. # The default value is: YES. WARNINGS = YES # If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate # warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag # will automatically be disabled. # The default value is: YES. WARN_IF_UNDOCUMENTED = YES # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for # potential errors in the documentation, such as not documenting some parameters # in a documented function, or documenting parameters that don't exist or using # markup commands wrongly. # The default value is: YES. WARN_IF_DOC_ERROR = YES # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that # are documented, but have no documentation for their parameters or return # value. If set to NO, doxygen will only warn about wrong or incomplete # parameter documentation, but not about the absence of documentation. # The default value is: NO. WARN_NO_PARAMDOC = NO # If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when # a warning is encountered. # The default value is: NO. WARN_AS_ERROR = NO # The WARN_FORMAT tag determines the format of the warning messages that doxygen # can produce. The string should contain the $file, $line, and $text tags, which # will be replaced by the file and line number from which the warning originated # and the warning text. Optionally the format may contain $version, which will # be replaced by the version of the file (if it could be obtained via # FILE_VERSION_FILTER) # The default value is: $file:$line: $text. WARN_FORMAT = "$file:$line: $text" # The WARN_LOGFILE tag can be used to specify a file to which warning and error # messages should be written. If left blank the output is written to standard # error (stderr). WARN_LOGFILE = #--------------------------------------------------------------------------- # Configuration options related to the input files #--------------------------------------------------------------------------- # The INPUT tag is used to specify the files and/or directories that contain # documented source files. You may enter file names like myfile.cpp or # directories like /usr/src/myproject. Separate the files or directories with # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. INPUT = # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses # libiconv (or the iconv built into libc) for the transcoding. See the libiconv # documentation (see: http://www.gnu.org/software/libiconv) for the list of # possible encodings. # The default value is: UTF-8. INPUT_ENCODING = UTF-8 # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and # *.h) to filter out the source-files in the directories. # # Note that for custom extensions or not directly supported extensions you also # need to set EXTENSION_MAPPING for the extension otherwise the files are not # read by doxygen. # # If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, # *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, # *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, # *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, # *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf and *.qsf. FILE_PATTERNS = *.c \ *.cc \ *.cxx \ *.cpp \ *.c++ \ *.java \ *.ii \ *.ixx \ *.ipp \ *.i++ \ *.inl \ *.idl \ *.ddl \ *.odl \ *.h \ *.hh \ *.hxx \ *.hpp \ *.h++ \ *.cs \ *.d \ *.php \ *.php4 \ *.php5 \ *.phtml \ *.inc \ *.m \ *.markdown \ *.mm \ *.dox \ *.py \ *.pyw \ *.f90 \ *.F90 \ *.f95 \ *.f03 \ *.f08 \ *.f \ *.for \ *.tcl \ *.vhd \ *.vhdl \ *.ucf \ *.qsf # The RECURSIVE tag can be used to specify whether or not subdirectories should # be searched for input files as well. # The default value is: NO. RECURSIVE = NO # The EXCLUDE tag can be used to specify files and/or directories that should be # excluded from the INPUT source files. This way you can easily exclude a # subdirectory from a directory tree whose root is specified with the INPUT tag. # # Note that relative paths are relative to the directory from which doxygen is # run. EXCLUDE = # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded # from the input. # The default value is: NO. EXCLUDE_SYMLINKS = NO # If the value of the INPUT tag contains directories, you can use the # EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude # certain files from those directories. # # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories for example use the pattern */test/* EXCLUDE_PATTERNS = # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the # output. The symbol name can be a fully qualified name, a word, or if the # wildcard * is used, a substring. Examples: ANamespace, AClass, # AClass::ANamespace, ANamespace::*Test # # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories use the pattern */test/* EXCLUDE_SYMBOLS = # The EXAMPLE_PATH tag can be used to specify one or more files or directories # that contain example code fragments that are included (see the \include # command). EXAMPLE_PATH = # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and # *.h) to filter out the source-files in the directories. If left blank all # files are included. EXAMPLE_PATTERNS = * # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be # searched for input files to be used with the \include or \dontinclude commands # irrespective of the value of the RECURSIVE tag. # The default value is: NO. EXAMPLE_RECURSIVE = NO # The IMAGE_PATH tag can be used to specify one or more files or directories # that contain images that are to be included in the documentation (see the # \image command). IMAGE_PATH = docimages # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program # by executing (via popen()) the command: # # # # where is the value of the INPUT_FILTER tag, and is the # name of an input file. Doxygen will then use the output that the filter # program writes to standard output. If FILTER_PATTERNS is specified, this tag # will be ignored. # # Note that the filter must not add or remove lines; it is applied before the # code is scanned, but not when the output code is generated. If lines are added # or removed, the anchors will not be placed correctly. # # Note that for custom extensions or not directly supported extensions you also # need to set EXTENSION_MAPPING for the extension otherwise the files are not # properly processed by doxygen. INPUT_FILTER = # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern # basis. Doxygen will compare the file name with each pattern and apply the # filter if there is a match. The filters are a list of the form: pattern=filter # (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how # filters are used. If the FILTER_PATTERNS tag is empty or if none of the # patterns match the file name, INPUT_FILTER is applied. # # Note that for custom extensions or not directly supported extensions you also # need to set EXTENSION_MAPPING for the extension otherwise the files are not # properly processed by doxygen. FILTER_PATTERNS = # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using # INPUT_FILTER) will also be used to filter the input files that are used for # producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES). # The default value is: NO. FILTER_SOURCE_FILES = NO # The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file # pattern. A pattern will override the setting for FILTER_PATTERN (if any) and # it is also possible to disable source filtering for a specific pattern using # *.ext= (so without naming a filter). # This tag requires that the tag FILTER_SOURCE_FILES is set to YES. FILTER_SOURCE_PATTERNS = # If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that # is part of the input, its contents will be placed on the main page # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. USE_MDFILE_AS_MAINPAGE = #--------------------------------------------------------------------------- # Configuration options related to source browsing #--------------------------------------------------------------------------- # If the SOURCE_BROWSER tag is set to YES then a list of source files will be # generated. Documented entities will be cross-referenced with these sources. # # Note: To get rid of all source code in the generated output, make sure that # also VERBATIM_HEADERS is set to NO. # The default value is: NO. SOURCE_BROWSER = NO # Setting the INLINE_SOURCES tag to YES will include the body of functions, # classes and enums directly into the documentation. # The default value is: NO. INLINE_SOURCES = NO # Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any # special comment blocks from generated source code fragments. Normal C, C++ and # Fortran comments will always remain visible. # The default value is: YES. STRIP_CODE_COMMENTS = YES # If the REFERENCED_BY_RELATION tag is set to YES then for each documented # function all documented functions referencing it will be listed. # The default value is: NO. REFERENCED_BY_RELATION = NO # If the REFERENCES_RELATION tag is set to YES then for each documented function # all documented entities called/used by that function will be listed. # The default value is: NO. REFERENCES_RELATION = NO # If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set # to YES then the hyperlinks from functions in REFERENCES_RELATION and # REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will # link to the documentation. # The default value is: YES. REFERENCES_LINK_SOURCE = YES # If SOURCE_TOOLTIPS is enabled (the default) then hovering a hyperlink in the # source code will show a tooltip with additional information such as prototype, # brief description and links to the definition and documentation. Since this # will make the HTML file larger and loading of large files a bit slower, you # can opt to disable this feature. # The default value is: YES. # This tag requires that the tag SOURCE_BROWSER is set to YES. SOURCE_TOOLTIPS = YES # If the USE_HTAGS tag is set to YES then the references to source code will # point to the HTML generated by the htags(1) tool instead of doxygen built-in # source browser. The htags tool is part of GNU's global source tagging system # (see http://www.gnu.org/software/global/global.html). You will need version # 4.8.6 or higher. # # To use it do the following: # - Install the latest version of global # - Enable SOURCE_BROWSER and USE_HTAGS in the config file # - Make sure the INPUT points to the root of the source tree # - Run doxygen as normal # # Doxygen will invoke htags (and that will in turn invoke gtags), so these # tools must be available from the command line (i.e. in the search path). # # The result: instead of the source browser generated by doxygen, the links to # source code will now point to the output of htags. # The default value is: NO. # This tag requires that the tag SOURCE_BROWSER is set to YES. USE_HTAGS = NO # If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a # verbatim copy of the header file for each class for which an include is # specified. Set to NO to disable this. # See also: Section \class. # The default value is: YES. VERBATIM_HEADERS = YES # If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the # clang parser (see: http://clang.llvm.org/) for more accurate parsing at the # cost of reduced performance. This can be particularly helpful with template # rich C++ code for which doxygen's built-in parser lacks the necessary type # information. # Note: The availability of this option depends on whether or not doxygen was # generated with the -Duse-libclang=ON option for CMake. # The default value is: NO. CLANG_ASSISTED_PARSING = NO # If clang assisted parsing is enabled you can provide the compiler with command # line options that you would normally use when invoking the compiler. Note that # the include paths will already be set by doxygen for the files and directories # specified with INPUT and INCLUDE_PATH. # This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. CLANG_OPTIONS = #--------------------------------------------------------------------------- # Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- # If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index of all # compounds will be generated. Enable this if the project contains a lot of # classes, structs, unions or interfaces. # The default value is: YES. ALPHABETICAL_INDEX = YES # The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in # which the alphabetical index list will be split. # Minimum value: 1, maximum value: 20, default value: 5. # This tag requires that the tag ALPHABETICAL_INDEX is set to YES. COLS_IN_ALPHA_INDEX = 5 # In case all classes in a project start with a common prefix, all classes will # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag # can be used to specify a prefix (or a list of prefixes) that should be ignored # while generating the index headers. # This tag requires that the tag ALPHABETICAL_INDEX is set to YES. IGNORE_PREFIX = #--------------------------------------------------------------------------- # Configuration options related to the HTML output #--------------------------------------------------------------------------- # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output # The default value is: YES. GENERATE_HTML = YES # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of # it. # The default directory is: html. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_OUTPUT = html # The HTML_FILE_EXTENSION tag can be used to specify the file extension for each # generated HTML page (for example: .htm, .php, .asp). # The default value is: .html. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_FILE_EXTENSION = .html # The HTML_HEADER tag can be used to specify a user-defined HTML header file for # each generated HTML page. If the tag is left blank doxygen will generate a # standard header. # # To get valid HTML the header file that includes any scripts and style sheets # that doxygen needs, which is dependent on the configuration options used (e.g. # the setting GENERATE_TREEVIEW). It is highly recommended to start with a # default header using # doxygen -w html new_header.html new_footer.html new_stylesheet.css # YourConfigFile # and then modify the file new_header.html. See also section "Doxygen usage" # for information on how to generate the default header that doxygen normally # uses. # Note: The header is subject to change so you typically have to regenerate the # default header when upgrading to a newer version of doxygen. For a description # of the possible markers and block names see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_HEADER = # The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each # generated HTML page. If the tag is left blank doxygen will generate a standard # footer. See HTML_HEADER for more information on how to generate a default # footer and what special commands can be used inside the footer. See also # section "Doxygen usage" for information on how to generate the default footer # that doxygen normally uses. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_FOOTER = # The HTML_STYLESHEET tag can be used to specify a user-defined cascading style # sheet that is used by each HTML page. It can be used to fine-tune the look of # the HTML output. If left blank doxygen will generate a default style sheet. # See also section "Doxygen usage" for information on how to generate the style # sheet that doxygen normally uses. # Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as # it is more robust and this tag (HTML_STYLESHEET) will in the future become # obsolete. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_STYLESHEET = # The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined # cascading style sheets that are included after the standard style sheets # created by doxygen. Using this option one can overrule certain style aspects. # This is preferred over using HTML_STYLESHEET since it does not replace the # standard style sheet and is therefore more robust against future updates. # Doxygen will copy the style sheet files to the output directory. # Note: The order of the extra style sheet files is of importance (e.g. the last # style sheet in the list overrules the setting of the previous ones in the # list). For an example see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_EXTRA_STYLESHEET = # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note # that these files will be copied to the base HTML output directory. Use the # $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these # files. In the HTML_STYLESHEET file, use the file name only. Also note that the # files will be copied as-is; there are no commands or markers available. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_EXTRA_FILES = # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen # will adjust the colors in the style sheet and background images according to # this color. Hue is specified as an angle on a colorwheel, see # http://en.wikipedia.org/wiki/Hue for more information. For instance the value # 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 # purple, and 360 is red again. # Minimum value: 0, maximum value: 359, default value: 220. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_COLORSTYLE_HUE = 220 # The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors # in the HTML output. For a value of 0 the output will use grayscales only. A # value of 255 will produce the most vivid colors. # Minimum value: 0, maximum value: 255, default value: 100. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_COLORSTYLE_SAT = 100 # The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the # luminance component of the colors in the HTML output. Values below 100 # gradually make the output lighter, whereas values above 100 make the output # darker. The value divided by 100 is the actual gamma applied, so 80 represents # a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not # change the gamma. # Minimum value: 40, maximum value: 240, default value: 80. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_COLORSTYLE_GAMMA = 80 # If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML # page will contain the date and time when the page was generated. Setting this # to YES can help to show when doxygen was last run and thus if the # documentation is up to date. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_TIMESTAMP = NO # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML # documentation will contain sections that can be hidden and shown after the # page has loaded. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_DYNAMIC_SECTIONS = NO # With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries # shown in the various tree structured indices initially; the user can expand # and collapse entries dynamically later on. Doxygen will expand the tree to # such a level that at most the specified number of entries are visible (unless # a fully collapsed tree already exceeds this amount). So setting the number of # entries 1 will produce a full collapsed tree by default. 0 is a special value # representing an infinite number of entries and will result in a full expanded # tree by default. # Minimum value: 0, maximum value: 9999, default value: 100. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_INDEX_NUM_ENTRIES = 100 # If the GENERATE_DOCSET tag is set to YES, additional index files will be # generated that can be used as input for Apple's Xcode 3 integrated development # environment (see: http://developer.apple.com/tools/xcode/), introduced with # OSX 10.5 (Leopard). To create a documentation set, doxygen will generate a # Makefile in the HTML output directory. Running make will produce the docset in # that directory and running make install will install the docset in # ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at # startup. See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html # for more information. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_DOCSET = NO # This tag determines the name of the docset feed. A documentation feed provides # an umbrella under which multiple documentation sets from a single provider # (such as a company or product suite) can be grouped. # The default value is: Doxygen generated docs. # This tag requires that the tag GENERATE_DOCSET is set to YES. DOCSET_FEEDNAME = "Doxygen generated docs" # This tag specifies a string that should uniquely identify the documentation # set bundle. This should be a reverse domain-name style string, e.g. # com.mycompany.MyDocSet. Doxygen will append .docset to the name. # The default value is: org.doxygen.Project. # This tag requires that the tag GENERATE_DOCSET is set to YES. DOCSET_BUNDLE_ID = org.doxygen.Project # The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify # the documentation publisher. This should be a reverse domain-name style # string, e.g. com.mycompany.MyDocSet.documentation. # The default value is: org.doxygen.Publisher. # This tag requires that the tag GENERATE_DOCSET is set to YES. DOCSET_PUBLISHER_ID = org.doxygen.Publisher # The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher. # The default value is: Publisher. # This tag requires that the tag GENERATE_DOCSET is set to YES. DOCSET_PUBLISHER_NAME = Publisher # If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three # additional HTML index files: index.hhp, index.hhc, and index.hhk. The # index.hhp is a project file that can be read by Microsoft's HTML Help Workshop # (see: http://www.microsoft.com/en-us/download/details.aspx?id=21138) on # Windows. # # The HTML Help Workshop contains a compiler that can convert all HTML output # generated by doxygen into a single compiled HTML file (.chm). Compiled HTML # files are now used as the Windows 98 help format, and will replace the old # Windows help format (.hlp) on all Windows platforms in the future. Compressed # HTML files also contain an index, a table of contents, and you can search for # words in the documentation. The HTML workshop also contains a viewer for # compressed HTML files. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_HTMLHELP = NO # The CHM_FILE tag can be used to specify the file name of the resulting .chm # file. You can add a path in front of the file if the result should not be # written to the html output directory. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. CHM_FILE = # The HHC_LOCATION tag can be used to specify the location (absolute path # including file name) of the HTML help compiler (hhc.exe). If non-empty, # doxygen will try to run the HTML help compiler on the generated index.hhp. # The file has to be specified with full path. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. HHC_LOCATION = # The GENERATE_CHI flag controls if a separate .chi index file is generated # (YES) or that it should be included in the master .chm file (NO). # The default value is: NO. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. GENERATE_CHI = NO # The CHM_INDEX_ENCODING is used to encode HtmlHelp index (hhk), content (hhc) # and project file content. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. CHM_INDEX_ENCODING = # The BINARY_TOC flag controls whether a binary table of contents is generated # (YES) or a normal table of contents (NO) in the .chm file. Furthermore it # enables the Previous and Next buttons. # The default value is: NO. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. BINARY_TOC = NO # The TOC_EXPAND flag can be set to YES to add extra items for group members to # the table of contents of the HTML help documentation and to the tree view. # The default value is: NO. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. TOC_EXPAND = NO # If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and # QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that # can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help # (.qch) of the generated HTML documentation. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_QHP = NO # If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify # the file name of the resulting .qch file. The path specified is relative to # the HTML output folder. # This tag requires that the tag GENERATE_QHP is set to YES. QCH_FILE = # The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help # Project output. For more information please see Qt Help Project / Namespace # (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace). # The default value is: org.doxygen.Project. # This tag requires that the tag GENERATE_QHP is set to YES. QHP_NAMESPACE = org.doxygen.Project # The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt # Help Project output. For more information please see Qt Help Project / Virtual # Folders (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#virtual- # folders). # The default value is: doc. # This tag requires that the tag GENERATE_QHP is set to YES. QHP_VIRTUAL_FOLDER = doc # If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom # filter to add. For more information please see Qt Help Project / Custom # Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- # filters). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_CUST_FILTER_NAME = # The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the # custom filter to add. For more information please see Qt Help Project / Custom # Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- # filters). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_CUST_FILTER_ATTRS = # The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this # project's filter section matches. Qt Help Project / Filter Attributes (see: # http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_SECT_FILTER_ATTRS = # The QHG_LOCATION tag can be used to specify the location of Qt's # qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the # generated .qhp file. # This tag requires that the tag GENERATE_QHP is set to YES. QHG_LOCATION = # If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be # generated, together with the HTML files, they form an Eclipse help plugin. To # install this plugin and make it available under the help contents menu in # Eclipse, the contents of the directory containing the HTML and XML files needs # to be copied into the plugins directory of eclipse. The name of the directory # within the plugins directory should be the same as the ECLIPSE_DOC_ID value. # After copying Eclipse needs to be restarted before the help appears. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_ECLIPSEHELP = NO # A unique identifier for the Eclipse help plugin. When installing the plugin # the directory name containing the HTML and XML files should also have this # name. Each documentation set should have its own identifier. # The default value is: org.doxygen.Project. # This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES. ECLIPSE_DOC_ID = org.doxygen.Project # If you want full control over the layout of the generated HTML pages it might # be necessary to disable the index and replace it with your own. The # DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top # of each HTML page. A value of NO enables the index and the value YES disables # it. Since the tabs in the index contain the same information as the navigation # tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. DISABLE_INDEX = NO # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index # structure should be generated to display hierarchical information. If the tag # value is set to YES, a side panel will be generated containing a tree-like # index structure (just like the one that is generated for HTML Help). For this # to work a browser that supports JavaScript, DHTML, CSS and frames is required # (i.e. any modern browser). Windows users are probably better off using the # HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can # further fine-tune the look of the index. As an example, the default style # sheet generated by doxygen has an example that shows how to put an image at # the root of the tree instead of the PROJECT_NAME. Since the tree basically has # the same information as the tab index, you could consider setting # DISABLE_INDEX to YES when enabling this option. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_TREEVIEW = NO # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that # doxygen will group on one line in the generated HTML documentation. # # Note that a value of 0 will completely suppress the enum values from appearing # in the overview section. # Minimum value: 0, maximum value: 20, default value: 4. # This tag requires that the tag GENERATE_HTML is set to YES. ENUM_VALUES_PER_LINE = 4 # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used # to set the initial width (in pixels) of the frame in which the tree is shown. # Minimum value: 0, maximum value: 1500, default value: 250. # This tag requires that the tag GENERATE_HTML is set to YES. TREEVIEW_WIDTH = 250 # If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to # external symbols imported via tag files in a separate window. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. EXT_LINKS_IN_WINDOW = NO # Use this tag to change the font size of LaTeX formulas included as images in # the HTML documentation. When you change the font size after a successful # doxygen run you need to manually remove any form_*.png images from the HTML # output directory to force them to be regenerated. # Minimum value: 8, maximum value: 50, default value: 10. # This tag requires that the tag GENERATE_HTML is set to YES. FORMULA_FONTSIZE = 10 # Use the FORMULA_TRANPARENT tag to determine whether or not the images # generated for formulas are transparent PNGs. Transparent PNGs are not # supported properly for IE 6.0, but are supported on all modern browsers. # # Note that when changing this option you need to delete any form_*.png files in # the HTML output directory before the changes have effect. # The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. FORMULA_TRANSPARENT = YES # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see # http://www.mathjax.org) which uses client side Javascript for the rendering # instead of using pre-rendered bitmaps. Use this if you do not have LaTeX # installed or if you want to formulas look prettier in the HTML output. When # enabled you may also need to install MathJax separately and configure the path # to it using the MATHJAX_RELPATH option. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. USE_MATHJAX = NO # When MathJax is enabled you can set the default output format to be used for # the MathJax output. See the MathJax site (see: # http://docs.mathjax.org/en/latest/output.html) for more details. # Possible values are: HTML-CSS (which is slower, but has the best # compatibility), NativeMML (i.e. MathML) and SVG. # The default value is: HTML-CSS. # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_FORMAT = HTML-CSS # When MathJax is enabled you need to specify the location relative to the HTML # output directory using the MATHJAX_RELPATH option. The destination directory # should contain the MathJax.js script. For instance, if the mathjax directory # is located at the same level as the HTML output directory, then # MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax # Content Delivery Network so you can quickly see the result without installing # MathJax. However, it is strongly recommended to install a local copy of # MathJax from http://www.mathjax.org before deployment. # The default value is: http://cdn.mathjax.org/mathjax/latest. # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest # The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax # extension names that should be enabled during MathJax rendering. For example # MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_EXTENSIONS = # The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces # of code that will be used on startup of the MathJax code. See the MathJax site # (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an # example see the documentation. # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_CODEFILE = # When the SEARCHENGINE tag is enabled doxygen will generate a search box for # the HTML output. The underlying search engine uses javascript and DHTML and # should work on any modern browser. Note that when using HTML help # (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET) # there is already a search function so this one should typically be disabled. # For large projects the javascript based search engine can be slow, then # enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to # search using the keyboard; to jump to the search box use + S # (what the is depends on the OS and browser, but it is typically # , /