Change deepheating code style to match rest of AGNI style: renamed variables, removed redundant code, and consolidated config-parser. Added Andy to collaborators page. Version bump (1.8.7). Deep_heating functionality otherwise unchanged

Author: nichollsh

.zenodo.json

@@ -22,7 +22,7 @@
         }
     ],
     "title": "AGNI: An open-source model for extreme atmospheres on rocky exoplanets",
-    "version": "1.8.6",
+    "version": "1.8.7",
     "access_right": "open",
     "related_identifiers": [
         {

CITATION.cff

@@ -10,7 +10,7 @@ title: "AGNI: An open-source model for extreme atmospheres on rocky exoplanets"
 doi: 10.21105/joss.07726
 date-released: 2025-11-20
 
-version: 1.8.6
+version: 1.8.7
 url: "https://github.com/nichollsh/AGNI"
 type: software
 license: "GPL-3.0"

Project.toml

@@ -1,7 +1,7 @@
 name = "AGNI"
 uuid = "ede838c1-9ec3-4ebe-8ae8-da4091b3f21c"
 authors = ["Harrison Nicholls <harrison.nicholls@physics.ox.ac.uk>"]
-version = "1.8.6"
+version = "1.8.7"
 
 [deps]
 ArgParse = "c7e460c6-2fb9-53a9-8c5b-16f535851c63"

codemeta.json

@@ -19,5 +19,5 @@
   "keywords": "exoplanets, radiation, astronomy, atmosphere, optimization, julia, fortran, convection, chemistry, magma, planetary, physics",
   "license": "GPL-3.0",
   "title": "AGNI",
-  "version": "1.8.6"
+  "version": "1.8.7"
 }

docs/src/thanks.md

@@ -4,14 +4,15 @@ I would like to thank the following people for their input and assistance during
 
 * [Tim Lichtenberg](https://www.formingworlds.space/team/tim-lichtenberg)
 * [Raymond Pierrehumbert](https://users.physics.ox.ac.uk/~pierrehumbert/)
-* [Namrah Habib](https://www.physics.ox.ac.uk/our-people/habibn)
-* [Claire Marie Guimond](https://clairesworld.github.io/)
 * [Arjun Savel](https://www.arjunsavel.com/) -- JOSS paper reviewer
 * [Ryan Macdonald](https://distantworlds.space/) -- JOSS paper reviewer
+* [Cheng An Hsieh](https://didymos65803.github.io/)
+* [Namrah Habib](https://www.physics.ox.ac.uk/our-people/habibn)
 * [Leoni Janssen](https://www.universiteitleiden.nl/en/staffmembers/leoni-janssen)
 * [Karen Stuitje](https://github.com/stuitje)
 * [Boding Ouyang](https://github.com/OYBDOOO)
 * [Soumil Kelkar](https://research.rug.nl/en/persons/soumil-kelkar/)
+* [Claire Marie Guimond](https://clairesworld.github.io/)
 * [Stuart Daines](https://scholar.google.com/citations?user=EZqVB7wAAAAJ)
 
 Please contact [Harrison Nicholls](https://www.h-nicholls.space/) for any queries relating to AGNI.

res/config/default.toml

@@ -22,16 +22,6 @@ title = "Default"                       # Name for this configuration file
     wind_speed      = 2.0               # Effective wind speed for sensible heat [m s-1].
     stellar_Teff    = 4000.0            # Stellar effective temperature, if using `input_star="blackbody"`
 
-[deep_heating]
-    active          = false             # Enable deep atmospheric heating.
-    P_dep           = 1.0e5             # Deposition pressure [Pa] - center of Gaussian heating profile.
-    sigma_P         = 1.0               # Width of Gaussian in log-pressure space [dimensionless].
-    efficiency      = 0.0               # Heating efficiency as fraction of instellation.
-    normalization   = "pressure"        # "pressure" (legacy dF/dP) | "mass" (dm-weighted).
-    below_domain    = "clamp"           # "clamp" | "boundary_flux" (if P_dep outside domain).
-    power_mode      = "efficiency"      # "efficiency" | "flux".
-    F_total         = 0.0               # [W m-2] used when power_mode="flux".
-
 [files]
     input_sf        = "res/spectral_files/Dayspring/48/Dayspring.sf"    # Path to SOCRATES spectral file. Set to "greygas" for grey RT.
     input_star      = "res/stellar_spectra/sun.txt"                     # Path to stellar spectrum. Set to "blackbody" to use `planet.stellar_Teff`.
@@ -80,6 +70,15 @@ title = "Default"                       # Name for this configuration file
     convection_crit = "s"                       # Stability criterion for convection. Options: (s)chwarzschild or (l)edoux.
     convection      = true                      # Include heat transport by convection
 
+    [physics.deep_heating]
+        Pmid            = 1e-3              # Center of Gaussian heating profile [bar]
+        Pwid            = 1.0               # Width of Gaussian in log-Pascal units.
+        power_mode      = "off"             # Power mode for heating (off, rel, abs)
+        norm_method     = "pressure"        # Normalisation coordinate: "pressure" (legacy dF/dP), or "mass" (dm-weighted).
+        domain          = "clamp"           # How to handle Pmid outside domain (clamp, boundary_flux)
+        flux_rel        = 0.0               # Set flux by fraction of instellation, used for power_mode="rel".
+        flux_abs        = 10.0              # Set flux by [W m-2], used for power_mode="abs".
+
 [plots]
     at_runtime      = true                      # Make some plots at runtime?
     temperature     = true                      # Plot temperature profile?

src/AGNI.jl

@@ -486,42 +486,6 @@ module AGNI
             io_dir = cfg["files"]["io_dir"]
         end
 
-        # Deep heating configuration
-        deep_active::Bool         = false
-        deep_P_dep::Float64       = 1.0e5
-        deep_sigma_P::Float64     = 1.0
-        deep_efficiency::Float64  = 0.0
-        deep_norm::Symbol         = :pressure
-        deep_below::Symbol        = :clamp
-        deep_power_mode::Symbol   = :efficiency
-        deep_F_total::Float64     = 0.0
-        if haskey(cfg, "deep_heating")
-            dh = cfg["deep_heating"]
-            if haskey(dh, "active")
-                deep_active = Bool(dh["active"])
-            end
-            if haskey(dh, "P_dep")
-                deep_P_dep = Float64(dh["P_dep"])
-            end
-            if haskey(dh, "sigma_P")
-                deep_sigma_P = Float64(dh["sigma_P"])
-            end
-            if haskey(dh, "efficiency")
-                deep_efficiency = Float64(dh["efficiency"])
-            end
-            if haskey(dh, "normalization")
-                deep_norm = Symbol(lowercase(String(dh["normalization"])))
-            end
-            if haskey(dh, "below_domain")
-                deep_below = Symbol(lowercase(String(dh["below_domain"])))
-            end
-            if haskey(dh, "power_mode")
-                deep_power_mode = Symbol(lowercase(String(dh["power_mode"])))
-            end
-            if haskey(dh, "F_total")
-                deep_F_total = Float64(dh["F_total"])
-            end
-        end
 
         # Create atmosphere structure
         @debug "Instantiate atmosphere"
@@ -567,17 +531,24 @@ module AGNI
         atmosphere.allocate!(atmos,star_file; stellar_Teff=star_Teff) || return false
 
         # Configure deep atmospheric heating
-        if deep_active
+        if haskey(cfg["physics"],"deep_heating")
+            dh = cfg["physics"]["deep_heating"]
+            if ! all(k in keys(dh) for k in ["Pmid","Pwid","flux_rel","flux_abs","norm_method","domain","power_mode"])
+                @error "Config: deep heating enabled but parameters are not set"
+                @error "        you must provide `Pmid`, `Pwid`, `flux_rel`, `flux_abs`, `norm_method`, `domain`, and `power_mode`"
+                return false
+            end
+
+            # Pass values, converting Bar->Pa where needed
             atmosphere.set_deep_heating!(atmos,
-                                         active=deep_active,
-                                         P_dep=deep_P_dep,
-                                         sigma_P=deep_sigma_P,
-                                         efficiency=deep_efficiency,
-                                         normalization=deep_norm,
-                                         below_domain=deep_below,
-                                         power_mode=deep_power_mode,
-                                         F_total=deep_F_total)
+                                            Float64(dh["Pmid"])*1e5, Float64(dh["Pwid"]),
+                                            Float64(dh["flux_rel"]), Float64(dh["flux_abs"]),
+                                            Symbol(dh["norm_method"]),
+                                            Symbol(dh["domain"]),
+                                            Symbol(dh["power_mode"])) || return false
         end
+        incl_deep::Bool = atmos.deepheat_power_mode != :off
+
 
         # Set temperatures as appropriate
         if transparent
@@ -619,6 +590,7 @@ module AGNI
             energy.calc_fluxes!(atmos, radiative=true, latent_heat=incl_latent,
                                 convective=incl_convect, sens_heat=incl_sens,
                                 conductive=incl_conduct, advective=incl_advect,
+                                deep=incl_deep,
                                 calc_cf=Bool(cfg["plots"]["contribution"]))
 
         # Transparent atmosphere solver
@@ -711,7 +683,7 @@ module AGNI
             plotting.plot_fluxes(atmos, joinpath(atmos.OUT_DIR,"plot_fluxes.png"),
                                     incl_mlt=incl_convect, incl_eff=(sol_type==3),
                                     incl_cdct=incl_conduct, incl_latent=incl_latent,
-                                    incl_advect=incl_advect)
+                                    incl_advect=incl_advect, incl_deep=incl_deep)
         cfg["plots"]["emission"] && \
             plotting.plot_emission(atmos, joinpath(atmos.OUT_DIR,"plot_emission.png"))
         cfg["plots"]["albedo"] && \

src/atmosphere.jl

@@ -33,7 +33,7 @@ module atmosphere
     import ..spectrum
 
     # Code versions
-    const AGNI_VERSION::String     = "1.8.6"  # current agni version
+    const AGNI_VERSION::String     = "1.8.7"  # current agni version
     const SOCVER_minimum::Float64  = 2407.2    # minimum required socrates version
 
     # Hydrostatic+gravity+mass calculation (constants and limits)
@@ -62,51 +62,6 @@ module atmosphere
     # Enum of available radiative transfer schemes
     @enum RTSCHEME RT_SOCRATES=1 RT_GREYGAS=2
 
-    """
-    **Parameters for deep atmospheric heating.**
-
-    AGNI treats deep heating as an *additional upward energy flux* that is deposited
-    within the column following a Gaussian profile in log-pressure space.
-
-    Two power modes are supported:
-    - `:efficiency` — heating flux = `efficiency × instellation` (stellar efficiency)
-    - `:flux`       — heating flux = `F_total` (fixed radiative flux in W m⁻²)
-
-    Additional design choices:
-    - Pressure-normalised deposition (dF/dP profile; legacy behaviour)
-    - Mass-normalised deposition (dm-weighted; aligns with ∂L/∂m forms)
-    - Handling deposition below the model bottom as a *bottom boundary flux*
-
-    Notes:
-    - Pressures are in Pa throughout AGNI.
-    - `efficiency` is always clamped to [0,1].
-
-    Fields:
-    - `active::Bool`              Enable/disable deep heating.
-    - `P_dep::Float64`            Deposition pressure centre [Pa].
-    - `sigma_P::Float64`          Width of Gaussian in log-pressure space [dimensionless].
-    - `efficiency::Float64`       Heating efficiency (fraction of instellation), used when `power_mode=:efficiency`.
-    - `normalization::Symbol`     `:pressure` (legacy) or `:mass` (dm-weighted).
-    - `below_domain::Symbol`      `:clamp` or `:boundary_flux`.
-    - `power_mode::Symbol`        `:efficiency` | `:flux`.
-    - `F_total::Float64`          Total deposited flux [W m-2], used when `power_mode=:flux`.
-    """
-    struct DeepHeatingParams
-        active::Bool
-        P_dep::Float64
-        sigma_P::Float64
-        efficiency::Float64
-        normalization::Symbol
-        below_domain::Symbol
-        power_mode::Symbol
-        F_total::Float64
-    end
-
-    # Default constructor with heating disabled
-    DeepHeatingParams() = DeepHeatingParams(false, 1.0e5, 1.0, 0.0,
-                                            :pressure, :clamp,
-                                            :efficiency, 0.0)
-
     # Contains data pertaining to the atmosphere (fluxes, temperature, etc.)
     mutable struct Atmos_t
 
@@ -331,8 +286,14 @@ module atmosphere
         flux_advect::Array{Float64, 1}     # Energy flux advected into each cell [W m-2], treated as entering into its bottom edge
 
         # Deep atmospheric heating
-        deep_heating::DeepHeatingParams     # Parameters for deep heating
-        flux_deep::Array{Float64,1}         # Deep heating flux at cell edges [W m-2] # should add at lw flux level
+        deepheat_norm_method::Symbol    # Normalisation method for deep heating (:pressure or :mass)
+        deepheat_Pmid::Float64          # Deposition pressur centre [Pa]
+        deepheat_Pwid::Float64          # Width of Gaussian in log-pressure space [logPa]
+        deepheat_domain::Symbol         # Method for treating deep heating below the model domain (:clamp or :boundary_flux)
+        deepheat_power_mode::Symbol     # Method for setting total flux (:off, :rel, or :abs)
+        deepheat_flux_rel::Float64      # Total heating as fraction of instellation, used when `power_mode=:rel`.
+        deepheat_flux_abs::Float64      # Total heating flux [W m-2], used when `power_mode=:abs`.
+        flux_deep::Array{Float64,1}     # Deep heating flux at cell edges [W m-2] # should add at lw flux level
 
         # Total energy flux
         flux_dif::Array{Float64,1}      # Flux lost at each level [W m-2] (positive is heating up)
@@ -1174,7 +1135,13 @@ module atmosphere
         end
 
         # Deep atmospheric heating (default: disabled)
-        atmos.deep_heating = DeepHeatingParams()
+        atmos.deepheat_norm_method  = :pressure
+        atmos.deepheat_Pmid         = 1e5
+        atmos.deepheat_Pwid         = 1.0
+        atmos.deepheat_domain       = :clamp
+        atmos.deepheat_power_mode   = :off
+        atmos.deepheat_flux_rel     = 0.0
+        atmos.deepheat_flux_abs     = 0.0
 
         # Record that the parameters are set
         atmos.is_param = true
@@ -1193,64 +1160,77 @@ module atmosphere
     which deposits energy as a Gaussian distribution in log-pressure space.
 
     Arguments:
-    - `atmos::Atmos_t`          the atmosphere struct instance to be used.
-    - `active::Bool`            enable/disable deep heating.
-    - `P_dep::Float64`          deposition pressure [Pa].
-    - `sigma_P::Float64`        width of Gaussian in log-pressure space [dimensionless].
-    - `efficiency::Float64`     heating efficiency as fraction of instellation.
+    - `atmos::Atmos_t`         the atmosphere struct instance to be used.
+    - `Pmid::Float64`          deposition pressure [Pa].
+    - `Pwid::Float64`          width of Gaussian in log-pressure space [logPa].
+    - `flux_rel::Float64`      heating flux relative to instellation.
+    - `flux_abs::Float64`      heating flux absolute [W m-2].
+    - `norm_method::Symbol`    method for normalising the Gaussian (:pressure, :mass).
+    - `domain::Symbol`         how to handle deposition pressures outside the domain (:clamp, :below_domain).
+    - `power_mode::Symbol`     off, or relative/absolute flux (:off, :rel, :abs).
 
     Returns:
-        Nothing
+    - `Bool` indicating success or failure of the operation.
     """
-    function set_deep_heating!(atmos::atmosphere.Atmos_t;
-                                active::Bool=false,
-                                P_dep::Float64=1.0e5,
-                                sigma_P::Float64=1.0,
-                                efficiency::Float64=0.0,
-                                normalization::Symbol=:pressure,
-                                below_domain::Symbol=:clamp,
-                                power_mode::Symbol=:efficiency,
-                                F_total::Float64=0.0)
-
-        # Validate/normalise parameters
-        sigma_P = max(sigma_P, 0.01)  # Prevent division issues
-        efficiency = clamp(efficiency, 0.0, 1.0)
-
-        # Normalise symbols
-        if !(normalization in (:pressure, :mass))
-            error("Invalid deep heating normalization: $(normalization)")
-        end
-        if !(below_domain in (:clamp, :boundary_flux))
-            error("Invalid deep heating below_domain: $(below_domain)")
+    function set_deep_heating!(atmos::atmosphere.Atmos_t,
+                                Pmid::Float64,
+                                Pwid::Float64,
+                                flux_rel::Float64,
+                                flux_abs::Float64,
+                                norm_method::Symbol,
+                                domain::Symbol,
+                                power_mode::Symbol
+                                )::Bool
+
+        # Fail safe mode
+        atmos.deepheat_power_mode = :off
+        if power_mode == :off
+            atmos.deepheat_power_mode = :off
+            return true
+        elseif !(power_mode in (:rel, :abs))
+            @error "Invalid deep heating power mode: $(power_mode)"
+            return false
         end
-        if !(power_mode in (:efficiency, :flux))
-            error("Invalid deep heating power_mode: $(power_mode)")
+
+        # Normalisation coordinate
+        if !(norm_method in (:pressure, :mass))
+            @error "Invalid deep heating normalisation: $(norm_method)"
+            return false
+        else
+            atmos.deepheat_norm_method = norm_method
         end
 
+        # Set centre and width of Gaussian
+        atmos.deepheat_Pmid = max(Pmid, 0.0)   # Pascals
+        atmos.deepheat_Pwid = max(Pwid, 0.01)  # relative
+
         # Deposition pressure handling
-        if below_domain == :clamp
-            P_dep = clamp(P_dep, atmos.p_toa, atmos.p_boa)
+        if domain == :clamp
+            atmos.deepheat_Pmid = clamp(atmos.deepheat_Pmid, atmos.p_toa, atmos.p_boa)
+        elseif domain == :below_domain
+            # Allow Poutside domain
+            atmos.deepheat_Pmid = max(atmos.deepheat_Pmid, atmos.p_toa)
         else
-            # Allow P_dep outside domain (used as a signal for boundary-flux mode)
-            P_dep = max(P_dep, atmos.p_toa)
+            @error "Invalid deep heating domain treatment: $(domain)"
+            return false
         end
 
-        # Create and store the parameters
-        atmos.deep_heating = DeepHeatingParams(active, P_dep, sigma_P, efficiency,
-                               normalization, below_domain,
-                               power_mode, F_total)
-
-        if active
-            @info @sprintf("Deep heating enabled: norm=%s below=%s mode=%s",
-                           String(normalization), String(below_domain), String(power_mode))
-            if power_mode == :efficiency
-                @info @sprintf("    P_dep=%.2e Pa, σ_P=%.2f, ε=%.4f", P_dep, sigma_P, efficiency)
-            else
-                @info @sprintf("    P_dep=%.2e Pa, σ_P=%.2f, F_total=%.4e W/m²", P_dep, sigma_P, F_total)
-            end
+        # Set power mode
+        atmos.deepheat_power_mode = power_mode
+        atmos.deepheat_flux_rel = flux_rel
+        atmos.deepheat_flux_abs = flux_abs
+        @info "Deep heating configured with power_mode=$(atmos.deepheat_power_mode)"
+        if power_mode  == :rel
+            @info @sprintf("    Pmid=%.2e Pa, Pwid=%.2f, ε=%.4f",
+                            atmos.deepheat_Pmid, atmos.deepheat_Pwid, flux_rel)
+        elseif power_mode == :abs
+            @info @sprintf("    Pmid=%.2e Pa, Pwid=%.2f, F_total=%.4e W/m²",
+                            atmos.deepheat_Pmid, atmos.deepheat_Pwid, flux_abs)
         end
+        @info "    norm_method=$(atmos.deepheat_norm_method), domain=$(atmos.deepheat_domain)"
 
-        return nothing
+
+        return true
     end