### Examples

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/code-quality/documentation_policy.md

Include at least one runnable example for any user-facing API, demonstrating setup and usage.

```APIDOC
## Examples

```julia
sponge = ViscousSponge(Float32; zd = 20_000, κ₂ = 1e6)
```
```

--------------------------------

### Wiring Setup in get_setup_type

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/setups.md

Example of how to wire a new setup constructor into the `get_setup_type` function based on a configuration string.

```julia
elseif ic_name == "MyCase"
    return Setups.MyCase()
```

--------------------------------

### Custom Setup with Temperature Gradient

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/setups.md

Example of a custom setup struct `MyCase` with a `center_initial_condition` method that defines temperature as a function of height.

```julia
"".
    MyCase

Description of the case and citation.
""".
struct MyCase end

function center_initial_condition(::MyCase, local_geometry, params)
    FT = eltype(params)
    (; z) = local_geometry.coordinates
    T = FT(300) - FT(0.01) * z
    p = FT(101500)
    return physical_state(; T, p)
end
```

--------------------------------

### Minimal Setup Implementation

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/setups.md

A minimal setup struct and its `center_initial_condition` method. It defines temperature and pressure at each grid point.

```julia
struct MySetup end

function Setups.center_initial_condition(::MySetup, local_geometry, params)
    z = local_geometry.coordinates.z
    FT = typeof(z)
    return physical_state(; T = FT(300), p = FT(101500))
end
```

--------------------------------

### REPL Debugging Workflow Example

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/repl_scripts.md

This script shows how to set up the ClimaAtmos environment in the REPL, activate a specific Pkg environment, and run a simulation. It includes examples of advancing a single timestep and updating configuration arguments to re-run the simulation.

```julia
ca_dir = joinpath(@__DIR__, "..", "..")
buildkite_env = joinpath(ca_dir, ".buildkite")
using Pkg
Pkg.activate(buildkite_env)

# julia> using Revise # This is useful For REPL debugging. See also: Infiltrator.jl and Main.@infiltrate

import ClimaAtmos as CA
import ClimaTimeSteppers: step!

# If you wish to run your simulation on a `CUDA` device, use

# import ClimaComms
# ClimaComms.@import_required_backends
# ENV["CLIMACOMMS_DEVICE"]="CUDA"

# (Note that the example below runs on a single CPU, which uses 
# ENV["CLIMACOMMS_DEVICE"]="CPU")

config_file = joinpath(ca_dir, "config/model_configs/baroclinic_wave.yml")
config = CA.AtmosConfig(config_file)

# Generate temporary directory for Documenter run-script, clear after 
# demo is completed. 

temp_output_dir = mktempdir(ca_dir, cleanup=true)
config.parsed_args["output_dir"]=temp_output_dir
simulation = CA.AtmosSimulation(config) 

# Example: Advance a single timestep and explore the solution
# stored in `simulation.integrator.u`
step!(simulation.integrator) 

# Example: Update command line argument, reset simulation, re-run to completion
# Note that you can also to update the configuration `.yml` and 
# load the simulation again from the `config_file` as above in the same REPL session. 
# Note that you'd need to use `Revise` at the start of your session to apply changes 
# to the source code within your REPL session.
# e.g. 
# julia> simulation = CA.AtmosSimulation(config_file)

@info "----------------------------------"
@info "Update config arguments and re-run"
@info "----------------------------------"

config.parsed_args["dt"]="400secs"
config.parsed_args["t_end"]="800secs" 
simulation = CA.AtmosSimulation(config)
CA.solve_atmos!(simulation) 

@info "----------------------------------"
@info "Reactivate docs environment"
@info "----------------------------------"

# The final step, which is not part of the standard workflow
# resets the environment to `docs`.
# (it is necessary for the documentation generation only)
ca_dir = joinpath(@__DIR__, "..", "..")
docs_env = joinpath(ca_dir, "docs")
Pkg.activate(docs_env) 

nothing # hide
```

--------------------------------

### Define and Use Custom Initial Condition Setup

Source: https://context7.com/clima/climaatmos.jl/llms.txt

Defines a custom setup 'MyLapseRate' with a linear temperature lapse rate and uses it to initialize an atmospheric simulation. The simulation runs for 12 hours with a 60-second time step.

```julia
struct MyLapseRate end

function Setups.center_initial_condition(::MyLapseRate, local_geometry, params)
    z  = local_geometry.coordinates.z
    FT = typeof(z)
    T  = FT(300) - FT(0.007) * z   # 7 K/km lapse rate
    p  = FT(101_325)
    return Setups.physical_state(; T, p)
end

custom_sim = CA.AtmosSimulation{Float64}(;
    grid  = CA.ColumnGrid(Float64; z_elem = 50, z_max = 20_000.0),
    setup = MyLapseRate(),
    dt    = 60,
    t_end = 3600 * 12,
)
CA.solve_atmos!(custom_sim)
```

