GitHub

Physical constants

Warning

This page is a work in progress. If you have any questions or notice any errors, please raise an issue.

Overview

Physical constants are organised into three sub-structs grouped by category and collected into the top-level PhysicalConstants container. All constants are passed explicitly through the call graph — avoiding global state and keeping the code fully differentiable with Enzyme.jl. Every struct is parametrically typed so that constants are automatically promoted to the model's numeric precision NF.

Functions that require only a subset of constants take the most specific sub-struct as input. Functions that span multiple categories, or kernel-launching and kernel functions, take the full PhysicalConstants.

Terrarium.PhysicalConstants — Type
struct PhysicalConstants{NF}

Top-level container for all physical constants used in Terrarium. Groups three sub-structs by category:

Construction

julia> show(PhysicalConstants())
PhysicalConstants{Float64}(ThermodynamicConstants{Float64}(1004.5, 2070.0, 4186.0, 1846.0, 334000.0, 2.257e6, 2.834e6, 273.16, 273.16, 273.16, 611.657, 287.058, 461.5), MaterialConstants{Float64}(1000.0, 916.7, 12.0), UniversalConstants{Float64}(9.80665, 5.6704e-8, 0.4))

To override individual constants, pass a customised sub-struct:

julia> tc = ThermodynamicConstants(Float64; temperature_reference = 273.15);

julia> c = PhysicalConstants(Float64; thermodynamics = tc);

julia> c.thermodynamics.temperature_reference
273.15

Properties:

  • thermodynamics

  • material

  • universal

source

Thermodynamic constants

ThermodynamicConstants holds thermodynamic and atmospheric constants. It subtypes AbstractThermodynamicsParameters to integrate directly with Thermodynamics.jl.

Terrarium.ThermodynamicConstants — Type
struct ThermodynamicConstants{NF} <: Thermodynamics.Parameters.AbstractThermodynamicsParameters{NF}

Thermodynamic and atmospheric constants used in surface energy, turbulent flux, and vegetation process implementations. Subtypes AbstractThermodynamicsParameters so that it integrates directly with Thermodynamics.jl.

julia> show(ThermodynamicConstants(Float64))
ThermodynamicConstants{Float64}(1004.5, 2070.0, 4186.0, 1846.0, 334000.0, 2.257e6, 2.834e6, 273.16, 273.16, 273.16, 611.657, 287.058, 461.5)

Properties:

  • specific_heat_capacity_dry_air: Isobaric specific heat capacity of dry air at standard pressure and 0°C in J/(m^3*K)

  • specific_heat_capacity_ice: Isobaric specific heat capacity of ice at standard pressure and 0°C in J/(m^3*K)

  • specific_heat_capacity_liquid_water: Isobaric specific heat capacity of liquid water at standard pressure and 0°C in J/(m^3*K)

  • specific_heat_capacity_water_vapor: Isobaric specific heat capacity of water vapor at standard pressure and 0°C in J/(m^3*K)

  • latent_heat_fusion: Specific latent heat of fusion of water in J/kg at 0°C

  • latent_heat_vaporization: Specific latent heat of vaporization of water in J/kg at 0°C

  • latent_heat_sublimation: Specific latent heat of sublimation of water in J/kg at 0°C

  • temperature_reference: Reference temperature (0°C in Kelvin)

  • temperature_water_freeze: Freezing temperature of water in Kelvin

  • temperature_water_triple_point: Triple point temperature of water in Kelvin

  • pressure_water_triple_point: Triple point pressure of water in Pa

  • gas_constant_dry_air: Specific gas constant of dry air in J/(kg*K)

  • gas_constant_water_vapor: Specific gas constant of water vapor in J/(kg*K)

source
FieldSymbolDefaultUnitsDescription
specific_heat_capacity_dry_air$c_{p,d}$1004.5J/(kg·K)Isobaric specific heat capacity of dry air at 0°C
specific_heat_capacity_ice$c_{p,i}$2070.0J/(kg·K)Isobaric specific heat capacity of ice at 0°C
specific_heat_capacity_liquid_water$c_{p,l}$4186.0J/(kg·K)Isobaric specific heat capacity of liquid water at 0°C
specific_heat_capacity_water_vapor$c_{p,v}$1846.0J/(kg·K)Isobaric specific heat capacity of water vapor at 0°C
latent_heat_fusion$L_{sl}$3.34×10⁵J/kgSpecific latent heat of fusion at 0°C
latent_heat_vaporization$L_{lv}$2.257×10⁶J/kgSpecific latent heat of vaporization at 0°C
latent_heat_sublimation$L_{sg}$2.834×10⁶J/kgSpecific latent heat of sublimation at 0°C
temperature_reference$T_{\text{ref}}$273.16KReference temperature (0°C in Kelvin)
temperature_water_freeze$T_{\text{freeze}}$273.16KFreezing temperature of water
temperature_water_triple_point$T_{\text{triple}}$273.16KTriple point temperature of water
pressure_water_triple_point$p_{\text{triple}}$611.657PaTriple point pressure of water
gas_constant_dry_air$R_d$287.058J/(kg·K)Specific gas constant of dry air
gas_constant_water_vapor$R_v$461.5J/(kg·K)Specific gas constant of water vapor

