Modularisation: global radiation and sunshine duration

[tyralla]

We strive for a higher modularisation of our application models. Meaning we want to make many application models smaller, focussing on fewer processes. Such a modularisation would make individual models easier to understand and maintain and offer new possibilities in model coupling. One good example is the evap_v001 model, which calculates the FAO reference evaporation. Models like wland_v001 or lland_v2 get this reference evaporation (or another kind of potential evaporation) as their input and do not need to calculate the many intermediate terms of reference evaporation on their own.

The next thing we try to factor out is the calculation of global radiation from sunshine duration and the inverse case, sunshine duration from global radiation. The current reason to address this problem is as follows. lland_v3 gets the sunshine duration as input and derives the global radiation from it. This direction fits for simulating historical periods with measured data, which includes much more often sunshine duration than global radiation. However, when using the output data from meteorological models as input, we get global radiation as input data. Then, we need to calculate sunshine duration from it (or use other equations for the longwave energy balance). Principally, we could create another application model deviating from lland_v3 just in this aspect but being identical in all others. But factoring out the related process equations seem preferable, especially when taking the enormous number of process equations of lland_v3 into account.

When factoring out global radiation from lland_v3, we probably should do the same for evap_v001, which also calculates global radiation from sunshine duration. I would even suggest starting with evap_v001, as it comes with simpler equations with less need for discussion.

First, I propose to introduce a new model family. For example, we could name it Meteo if we think it should later target also other meteorological factors than sunshine duration and global radiation. Alternatively, if we want to keep the field of application more limited, we could name it something like Radiotion.

The following graph shows how evap_v001 calculates the NetRadiation (input sequences in blue, all others in black). The red line is my suggestion on how to split the old evap_001 model into the new meteo_v001 and evap_v001 models.

The reason for the chosen position of the line is that all factors left from it are mainly associated with the atmosphere, while net radiation more directly depends on the current state of the earth's surface (e.g., is there a snow cover or not?).

What surprised me when looking at the graph was that the new evap_v001 model would require two inputs, GlobalRadiation and ClearSkySolarRadiation. Using more theoretical factors like ClearSkySolarRadiation as the input to a model seems a little bit strange. Still, maybe that is the price to pay when striving for more modularity.

I have not yet thought it through thoroughly, but meteo_v001 should work in combination with a refactored version of lland_v3, too. Then, one would need to select PossibleSunshineDuration as the output of meteo_v001, because LARSIM uses the ratio between actual and possible sunshine duration instead of the ratio between actual and potential global radiation for guessing cloudiness.

The required flexibility in defining the relevant output sequences of meteo_v001 is technically already supported. However, we still could improve the usability of the related features, but we should discuss this in another issue.

The graph does not separate the "normal" radiation terms and their logged equivalents. To clarify: I think, the new evap_v001 model should be responsible to calculate LoggedGlobalRadiation and LoggedClearSkySolarRadiation, because different evaporation approaches favour different ways of guessing cloudiness during nighttime.

[tyralla]

Commit e16402eba684dee068ffa4481ebebc78118b847c split the old evap_v001 model into meteo_v001 and the new evap_v001 model. Commit be1e3e50b23ba66fef9c37de0a85bcc627d4d5be introduces meteo_v002, which calculates sunshine radiation from global radiation.

[tyralla]

Next, we do the same with HydPy-L-Land (LARSIM). One point that needs discussion is making names more consistent. As Evap and Meteo, we prefer non-abbreviated, self-explaining variable names. For historical reasons, most terms of HydPy-L-Land already follow this convention, but some are still (German) abbreviations.

The following list gives the old sequence names in L-Land (left) and my suggestions for Meteo (right).

Sequences:

• SolarDeclination: SolarDeclination
• TSA: TimeOfSunrise
• TSU: TimeOfSunset
• EarthSunDistance: EarthSunDistance
• ExtraterrestrialRadiation: ExtraterrestrialRadiation
• PossibleSunshineDuration: PossibleSunshineDuration
• DailyPossibleSunshineDuration: DailyPossibleSunshineDuration
• LoggedSunshineDuration: LoggedSunshineDuration
• DailySunshineDuration: DailySunshineDuration
• LoggedGlobalRadiation: LoggedUnadjustedGlobalRadiation
• DailyGlobalRadiation: DailyGlobalRadiation
• SP: PortionDailyRadiation
• GlobalRadiation: UnadjustedGlobalRadiation
• AdjustedGlobalRadiation: GlobalRadiation

