Case API

eastern_north_atlantic(; arch=GPU(), FT=Float32, microphysics=:p3_n75,
                        Nx=256, Ny=256, stop_time=6hours,
                        data_dir, output_dir, kwargs...)

Build the public Covert ENA development case for 18 July 2017, starting at 06 UTC. Return a named tuple containing simulation, model, config, and input metadata, without advancing the simulation. Call run!(case.simulation) to run it.

Defaults use 35 m horizontal spacing, 192 reconstructed vertical levels, prescribed surface fluxes, simple longwave radiation, no mean-wind nudging, and a fixed 0.5 s step. Choose :one_moment, :p3_n75, :p3_covert_n75 (prognostic aerosol activating the case's observed 75 cm⁻³) or :p3_aer2 (LASSO aer2 aerosol sensitivity); the aerosol members use diagnostic CCN replenishment. Extra keywords are passed to ena_simulation.

Inputs default to data/covert2022_bin in the package checkout; fetch them with julia data_wrangling/fetch_covert_inputs.jl. Outputs default to output/ena_<microphysics> in the working directory. Input acquisition and provenance writing are explicit caller actions.

This is the public development configuration, not the larger published experiment or official LASSO. Use ena_simulation with protocol=:lasso_ena_official and an official input bundle for LASSO.

ena_simulation(data_dir; protocol, dimensions=nothing, kwargs...)

Build an ENA experiment with an explicit protocol (:covert_public_bin or :lasso_ena_official). Overrides create a labelled sensitivity experiment and are recorded separately from the protocol defaults. For LASSO, supply the run ID member, epoch::DateTime (UTC; the year is never inferred from the day of year) and, when the namelist carries no dimensions, dimensions=(Nx, Ny, Nz); the bundle is validated by validate_lasso_bundle and its record is kept under case.bundle for provenance. This is a Breeze implementation of the forcing protocol, not a claim of SAM equivalence.

ena_protocol_settings(data_dir; protocol, dimensions=nothing, member=nothing, epoch=nothing)

Read and validate protocol inputs without allocating a model. Return namelist-derived defaults. If a LASSO bundle omits dimensions from its namelist, supply dimensions=(Nx, Ny, Nz) from the original domain configuration; member (the run ID) and epoch (UTC) are checked against it (see inspect_lasso_bundle). Neither path is a numerically validated reproduction of the original SAM runs.

• :covert_public_bin — the runnable development benchmark from the public files of the Covert et al. (2022) bin-paper repository: caseid = 256x256x192 at dx = dy = 35 m (8.96 km), day0 = 199.25 (18 July 2017 06 UTC), nstop × dt = 6 h, prescribed H/LE/τ (SFC_FLX_FXD, SFC_TAU_FXD), SAM rad_simple longwave only, no wind nudging, doupperbound, dodamping. Not the 864²×192, 30.24-km, 06-15 UTC configuration of the published paper, and not an official LASSO-ENA reproduction.
• :lasso_ena_official — the official protocol from a samin bundle directory (snd, lsf, sfc, prm, grd): grid from grd and the namelist, bulk fluxes from SST, RRTMGP LW+SW with SAM's 0.95 surface emissivity and 14 μm ocean effective radius, tauls wind nudging (n0), P3 with the member's aerosol setting and the SBM diagCCN aerosol-reservoir projection, nrad × dt radiation cadence, fixed dt, duration nstop × dt, and the namelist's perturb_type. Unsupported namelist settings (T/q nudging, delayed forcing, restarts, …) are rejected with the reason.

ena_lasso(bundle_dir=lasso_bundle_directory(member); member=DEFAULT_LASSO_MEMBER, epoch,
          dimensions=:documented, arch=nothing, FT=Float32, output_dir, output_prefix="ena_lasso", kwargs...)

Build the official LASSO-ENA member member from its staged samin bundle without running it. Returns the ena_simulation case extended with staging (the bundle.toml written by data_wrangling/stage_lasso_bundle.jl, or a note when absent) so that write_provenance records the archive checksum, DOI and download date next to the input-file checksums.

• epoch::DateTime is the UTC start; it must agree with the namelist day0 and the member date (checked).
• dimensions = :documented uses lasso_documented_dimensions for the member's domain token (recorded in provenance as such); pass a tuple to be fully explicit, or nothing when the namelist carries nx_gl/ny_gl/nz_gl.
• A missing bundle raises an ArgumentError with lasso_bundle_missing_message, before the architecture is touched (arch = nothing becomes GPU() only afterwards, so the staging message also appears on machines without a GPU).

Everything else (Nx, Ny, z_faces, microphysics, stop_time, …) is an explicit, provenance-recorded override of the protocol defaults, exactly as in ena_simulation.

inspect_lasso_bundle(directory; member=nothing, dimensions=nothing, epoch=nothing)

Read a LASSO-ENA samin bundle (snd, lsf, sfc, prm, grd in directory) and return a record describing what it contains, what the Breeze adapter will use, and every setting the adapter cannot represent. Nothing is substituted or inferred:

• member (run ID or LassoMember) fixes the member identity; it is required by ena_lasso and recorded in provenance. The aerosol setting and the SAM microphysics come from it (the namelist does not carry them: the HUJI-SBM spectrum is compiled in).
• dimensions = (Nx, Ny, Nz) is required when the namelist carries neither nx_gl/ny_gl/nz_gl nor a numeric NxxNyxNz case ID (SAM fixes them at compile time in domain.f90).
• epoch::DateTime (UTC) is checked against day0 and the member date when given; SAM's day0 never identifies the year.

The returned named tuple has problems (fatal, each an actionable sentence), warnings (deliberate, recorded differences), settings (keyword defaults for build_case), namelist, groups, grid, time, switches, checksums and member. Use validate_lasso_bundle to turn problems into an error.

validate_lasso_bundle(directory; kwargs...)

inspect_lasso_bundle and throw an ArgumentError listing every unsupported or missing setting when the bundle cannot be reproduced. Returns the inspection record.

parse_lasso_member(id)

Parse a LASSO-ENA run ID into a LassoMember. The ID is never guessed: an ID that does not follow the listing's pattern is an error.

sea_starr(; member=:CTRL, arch=GPU(), FT=Float32, data_dir, kwargs...)

Build the SEA STARR experiment member from its DEPHY driver and return (; simulation, model, grid, driver, config, inputs, ...) without advancing it.

Keyword arguments (protocol defaults):

• data_dir: directory holding the three SEA_STARR_*_SCM_driver.nc files (default data/seastarr_22241697 in the package; stage them with julia data_wrangling/fetch_manifest.jl cases/seastarr/inputs.toml data/seastarr_22241697)
• Nx = 192, Ny = 192, Δx = Δy = 50, z_faces = sea_starr_vertical_faces() (Nz = 288)
• stop_time = 66hours, Δt = 1, max_Δt = 1 (fixed 1 s step unless the CFL wizard must shorten it), cfl = 0.7
• initialization = :equilibrium: partition (θₗ, qₜ) into (T, qᵛ, qᶜˡ) with Breeze's warm-phase saturation adjustment and activate the fraction initial_activated_fraction (default 1) of the aerosol in cloudy cells; :condensate_free starts from the supersaturated vapor and lets P3 condense
• aerosol_surface_flux = 7e5 m⁻² s⁻¹ (70 cm⁻² s⁻¹); regeneration = true
• mean_diameter = 185e-9, geometric_std = 1.5, kappa = 0.2
• radiation = :rrtmgp (all-sky LW+SW, radiation_interval = 60 s) or nothing; ozone = :driver
• liquid_effective_radius = 10e-6, surface_albedo = 0.07, surface_emissivity = 0.98
• nudging = true, nudging_offset = 100, nudging_ramp = 200, inversion_search_top = 4000 m
• vertical_advection = :full_field or nothing; geostrophic = true; surface = :bulk_sst or nothing
• sponge = SAMSponge(damping_depth_fraction=0.15): numerical damping of the top 15 % (not in the protocol)
• closure = :smagorinsky_lilly, advection_order = 5, perturbation = InitialPerturbation()
• output: output_dir, output_prefix, statistics_interval = 15minutes, timeseries_interval = 60, fields_2d_interval = 15minutes, fields_3d_interval = 1hour, checkpoint_interval = 3hours (or nothing), write_output = true, progress_interval = 10minutes

tracer_dp_scream(; iop_path, start=DateTime(2022, 8, 1), stop=DateTime(2022, 8, 15), kwargs...)

Build the periodic TRACER case driven by the DP-SCREAM IOP forcing without running it. Returns the build_case bundle plus iop, start, stop, window and protocol records.

Defaults (all overridable, overrides are recorded in the provenance):

• start/stop: UTC DateTimes on IOP records. The DP-SCREAM August run started at 2022-08-01 00 UTC and the paper's 5–15 August window is its days 5–15, so the default reproduces that initialization and continuous forcing history (14 days); the archived 0.5-km run started cold at 2022-08-05 00 UTC.
• arch = GPU(), FT = Float32, Nx = Ny = 256, Δx = Δy = 200 m, z_faces = tracer_dp_scream_vertical_faces()
• microphysics = :p3_n75 with droplet_number = 200e6 m⁻³ (continental assumption, see above)
• large_scale_transport = :iop_3d, hold_forcing = true (piecewise-constant hourly forcing)
• wind_nudging_timescale = nothing (archived runs), coriolis = nothing
• radiation = :rrtmgp every radiation_interval = 300 s with the IOP Tg as surface temperature, surface_albedo from the IOP shortwave fluxes (≈ 0.15), surface_emissivity = 0.98
• surface = :prescribed_heat_fluxes_bulk_drag: IOP sensible/latent heat fluxes, neutral log-law drag for roughness_length = 0.1 m referenced to the first cell center, gustiness = 1 m/s
• sponge = SAMSponge(damping_depth_fraction = 0.25), Δt = 2, max_Δt = 5, cfl = 0.7
• outputs: profiles every 30 min, time series every 60 s, slices every 30 min at 1500 m, checkpoint_interval = nothing (set e.g. 6hours for resumable runs)