--------------------------------

### Runnable Code Example

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/code-quality/documentation_policy.md

Include at least one runnable example for user-facing APIs using a plain fenced Julia code block. Ensure any non-trivial setup is spelled out so a reader can reproduce it.

```julia
sponge = ViscousSponge(Float32; zd = 20_000, κ₂ = 1e6)
```

--------------------------------

### Install and Run JuliaFormatter CLI

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/code-quality/code_style.md

Install JuliaFormatter as an application for direct command-line use. Ensure the Julia bin directory is added to your system's PATH.

```julia-repl
julia> import Pkg; Pkg.Apps.add("JuliaFormatter")
```

```bash
jlfmt -i .
```

--------------------------------

### Run Model with Custom Configuration

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/config_no_table.md

Use this command to start the model with a custom configuration file. Replace `<yaml>` with the path to your YAML configuration file.

```bash
julia --project=.buildkite .buildkite/ci_driver.jl --config_file <yaml>
```

--------------------------------

### Verify ClimaAtmos and CUDA Installation

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/installation.md

Import ClimaAtmos and CUDA to verify that they have been installed correctly and are accessible. Successful imports without errors indicate a ready-to-use environment.

```julia
import ClimaAtmos as CA
import CUDA
```

--------------------------------

### Setup SCM Simulation with Built-in Bomex Preset

Source: https://context7.com/clima/climaatmos.jl/llms.txt

Configures and solves a Single Column Model (SCM) simulation using the built-in Bomex setup. Specifies grid, model, and time parameters.

```julia
import ClimaAtmos as CA
import ClimaAtmos.Setups

sim = CA.AtmosSimulation{Float32}(;
    grid  = CA.ColumnGrid(Float32; z_elem = 60, z_max = 3000.0, z_stretch = false),
    setup = Setups.Bomex(),
    model = CA.Presets.equil_moist_0m(),
    dt    = 10,
    t_end = 3600 * 6,
)
CA.solve_atmos!(sim)
```

--------------------------------

### Install ClimaAtmos.jl

Source: https://context7.com/clima/climaatmos.jl/llms.txt

Install the package from Julia's general registry or clone the repository for development.

```julia
using Pkg
Pkg.add("ClimaAtmos")
```

```julia
# Or clone for bleeding-edge changes:
# git clone https://github.com/CliMA/ClimaAtmos.jl.git
# cd ClimaAtmos.jl
# julia --project -e 'using Pkg; Pkg.instantiate()'
```

--------------------------------

### Interactive Simulation Setup and Execution

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/single_column_prospect.md

Load and run a simulation in interactive Julia mode. This is useful for debugging and development, allowing examination of the simulation object.

```julia
using Revise # if you are developing ClimaAtmos
import ClimaAtmos as CA

# get the configuration arguments
simulation = CA.get_simulation(CA.AtmosConfig("config/model_configs/prognostic_edmfx_bomex_column.yml"))
sol_res = CA.solve_atmos!(simulation) # run the simulation
```

--------------------------------

### Install JuliaFormatter.jl

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/contributor_guide.md

Command to install JuliaFormatter.jl in your base Julia environment for code formatting.

```sh
julia -e 'using Pkg; Pkg.add("JuliaFormatter")'
```

--------------------------------

### Customizing Setup with BOMEX Case

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/first_simulation.md

Set up a simulation for the BOMEX shallow cumulus case. This involves specifying the initial condition, timestep, duration, and a job ID.

```julia
simulation = CA.AtmosSimulation{Float32}(
    grid = CA.ColumnGrid(Float32; z_elem = 60, z_max = 3000.0),
    initial_condition = CA.Setups.Bomex(),
    dt = 5,
    t_end = 3600 * 6,
    job_id = "my_bomex",
)
CA.solve_atmos!(simulation)
```

--------------------------------

### Clone and Instantiate CliMA Repository

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/workflow/onboarding.md

Clone the repository, navigate into its directory, and start a Julia REPL. Then, instantiate the project's dependencies and check their status.

```bash
git clone git@github.com:CliMA/<repo-name>.jl.git
cd <repo-name>.jl
julia --project
```

```julia
using Pkg
Pkg.instantiate()    # download every dep at the manifest-pinned version
Pkg.status()         # sanity-check the resolved versions
import <RepoName>    # confirm the package loads
```

--------------------------------

### NEWS.md Changelog Example with Badges

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/code-quality/changelogs_and_versions.md

Provides an example of a NEWS.md changelog entry using badges to classify changes like breaking updates, features, and bug fixes, along with PR links.

