Private types and functions

BoundingBox(; longitude=nothing, latitude=nothing, z=nothing)

Create a bounding box with latitude, longitude, and z bounds on the sphere.

DatasetBackend(length, metadata;
               on_native_grid = false,
               cache_inpainted_data = false,
               inpainting = NearestNeighborInpainting(Inf))

Represent a FieldTimeSeries backed by the backend that corresponds to the dataset with metadata (e.g., netCDF). Each time instance is stored in an individual file.

NearestNeighborInpainting{M}

A structure representing the nearest neighbor inpainting algorithm, where a missing value is substituted with the average of the surrounding valid values. This process is repeated a maximum of maxiter times or until the field is completely inpainted.

Field(metadata::Metadatum;
      architecture = CPU(),
      inpainting = default_inpainting(metadata),
      mask = nothing,
      halo = (7, 7, 7),
      cache_inpainted_data = true)

Return a Field on architecture described by metadata with halo size. If not nothing, the inpainting method is used to fill the cells within the specified mask. mask is set to compute_mask for non-nothing inpainting. Keyword argument cache_inpainted_data dictates whether the inpainted data is cached to avoid recomputing it; default: true.

FieldTimeSeries(metadata::Metadata [, arch_or_grid=CPU() ];
                time_indices_in_memory = 2,
                time_indexing = Cyclical(),
                inpainting = nothing,
                cache_inpainted_data = true)

Create a FieldTimeSeries from a dataset that corresponds to metadata.

Arguments

• metadata: Metadata containing information about the dataset.

• arch_or_grid: Either a grid to interpolate the data to, or an architecture to use for the native grid. Default: CPU().

Keyword Arguments

• time_indices_in_memory: The number of time indices to keep in memory. Default: 2.

• time_indexing: The time indexing scheme to use. Default: Cyclical().

• inpainting: The inpainting algorithm to use for the interpolation. The only option is NearestNeighborInpainting(maxiter), where an average of the valid surrounding values is used maxiter times.

• cache_inpainted_data: If true, the data is cached to disk after inpainting for later retrieving. Default: true.

available_variables(metadata)

Return the available variables in the dataset.

compute_mask(metadata::Metadatum, dataset_field,
             mask_value = default_mask_value(metadata),
             minimum_value = -1f5,
             maximum_value = 1f5)

A boolean field where true represents a missing value in the dataset_field.

compute_native_date_range(native_dates, start_date, end_date)

Compute the range of native_dates that fall within the specified start_date and end_date.

continue_downwards!(field, mask)

Continue downwards a field with missing values within mask. Cells where mask[i, k, k] == false will be preserved.

dataset_variable_name(metadata)

Return the name used for the variable metadata.name in its raw dataset file.

default_download_directory(dataset)

Return the default directory to which dataset is downloaded.

download_dataset(metadata; url = urls(metadata))

Download the dataset specified by the metadata::ECCOMetadata. If metadata.dates is a single date, the dataset is downloaded directly. If metadata.dates is a vector of dates, each date is downloaded individually.

Note: if called by multiple processes via MPI, download_dataset should only run on the root process.

Arguments

• metadata: The metadata specifying the dataset to be downloaded. Available options are metadata for ETOPO, ECCO4, ECCO2, EN4, and JRA55 datasets.

ECCO_USERNAME=myusername ECCO_PASSWORD=mypassword julia

julia> ENV["ECCO_USERNAME"] = "myusername"

julia> ENV["ECCO_PASSWORD"] = "mypassword"

download_progress(total, now; filename="")

inpaint_mask!(field, mask; inpainting=NearestNeighborInpainting(Inf))

Inpaint field within mask, using values outside mask. In other words, regions where mask[i, j, k] == 1 is inpainted and regions where mask[i, j, k] == 0 are preserved.

Arguments

• field: Field to be inpainted.

• mask: Boolean-valued Field, values where mask[i, j, k] == true are inpainted.

• inpainting: The inpainting algorithm to use. The only option is NearestNeighborInpainting(maxiter), where an average of the valid surrounding values is used maxiter times. Default: NearestNeighborInpainting(Inf).

metadata_filename(metadata)

File names of metadata containing multiple dates. The specific version for a Metadatum object is extended in the data specific modules.

native_times(metadata; start_time=first(metadata).dates)

Extract the time values from the given metadata, calculate the time difference from the start_time, and return an array of time differences in seconds.

Argument

• metadata: The metadata containing the date information.

Keyword Argument

• start_time: The start time for calculating the time difference. Defaults to the first date in the metadata.

netrc_downloader(username, password, machine, dir)

Create a downloader that uses a netrc file to authenticate with the given machine. This downloader writes the username and password in a file named auth.netrc (for Unix) and auth_netrc (for Windows), located in the directory dir. To avoid leaving the password on disk after the downloader has been used, it is recommended to initialize the downloader in a temporary directory, which will be removed after the download is complete.

For example:

mktempdir(dir) do tmp
    dowloader = netrc_downloader(username, password, machine, tmp)
    Downloads.download(fileurl, filepath; downloader)
end

propagate_horizontally!(inpainting, field, mask [, substituting_field=deepcopy(field)])

