Energy-balance multi-layer snowpack model implementation by jpnousu · Pull Request #15 · LukeEcomod/pyAPES_main

jpnousu · 2026-03-12T14:56:19Z

The original degreeday snow model approach has been complemented with an option to use an energy-balance, multi-layer snowpack model based on FSM2 (Essery et al., 2025). The original snow process modules written in Fortran were translated to Python, made consistent with pyAPES coding style, and coupled to pyAPES' forestfloor computations. Tests: forestfloor runs standalone with both FSM2 and degreeday snowpack models. Full multi-layer canopy model with prescribed canopy also works with both snowmodel options.

Essery, R., Mazzotti, G., Barr, S., Jonas, T., Quaife, T., and Rutter, N.: A Flexible Snow Model (FSM 2.1.1) including a forest canopy, Geosci. Model Dev., 18, 3583–3605, https://doi.org/10.5194/gmd-18-3583-2025, 2025.

…soil

…now heat flux

…ning

khaahti

Looks good, only minor comments to check before merge!

khaahti · 2026-04-02T07:18:05Z

pyAPES/bottomlayer/organiclayer.py


        return fluxes, states

+    def heat_and_water_exchange_under_snow(self, dt: float, forcing: Dict, parameters: Dict, sub_dt: float=60.0) -> Tuple:


Maybe add here in documentation that this is not used do to instability.

If we at some point want to return to this, we should check iterative solution of temperature need when freezing/thawing is happening. Implemented in heat_and_water_exchange().

khaahti · 2026-04-02T07:25:13Z

pyAPES/canopy/forestfloor.py


+        if self.snow_model == 'degreeday':
+            fluxes_snow['snow_heat_flux'] = 0.
+            snow_bottom_temperature = 0.


Do we get reasonable soil temperatures under degree-day snow if we keep these zero? Or are we fine with that.

khaahti · 2026-04-02T07:28:32Z

pyAPES/snow/degreeday/degreeday.py

+                kmelt melting coefficient [m degC-1 s-1]
+                kfreeze (float): freezing coefficient coefficient [m degC-1 s-1]
+                retention (float): max fraction of liquid water in snow [-]
+                Tmelt (float): melting temperature (~0.0 degC) [degC]


convert units in documentation to Kelvin

khaahti · 2026-04-02T07:31:46Z

pyAPES/snow/pyFSM2/fsm2_coupled.py