```markdown
main
----

v0.39.0
-------
- ![][badge-💥breaking] Removed deprecated `old_config_key`. Use `new_config_key` instead.
  PR [#1234](https://github.com/CliMA/MyPackage.jl/pull/1234).
- ![][badge-✨feature/enhancement] Added `my_new_config_key` to control feature X.
  PR [#1235](https://github.com/CliMA/MyPackage.jl/pull/1235).

v0.38.4
-------
- ![][badge-🐛bugfix] Fixed incorrect surface flux calculation.
  PR [#1230](https://github.com/CliMA/MyPackage.jl/pull/1230).
```

--------------------------------

### Instantiate ClimaAtmos.jl Development Environment

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/contributor_guide.md

Open Julia in the project directory and run 'instantiate' to install all project dependencies. This command reads the Project.toml file and ensures all required packages are downloaded and compiled.

```julia
julia --project
] instantiate
```

--------------------------------

### Configuration with Artifacts

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/config_no_table.md

Example of specifying an artifact for insolation and external forcing files. Artifacts are folders, so specify the artifact name and the file within it, separated by '/'.

```yaml
insolation: "gcmdriven"
external_forcing_file: artifact"cfsite_gcm_forcing"/HadGEM2-A_amip.2004-2008.07.nc
```

--------------------------------

### Clone and Install ClimaAtmos for Development

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/installation.md

Clone the ClimaAtmos repository and instantiate its dependencies to set up the project for development or to use the latest changes. Ensure you are in the cloned directory before running the Julia command.

```bash
git clone https://github.com/CliMA/ClimaAtmos.jl.git
cd ClimaAtmos.jl
julia --project -e 'using Pkg; Pkg.instantiate()'
```

--------------------------------

### Load Simulation from YAML Configuration

Source: https://context7.com/clima/climaatmos.jl/llms.txt

Use the config API to load a simulation setup from a YAML file. This is suitable for reproducible runs and CI pipelines.

```yaml
# config.yml
initial_condition: "Bomex"
config: "column"
z_elem: 60
z_max: 3000.0
z_stretch: false
dt: "5secs"
t_end: "6hours"
job_id: "bomex_yaml"
output_default_diagnostics: true
dt_save_state_to_disk: "10mins"
```

```julia
import ClimaAtmos as CA

config = CA.AtmosConfig("config.yml")
sim    = CA.get_simulation(config)
CA.solve_atmos!(sim)
```

--------------------------------

### ITime Conversion and Promotion Functions

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/itime.md

Demonstrates how to convert an ITime to a Float64, get the current date, and promote ITime objects with different periods.

```julia
float(x)
date(x)
promote(x, y)
```

--------------------------------

### Internal Helper Docstring Example

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/code-quality/documentation_policy.md

Use for internal helper functions with one or two call sites. Includes a one-line summary and references to its caller. Skip '# Arguments' unless names/units are unclear.

```julia
"""
    e_tot_0M_precipitation_sources_helper(thp, T, q_liq, q_ice, Φ)

Compute the specific energy carried away by precipitation in the 0-moment scheme.

Called from [`Microphysics0MEvaluator`](@ref) and [`microphysics_tendencies_0m`](@ref).
"""
```

--------------------------------

### Acquire Device and Context with ClimaComms

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/infrastructure/clima_comms.md

Obtain the device (CPU or CUDA) and communication context (Singleton or MPI) at the start of your entry point. Initialize the context before any collective operations.

```julia
import ClimaComms

device  = ClimaComms.device()          # CPU or CUDA, inferred from the environment
context = ClimaComms.context(device)   # SingletonCommsContext, or MPICommsContext if an MPI backend is loaded
ClimaComms.init(context)               # required before any collective; no-op for singleton contexts
```

--------------------------------

### Visualize BoxGrid Element Traversal Order

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/grids.md

This setup code generates a visualization of the space-filling curve for a small BoxGrid, illustrating element traversal order and physical coordinates.

```julia
import ClimaAtmos as CA
CC = CA.CC
using CairoMakie

# Create a small grid for visualization
grid = CA.BoxGrid(Float64; nh_poly=1, x_elem=3, y_elem=6, x_max=100, y_max=100)

# Extract the space-filling curve from the topology's mesh
spacefilling = CC.Topologies.spacefillingcurve(grid.horizontal_grid.topology.mesh)

# Extract coordinates for plotting
coords = tuple.(
   parent(grid.horizontal_grid.local_geometry.coordinates.x)[1,1,1,:],
   parent(grid.horizontal_grid.local_geometry.coordinates.y)[1,1,1,:]
)

# Plot the ordering index vs coordinate index
fig = Figure(size = (800, 400))
ax = Axis(fig[1, 1]; title = "Element Traversal Order")
sc = scatterlines!(ax, getfield.(spacefilling, :I); markersize = (1:length(coords)) .* 2, label = "Order")

# Plot the physical coordinates and the path
ax2 = Axis(fig[1, 2]; title = "Physical Coordinates Path")
scatterlines!(ax2, coords; markersize = (1:length(coords)) .* 2)

save("grid_order.png", fig); nothing # hide
```

