From 221d790e3e3b4d57d122fb70a1e6ed19f2c79249 Mon Sep 17 00:00:00 2001
From: nefrathenrici <nat.henrici@gmail.com>
Date: Mon, 26 Feb 2024 12:15:53 -0800
Subject: [PATCH] Add documentation for precompiletools

---
 Project.toml               |  2 ++
 docs/make.jl               |  1 +
 docs/src/precompilation.md | 37 +++++++++++++++++++++++++++++++++++++
 3 files changed, 40 insertions(+)
 create mode 100644 docs/src/precompilation.md

diff --git a/Project.toml b/Project.toml
index 20f460ff..d065aa50 100644
--- a/Project.toml
+++ b/Project.toml
@@ -12,7 +12,9 @@ Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 EnsembleKalmanProcesses = "aa8a2aa5-91d8-4396-bcef-d4f2ec43552d"
 JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
 TOML = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
 YAML = "ddb6d928-2868-570f-bddf-ab3f9cf99eb6"
 
diff --git a/docs/make.jl b/docs/make.jl
index b554e982..65190b62 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -26,6 +26,7 @@ makedocs(
         "Getting Started" => "quickstart.md",
         "Experiment Setup Guide" => "experiment_setup_guide.md",
         "Emulate and Sample" => "emulate_sample.md",
+        "Precompilation" => "precompilation.md",
         "API" => "api.md",
     ],
 )
diff --git a/docs/src/precompilation.md b/docs/src/precompilation.md
new file mode 100644
index 00000000..886a7354
--- /dev/null
+++ b/docs/src/precompilation.md
@@ -0,0 +1,37 @@
+# Using PrecompileTools faster model runs
+
+PrecompileTools.jl enables developers to force the Julia compiler to save more code to disk, preventing re-compilation in the future.
+
+For CalibrateAtmos, this is useful under certain conditions:
+1. The atmosphere model configuration is set and will not change often. 
+2. The model runtime is short compared to the compile time.
+
+For point 1 above, this is because the model configuration specifies things like the floating-point type and callbacks, which affect the MethodInstances that get precompiled. Generically precompiling ClimaAtmos would take much too long to be useful.
+
+For point 2, if the model runtime is an order of magnitude or more than the compilation time, any benefit from reduced compilation time will be trivial.
+
+# How do I precompile my configuration?
+The easiest way is by copying and pasting the code snippet below into `src/CalibrateAtmos.jl` and replacing the `job_id` with your experiment ID.
+This will precompile the model step and all callbacks for the given configuration.
+```julia
+using PrecompileTools
+import SciMLBase
+import ClimaAtmos as CA
+import YAML
+
+@setup_workload begin
+    output = joinpath("precompilation")
+    job_id = "your configuration"
+    config_file = joinpath("experiments", job_id, "atmos_config.yml")
+    config_dict = YAML.load_file(config_file)
+    config_dict["output_dir"] = output
+    @compile_workload begin
+        initialize(job_id)
+        config = CA.AtmosConfig(config_dict)
+        simulation = CA.get_simulation(config)
+        (; integrator) = simulation
+        SciMLBase.step!(integrator)
+        CA.call_all_callbacks!(integrator)
+    end
+end
+```