+                    }
+
+            fluxes = {'potential_infiltration': snow_fluxes['Roff'],
+                    'snow_heat_flux': snow_fluxes['Gsoil'],  # heat flux to organiclayer


or actually directly to soil now, right?

khaahti · 2026-04-02T07:39:53Z

pyAPES/parameters/mlm_parameters.py

 # --- Model control flags
 ctr = {'Eflow': True,  # use ensemble flow statistics; i.e fixed ratio of Utop/ustar.
       'WMA': False,  # assume air-space scalar profiles well-mixed
       'Ebal': True,  # computes leaf temperature by solving energy balance


Did you check with Ebal=False? When energy balance is not solved the snow model should be forced to degree-day i think.

khaahti · 2026-04-02T07:44:09Z

pyAPES/utils/iotools.py

    dat['Prec'] = dat['Prec'] / dt

-    cols = ['doy', 'Prec', 'P', 'Tair', 'Tdaily', 'U', 'Ustar', 'H2O', 'CO2', 'Zen',
+    cols = ['doy', 'Prec', 'P', 'Tair', 'Tdaily', 'U', 'Ustar', 'H2O', 'RH', 'CO2', 'Zen',


can be calculated if we want to avoid adding variables to forcing.

See also my comment above to mlm_canopy. I think we want to avoid adding variables to forcing to maintain as much backwards compatibility as possible

Altesmi

Looks almost ready, great work!

Two important things

Add comments to new if statements what real-life state the if/elif/else block is modelling e.g., if swe <= 0 # no snow -> do not solve snowpack
Remove RH dependency from forcing. IMO we don't need both [H2O]_air and RH in forcing files

Altesmi · 2026-04-03T09:01:25Z

data/FiHy_cuv_FFlux2018.425

Delete this data before merge

Altesmi · 2026-04-03T09:01:41Z

data/FIHy_flx_2018.dat

Delete this data before merge

Altesmi · 2026-04-03T09:01:58Z

Examples/results/USPrr_test4.nc

Delete this result file before merge

Altesmi · 2026-04-03T09:03:54Z

Examples/Demo_multi_layer_model.ipynb

I've made changes to this notebook. Remember to fetch and merge main before merging

Altesmi · 2026-04-03T09:05:26Z

pyAPES/bottomlayer/organiclayer.py

        if controls['energy_balance']:
            # calculate moss / litter energy and water balance
-            fluxes, states = self.heat_and_water_exchange(
+            if forcing['snow_water_equivalent'] > 0.:


Could you add comment here (and perhaps elsewhere) what we are doing and why when we are entering a certain if/elif/else block

Altesmi · 2026-04-03T09:18:08Z

pyAPES/parameters/mlm_outputs.py

@@ -180,6 +180,11 @@
      ['ffloor_nir_albedo', 'NIR albedo (forest floor) [-]', ('date', 'simulation')],
      ['ffloor_groundtypes', 'forestfloor groundtype names', ('groundtype')],



Are these the only outputs from fsm2?

Altesmi · 2026-04-03T09:21:18Z

pyAPES/canopy/mlm_canopy.py

                'air_pressure': forcing['air_pressure'],
                'wind_speed': U[1],
                'friction_velocity': ustar[1],
+                'relative_humidity': forcing['relative_humidity'],


Do we need relative humidity from forcing or should we calculate it from [H2O]_air. At minimum relative humidity should be added to the run function documentation that it is needed. Does this brake old run scripts that do not have relative humidity in forcing?

Altesmi · 2026-04-03T09:23:24Z

pyAPES/parameters/Degero.py

    'r10': 2.5, # [umol m-2 s-1]
    'q10': 2.0, # [-]
-    'moisture_coeff': [3.83, 4.43, 1.25, 0.854]  # Skopp moisture function param [a ,b, d, g]}
+    'moisture_coeff': [3.83, 4.43, 1.25, 0.854],  # Skopp moisture function param [a ,b, d, g]}


Is skopp moisture function generally known or should we add a reference?

Altesmi · 2026-04-03T09:25:23Z

pyAPES/snow/pyFSM2/fsm2_coupled.py

+        Args:
+            snowpara (dict):
+                'initial_conditions' (dict)
+                    'Sice' (np.ndarray): # Snow ice content (kg/m^2)


Here the style of units has been kg m-2

Altesmi · 2026-04-03T09:28:50Z

pyAPES/utils/iotools.py

    dat['Prec'] = dat['Prec'] / dt

-    cols = ['doy', 'Prec', 'P', 'Tair', 'Tdaily', 'U', 'Ustar', 'H2O', 'CO2', 'Zen',
+    cols = ['doy', 'Prec', 'P', 'Tair', 'Tdaily', 'U', 'Ustar', 'H2O', 'RH', 'CO2', 'Zen',


See also my comment above to mlm_canopy. I think we want to avoid adding variables to forcing to maintain as much backwards compatibility as possible

Jari-Pekka Nousu and others added 30 commits January 18, 2024 17:17

Work-in-progress with snowmodel development

9b656c1

Developments for the snowmodel

6e51f15

Snowmodel devs

8ef23c0

Updates to snowmodel

1dc5d7c

Updates to snowmodel

a4c7e6b

Resolving conflicts

ac4cbe5

bug fix

caf76ff

latest update

58df3fa

baby steps towards snowmodel integration

f4aa355

going around a warning

df56405

updates..

76aa89b

updates for snowmodel

3372b2d

towards fsm integration

fa16de8

Bug fixes

e15ff45

Coupling pyAPES.soil and FSM snow modules

908c237

Bug fix due to soil layering

40e8e2b

new structure

04e8c8d

FSM standalone runs within forestfloor.py

4cee9cc

added wind_speed to forcing

8c67abd

towards coupling of snow and forestfloor

5a0678a

few updates

d8eecc6

organic layer heat and water under snow

112738d

minor changes and closures

c6410a6

freezing and thawing to moss

a194ccf

coupling progress

7c01917

Merge remote-tracking branch 'origin/snowmodel_kersti' into snowmodel

f727141

working with numerical instabilities in surface temps, checkpoint here

a9c96b4

fsm takes in roughness and albedo from bt

f05d4be

bug fix in albedo, other devs

2916f31

back at it

bf45d6e

khaahti and others added 25 commits October 8, 2025 16:10

trying to figure out oscillation, subtimstepping to moss under snow

c935def

testin

ece383b

checkpoint for starting to modify snow coupling from organiclayer to …

0ece092

…soil

snow coupled to soil, still some issues with soil temperature below snow

3b41d0d

snow-soil coupling works?

35323fb

properties of organiclayer and soil combined for the calculation of s…

1448981

…now heat flux

moved the calculation of soil-orglayer properties for snow. plus clea…

92ad688

…ning

few updates and celsius to kelvin conversion in organiclayer

10d8c02

update

54a2ad1

Merge remote-tracking branch 'origin/main' into snowmodel

75a1af7

merges

cf07418

first fsm snowmodel application with mlm canopy

6da9ec7

cleaning fsm2 vegetation parameters away

33db18c

improving snow output handling in fsm and forestfloor

8a86321

lots of documentation and minor edits

3627e2a

minor, something wrong

9ebb963

snow and bt temperature variable updates and unified units etc minor

926a97b

minor

46ef297

Merge remote-tracking branch 'origin/main' into snowmodel

9cd8a73

merge missed snowmodel organiclayer devs

ae0a769

degerö snow demo does not work

15a4adc

fix lw solving with fsm snow

6af39f2

cleaning demos

8d8d82e

removed dependencygraph

47df659

minor

bbc4810

jpnousu requested review from Altesmi, khaahti and slauniainen March 12, 2026 14:56

khaahti reviewed Apr 2, 2026

View reviewed changes

Altesmi requested changes Apr 3, 2026

View reviewed changes


		return fluxes, states

		def heat_and_water_exchange_under_snow(self, dt: float, forcing: Dict, parameters: Dict, sub_dt: float=60.0) -> Tuple:

		@@ -180,6 +180,11 @@
		['ffloor_nir_albedo', 'NIR albedo (forest floor) [-]', ('date', 'simulation')],
		['ffloor_groundtypes', 'forestfloor groundtype names', ('groundtype')],

Conversation

jpnousu commented Mar 12, 2026

Uh oh!

khaahti left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Altesmi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants