Run Examples on GPU for Documentation

.buildkite/examples_build.yml

@@ -0,0 +1,57 @@
+agents:
+  queue: new-central
+  slurm_mem: 8G
+  modules: climacommon/2024_05_27
+  slurm_time: 48:00:00
+
+timeout_in_minutes: 1440
+
+env:
+  JULIA_LOAD_PATH: "${JULIA_LOAD_PATH}:${BUILDKITE_BUILD_CHECKOUT_PATH}/.buildkite"
+  OPENBLAS_NUM_THREADS: 1
+  OMPI_MCA_opal_warn_on_missing_libcuda: 0
+
+steps:
+  - label: "initialize"
+    key: "init"
+    command:
+      - "echo '--- Instantiate project'"
+      - "julia --project -e 'using Pkg; Pkg.instantiate(; verbose=true); Pkg.precompile(; strict=true)'"
+      # force the initialization of the CUDA runtime as it is lazily loaded by default
+      - "julia --project -e 'using CUDA; CUDA.precompile_runtime()'"
+
+    agents:
+      slurm_mem: 120G
+      slurm_gpus: 1
+      slurm_cpus_per_task: 8
+    env:
+      JULIA_NUM_PRECOMPILE_TASKS: 8
+
+  - wait
+
+  - label: "Run documentation"
+    key: "build_documentation"
+    commands:
+      - "julia --color=yes --project=docs/ -e 'using Pkg; Pkg.instantiate(); Pkg.develop(PackageSpec(path=pwd()))'"
+      - "julia --color=yes --project=docs/ docs/make.jl"
+
+    agents:
+      slurm_mem: 120G
+      slurm_gpus: 1
+      slurm_cpus_per_task: 8
+      slurm_ntasks: 1
+      slurm_gpus_per_task: 1
+      slurm_time: 48:00:00
+
+    env:
+      JULIA_NUM_PRECOMPILE_TASKS: 8
+      JULIA_DEBUG: "Documenter"
+      # This environment variable is needed to avoid SSL verification errors when Downloads.jl 
+      # tries to download the bathymetry data. It should not be required so we need to fix our certificates.
+      # and remove this environment variable. ref: https://github.com/JuliaLang/Downloads.jl/issues/97
+      JULIA_SSL_NO_VERIFY: "**" 
+
+    timeout_in_minutes: 1440
+
+  - wait: ~
+    continue_on_failure: true

.buildkite/pipeline.yml

@@ -20,6 +20,7 @@ steps:
 
     agents:
       slurm_mem: 32G
+      slurm_gpus: 1
       slurm_cpus_per_task: 8
       slurm_gpus: 1
       slurm_ntasks: 1

Manifest.toml

@@ -885,7 +885,9 @@ version = "1.2.0"
 
 [[deps.Oceananigans]]
 deps = ["Adapt", "CUDA", "Crayons", "CubedSphere", "Dates", "Distances", "DocStringExtensions", "FFTW", "Glob", "IncompleteLU", "InteractiveUtils", "IterativeSolvers", "JLD2", "KernelAbstractions", "LinearAlgebra", "Logging", "MPI", "NCDatasets", "OffsetArrays", "OrderedCollections", "PencilArrays", "PencilFFTs", "Pkg", "Printf", "Random", "Rotations", "SeawaterPolynomials", "SparseArrays", "Statistics", "StructArrays"]
-git-tree-sha1 = "942c78ad3c95e47bcbab3eeacb0b8a846bcfb33b"
+git-tree-sha1 = "937a5ba25152cbcd0b74e66d21ce931a620a6cc4"
+repo-rev = "main"
+repo-url = "https://github.com/CliMA/Oceananigans.jl.git"
 uuid = "9e8cae18-63c1-5223-a75c-80ca9d6e9a09"
 version = "0.91.4"
 

docs/Project.toml

@@ -3,10 +3,9 @@ CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 DataDeps = "124859b0-ceae-595e-8997-d05f6a7a8dfe"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
-Oceananigans = "9e8cae18-63c1-5223-a75c-80ca9d6e9a09"
+OrthogonalSphericalShellGrids = "c2be9673-fb75-4747-82dc-aa2bb9f4aed0"
 
 [compat]
 CairoMakie = "0.10.12"
 DataDeps = "0.7"
 Documenter = "1"
-Oceananigans = "0.91.4"

docs/make.jl

@@ -15,26 +15,30 @@ const EXAMPLES_DIR = joinpath(@__DIR__, "..", "examples")
 const OUTPUT_DIR   = joinpath(@__DIR__, "src/literated")
 
 to_be_literated = [
-    "inspect_ecco_data.jl",
+    # "inspect_ecco_data.jl",
+    "generate_bathymetry.jl",
     "generate_surface_fluxes.jl",
-    "single_column_simulation.jl",
-    # "near_global_omip_simulation.jl"
+    # "single_column_simulation.jl",
+    # "mediterranean_simulation_with_ecco_restoring.jl",
+    "near_global_ocean_simulation.jl"
 ]
 
 for file in to_be_literated
     filepath = joinpath(EXAMPLES_DIR, file)
-    Literate.markdown(filepath, OUTPUT_DIR; flavor = Literate.DocumenterFlavor())
+    withenv("JULIA_DEBUG" => "Literate") do
+        Literate.markdown(filepath, OUTPUT_DIR; flavor = Literate.DocumenterFlavor(), execute = true)
+    end
 end
 
 #####
 ##### Build and deploy docs
 #####
 
 format = Documenter.HTML(
-       collapselevel = 2,
-      size_threshold = nothing,
-          prettyurls = get(ENV, "CI", nothing) == "true",
-           canonical = "https://clima.github.io/ClimaOceanDocumentation/dev/",
+   collapselevel = 2,
+  size_threshold = nothing,
+      prettyurls = get(ENV, "CI", nothing) == "true",
+       canonical = "https://clima.github.io/ClimaOceanDocumentation/dev/",
 )
 
 pages = [
@@ -48,9 +52,12 @@ pages = [
         ],
 
     "Examples" => [
-        "Inspect ECCO2 data" => "literated/inspect_ecco_data.md",
+        # "Inspect ECCO2 data" => "literated/inspect_ecco_data.md",
+        "Generate bathymetry" => "literated/generate_bathymetry.md",
         "Surface fluxes" => "literated/generate_surface_fluxes.md",
-        "Single column simulation" => "literated/single_column_simulation.md",
+        # "Single column simulation" => "literated/single_column_simulation.md",
+        # "Mediterranean simulation with ECCO restoring" => "literated/mediterranean_simulation_with_ecco_restoring.md",
+        "Near-global Ocean simulation" => "literated/near_global_ocean_simulation.md",
         ]
 ]
 
@@ -86,10 +93,8 @@ for file in files
     rm(file)
 end
 
-withenv("GITHUB_REPOSITORY" => "CliMA/ClimaOceanDocumentation") do
-    deploydocs(        repo = "github.com/CliMA/ClimaOceanDocumentation.git",
-                   versions = ["stable" => "v^", "v#.#.#", "dev" => "dev"],
-                  forcepush = true,
-                  devbranch = "main",
-               push_preview = true)
-end
+deploydocs(repo = "github.com/CliMA/ClimaOceanDocumentation.git",
+       versions = ["stable" => "v^", "v#.#.#", "dev" => "dev"],
+      forcepush = true,
+      devbranch = "main",
+   push_preview = true)