Packaged utils

.github/workflows/documentation.yml

@@ -28,7 +28,10 @@ jobs:
       - name: Set up Julia
         uses: julia-actions/setup-julia@v2
         with:
-          version: '1'
+          version: '1.10'
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
 
       - name: Cache Julia artifacts
         uses: julia-actions/cache@v2
@@ -37,8 +40,12 @@ jobs:
         shell: julia --color=yes --project=2026-05/docs {0}
         run: |
           using Pkg
+          Pkg.develop(Pkg.PackageSpec(path="2026-05"))
           Pkg.instantiate()
 
+      - name: Render Quarto slides
+        run: quarto render 2026-05/slides
+
       - name: Build and deploy documentation
         run: julia --color=yes --project=2026-05/docs 2026-05/docs/make.jl
         env:

.gitignore

@@ -2,13 +2,20 @@
 2026-05/docs/build/
 2026-05/docs/Manifest.toml
 2026-05/docs/src/generated
+2026-05/docs/src/slides
+
+# Quarto slides
+2026-05/slides/01_intro_files/
+2026-05/slides/_site/
+2026-05/slides/.quarto
+
+*.html
 
 # Model output
 *.jld
 *.jld2
 
 # Plots
 *.png
-*.svg
 *.gif
 *.mp4

2026-05/Project.toml

@@ -0,0 +1,18 @@
+name = "AgateWorkshop"
+uuid = "63d0df89-dfc1-4d5a-a86d-28cde1db1234"
+version = "0.1.0"
+
+[deps]
+Agate = "41889b7c-c35c-4f16-abd7-94b299d9fd29"
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
+JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
+OceanBioME = "a49af516-9db8-4be4-be45-1dad61c5a376"
+Oceananigans = "9e8cae18-63c1-5223-a75c-80ca9d6e9a09"
+
+[compat]
+Agate = "0.5.3"
+CairoMakie = "0.12, 0.13, 0.14, 0.15"
+JLD2 = "0.5"
+OceanBioME = "0.16"
+Oceananigans = "0.101.1, 0.102"
+julia = "1.10"

2026-05/advances_excercises/06_diffusivity_sensitivity.jl