--------------------------------

### Configure Julia Startup File

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/workflow/onboarding.md

Add using statements for Revise.jl and Infiltrator.jl to your Julia startup file (~/.julia/config/startup.jl). This ensures they are loaded automatically when you start a REPL.

```julia
using Revise
using Infiltrator
```

--------------------------------

### Serve Documentation Locally with LiveServer.jl

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/workflow/onboarding.md

Employ servedocs() from LiveServer.jl to build and preview your documentation site locally, with automatic reloading on file changes.

```julia
servedocs()
```

--------------------------------

### Configure OhMyREPL.jl for Auto-Loading

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/workflow/onboarding.md

Add 'using OhMyREPL' to your '~/.julia/config/startup.jl' file to ensure OhMyREPL.jl provides syntax highlighting in every REPL session.

```julia
using OhMyREPL
```

--------------------------------

### Construct and Run a Minimal Simulation

Source: https://context7.com/clima/climaatmos.jl/llms.txt

Create a minimal 1-day global simulation using default settings and advance it in time. Inspect the prognostic state and output directory.

```julia
import ClimaAtmos as CA

# Minimal 1-day global simulation (Float32, all defaults)
sim = CA.AtmosSimulation{Float32}(; t_end = 86400)
CA.solve_atmos!(sim)

# Inspect the prognostic state after the run
Y = sim.integrator.u
propertynames(Y.c)   # => (:ρ, :ρe_tot, :uₕ, ...)
propertynames(Y.f)   # => (:w, ...)

# Output files are written here:
println(sim.output_dir)
```

--------------------------------

### Floating Point Inaccuracy Example

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/itime.md

Demonstrates how floating-point arithmetic can lead to inaccuracies in time calculations.

```julia
0.1 + 0.1 + 0.1 == 0.3
```

```julia
Float32(16777216) + Float32(1) == Float32(16777216)
```

--------------------------------

### Build Documentation Locally

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/contributor_guide.md

Commands to build the documentation locally and preview it. Use JULIA_DEBUG=Documenter for verbose output during the build process.

```sh
julia --project -e 'using Pkg; Pkg.instantiate()'
```

```sh
julia --project=docs/ -e 'using Pkg; Pkg.instantiate(); develop(PackageSpec(path=pwd()))'
```

```sh
JULIA_DEBUG=Documenter julia --project=docs/ docs/make.jl
```

--------------------------------

### Warning Admonition

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/code-quality/documentation_policy.md

Use admonitions sparingly for genuinely important caveats. This example shows a 'warning' admonition.

```markdown
!!! warning
    Calling this function outside `set_precomputed_quantities!` will read stale `p.scratch`
    values. Run after `set_implicit_precomputed_quantities_part1!`.
```

--------------------------------

### Define Shell Alias for Formatting

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/contributor_guide.md

Example of a shell alias to quickly format the current directory using JuliaFormatter.jl.

```sh
alias julia_format_here="julia -e 'using JuliaFormatter; format(".")'"
```

--------------------------------

### Add ClimaAtmos Package

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/installation.md

Use this command to add ClimaAtmos as a registered Julia package. This is the standard way to install the package for general use.

```julia
using Pkg
Pkg.add("ClimaAtmos")
```

--------------------------------

### Run a 1-Day Global Simulation with ClimaAtmos.jl

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/index.md

This snippet demonstrates how to initialize and run a global atmospheric simulation for one day using default settings. Ensure ClimaAtmos is imported before execution.

```julia
import ClimaAtmos as CA

simulation = CA.AtmosSimulation{Float64}(; t_end = 86400)
CA.solve_atmos!(simulation)
```

--------------------------------

### Add ClimaAtmos.jl Package

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/getting_started.md

Use this command to add ClimaAtmos.jl as a registered Julia package. Ensure you have Julia installed and a Julia REPL open.

```julia
using Pkg

pkg> Pkg.add("ClimaAtmos")
```

--------------------------------

### Run All Test Cases from Command Line

Source: https://github.com/clima/climaatmos.jl/blob/main/README.md

An alternative command to run all test cases directly from the command line.

```bash
$ julia --project -e 'using Pkg; Pkg.test()'
```

--------------------------------

### Configure Default Diagnostics for Simulation

Source: https://context7.com/clima/climaatmos.jl/llms.txt

Sets up an atmospheric simulation with default diagnostics enabled. The simulation runs for 5 days.