Material constants

MaterialConstants holds material properties.

Terrarium.MaterialConstants — Type
struct MaterialConstants{NF}

Material constants for water, ice, and carbon used in soil energy, hydrology, and vegetation process implementations.

julia> show(MaterialConstants(Float64))
MaterialConstants{Float64}(1000.0, 916.7, 12.0)

Properties:

  • density_water: Density of water in kg/m^3

  • density_ice: Density of ice in kg/m^3

  • atomic_weight_carbon: Atomic mass of carbon [gC/mol]

source
FieldSymbolDefaultUnitsDescription
density_water$\rho_w$1000.0kg/m³Density of liquid water
density_ice$\rho_i$916.7kg/m³Density of ice
atomic_weight_carbon$M_C$12.0gC/molAtomic mass of carbon

Universal constants

UniversalConstants holds universal constants.

Terrarium.UniversalConstants — Type
struct UniversalConstants{NF}

Universal physical constants used in surface energy and turbulent flux process implementations.

julia> show(UniversalConstants(Float64))
UniversalConstants{Float64}(9.80665, 5.6704e-8, 0.4)

Properties:

  • gravitational_acceleration: Gravitational constant in m/s^2

  • stefan_boltzmann_constant: Stefan-Boltzmann constant in J/(sm^2K^4)

  • von_karman_constant: von Kármán constant

source
FieldSymbolDefaultUnitsDescription
gravitational_acceleration$g$9.80665m/s²Gravitational acceleration
stefan_boltzmann_constant$\sigma$5.6704×10⁻⁸W/(m²·K⁴)Stefan-Boltzmann constant
von_karman_constant$\kappa$0.4—von Kármán constant

Construction

All four structs default to Float64 and can be constructed without arguments:

PhysicalConstants()
PhysicalConstants{Float64}(ThermodynamicConstants{Float64}(1004.5, 2070.0, 4186.0, 1846.0, 334000.0, 2.257e6, 2.834e6, 273.16, 273.16, 273.16, 611.657, 287.058, 461.5), MaterialConstants{Float64}(1000.0, 916.7, 12.0), UniversalConstants{Float64}(9.80665, 5.6704e-8, 0.4))

To use a different numeric precision, pass the type as the first positional argument:

PhysicalConstants(Float32)
PhysicalConstants{Float32}(ThermodynamicConstants{Float32}(1004.5f0, 2070.0f0, 4186.0f0, 1846.0f0, 334000.0f0, 2.257f6, 2.834f6, 273.16f0, 273.16f0, 273.16f0, 611.657f0, 287.058f0, 461.5f0), MaterialConstants{Float32}(1000.0f0, 916.7f0, 12.0f0), UniversalConstants{Float32}(9.80665f0, 5.6704f-8, 0.4f0))

To override individual constants, construct the relevant sub-struct explicitly and pass it as a keyword argument:

tc = ThermodynamicConstants(Float64; temperature_reference = 273.15)
PhysicalConstants(Float64; thermodynamics = tc)
PhysicalConstants{Float64}(ThermodynamicConstants{Float64}(1004.5, 2070.0, 4186.0, 1846.0, 334000.0, 2.257e6, 2.834e6, 273.15, 273.16, 273.16, 611.657, 287.058, 461.5), MaterialConstants{Float64}(1000.0, 916.7, 12.0), UniversalConstants{Float64}(9.80665, 5.6704e-8, 0.4))

Sub-structs can also be constructed and used independently, for example:

ThermodynamicConstants(Float64)
ThermodynamicConstants{Float64}(1004.5, 2070.0, 4186.0, 1846.0, 334000.0, 2.257e6, 2.834e6, 273.16, 273.16, 273.16, 611.657, 287.058, 461.5)

Methods

Terrarium.celsius_to_kelvin — Function
celsius_to_kelvin(c::ThermodynamicConstants, T)

Convert the given temperature in °C to Kelvin based on the constant temperature_reference.

source
Terrarium.specific_heat_capacity_moist_air — Function
specific_heat_capacity_moist_air(c::ThermodynamicConstants, q)

Compute the isobaric specific heat capacity [J/(kg*K)] of moist air as a function of the total specific humidity q [kg/kg]. Wrapper around cp_m.

source
Terrarium.stefan_boltzmann — Function
stefan_boltzmann(c::UniversalConstants, T, ϵ)

Stefan-Boltzmann law $M = \epsilon \sigma T^4$ where T is the surface temperature in Kelvin and ϵ is the emissivity and σ is the Stefan-Boltzmann constant.

source