@@ -0,0 +1,158 @@
+# # [Exercise 06 supplement: Diffusivity sensitivity] (@id diffusivity_sensitivity_exercise)
+
+# !!! info
+#     This example uses [Oceananigans.jl](https://clima.github.io/OceananigansDocumentation/stable/) and [OceanBioME.jl](https://oceanbiome.github.io/OceanBioME.jl/stable/).
+#     We recommend familiarizing yourself with their user interface if you intend to make changes to the physical model setup.
+
+# In this example we run a default Agate.jl-NiPiZD model inside a 2 layer column model.
+# The simulation is repeated across a range of vertical diffusivities, then the top-layer
+# total plankton biomass is summarized as a function of κ_max.
+
+# ## Loading dependencies
+
+using Agate
+using Agate.Library.Light
+using OceanBioME
+using OceanBioME: Biogeochemistry
+using Oceananigans
+using Oceananigans.Units
+using CairoMakie
+using Statistics
+
+stop_time = 3*365day
+Δt = 1hour
+output_interval = 1day
+LAYER_INTERFACE = -100meters
+PAR_SURFACE_MAX = 80
+
+κ_values = [
+    3e-5,
+    1e-4,
+    3e-4,
+    1e-3,
+]
+
+# ## Forcings
+
+struct LayeredDiffusivity{T}
+    κ_max::T
+    layer_interface::T
+end
+
+@inline function (diffusivity::LayeredDiffusivity)(x, y, z, t)
+    return ifelse(z >= diffusivity.layer_interface, diffusivity.κ_max, zero(diffusivity.κ_max))
+end
+
+function surface_irradiance(x, y, z, t)
+    return ifelse(z >= LAYER_INTERFACE, PAR_SURFACE_MAX, 0.0)
+end
+
+# ## Physical and ecosystem model
+
+function build_model(κ_max)
+    grid = RectilinearGrid(; size=(1, 1, 2), extent=(20meters, 20meters, 200meters))
+    diffusivity = LayeredDiffusivity(κ_max, LAYER_INTERFACE)
+
+    bgc = Agate.Models.NiPiZD.construct()
+    bgc_model = Biogeochemistry(
+        bgc; light_attenuation=FunctionFieldPAR(; grid, PAR_f=surface_irradiance)
+    )
+
+    model = NonhydrostaticModel(;
+        grid,
+        clock=Clock(; time=0.0),
+        timestepper=:QuasiAdamsBashforth2,
+        closure=ScalarDiffusivity(
+            VerticallyImplicitTimeDiscretization(); ν=diffusivity, κ=diffusivity
+        ),
+        biogeochemistry=bgc_model,
+    )
+
+    set!(model; N=7.0, P1=0.01, P2=0.01, Z1=0.05, Z2=0.05, D=0.0)
+
+    return model
+end
+
+function output_filename(κ_max)
+    κ_label = replace(string(κ_max), "." => "p", "-" => "m")
+    return "N2P2ZD_column_k$(κ_label).jld2"
+end
+
+function run_column(κ_max)
+    model = build_model(κ_max)
+    filename = output_filename(κ_max)
+
+    simulation = Simulation(model; Δt, stop_time)
+
+    simulation.output_writers[:profiles] = JLD2Writer(
+        model,
+        model.tracers;
+        filename,
+        schedule=TimeInterval(output_interval),
+        overwrite_existing=true,
+    )
+
+    run!(simulation)
+
+    return filename, model
+end
+
+function top_layer_index(timeseries_field)
+    _, _, z_nodes = nodes(timeseries_field)
+    z_vals = collect(z_nodes)
+    return argmax(z_vals)
+end
+
+function top_layer_plankton_biomass(filename)
+    P1 = FieldTimeSeries(filename, "P1")
+    P2 = FieldTimeSeries(filename, "P2")
+    Z1 = FieldTimeSeries(filename, "Z1")
+    Z2 = FieldTimeSeries(filename, "Z2")
+
+    k_top = top_layer_index(P1)
+    times = collect(P1.times ./ days)
+
+    biomass = vec(
+        interior(P1, 1, 1, k_top, :) .+
+        interior(P2, 1, 1, k_top, :) .+
+        interior(Z1, 1, 1, k_top, :) .+
+        interior(Z2, 1, 1, k_top, :)
+    )
+
+    final_biomass = biomass[end]
+    final_year = times .>= maximum(times) - 365
+    mean_final_year_biomass = mean(biomass[final_year])
+
+    return final_biomass, mean_final_year_biomass
+end
+
+# ## Sensitivity runs
+
+final_top_layer_biomass = Float64[]
+mean_final_year_top_layer_biomass = Float64[]
+
+for κ_max in κ_values
+    @info "Running diffusivity sensitivity" κ_max
+    filename, _ = run_column(κ_max)
+    final_biomass, mean_final_year_biomass = top_layer_plankton_biomass(filename)
+    push!(final_top_layer_biomass, final_biomass)
+    push!(mean_final_year_top_layer_biomass, mean_final_year_biomass)
+end
+
+# ## Plot top-layer total plankton biomass against κ_max
+
+fig = Figure(; size=(850, 550), fontsize=16)
+ax = Axis(
+    fig[1, 1];
+    xlabel="κ_max (m² s⁻¹)",
+    ylabel="Top-layer total plankton biomass (mmol N m⁻³)",
+    title="Diffusivity sensitivity",
+    xscale=log10,
+)
+
+scatterlines!(ax, κ_values, mean_final_year_top_layer_biomass; label="Final-year mean")
+axislegend(ax; position=:rb)
+
+save("top_layer_plankton_biomass_vs_kmax.png", fig)
+
+fig

2026-05/docs/Project.toml

@@ -1,4 +1,5 @@
 [deps]
+AgateWorkshop = "63d0df89-dfc1-4d5a-a86d-28cde1db1234"
 Agate = "41889b7c-c35c-4f16-abd7-94b299d9fd29"
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
@@ -10,7 +11,8 @@ OceanBioME = "a49af516-9db8-4be4-be45-1dad61c5a376"
 Oceananigans = "9e8cae18-63c1-5223-a75c-80ca9d6e9a09"
 
 [compat]
-Agate = "0.5.2"
+AgateWorkshop = "0.1"
+Agate = "0.5.3"
 CairoMakie = "0.12, 0.13, 0.14, 0.15"
 CSV = "0.10"
 DataFrames = "1"

2026-05/docs/make.jl

@@ -1,21 +1,43 @@
 using Pkg
 
 Pkg.activate(@__DIR__)
+
+workshop_root = normpath(joinpath(@__DIR__, ".."))
+Pkg.develop(Pkg.PackageSpec(path=workshop_root))
 Pkg.instantiate()
 
 using Literate
 using Documenter
 
-workshop_root = normpath(joinpath(@__DIR__, ".."))
-
 examples_dir = joinpath(workshop_root, "examples")
 docs_src_dir = joinpath(@__DIR__, "src")
-docs_exercises_dir = joinpath(docs_src_dir, "exercises")
+docs_exercises_dir = joinpath(docs_src_dir, "generated")
 mkpath(docs_exercises_dir)