```julia
import ClimaAtmos as CA
import ClimaAtmos.Diagnostics as CAD

# Use default diagnostics for the chosen model
sim = CA.AtmosSimulation{Float32}(;
    t_end      = 86400 * 5,
    diagnostics = CA.DiagnosticsConfig(; default = true),
    job_id     = "with_defaults",
)
CA.solve_atmos!(sim)
```

--------------------------------

### Docstring Structure for Structs

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/code-quality/documentation_policy.md

A docstring template for Julia structs, detailing the struct's purpose, type parameters, fields, and providing an example of instantiation.

```julia
"..."
@kwdef struct MyStruct{T}
    field::T
end
```

--------------------------------

### Instantiate ClimaAtmos.jl Dependencies

Source: https://github.com/clima/climaatmos.jl/blob/main/README.md

After cloning the repository, navigate to the project directory and use this command to instantiate all necessary dependencies.

```bash
julia --project
julia> ]
(ClimaAtmos) pkg> instantiate
```

--------------------------------

### Summarize Julia Values with About.jl

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/workflow/onboarding.md

Use the about(x) function from About.jl to get a summary of a value's type, memory layout, and associated methods.

```julia
about(x)
```

--------------------------------

### Device-Agnostic Array Allocation

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/infrastructure/clima_comms.md

Use ClimaComms.array_type to get the appropriate array type for the current device, avoiding hard-coded references to CPU or CUDA arrays.

```julia
# ❌ Hard-codes CPU
buffer = Array{FT}(undef, n)

# ❌ Hard-codes CUDA
using CUDA
buffer = CUDA.CuArray{FT}(undef, n)

# ✅ Device-agnostic
ArrayType = ClimaComms.array_type(device)
buffer = ArrayType{FT}(undef, n)
```

--------------------------------

### AtmosSimulation Constructor and solve_atmos!

Source: https://context7.com/clima/climaatmos.jl/llms.txt

Construct an AtmosSimulation object using keyword arguments and advance it in time using solve_atmos!.

```APIDOC
## AtmosSimulation{FT} — construct and run a simulation

The primary entry point. Accepts keyword arguments for every aspect of the simulation. Omitting a keyword uses the default (global cubed-sphere, dry compressible Euler, 10-day run).

### Description
Constructs an `AtmosSimulation` object, which represents the state and configuration of an atmospheric simulation. It allows for customization of various simulation parameters via keyword arguments.

### Method
`AtmosSimulation{FT}(; kwargs...)
`

### Parameters
- `FT`: The floating-point type for the simulation (e.g., `Float32`, `Float64`).
- `t_end` (optional): The end time of the simulation in seconds. Defaults to a 10-day run.
- `grid` (optional): The computational grid for the simulation. Defaults to a global cubed-sphere grid.
- `dt` (optional): The time step size in seconds.
- `job_id` (optional): A string identifier for the simulation job.

### Request Example
```julia
import ClimaAtmos as CA

# Minimal 1-day global simulation (Float32, all defaults)
sim = CA.AtmosSimulation{Float32}(; t_end = 86400)
```

## solve_atmos! — advance the integrator to `t_end`

Runs the time integration loop from `t_start` to `t_end`, firing all registered callbacks (checkpointing, diagnostics, radiation updates, etc.).

### Description
Advances the `AtmosSimulation` object's internal integrator to the specified end time (`t_end`), executing all configured physics and callbacks during the integration.

### Method
`solve_atmos!(sim::AtmosSimulation)
`

### Parameters
- `sim`: The `AtmosSimulation` object to advance.

### Request Example
```julia
import ClimaAtmos as CA

sim = CA.AtmosSimulation{Float64}(;
    grid  = CA.SphereGrid(Float64; h_elem = 6, z_elem = 45),
    dt    = 600,
    t_end = 86400 * 10,   # 10 days
    job_id = "global_dry_run",
)
CA.solve_atmos!(sim)
# NetCDF / HDF5 output written to sim.output_dir
```

### Response
#### Success Response (void)
This function does not return a value but modifies the `sim` object in place and writes output files.

#### Response Example
```julia
# Output files are written to sim.output_dir
println(sim.output_dir)

# Inspect the prognostic state after the run
Y = sim.integrator.u
propertynames(Y.c)   # => (:ρ, :ρe_tot, :uₕ, ...)
propertynames(Y.f)   # => (:w, ...)
```
```

--------------------------------

### Log Information with @show and @info

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/workflow/debugging.md

Employ `@show` for simple one-line value printing and `@info` for structured, grep-able log messages. These are useful for tracking variable changes during simulation.

```julia
@show x                  # one-line printout: "x = 3.14"
@info "before update" x y # structured log line, easier to grep
```

--------------------------------

### Configure Custom Diagnostics for Simulation

Source: https://context7.com/clima/climaatmos.jl/llms.txt

