Model names in HydPy 6.0

[tyralla]

In HydPy 5, model names are not overly consistent. We aim to improve this in HydPy 6.0. The following table lists the current and future names. The future names are still open for discussion. Hence, I will edit the table until we agree on all names. The discussion can take place as additional comments, as usual.

HydPy 5.0 source code	HydPy 6.0 source code	HydPy 6.0 documentation
arma_v1	arma_rimorido	HydPy-ARMA-RIMO/RIDO (nonlinear routing by multiple ARMA processes)
conv_v001	conv_nn	HydPy-Conv-NN (nearest neighbour interpolation)
conv_v002	conv_idw	HydPy-Conv-IDW (inverse distance weighted interpolation)
conv_v003	conv_idw_ed	HydPy-Conv-IDW-ED (inverse distance weighted interpolation with external drift)
dam_v001	?	?
dam_v002	?	?
dam_v003	?	?
dam_v004	?	?
dam_v005	?	?
dam_v006	dam_llake	HydPy-Dam-L-Lake (controlled lake model adopted from LARSIM)
dam_v007	dam_lretention	HydPy-Dam-L-RB (retention basin model adopted from LARSIM)
dam_v008	dam_lreservoir	HydPy-Dam-L-Res (reservoir model adopted from LARSIM)
	dam_pump	HydPy-Dam-Pump (pumping station model)
	dam_sluice	HydPy-Dam-Sluice (sluice model)
	dam_pump_sluice	HydPy-Dam-Pump-Sluice (pumping station with sluice model)
dummy_v1	dummy_node2node	HydPy-Dummy-Node2Node (dummy model passing data from inlet to outlet nodes)
	dummy_interceptedwater	HydPy-Dummy-InterceptedWater (dummy model supplying main models with intercepted water states)
	dummy_soilwater	HydPy-Dummy-SoilWater (dummy model supplying main models with soil water states)
	dummy_snowcover	HydPy-Dummy-SnowCover (dummy model supplying main models with snow cover states)
	dummy_snowycanopy	HydPy-Dummy-SnowyCanopy (dummy model supplying main models with snow cover degrees in canopies)
	dummy_snowalbedo	HydPy-Dummy-SnowAlbedo (dummy model supplying main models with snow albedo states)
evap_v001	evap_ret_fao56	HydPy-Evap-RET-FAO56 (FAO-56 Penman-Monteith reference evapotranspiration)
	evap_ret_tw2002	HydPy-Evap-RET-TW2002 (Turc-Wendling reference evapotranspiration, 2002)
	evap_ret_io	HydPy-Evap-RET-IO (external data)
	evap_pet_m	HydPy-Evap-PET-M (month-based adjustment of reference evapotranspiration)
	evap_pet_mlc	HydPy-Evap-PET-M-LC (month-based land cover adjustment of reference evapotranspiration)
	evap_pet_ambav1	HydPy-Evap-PET-AMBAV-1.0 (potential evapotranspiration based on AMBAV 1.0)
	evap_pet_hbv96	HydPy-Evap-PET-HBV96 (potential evapotranspiration after HBV96)
	evap_aet_hbv96	HydPy-Evap-AET-HBV96 (actual evapotranspiration after HBV96)
	evap_aet_minhas	HydPy-Evap-AET-Minhas (actual evapotranspiration based on the Minhas equation)
	evap_aet_morsim	HydPy-Evap-AET-MORSIM (actual evapotranspiration based on MORECS/LARSIM)
exch_v001	exch_weir_hbv96	HydPy-Exch-Weir-HBV96 (weir model adopted from IHMS-HBV96)
	exch_waterlevel	HydPy-Exch-WL (submodel for querying the water level from a remote node)
	gland_gr4	HydPy-G-GR4 (Génie Rural model with 4 parameters)
	gland_gr5	HydPy-G-GR5 (Génie Rural model with 5 parameters)
	gland_gr6	HydPy-G-GR6 (Génie Rural model with 6 parameters)
hbranch_v1	exch_branch_hbv96	HydPy-Exch-Branch-HBV96 (branch model adopted from IHMS-HBV96)
	ga_garto	HydPy-GA-GARTO (main model for calculating the Green-Ampt / Talbot-Ogden infiltration with redistribution)
	ga_garto_submodel1	HydPy-GA-GARTO-Sub1 (submodel for calculating the Green-Ampt / Talbot-Ogden infiltration with redistribution)
