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