In L-Land, we first calculate the global radiation and then the "adjusted" global radiation, meaning GlobalRadiation is not the final value to be used by other methods. To keep things consistent in Meteo, we rename GlobalRadiation to UnadjustedGlobalRadiation and AdjustedGlobalRadiation to GlobalRadiation.

Global radiation is already a valid input value for the application model lland_v1, named Glob. I suggest renaming it to GlobalRadiation.

The following list suggests the new parameter names:

• Latitude: Latitude
• Longitude: Longitude
• AngstromConstant: AngstromConstant
• AngstromFactor: AngstromFactor
• AngstromAlternative: AngstromAlternative
• Sol: SolarConstant
• NmbLogEntries: NmbLogEntries

[tyralla]

The following figure shows a possible choice on extracting meteo_v003 from lland_v3 (I hope I did not miss a relevant connection):

In the above configuration, there were no need for duplicate calculations. However, we would need to specify five input sequences for our new lland_v3 model to couple it to meteo_v003:

• DailySunshineDuration
• DailyPossibleSunshineDuration
• PossibleSunshineDuration
• GlobalRadiation
• DailyGlobalRadiation

The following design prevents such a tight coupling:

However, there are three (potential) drawbacks:

1. Code duplication for logging and calculating daily values.
2. Increased simulation time due to performing the logging and calculating the daily values twice.
3. I am unsure if the calculated daily values would always be identical in meteo_v003 and lland_v3.

Thoughts on these points:

1. Not the most relevant concern. Other issues are making lland_v3 unnecessarily complicated. Nevertheless, we could minimise this problem by introducing sequence classes that solve these tasks in a standardised way.
2. Also not the most important point, as the concerned terms are scalar, meaning we do not need to repeat the procedures for all hydrological response units. Maybe we could introduce a more efficient algorithm for calculating daily values later.
3. Regarding DailySunshineDuration, there will be no problem, as we need to recalculate it from scratch. Regarding DailyPossibleSunshineDuration, the documentation on method Calc_PossibleSunshineDuration_V1 seems to imply that the sum of, for example, hourly values and a directly calculated daily value must always be equal. Regarding DailyGlobalRadiation, I am relatively confident. Principally, the involved norming process should guarantee that the sums of hourly values and directly calculated daily values are identical. However, at the moment, I cannot rule out for sure if slight inconsistencies in the handling of time points by the related methods result in (slight) inconsistencies in recalculated DailyGlobalRadiation.

[sivogel]

Next, we do the same with HydPy-L-Land (LARSIM). One point that needs discussion is making names more consistent. As Evap and Meteo, we prefer non-abbreviated, self-explaining variable names. For historical reasons, most terms of HydPy-L-Land already follow this convention, but some are still (German) abbreviations.

The following list gives the old sequence names in L-Land (left) and my suggestions for Meteo (right).

Sequences:

• SolarDeclination: SolarDeclination
• TSA: TimeOfSunrise
• TSU: TimeOfSunset
• EarthSunDistance: EarthSunDistance
• ExtraterrestrialRadiation: ExtraterrestrialRadiation
• PossibleSunshineDuration: PossibleSunshineDuration
• DailyPossibleSunshineDuration: DailyPossibleSunshineDuration
• LoggedSunshineDuration: LoggedSunshineDuration
• DailySunshineDuration: DailySunshineDuration
• LoggedGlobalRadiation: LoggedUnadjustedGlobalRadiation
• DailyGlobalRadiation: DailyGlobalRadiation
• SP: PortionDailyRadiation
• GlobalRadiation: UnadjustedGlobalRadiation
• AdjustedGlobalRadiation: GlobalRadiation

In L-Land, we first calculate the global radiation and then the "adjusted" global radiation, meaning GlobalRadiation is not the final value to be used by other methods. To keep things consistent in Meteo, we rename GlobalRadiation to UnadjustedGlobalRadiation and AdjustedGlobalRadiation to GlobalRadiation.

Global radiation is already a valid input value for the application model lland_v1, named Glob. I suggest renaming it to GlobalRadiation.

The following list suggests the new parameter names:

• Latitude: Latitude
• Longitude: Longitude
• AngstromConstant: AngstromConstant
• AngstromFactor: AngstromFactor
• AngstromAlternative: AngstromAlternative
• Sol: SolarConstant
• NmbLogEntries: NmbLogEntries

Two names are a bit cumbersome: PortionDailyRadiation: I would suggest DailyRadiationRatio or RelativeRadiationSum UnadjustedGlobalRadiation: I would suggest RawGlobalRadiation, but those different Radiations calculations are confusing anyhow