hland_v1	hland_96	HydPy-H-HBV96 (adoption of SMHI-IHMS-HBV96)
hland_v2		(obsolete after extracting the unit hydrograph / linear storage cascade)
hland_v3	hland_96p	HydPy-H-HBV96-PREVAH (fusion of SMHI-IHMS-HBV96 and PREVAH)
hland_v4	hland_96c	HydPy-H-HBV96-COSERO (fusion of SMHI-IHMS-HBV96 and COSERO)
lland_v1	lland_dd	HydPy-L-DD (adoption of LARSIM with degree day-based snow modelling)
lland_v2		(obsolete after extracting Turc-Wendling / reading reference evapotranspiration)
lland_v3	lland_knauf	HydPy-L-Knauf (adoption of LARSIM with Knauf-based snow modelling)
lland_v4	lland_knauf_ic	HydPy-L-Knauf-Ic (adoption of LARSIM with Knauf-based snow modelling including snow interception)
lstream_v001	kinw_williams	HydPy-KinW-Williams (Williams routing based on a triple trapeze profile and the Strickler equation)
lstream_v002	kinw_williams_ext	HydPy-KinW-Williams-Ext (Williams routing based on an externally calculated volume-discharge relationship )
llake_v1		(can be removed, replaced by dam_v006 for a long time now)
meteo_v001	meteo_glob_fao56	HydPy-Meteo-Glob-FAO56 (global radiation estimation adopted from FAO56)
meteo_v002	meteo_sun_fao56	HydPy-Meteo-Sun-FAO56 (sunshine duration estimation adopted from FAO56)
meteo_v003	meteo_glob_morsim	HydPy-Meteo-Glob-MORSIM (global radiation estimation adopted from MORECS/LARSIM)
meteo_v004	meteo_sun_morsim	HydPy-Meteo-Sun-MORSIM (sunshine duration estimation adopted from MORECS/LARSIM)
	meteo_glob_io	HydPy-Meteo-Glob-IO (external global radiation data)
	meteo_clear_glob_io	HydPy-Meteo-Clear-Glob-IO (external clear sky and global radiation data)
	meteo_psun_sun_glob_io	HydPy-PSun-Sun-Glob-IO (external possible and actual sunshine duration and global radiation data)
	meteo_precip_io	HydPy-Meteo-Precip-IO (external precipitation data)
	meteo_temp_io	HydPy-Meteo_Temp-IO (external temperature data)
