Add documentation for precompiletools

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"
 

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",
     ],
 )

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
+```