[tyralla]

PortionDailyRadiation: I would suggest DailyRadiationRatio or RelativeRadiationSum

Maybe DailyRadiationRation is a little bit misleading, but RelativeRadiationSum sounds good (similar meaning, I guess, but appears more scientific).

UnadjustedGlobalRadiation: I would suggest RawGlobalRadiation, but those different Radiations calculations are confusing anyhow

Yes, I agree we cannot avoid confusion by choosing good names here. UnadjustedGlobalRadiation is a little long but maybe also more self-explaining than RawGlobalRadiation. Another idea we had is UncorrectedGlobalRadiation.

[tyralla]

The issue of units:

In lland_v1, Glob must be given in W/m². For all other models, we preferred MJ/m² for all energy fluxes (sometimes we write MJ/m²/T, T being the project-specific simulation step size).

Intuitively, W/m² seems clearer to me. However, MJ/m² is more consistent with how we handle most area-related mass fluxes (for example, mm or mm/T for precipitation, which is l/m² or l/m²/T).

Going from W/m² to MJ/m² would require much more work than just changing the unit of Glob.

[BGWKlein]

I would prefer the unit W/m2 for global radiation as it is often used in hydrological modelling as unit of global radiation Also in the ATV-DVWK-M 504 Merkblatt and in several meteorological models the unit W/m2 is used (see e.g. DWD-ICON https://www.dwd.de/SharedDocs/downloads/DE/modelldokumentationen/nwv/icon/icon_dbbeschr_aktuell.html)

[tyralla]

I unsure if the calculated daily values would always be identical in meteo_v003 and lland_v3.

... Regarding DailyGlobalRadiation, I am relatively confident. Principally, the involved norming process should guarantee that the sums of hourly values and directly calculated daily values are identical. However, at the moment I cannot rule out for sure if slight inconsistencies in the handling of time points by the related methods result in (slight) inconsistencies in recalculated DailyGlobalRadiation.

It seems like I was too optimistic. There is a problem with defining daily values and how LARSIM adjusts hourly global radiation to daily global radiation.

In most cases, we say that, for example, the daily sunshine duration is the sunshine duration measured over the last 24 hours. Also, some daily values are determined based on other daily values. Daily global radiation estimates, for example, rely on daily sunshine duration and daily possible sunshine duration.

LARSIM calculates global radiation based on the Ångström formula. For hourly simulations, it estimates 24 hourly values and one daily value. Then it adjusts the 24 hourly values so that their sum is equal to the daily value. However, LARSIM always uses the daily global radiation of the current calendar day, while L-Land uses the global radiation sum of the last 24 hours for norming.

We use the following equation (i is the current hour, GR is (adjusted) hourly global radiation, DGR is (directly calculated) daily global radiation, UGR is unadjusted hourly global radiation):

This is what we do when recalculating daily global radiation based on adjusted hourly global radiation:

Obviously, DGR and DGR* are not the same. However, I hope (and think) differences are just random and do not introduce any bias.

So what seems preferable when, for example, calculating evaporation based on the Penman equation? DGR* is consistent with GR but hard to understand, as its current value depends on the last 48 hourly values of measured sunshine duration.

I am still unsure but tend to let lland_v3 calculate DGR*, which simplifies model coupling, as discussed above. If lland_v3 would also require DGR as input, we could not couple it to meteo_v001 and meteo_002 anymore. Or, we would need to add features to these FAO-inspired models that are unique to LARSIM.

[tyralla]

There is another difference, but this one is smaller. It is due to the method Calc_DailyPossibleSunshineDuration_V1, which is the only one where L-Land calculates a daily value in LARSIM's style, meaning for the current calendar day (blue line in the following figure). If we instead recalculate daily possible sunshine duration by summing the last 24 hourly possible sunshine duration values, we get a slightly different pattern (orange line):

I note this down mainly for completeness and as a reminder. The differences are too small to be relevant. However, maybe we should adjust the calculation of daily possible sunshine duration in meteo_v003 (so that it also calculates the orange line) for the sake of consistency?

[tyralla]

We found an inconsistency in the definition of extraterrestrial radiation: in L-Land, ExtraterrestrialRadiation has the unit MJ/m²/d, in Evap, ExtraterrestrialRadiation has the unit MJ/m² or MJ/m²/T. Now that we merge the related features into Meteo, we must decide on one option. I tend to MJ/m² or MJ/m²/T for the sake of consistency with other (radiation) fluxes.

This issue is related to the definition of the solar constant. L-Land uses MJ/m²/d for Sol (despite the nonsense unit m given in the documentation). We should make the new parameter SolarConstant of Meteo time-dependent so that its actual value always has the unit MJ/m² or MJ/m²/T (then, only its "INIT" value would be defined in MJ/m²/d ).

[BGWKlein]

Why not using the same unit for extraterrestrialradiation as for global radiation, to be consistent, e.g. W/m2?

[tyralla]

I would prefer the unit W/m2 for global radiation as it is often used in hydrological modelling as unit of global radiation

After a thorough personal discussion, we came to the following decisions (which are also the next working steps):

• [x] We use the unit W/m² for all energy fluxes.
• [x] We adjust the units of all related parameters, for example Sol.
• [x] We use the unit WT/m² for all energy states, T being the simulation step size.
• [x] We always write mm/T instead of mm (or analogue for other mass fluxes).
• [ ] We adjust the writing of the integration test tables to avoid writing results with too many digits (at most eight, nine or ten?)
• [x] A little off-topic: We prefer hPa over kPa for air pressure.

This way, users can supply inputs like global radiation in a commonly used unit.

WT/m² is probably not the most intuitive choice but keeps updating energy states straightforward and consistent with updating mass states. A usual mass update already follows

,

while a energy update then follows

.

This conversion factor free approach avoids unnecessary computations and eases comparisons between energy fluxes and states.

The unintuitiveness of WT/m² does not appear overly relevant, as HydPy implements only a few sequences reflecting energy states. Additionally, these should be only relevant for specialists diving deep into the theory of the respective model.

[tyralla]

Commit d56db88ce232d02c47876b4f7c689f7d06146b61 implements meteo_v003 and commit bf27f69822ce45276bcc7ea1a18e60b724e87dfb removes the related features from lland_v3 and lland_v4. We followed the second suggestions where meteo_v003 only passes global radiation and the astronomically possible sunshine duration to lland_v3. The refinements discussed above (improve some names, calculate the astronomically possible daily sunshine duration like other daily values, W/m² instead of MJ/m²/T) are still open.

[tyralla]

The next step is to add the application model meteo_v004 as the counterpart of meteo_v003 like meteo_v002 is the counterpart of meteo_v001. Meaning meteo_v004 calculates sunshine duration based on global radiation, using LARSIM-like instead of FAO-like equations. I try to include a methodology that "reverses" the adjustment of global radiation as good as possible. Or, said reversely, that adjusts the sum of the hourly sunshine duration values of the last 24 hours to the directly calculated daily sunshine duration. If I remember correctly, this is nothing that LARSIM does but seems more consistent to me when switching from meteo_v003 to meteo_v004 in the context of forecasting. (We could implement the even more consistent approach of neglecting the adjustment in both ways later in meteo_v005 and meteo_v006, which seems like little effort.)

[tyralla]

(We could implement the even more consistent approach of neglecting the adjustment in both ways later in meteo_v005 and meteo_v006, which seems like little effort.)

Not really necessary because we can define the "unadjusted sunshine duration" as output. Removing the adjustment process would only save computation time.

[tyralla]

Commit 39c24936574a91f434dd9ebf9863d247b9e1508d adds meteo_v004, but maybe this is just a preliminary version. I am not completely happy because it cannot "revert" meteo_v003 perfectly for sub-daily timesteps. Maybe someone has an idea to improve it later. Until then, we should apply it to a real project and see how it performs.

[tyralla]

As discussed above, we modified all energy-related and pressure-related parameter and sequence classes of lland, evap, and meteo as well as the corresponding equations and doctests. See commits 1453b6e6d573ed9fb1eaed770dfb6340e04c21bb, 98234b8fabfeda4c908a9d156e2e64e16096bdf8, 84fec008ba549ef3250d1ecdbc57bed15a3970b5, 50a60de665d5f570e41a730ac4be5ed59cd8db43, 64b82d5208c6efb892955d4655e1c5ac39a9df42, and 83de253c4328c92c2955897b5bfaa3794ee649e4. All unit and integration tests pass, but experience in real projects is still missing. Restricting the number of digits in the relevant integration tests proved unnecessary.

One thing that came into my mind when adjusting lland_v1 and lland_v2: I think now the time is right to remove lland_v1 and to move its Turc-Wendling approach for estimating potential evapotranspiration into the evap model family, meaning we would introduce evap_v002. I am pretty sure that coupling evap_v002 and lland_v2 would lead to the same results as applying lland_v1.

[BGWKlein]

following the new modularization paradigma, it is consequent to shift Turc-Wendling to evap and to remove lland_v1