Adding Clima Thermodynamics by olivierbonte · Pull Request #112 · NumericalEarth/Terrarium.jl

olivierbonte · 2026-04-30T15:04:03Z

As previously mentioned in #108, I thought Thermodynamics.jl could be a nice way to avoid reimplementation of a lot of the thermodynamics. This PR is an attempt at replacing some utilities by functions from Thermodynamics.jl.

To avoid the use of ClimaParams.jl, PhysicalConstants is defined as a subtype of AbstractThermodynamicsParameters. This approach is inspired by the use of Thermodynamics.jl in NumericalEarth.jl for the atmospheric thermodynamics (see here).

This PR also introduces specific heat capacity and air density as functions, not constants, consistent with the use in Thermodynamics.jl

Co-authored-by: Copilot <copilot@github.com>

…into ob/feature_clima_thermodyn

Co-authored-by: Copilot <copilot@github.com>

olivierbonte · 2026-04-30T15:06:54Z

I now also see that there is an issue on the use of abbreviations in physical constants #111. Is this something to fix in this PR or not @bgroenks96 ?

bgroenks96 · 2026-04-30T16:57:48Z

Hey @olivierbonte, I think this PR would be a good opportunity to resolve #111!

I had also considered splitting up PhysicalConstants into separate types for thermodynamic vs material and hydraulic constants. What do you think about this?

olivierbonte · 2026-05-01T20:24:56Z

Alright! I'll try to address this soon

I agree that splitting up the constants in categories makes sense, otherwise this one struct will get very large I think. Given the current set of properties, thermodynamic vs material makes sense to me. Any preferences for the naming of these structs?

bgroenks96

Looks really great! Thanks a lot!

bgroenks96 · 2026-05-11T14:15:58Z

@olivierbonte Any updates on this? I guess once we merge this we could release a v0.1.1.

olivierbonte · 2026-05-11T15:27:39Z

Sorry for the delay on this @bgroenks96, had some deadlines for teaching responsibilities last week, but this week I'll pick this up again!

…into ob/feature_clima_thermodyn

bgroenks96

Oops, sorry forgot to submit these comments yesterday. I always find this "review" feature of GitHub a bit unintuitive.

olivierbonte · 2026-05-13T17:47:24Z

@bgroenks96 I think all comments are addressed now, let me know what you think!

bgroenks96 · 2026-05-13T19:14:39Z

 )

+# Always have `using Terrarium` available in doctests
+DocMeta.setdocmeta!(Terrarium, :DocTestSetup, :(using Terrarium); recursive = true)


Nice, didn't know about this!

What exactly does this do? I also haven't seen it.

I think it inserts the given expression in every doctest so you don't need a @meta block everywhere.

bgroenks96

Looks good, great work! Just a few more comments, though, sorry 😅

bgroenks96 · 2026-05-13T19:16:42Z

+| `specific_heat_capacity_ice` | $c_{p,i}$ | 2070.0 | J/(kg·K) | Isobaric specific heat capacity of ice at 0°C |
+| `specific_heat_capacity_liquid_water` | $c_{p,l}$ | 4186.0 | J/(kg·K) | Isobaric specific heat capacity of liquid water at 0°C |
+| `specific_heat_capacity_water_vapor` | $c_{p,v}$ | 1846.0 | J/(kg·K) | Isobaric specific heat capacity of water vapor at 0°C |
+| `latent_heat_fusion_at_reference` | $L_{sl}$ | 3.34×10⁵ | J/kg | Specific latent heat of fusion at 0°C |


Hmm, I get the inclination towards being precise by including _at_reference but I wonder whether or not this is really necessary? Can you imagine a situation where we would add more latent heat constants that would not be at a (or rather the) reference temperature?

bgroenks96 · 2026-05-13T19:27:39Z

+$FIELDS
+"""
+struct PhysicalConstants{NF}
+    thermodynamic_constants::ThermodynamicConstants{NF}


To be slightly less verbose, how about thermodynamics, material, and unviersal? That way it's constants.thermodynamics.specific_heat_capacity_dry_air. That would read a bit nicer, no?

bgroenks96 · 2026-05-13T19:59:58Z

+
+# Derived parameters
+@inline Thermodynamics.Parameters.Rv_over_Rd(c::ThermodynamicConstants) = Thermodynamics.Parameters.R_v(c) / Thermodynamics.Parameters.R_d(c)
+@inline ε(c::ThermodynamicConstants) = R_d(c) / R_v(c)


Can you make this explicitly spelled out? I guess it would be ratio_gas_constant_dry_air_to_water_vapor? A bit long but I guess OK?

particularly important given that epsilon (not \varpesilon but still) is used for emissivity.

bgroenks96 · 2026-05-13T20:06:17Z

-        Tₛ = skin_temperature(i, j, grid, fields, skinT) # skin temperature
-        Tₐ = air_temperature(i, j, grid, fields, atmos) # air temperature
-        Q_T = (Tₛ - Tₐ) / rₐ  # bulk aerodynamic temperature-gradient
+    let rₐ = aerodynamic_resistance(i, j, grid, fields, atmos), # aerodynamic resistance


Can you revert the formatting change here? With Runic, I find it better not to use commas in the let block because otherwise it does this weird indenting here. We could also disable the formatter on all let blocks, but I think omitting commas is a cleaner solution. They aren't really necessary anyway.

Actually you could also just remove the let block here since it's the only code in this function. I have a habit of using let blocks a lot, but it's admittedly kind of pointless in cases like this.

bgroenks96 · 2026-05-13T20:08:02Z

-        Δq = compute_specific_humidity_difference(i, j, grid, fields, atmos, constants, Tₛ)
-        Q_h = Δq / rₐ  # humidity flux
+    let L = constants.thermodynamic_constants.latent_heat_vaporization_at_reference,
+            Tₛ = skin_temperature(i, j, grid, fields, skinT),


Same thing here

bgroenks96 · 2026-05-13T20:08:28Z

-    let L = constants.Llg # specific latent heat of vaporization of water
-        ρₐ = constants.ρₐ # density of air
-        Q_h = surface_humidity_flux(i, j, grid, fields, evtr)   # humidity flux
+    let L = constants.thermodynamic_constants.latent_heat_vaporization_at_reference,


bgroenks96 · 2026-05-13T20:11:23Z

 @inline function compute_assimilation_factors(
        photo::LUEPhotosynthesis{NF},
-        constants::PhysicalConstants{NF},
+        constants::MaterialConstants{NF},


Yeah I think I like this! Much clearer dependency structure.

bgroenks96 · 2026-05-13T20:16:16Z


 """