Horizontally propagate the values of field into the mask. In other words, cells where mask[i, j, k] == false are preserved, and cells where mask[i, j, k] == true are painted over.

The first argument inpainting is the inpainting algorithm to use in the _propagate_field! step.

z_interfaces(dataset)

Return an array with the vertical interfaces ($z$-faces) of the dataset that metadata corresponds to.

JRA55NetCDFBackend(length)

Represents a JRA55 FieldTimeSeries backed by JRA55 native netCDF files.

remove_minor_basins!(z_data, keep_major_basins)

Remove independent basins from the bathymetry data stored in z_data by identifying connected regions below sea level. Basins are removed from smallest to largest until only keep_major_basins remain.

Arguments

• z_data: A 2D array representing the bathymetry data.
• keep_major_basins: The maximum number of connected regions to keep. If Inf is provided then all connected regions are kept.

TwoColorRadiation(grid;
                  first_color_fraction,
                  first_absorption_coefficient,
                  second_absorption_coefficient)

Return TwoColorRadiation that computes the radiative flux divergence associated with a two-color radiation flux that decays according to Beer's law,

\[I(z) = ϵ₁ I₀ \exp(κ₁ z) + (1 - ϵ₁) I₀ \exp(κ₂ z)\]

where $I₀$ is the surface flux, $ϵ₁$ is the "first color" fraction of the total radiation, and $κ₁$ and $κ₂$ are the absorption coefficients for the two colors.

default_or_override(default::Default, alternative_default=default.value) = alternative_default
default_or_override(override, alternative_default) = override

Either return default.value, an alternative_default, or an override.

The purpose of this function is to help define constructors with "configuration-dependent" defaults. For example, the default bottom drag should be 0 for a single column model, but 0.003 for a global model. We therefore need a way to specify both the "normal" default 0.003 as well as the "alternative default" 0, all while respecting user input and changing this to a new value if specified.

EdsonMomentumStabilityFunction{FT}

A struct representing the momentum stability function detailed by Edson et al. (2013). The formulation hinges on the definition of three different functions: one for stable atmospheric conditions $(ζ > 0)$, named $ψₛ$ and two for unstable conditions, named $ψᵤ₁$ and $ψᵤ₂$. These stability functions are obtained by regression to experimental data.

The stability parameter for stable atmospheric conditions is defined as

\[\begin{align*} dζ &= \min(ζ_{\max}, A⁺ ζ) \\ ψ⁺ &= - B⁺ ζ⁺ - C⁺ (ζ⁺ - D⁺) \exp(- dζ) - C⁺ D⁺ \end{align*}\]

While the stability parameter for unstable atmospheric conditions is calculated as a function of the two individual stability functions as follows

\[\begin{align*} f⁻₁ &= (1 - A⁻ζ)^{1/4} \\ ψ⁻₁ &= (B⁻ / 2) \log[(1 + f⁻₁ + f⁻₁² + f⁻₁³) / B⁻] - √B⁻ \mathrm{atan}(f⁻₁) - C⁻ \\ \\ f⁻₂ &= ∛(1 - D⁻ζ) \\ ψ⁻₂ &= (E⁻ / 2) \log[(1 + f⁻₂ + f⁻₂²) / E⁻]- √E⁻ \mathrm{atan}[(1 + 2f⁻₂) / √E⁻] + F⁻ \\ \\ f &= ζ² / (1 + ζ²) \\ ψ⁻ &= (1 - f) ψ⁻₁ + f ψ⁻₂ \end{align*}\]

The superscripts $+$ and $-$ indicate if the parameter applies to the stability function for stable or unstable atmospheric conditions, respectively.

EdsonScalarStabilityFunction{FT}

A struct representing the scalar stability function detailed by Edson et al. (2013). The formulation hinges on the definition of two different functions: one for stable atmospheric conditions $(ζ > 0)$, named $ψ⁺$ and one for unstable conditions, named $ψ⁻$.

These stability functions are obtained by regression to experimental data.

The stability parameter for stable atmospheric conditions is defined as

\[\begin{align*} dζ &= \min(ζ_{\max}, A⁺ζ) \\ ψ⁺ &= - (1 + B⁺ ζ)^{C⁺} - B⁺ (ζ - D⁺) \exp( - dζ) - E⁺ \end{align*}\]

While the stability parameter for unstable atmospheric conditions is calculated as a function of the two individual stability functions as follows

\[\begin{align*} f⁻₁ &= √(1 - A⁻ζ) \\ ψ⁻₁ &= B⁻ \log[(1 + f⁻₁) / B⁻] + C⁻ \\ \\ f⁻₂ &= ∛(1 - D⁻ζ) \\ ψ⁻₂ &= (E⁻ / 2) \log[(1 + f⁻₂ + f⁻₂²) / E⁻] - √E⁻ \mathrm{atan}[(1 + 2f⁻₂) / √E⁻] + F⁻ \\ \\ f &= ζ² / (1 + ζ²) \\ ψ⁻ &= (1 - f) ψ⁻₁ + f ψ⁻₂ \end{align*}\]