musk_classic	musk_classic	HydPy-Musk-Classic (classic Muskingum routing, compatible with SMHI-IHMS-HBV96)
musk_mct	musk_mct	HydPy-Musk-MCT (Muskingum-Cunge-Todini routing)
	rconc_uh	HydPy-Rconc-UH (Unit Hydrograph runoff concentration, compatible with HBV96 and GR4J)
	rconc_nash	HydPy-Rconc-Nash (Nash-Cascade runoff concentration)
	snow_cn	HydPy-Snow-CemaNeige (Cema-Neige model with mean temperature as input)
	snow_cn_temprange	HydPy-Snow-CemaNeige-TempRange (Cema-Neige model with minimum and maximum temperature as input)
	sw1d_channel	HydPy-SW1D-Channel ("user model" for preparing single channels that will be combined and solved by HydPy-SW1D-Network)
	sw1d_network	HydPy-SW1D-Network ("composite model" for solving the 1-dimensional shallow water equations in channel networks)
	sw1d_lias	HydPy-SW1D-LIAS (submodel for calculating the discharge between two channel segments based on Bates et al. (2010) and Almeida et al. (2012)
	sw1d_lias_sluice	HydPy-SW1D-LIAS/Sluice (submodel that extends HydPy-SW1D-LIAS with sluice functionalities)
	sw1d_pump	HydPy-SW1D-Pump (submodel for pumping water between two channel segments)
	sw1d_storage	HydPy-SW1D-Storage (submodel for calculating a single channel segment's water balance)
	sw1d_q_in	HydPy-SW1D-Q-In (submodel for adding pre-determined discharge to a channel inlet)
	sw1d_q_out	HydPy-SW1D-Q-Out (submodel for subtracting pre-determined discharge from a channel outlet)
	sw1d_weir_out	HydPy-SW1D-Weir-Out (submodel for calculating free weir flow at a channel outlet)
	sw1d_gate_out	HydPy-SW1D-Gate-Out (submodel for calculating flow under a submerged gate at a channel outlet)
test_v1	test_stiff0d	HydPy-Test-Stiff-0D (test model for stiff ODEs and scalar sequences)
test_v2	test_discontinous	HydPy-Test-Discontinuous (test model for discontinuous ODEs)
test_v3	test_stiff1d	HydPy-Test-Stiff-1D (test model for stiff ODEs and 1-dimensional sequences)
wland_v001	wland_wag	HydPy-W-Wag (extended version of the original Wageningen WALRUS model)
wland_v002	wland_gd	HydPy-W-GD (extended version of the WALRUS model with modified groundwater dynamics)
	wq_walrus	HydPy-WQ-WALRUS (WALRUS default function for calculating catchment outflow)
	wq_trapeze	HydPy-WQ-Trapeze (multi-trapeze river profile submodel)
	wq_trapeze_strickler	HydPy-WQ-Trapeze-Strickler (multi-trapeze river profile submodel including Strickler-based calculations)

[tyralla]

I would say we have three types of application model names:

• The short one. We use it in Python code and the technical part of the online documentation (as a link). It usually consists (or should consist) of the base model's name and a concise description, separated by an underscore. Example: musk_mct.
• The long one. We use it for introducing a new model, e.g. in the title of the model's documentation. It consists of the literal "HydPy", the base model's name, and a short description, all separated by dashes. Also, we append a more exhaustive explanation in brackets that should be even helpful when encountering the model for the first time. Example: HydPy-Musk-MCT (Muskingum-Cunge-Todini).
• The intermediate one, for when the short name appears too technical and the long one too long. Example: Musk-MCT.

[tyralla]

If find naming the hland..., lland..., and wland... models particularly difficult. For these models, modularisation allows reducing the number of different application models stemming from the same base model. Ideally, the main models would be flexible enough and the set of submodels complete enough so that only one child model would be necessary in each case...

[tyralla]

I added evap_io to the table above.

[tyralla]

I still do not know if we will keep them as independent models or merge them into other Evap models, but I added preliminary names for evap_lc and evap_mlc.

[tyralla]

Same for evap_m.

[tyralla]

I nearly finished evap_hbv96 and suggest the full name "HydPy-Evap-HBV96 (potential evaporation after HBV96"). However, for hland_v1, I suggested hland_96. A little inconsistent...

[tyralla]

The main models can be sub-submodels idea seems to be a good one. Hence, we really need something like a precip_io model. However, introducing a new model family named precip does not seem right, especially if precip_io would stay the only application model ever. So, adding it to the meteo family seems preferable. My suggestion for the new application model's name thus is meteo_precip_io. (meteo_p_io could be an alternative, but "p" could also stand for pressure).

[tyralla]

meteo_precip_io would be the first application model name with two underscores.

[tyralla]

A added meteo_temp_io.

[tyralla]

I changed evap_hbv96 to evap_pet_hbv96 for a reason discussed here.

[tyralla]

I removed evap_lc, which is currently not required.

[tyralla]

I added evap_aet_hbv96, which still requires some documentation updates but seems to work fine now.

[tyralla]

I changed the name dummy_v1 to dummy_n2n.

[tyralla]

I added dummy_ic, dummy_sw, and dummy_sc to the table. These models will now serve for testing evap_aet_hbv96 independently from a main model like hland_v1 and later for playing around with different approaches to calculate actual evapotranspiration and other properties to be calculated by submodels.

Adding them to the test model family is also an option. However, the test models are for model developers and provide actual mathematics, so I think the dummy model family fits slightly better.

[tyralla]

I added evap_minhas to the table (which should be in the master branch by today). This model is factored out from lland_v1 and applies an equation introduced by Minhas et al. (1974) to calculate potential evapotranspiration to soil evapotranspiration. Initially, we took this approach from LARSIM-ME, but as there is nothing LARSIM-specific here, I would prefer to let the name refer to the original authors. Like for evap_tw2002.

[tyralla]

I added evap_morsim: HydPy-Evap-MORSIM (actual evapotranspiration based on the LARSIM implementation of MORECS).

Consider this name as a very first suggestion. I tried to come up with a name that combines MORECS and LARSIM to clarify that there are some deviations from the original MORECS methodology that follow the LARSIM model.

[tyralla]

Our (successful!) extraction of the evapotranspiration calculations from lland simplifies the naming problem. So, lland_dd (for day degree) could replace lland_v1 and lland_knauf could replace lland_v3.

[tyralla]

I added the dummy models dummy_snowycanopy and dummy_snowalbedo and gave the others more descriptive names (evap_interceptedwater, evap_soilwater, evap_snowcover). The names are very long, but this should likely bother no one because these models will probably be only used for testing purposes and are of little relevance to model users.

[tyralla]

I added (preliminary versions) of dam_pump, dam_sluice, and dam_pump_sluice to the master branch and updated the above table.

[tyralla]

I added sw1d_channel, sw1d_network, sw1d_storage, sw1d_lias, sw1d_q_in, sw1d_q_out, and sw1d_weir_out to the table.

[tyralla]

I added sw1d_lias_sluice and sw1d_gate_out to the table. Suggestions for more precise words than sluice and gate are welcome!

[tyralla]

I added exch_waterlevel and q_walrus.

[tyralla]

I added evap_pet_ambav1.

[tyralla]

I added meteo_glob_io, meteo_clear_glob_io, and meteo_psun_sun_glob_io .

[BGWKlein]

For meteo and evap models I propose the naming convention:
evap|meteo_[parameter1]<[parameter2]><[parameter3]>_[method]

new model names according to this convention:

meteo_glob_fao56 instead of meteo_fao56glob
meteo_sd_fao56 instead of meteo_fao56sd
meteo_glob_larsim instead of meteo_lglob (probably another method name for larsim? thompsen? MORECS?)
meteo_sd_larsim instead of meteo_lsd (probably another method name for larsim? thompsen? MORECS?)

evap_rep_io instead of evap_io
and so on

[BGWKlein]

I propose model name
wland_wag(eningen) instead of wland_orig

[tyralla]

Yes, making the names of evap and meteo makes sense. I will adjust the table.

wland_wag and wland_orig are both only half-true. One can use wland_v001 like the original Wageningen model, but it offers many more functionalities (hydrological response units, elevated regions, bidirectional coupling with other models, etc.). However, I have no good idea how to express that. wland_wag_plus or wland_wag_ext???

meteo_glob_larsim adds some additional equations to Thompson's paper ("Necker-Korrektur"). For evap, we decided on evap_aet_morsim, which means something like "LARSIM version of MORECS". So, it could make sense to reuse this naming convention for meteo: meteo_glob_morsim and meteo_sd_morsim. (If not, we should eventually rename evap_aet_morsim.)

[BGWKlein]

I would interpret the name wland_wag as the HydPy model using wageningen equations for the walrus part

[tyralla]

I added sw1d_pump to the list.

[tyralla]

I added ga_garto_submodel1 and adjusted the documentation-style name of ga_garto. No nice solution - just in case we will not be able to work on #141 soon enough

[tyralla]

I will use names like "HydPy-Dam-V1 (dam model, version 1)" for dam_v001 to dam_v005. This is also a temporary solution. We considered merging these five models into one by extracting all "special features" into new submodels. Still, it is currently unclear if this is feasible and, if so, if we can work on it before releasing HydPy 6.0. (@sivogel: we do not have a separate issue or any progress on this matter, do we?)

[tyralla]

I changed lstream_v001 to kinw_williams and lstream_v002 to kinw_williams_ext in the list and added documentation-style names.

[tyralla]

I implemented everything as discussed.

I will open a separate issue regarding the further development of dam_v001 to dam_v005.

I kept the original variable names for exch_branch_hbv96, kinw_williams, and kinw_williams_ext. His might be okay for exch_branch_hbv96 (please open another issue if you think differently) but suboptimal for kinw_williams and kinw_williams_ext, which still rely on German abbreviations stemming from LARSIM. I left a warning in its documentation to clarify that one must expect breaking changes due to this and other issues with kinw_williams and `kinw_williams_ext.

We don't have separation into model groups and subgroups anymore! Now, every model family consists of exactly one base model, and all its application models are derived from it. So, we could rename "Model Collection" (a term I never liked too much) to "Model Families" to further increase the consistency of terms used in the documentation.