-    specific_humidity_to_vapor_pressure(q, p, ε)
+    vapor_pressure_to_specific_humidity(c::ThermodynamicConstants, e, pr)


Can you explain this change? Why does this need to be inverted now?

bgroenks96 · 2026-05-13T20:28:01Z

+"""
+@kwdef struct MaterialConstants{NF}
+    "Density of water in kg/m^3"
+    water_density::NF = 1000.0


I guess this should be density_water and density_ice if we want to be consistent with the pattern we have started following elsewhere of [quantity]_[constituent]_[location].

olivierbonte and others added 18 commits April 28, 2026 11:36

Add Thermodynamics dep

182d573

Add Thermodynamics dep examples

fc95052

Add WIP extension Thermodynamics

9a79a1a

Co-authored-by: Copilot <copilot@github.com>

Add Rv_over_Rd method

ab3b7e5

Merge branch 'main' of https://github.com/NumericalEarth/Terrarium.jl …

9ed03ed

…into ob/feature_clima_thermodyn

Remove constant air density

38a2a2e

Add utils from Thermodynamics

9be5386

Co-authored-by: Copilot <copilot@github.com>

Add WIP turbulent fluxes refactor

a7f81d7

Co-authored-by: Copilot <copilot@github.com>

Fix tests

89cbc7c

Co-authored-by: Copilot <copilot@github.com>

Add explicit vpd wrapper

fa1e0cc

Co-authored-by: Copilot <copilot@github.com>

Fix units temperature in VPD kernel function

19ceba3

clarify to do

4f460b9

Co-authored-by: Copilot <copilot@github.com>

Add wrapper specific heat capacity moist air

6ac1264

Co-authored-by: Copilot <copilot@github.com>

Add moist air specific heat capacity for sensible heat flux

e7e5742

Co-authored-by: Copilot <copilot@github.com>

Update docstrings

955e575

Co-authored-by: Copilot <copilot@github.com>

Rename q_vap_saturation wrapper

1162689

Add vapor pressure to specific humidity util

6bed9ad

Co-authored-by: Copilot <copilot@github.com>

Adapt docs

c463526

Co-authored-by: Copilot <copilot@github.com>

olivierbonte requested a review from bgroenks96 April 30, 2026 15:04

bgroenks96 requested changes May 2, 2026

View reviewed changes

Comment thread src/processes/physical_constants.jl Outdated

Comment thread src/processes/physics_utils.jl Outdated

olivierbonte added 5 commits May 13, 2026 10:42

Merge branch 'main' of https://github.com/NumericalEarth/Terrarium.jl …

4c414ef

…into ob/feature_clima_thermodyn

Explicitly prefix methods from Thermodynamics.Parameters

ec2e215

Saturation calcs to ifelse use

6c85f82

Fix import Thermodynamics

6d9da93

PhyiscalConstants to full names

33f7d63

bgroenks96 requested changes May 13, 2026

View reviewed changes

Comment thread src/processes/physical_constants.jl Outdated

bgroenks96 mentioned this pull request May 13, 2026

Version bump 0.1.1 #119

Open

olivierbonte added 4 commits May 13, 2026 18:55

Refactor PhyiscalConstants into subtypes

6eaa021

Update docs and docstrings

4eb1ad8

Change Thermodynamics.jl to explicit import style

87e6fba

Fix jldoctest

538c75a

olivierbonte requested a review from bgroenks96 May 13, 2026 17:46

bgroenks96 reviewed May 13, 2026

View reviewed changes

bgroenks96 requested changes May 13, 2026

View reviewed changes

bgroenks96 reviewed May 13, 2026

View reviewed changes

Conversation

olivierbonte commented Apr 30, 2026

Uh oh!

olivierbonte commented Apr 30, 2026

Uh oh!

bgroenks96 commented Apr 30, 2026

Uh oh!

olivierbonte commented May 1, 2026

Uh oh!

bgroenks96 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

bgroenks96 commented May 11, 2026

Uh oh!

olivierbonte commented May 11, 2026

Uh oh!

bgroenks96 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

olivierbonte commented May 13, 2026

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!

bgroenks96 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bgroenks96 May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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

bgroenks96 May 13, 2026 •

edited

Loading