Sets up an atmospheric simulation with custom diagnostics including hourly averages of temperature and wind, and daily maximums of air density. Uses Float64 precision and runs for 10 days.

```julia
import ClimaAtmos as CA
import ClimaAtmos.Diagnostics as CAD

# Add custom diagnostics via DiagnosticsConfig
custom_diag = CAD.hourly_average("air_temperature", "ua", "va")
push!(custom_diag, CAD.daily_max("air_density"))

sim2 = CA.AtmosSimulation{Float64}(;
    grid       = CA.SphereGrid(Float64; h_elem = 6, z_elem = 30),
    t_end      = 86400 * 10,
    diagnostics = CA.DiagnosticsConfig(;
        default    = false,
        additional = custom_diag,
    ),
    job_id     = "custom_diags",
)
CA.solve_atmos!(sim2)
```

--------------------------------

### Add CUDA for GPU Support

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/installation.md

Install the CUDA package to enable GPU acceleration for ClimaAtmos. This is an optional step for users who wish to leverage GPU hardware.

```julia
using Pkg
Pkg.add("CUDA")
```

--------------------------------

### Example Reproducibility Test Output Table

Source: https://github.com/clima/climaatmos.jl/blob/main/reproducibility_tests/README.md

This table displays the root-mean-square (RMS) differences for prognostic variables, along with their units, data scale, tolerance, and status.

```text
── Reference: abc1234 ──
┌───────────────────────────┬────────┬──────────┬────────────┬──────────┬────────┐
│ Variable                  │ Unit   │ RMS Diff │ Data Scale │ Tolerance│ Status │
├───────────────────────────┼────────┼──────────┼────────────┼──────────┼────────┤
│ ρ (density)               │ kg/m³  │ 0.00e+00 │ 1.17e+00   │ 1.40e-06 │   🟢   │
│ ρe_tot (total energy)     │ J/m³   │ 0.00e+00 │ 2.50e+05   │ 2.98e-01 │   🟢   │
│ u₁ (covariant horiz. u₁)  │ m/s    │ 0.00e+00 │ 1.23e+01   │ 1.47e-05 │   🟢   │
│ u₃ (covariant vert. u₃)   │ m/s    │ 0.00e+00 │ 3.45e-02   │ 1.19e-06 │   🟢   │
└───────────────────────────┴────────┴──────────┴────────────┴──────────┴────────┘
```

--------------------------------

### Run GCM-Driven Case

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/single_column_prospect.md

Execute the GCM-driven single column model experiment using the specified configuration file. This command initiates a simulation forced by GCM data.

```bash
julia --project=.buildkite .buildkite/ci_driver.jl --config_file config/model_configs/prognostic_edmfx_gcmdriven_column.yml --job_id gcm_driven_scm
```

--------------------------------

### Explore State Variables in ClimaAtmos

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/getting_started.md

This code snippet demonstrates how to initialize ClimaAtmos and access the simulation's state variables. It requires a path to a configuration file.

```julia
import ClimaAtmos as CA

config = CA.AtmosConfig([your_path_to_config_file])
simulation = CA.get_simulation(config)
Y = simulation.integrator.u
```

--------------------------------

### Generate default diagnostics from model

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/diagnostics.md

Obtain a list of default diagnostics for an atmospheric model using the `default_diagnostics` function. This is a convenient way to start with pre-configured diagnostics.

```julia
model = ClimaAtmos.AtmosModel(..., microphysics_model = ClimaAtmos.DryModel(), ...)

diagnostics = ClimaAtmos.default_diagnostics(model)
# => List of diagnostics that include the ones specified for the DryModel
```

--------------------------------

### Create AtmosSimulation with Script API

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/interfaces.md

Build an AtmosSimulation directly using Julia keyword arguments. Best for interactive exploration, notebooks, custom scripts, and programmatic parameter sweeps.

```julia
import ClimaAtmos as CA

simulation = CA.AtmosSimulation{Float64}(
    model = CA.AtmosModel(),
    grid = CA.SphereGrid(Float64; z_elem = 45, h_elem = 6),
    initial_condition = CA.Setups.DecayingProfile(; perturb = true),
    dt = 600,
    t_end = 86400 * 10,
    job_id = "my_run",
)
CA.solve_atmos!(simulation)
```

--------------------------------

### # Extended help

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/code-quality/documentation_policy.md

Use the '# Extended help' section for supplementary details, implementation notes, or detailed cross-references, visible only via `??function_name`.

```APIDOC
## saturation_adjustment(thp, h, ρ, q_tot)

### Description
Compute the saturation-adjusted thermodynamic state for given enthalpy, density, and total
water specific humidity.

### Arguments
- ...

### Extended help

The iteration uses Newton's method with bracketed bisection fallback. Convergence
   tolerances and edge-case handling are documented in [`SaturationAdjustmentSolver`](@ref).
...
```