+
+
 example_files = [
     "00_setup_check.jl",
+    "01_quick_start.jl",
+    "02_diagnostics.jl",
+    "03_allometric_scaling.jl",
+    "04_number_size_classes.jl",
+    "05_size_range.jl",
+    "06_palatability.jl",
+    "07_assimilation_efficiency.jl",
+    "08_closure_terms.jl",
+    "09_irradiance_box.jl",
+    "10_irradiance_column.jl",
+    "11_diffusivity_stratified.jl",
+    "12_diffusivity_seasonal.jl",
 ]
 
+function strip_jld2_warnings(content)
+    return replace(
+        content,
+        r"(?ms)^┌ Warning:.*?^└ @ JLD2 .*?/(writing_datatypes|reconstructing_datatypes)\.jl:\d+\n" => "",
+    )
+end
+
 # Run from the workshop root so relative paths in examples are predictable.
 cd(workshop_root) do
     mkpath("figures")
@@ -25,37 +47,72 @@ cd(workshop_root) do
         source = joinpath(examples_dir, file)
 
         # Generate and execute the rendered documentation page.
-        #
-        # Executing here lets CI pre-run the examples and include generated figures
+        # Executing here lets CI pre-run examples and include generated figures
         # in the deployed documentation.
         Literate.markdown(
             source,
             docs_exercises_dir;
-            documenter = true,
-            execute = true,
-            credit = false,
+            documenter=true,
+            execute=true,
+            credit=false,
+            postprocess=strip_jld2_warnings,
         )
     end
 end
 
+# Quarto renders slide decks into slides/_site before this script runs in CI.
+# Copy that site into docs/src before makedocs so Documenter can validate
+# local links to the rendered slide HTML.
+slides_site_src = joinpath(workshop_root, "slides", "_site")
+slides_docs_src = joinpath(docs_src_dir, "slides")
+
+if isdir(slides_site_src)
+    isdir(slides_docs_src) && rm(slides_docs_src; recursive=true, force=true)
+    cp(slides_site_src, slides_docs_src)
+else
+    @warn "Quarto slide output not found before makedocs; slide links may be unavailable" slides_site_src
+end
+
 makedocs(
-    sitename = "Agate.jl workshop 2026-05",
-    format = Documenter.HTML(
-        prettyurls = get(ENV, "CI", "false") == "true",
-        assets = String[],
+    sitename="Agate.jl workshop 2026-05",
+    format=Documenter.HTML(
+        prettyurls=get(ENV, "CI", "false") == "true",
+        assets=String[],
+        size_threshold_warn=1_000_000,
+        size_threshold=2_000_000,
     ),
-    modules = Module[],
-    pages = [
+    modules=Module[],
+    pages=[
         "Home" => "index.md",
         "Setup" => "setup.md",
+        "Workshop slides" => "lectures.md",
         "Examples" => [
-            "00 Setup Check" => "exercises/00_setup_check.md",
+            "00 Setup Check" => "generated/00_setup_check.md",
+            "01 Quick Start" => "generated/01_quick_start.md",
+            "02 Diagnostics" => "generated/02_diagnostics.md",
+            "03 Allometric Scaling" => "generated/03_allometric_scaling.md",
+            "04 Number of Size Classes" => "generated/04_number_size_classes.md",
+            "05 Size Range" => "generated/05_size_range.md",
+            "06 Palatability" => "generated/06_palatability.md",
+            "07 Assimilation Efficiency" => "generated/07_assimilation_efficiency.md",
+            "08 Closure Terms" => "generated/08_closure_terms.md",
+            "09 Irradiance Box" => "generated/09_irradiance_box.md",
+            "10 Irradiance Column" => "generated/10_irradiance_column.md",
+            "11 Diffusivity Stratified" => "generated/11_diffusivity_stratified.md",
+            "12 Diffusivity Seasonal" => "generated/12_diffusivity_seasonal.md",
         ],
     ],
 )
+# Ensure rendered slides are present in the final build output even if a
+# future Documenter version changes how non-markdown files are copied.
+slides_build_dst = joinpath(@__DIR__, "build", "slides")
+if isdir(slides_site_src)
+    isdir(slides_build_dst) && rm(slides_build_dst; recursive=true, force=true)
+    cp(slides_site_src, slides_build_dst)
+end
 
 deploydocs(
-    repo = "github.com/agate-model/workshops.git",
-    devbranch = "main",
-    push_preview = true,
+    repo="github.com/agate-model/workshops.git",
+    devbranch="main",
+    push_preview=true,
 )

2026-05/docs/src/advanced.md

@@ -0,0 +1,8 @@
+| Example | Theory |
+|---|---|
+| sinking + remin | POC attenuation |
+| exponential mortality | viral shunt |
+| kN vs umax | r/K trade-off |
+| specificity vs gmax | generalist-specialist trade-off |
+| alpha vs umax | LL vs HL prochlorococcus |
+| interaction roles | cannibalism |