The superscripts $+$ and $-$ indicate if the parameter applies to the stability function for stable or unstable atmospheric conditions, respectively.

ImpureSaturationSpecificHumidity(phase [, water_mole_fraction=1])

Return the formulation for computing specific humidity at an interface.

LogarithmicSimilarityProfile()

Represent the classic Monin-Obukhov similarity profile, which finds that

\[ϕ(z) = Π(z) ϕ★ / ϰ\]

where $ϰ$ is the Von Karman constant, $ϕ★$ is the characteristic scale for $ϕ$, and $Π$ is the "similarity profile",

\[Π(h) = log(h / ℓ) - ψ(h / L) + ψ(ℓ / L)\]

which is a logarithmic profile adjusted by the stability function $ψ$ and dependent on the Monin-Obukhov length $L$ and the roughness length $ℓ$.

The exchange fluxes depend on the relative velocity between the atmosphere and the interface

ReynoldsScalingFunction(FT=Float64; A=5.85e-5, b=0.72)

Empirical fit of the scalar roughness length with roughness Reynolds number R★ = u★ ℓu / ν. Edson et al. (2013), equation (28).

\[ ℓs = A / R★ ^ b\]

See equation (28) by Edson et al. (2013).

TabulatedAlbedo(arch = CPU(), FT = Float64;
                S₀ = convert(FT, 1365),
                α_table  = α_payne,
                φ_values = (0:2:90) ./ 180 * π,
                𝓉_values = 0:0.05:1)

Constructs a TabulatedAlbedo object that interpolated the albedo from a value table α_table that is function of latitude φ and atmospheric transimissivity 𝓉.

Note: TabulatedAlbedo assumes that the latitude and the transissivity in the table are uniformly spaced.

The transmissivity of the atmosphere is calculated as the ratio of the downwelling solar radiation to the maximum possible downwelling solar radiation for a transparent atmosphere, function of hour of the day, latitude, and day in the year.

Arguments

• arch: The architecture to use. Default: CPU().
• FT: The floating-point type to use. Default: Float64.

Keyword Arguments

• S₀: The solar constant. Default: convert(FT, 1365).
• α_table: The table of albedo values. Default: α_payne.
• φ_values: The latitude values for the table. Default: (0:2:90) ./ 180 * π.
• 𝓉_values: The transmissivity values for the table. Default: 0:0.05:1.

TemperatureDependentAirViscosity([FT = Oceananigans.defaults.FloatType;
                                  ℂ₀ = 1.326e-5,
                                  ℂ₁ = ℂ₀ * 6.542e-3,
                                  ℂ₂ = ℂ₀ * 8.301e-6,
                                  ℂ₃ = - ℂ₀ * 4.84e-9])

Construct a TemperatureDependentAirViscosity object that calculates the kinematic viscosity of air as

\[ℂ₀ + ℂ₁ T + ℂ₂ T^2 + ℂ₃ T^3\]

WindDependentWaveFormulation(FT = Oceananigans.defaults.FloatType;
                             Umax = 19, ℂ₁ = 0.0017, ℂ₂ = -0.005)

A gravity wave parameter based on the wind speed ΔU with the formula ℂ₁ * max(ΔU, Umax) + ℂ₂.

The exchange fluxes depend on the atmosphere velocity but not the interface velocity

Compute turbulent fluxes between an atmosphere and a interface state using similarity theory

Compute turbulent fluxes between an atmosphere and a interface state using similarity theory

buoyancy_scale(θ★, q★, ℂ, 𝒬, g)

Return the characteristic buoyancy scale b★ associated with the characteristic temperature θ★, specific humidity scale q★, surface thermodynamic state 𝒬, thermodynamic parameters ℂ, and gravitational acceleration g.

The buoyancy scale is defined in terms of the interface buoyancy flux,

\[u★ b★ ≡ w′b′,\]

where u★ is the friction velocity. Using the definition of buoyancy for clear air without condensation, we find that

\[b★ = g / 𝒯ₛ * (θ★ * (1 + δ * qₐ) + δ * 𝒯ₛ * q★),\]

where $𝒯ₐ$ is the virtual temperature at the surface, and $δ = Rᵥ / R_d - 1$, where $Rᵥ$ is the molar mass of water vapor and $R_d$ is the molar mass of dry air.

Note that the Monin-Obukhov characteristic length scale is defined in terms of b★ and additionally the Von Karman constant ϰ,

\[L★ = - u★² / ϰ b★ .\]

Calculate the air viscosity based on the temperature θ in Celsius.

iterate_interface_state(flux_formulation, Ψₛⁿ⁻¹, Ψₐ, Ψᵢ, Qᵣ, ℙₛ, ℙₐ, ℙᵢ)

Return the nth iterate of the interface state Ψₛⁿ computed according to the flux_formulation, given the interface state at the previous iterate Ψₛⁿ⁻¹, as well as the atmosphere state Ψₐ, the interior state Ψᵢ, downwelling radiation Qᵣ, and the interface, atmosphere, and interior properties ℙₛ, ℙₐ, and ℙᵢ.

Interpolate the atmospheric state onto the ocean / sea-ice grid.