--------------------------------

### Run Model with Multiple Configuration Files

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/config_no_table.md

Command to run the model specifying both a common configuration and a model-specific configuration. The model configuration overrides conflicting settings from the common configuration.

```bash
julia --project=.buildkite .buildkite/ci_driver.jl \
  --config_file config/common_configs/numerics_sphere_he16ze63.yml \
  --config_file config/model_configs/your_model_config.yml
```

--------------------------------

### Add New Configuration Argument

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/config_no_table.md

Format for adding a new configuration argument to `.buildkite/default_config.yml`. The `help` field is optional.

```yaml
<argument_name>:
    value: <argument_value>
    help: <help string>
```

--------------------------------

### Add Revise.jl and Infiltrator.jl to Base Environment

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/workflow/onboarding.md

Install Revise.jl and Infiltrator.jl into your base Julia environment to enable automatic loading in all REPL sessions. This avoids recompilation when making code changes.

```julia
julia -e 'using Pkg; Pkg.add(["Revise", "Infiltrator"])'
```

--------------------------------

### Docstring Structure for Functions

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/code-quality/documentation_policy.md

A comprehensive docstring template for Julia functions, including summary, elaboration, arguments, keyword arguments, returns, examples, and notes. Math can be included using LaTeX.

```julia
"..."
function function_name(positional1, positional2; kwarg1 = default1)
    ...
end
```

--------------------------------

### Build Docs Locally with Documenter.jl

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/code-quality/documentation_policy.md

Instantiate dependencies and build documentation locally using Documenter.jl. Set JULIA_DEBUG=Documenter for debugging build issues.

```sh
julia --project=docs/ -e 'using Pkg; Pkg.instantiate(); Pkg.develop(PackageSpec(path=pwd()))'
JULIA_DEBUG=Documenter julia --project=docs/ docs/make.jl
```

--------------------------------

### Configure Monthly Averaged Forcing

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/single_column_prospect.md

Configuration for a single-column simulation using monthly averaged ERA5 data, repeating daily data indefinitely. This setup is useful for calibrating to monthly statistics.

```YAML
initial_condition: "ReanalysisTimeVarying"
external_forcing: "ReanalysisMonthlyAveragedDiurnal"
surface_setup: "ReanalysisTimeVarying"
surface_temperature: "ReanalysisTimeVarying"
start_date: "20070701"
site_latitude: 17.0
site_longitude: -149.0
```

--------------------------------

### Running a ClimaAtmos Simulation with YAML Configuration

Source: https://context7.com/clima/climaatmos.jl/llms.txt

Load a simulation configuration from a YAML file and run the atmospheric simulation. Ensure the YAML file and any referenced TOML files are accessible.

```julia
import ClimaAtmos as CA

config = CA.AtmosConfig("config.yml")
sim    = CA.get_simulation(config)
CA.solve_atmos!(sim)
```

--------------------------------

### Run Simulation with Checkpointing Enabled

Source: https://context7.com/clima/climaatmos.jl/llms.txt

Initiates a simulation with checkpointing enabled every day. The simulation runs for 5 days and uses 'activelink' output directory style.

```julia
import ClimaAtmos as CA

# Run 1: set checkpoint frequency and save state to disk
sim1 = CA.AtmosSimulation{Float32}(;
    t_end                = 86400 * 5,
    checkpoint_frequency = 86400,        # checkpoint every day
    job_id               = "long_run",
    output_dir_style     = "activelink",
)
CA.solve_atmos!(sim1)
```

--------------------------------

### Format CliMA Repository Code

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/workflow/onboarding.md

Use JuliaFormatter.jl to format the code in the repository according to CliMA's style guidelines. Ensure you have the correct version of JuliaFormatter installed to match the CI configuration.

```julia
using JuliaFormatter
format(".")
```

--------------------------------

### Run All Test Cases

Source: https://github.com/clima/climaatmos.jl/blob/main/README.md

Launch Julia from the ClimaAtmos.jl directory with the project active, then switch to the package manager and run tests.

```bash
$ julia --project
julia> ]
(ClimaAtmos) pkg> test
```

--------------------------------

### Configure Matched ERA5 Trajectory

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/src/single_column_prospect.md

Configuration for a single-column simulation driven by matched ERA5 reanalysis data. Requires specifying initial condition, external forcing, start date, and site location.

```YAML
initial_condition: "ReanalysisTimeVarying"
external_forcing: "ReanalysisTimeVarying"
start_date: "20070701"
site_latitude: 17.0
site_longitude: -149.0
```

--------------------------------

### Start New Task with Latest Main Branch

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/code-quality/code_style.md

Ensure your new feature branch is based on the most recent version of the main branch. This involves stashing local changes, pulling the latest main, creating a new branch, and then reapplying stashed changes.

