API reference

LegacyConnectors

Readers and adapters that let Breeze.jl ingest initial conditions from legacy atmospheric modeling formats (CM1, WRF, ERF, …).

The public API:

• Sounding: a concretely-typed container whose four profile fields are Field{Nothing, Nothing, Center} on a column grid. Constructible from a path (Sounding("/path/to/file")) or a bundled example name (Sounding(:weisman_klemp_1982)).
• Oceananigans.Fields.interpolate!(target, sounding.potential_temperature) — the verb for filling a 3-D model Field from a column profile. Handled natively by Oceananigans ≥ 0.107.5.
• reference_state: build a Breeze.ReferenceState from a Sounding.

Three example soundings are bundled in data/soundings/ and discoverable via example_sounding.

Sounding(path::AbstractString; format::Symbol = :input_sounding) -> Sounding
Sounding(name::Symbol)                                            -> Sounding

Construct a vertical sounding from a file path, or from the name of one of the bundled examples (see example_sounding for the list).

The returned Sounding{F} is concretely typed: its four profile fields — potential_temperature, specific_humidity, x_momentum, y_momentum — are all Oceananigans Field{Nothing, Nothing, Face}s on a column grid whose z-faces are exactly the file's z-levels (with 0.0 prepended for the surface). They index, broadcast, and plot like any other Oceananigans field, and they are filled onto a Breeze model grid with Oceananigans.Fields.interpolate!.

specific_humidity may contain NaN at levels where the source did not provide moisture (e.g. mesospheric levels of a GFS point profile).

format selects the on-disk format. Currently supported:

• :input_sounding — the CM1/WRF/ERF text format (default).

s = Sounding("/path/to/input_sounding")
s = Sounding(:weisman_klemp_1982)

_column_grid(z_faces) -> RectilinearGrid

Build a column RectilinearGrid whose z-faces are exactly z_faces. Face-located fields on this grid carry one value per face — which is how we represent a sounding column: the file's z levels (with 0.0 prepended for the surface) become the face positions, and the values parsed off each line land at the matching face.

example_sounding(name::Symbol) -> String

Return the absolute path to a bundled example sounding. Dispatches on Val(name), so adding a new bundled example is a one-line method definition:

LegacyConnectors.example_sounding(::Val{:my_new_one}) =
    joinpath(pkgdir(LegacyConnectors), "data", "soundings", "my_new_one.txt")

Built-in names:

• :weisman_klemp_1982 — analytic supercell sounding from Weisman & Klemp (1982); generated by data/soundings/generate_weisman_klemp_1982.jl.
• :kabq_radiosonde — observed KABQ (Albuquerque) radiosonde, 2025-07-15 00Z.
• :abudhabi_gfs — GFS point forecast at Abu Dhabi, 2025-07-15 12Z; mesospheric qᵛ levels are NaN.

LegacyConnectors.reference_state(sounding::Sounding, grid; kwargs...)

Build a Breeze.ReferenceState whose surface state and (θ, qᵛ) profiles come from sounding. kwargs are forwarded to Breeze.ReferenceState.

sounding = Sounding(:weisman_klemp_1982)
ref      = LegacyConnectors.reference_state(sounding, grid)