```bash
git stash
git checkout main
git pull origin main
git checkout -b your/branch-name
git stash pop
```

--------------------------------

### Sample sbatch script for Clima Atmos simulations

Source: https://github.com/clima/climaatmos.jl/wiki/Caltech-central-cluster

Use this script to set up and run Clima Atmos simulations on the Caltech central cluster. Customize SBATCH directives for memory/GPU needs and update paths for your specific configuration.

```bash
#!/bin/bash
#SBATCH --ntasks=32
#SBATCH --job-name=[YOUR_JOB_NAME]
#SBATCH --time=2:00:00
#SBATCH --partition=expansion  # or gpu

export MODULEPATH="/groups/esm/modules:$MODULEPATH"
module purge
module load climacommon

CA_PATH=[YOUR_CLIMAATMOS_PATH]
CA_EXAMPLE=$CA_PATH'examples/'
DRIVER=$CA_EXAMPLE'hybrid/driver.jl'
CONFIG_FILE=[YOUR_CONFIG_FILE]

export OPENBLAS_NUM_THREADS=1
export JULIA_NVTX_CALLBACKS=gc
export JULIA_MAX_NUM_PRECOMPILE_FILES=100
export JULIA_LOAD_PATH="${JULIA_LOAD_PATH}:${CA_PATH}.buildkite"
export CLIMACORE_DISTRIBUTED="MPI"
export SLURM_KILL_BAD_EXIT=1

julia --project=$CA_EXAMPLE -e 'using Pkg; Pkg.instantiate()'
julia --project=$CA_EXAMPLE -e 'using Pkg; Pkg.precompile()'
julia --project=$CA_EXAMPLE -e 'using Pkg; Pkg.status()'

srun julia --project=$CA_EXAMPLE $DRIVER --config_file $CONFIG_FILE

```

--------------------------------

### Testing AD Compatibility with ForwardDiff

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/performance/ad_compatibility.md

Demonstrates how to test AD compatibility by verifying that a function accepts Dual numbers and that its gradient can be computed without errors.

```julia
using ForwardDiff

# Verify function accepts Dual numbers and returns Dual
x_dual = ForwardDiff.Dual(1.0f0, 1.0f0)
result = my_physics_func(x_dual, params)
@test result isa ForwardDiff.Dual

# Verify gradient computes without error
grad = ForwardDiff.derivative(x -> my_physics_func(x, params), 1.0f0)
@test isfinite(grad)
```

--------------------------------

### Reproduce Calibration Experiment

Source: https://github.com/clima/climaatmos.jl/blob/main/calibration/README.md

Use this command to reproduce the sphere_held_suarez_rhoe_equilmoist calibration experiment on the Caltech central cluster. Ensure you are in the correct directory.

```bash
sbatch calibration/experiments/sphere_held_suarez_rhoe_equilmoist/pipeline.sbatch
```

--------------------------------

### Run Package Tests

Source: https://github.com/clima/climaatmos.jl/blob/main/docs/dev-guides/workflow/onboarding.md

Execute the package's tests using Pkg.test(). This command activates the test environment and runs all defined tests, ensuring the test-only dependencies are correctly set up.

```julia
Pkg.test()
```

--------------------------------

### AtmosConfig and get_simulation

Source: https://context7.com/clima/climaatmos.jl/llms.txt

Load simulation configuration from a YAML file and create an AtmosSimulation object.

```APIDOC
## `AtmosConfig` + `get_simulation` — config-file (YAML) interface

Load a YAML file to build a simulation. Suitable for reproducible runs and CI pipelines.

### Description
This interface allows users to define and load simulation parameters from a YAML configuration file, promoting reproducibility and ease of use in automated workflows. The `AtmosConfig` object parses the YAML, and `get_simulation` uses this configuration to construct an `AtmosSimulation` object.

### Methods
- `AtmosConfig(yaml_file_path::String)
- `get_simulation(config::AtmosConfig)

### Parameters
- `yaml_file_path`: Path to the YAML configuration file.
- `config`: An `AtmosConfig` object loaded from a YAML file.

### Request Example (YAML Configuration)
```yaml
# config.yml
initial_condition: "Bomex"
config: "column"
z_elem: 60
z_max: 3000.0
z_stretch: false
dt: "5secs"
t_end: "6hours"
job_id: "bomex_yaml"
output_default_diagnostics: true
dt_save_state_to_disk: "10mins"
```

### Request Example (Julia Code)
```julia
import ClimaAtmos as CA

config = CA.AtmosConfig("config.yml")
sim    = CA.get_simulation(config)
CA.solve_atmos!(sim)
```

### Response
- `AtmosConfig`: An object representing the parsed simulation configuration.
- `AtmosSimulation`: A fully configured simulation object ready to be run with `solve_atmos!`.
```