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.

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.

Arguments

• metadata: The metadata specifying the dataset to be downloaded. Available options are metadata for 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 .nc 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.

EdsonMomentumStabilityFunction{FT}

A struct representing the momentum stability function detailed in 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

\[dζ = min(ζmax, Aˢζ) ψₛ = - Bˢ * ζ⁺ - Cˢ * (ζ⁺ - Dˢ) * exp(- dζ) - Cˢ * Dˢ\]

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

\[fᵤ₁ = √√(1 - Aᵘζ) ψᵤ₁ = Bᵘ / 2 ⋅ log((1 + fᵤ₁ + fᵤ₁² + fᵤ₁³) / Bᵘ) - √Bᵘ atan(fᵤ₁) - Cᵘ fᵤ₂ = ∛(1 - Dᵘζ) ψᵤ₂ = Eᵘ / 2 ⋅ log((1 + fᵤ₂ + fᵤ₂²) / Eᵘ) - √Eᵘ atan( (1 + 2fᵤ₂) / √Eᵘ) + Fᵘ f = ζ² / (1 + ζ²) ψᵤ = (1 - f) ψᵤ₁ + f ψᵤ₂\]

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 in 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

\[dζ = min(ζmax, Aˢζ) ψₛ = - (1 + Bˢ ζ) ^ Cₛ - Bˢ ( ζ - Dˢ ) * exp( - dζ) - Eˢ\]

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

\[fᵤ₁ = √(1 - Aᵘζ) ψᵤ₁ = Bᵘ ⋅ log((1 + fᵤ₁) / Bᵘ) + Cᵤ fᵤ₂ = ∛(1 - Dᵘζ) ψᵤ₂ = Eᵘ / 2 ⋅ log((1 + fᵤ₂ + fᵤ₂²) / Eᵘ) - √Eᵘ atan( (1 + 2fᵤ₂) / √Eᵘ) + Fᵘ f = ζ² / (1 + ζ²) ψᵤ = (1 - f) ψᵤ₁ + f ψᵤ₂\]

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

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 $ℓ$.

MomentumRoughnessLength(FT = Float64;
                        gravitational_acceleration = default_gravitational_acceleration,
                        maximum_roughness_length = 1.0,
                        air_kinematic_viscosity = TemperatureDependentAirViscosity(FT),
                        gravity_wave_parameter = 0.011,
                        laminar_parameter = 0.11)

Construct a MomentumRoughnessLength object that represents the momentum roughness length that regulates the exchange of momentum, heat, and water vapor between the ocean and the atmosphere.

Keyword Arguments

• gravitational_acceleration: The gravitational acceleration. Default: default_gravitational_acceleration.
• maximum_roughness_length: The maximum roughness length. Default: 1.0.
• air_kinematic_viscosity: The air kinematic viscosity. Default: TemperatureDependentAirViscosity(FT).
• gravity_wave_parameter: The wave parameter. Default: 0.011.
• laminar_parameter: The laminar parameter. Default: 0.11.

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\]

ScalarRoughnessLength(FT = Float64;
                      air_kinematic_viscosity = temperature_dependent_viscosity,
                      reynolds_number_scaling_function = empirical_scaling_function,
                      maximum_roughness_length = 1.6e-4)

Constructs a ScalarRoughnessLength object that represents the scalar roughness length that regulates the exchange of heat and water vapor between the ocean and the atmosphere.

Keyword Arguments

• air_kinematic_viscosity::Function: The function to compute the air kinematic viscosity.
• reynolds_number_scaling_function::Function: The function to compute the Reynolds number scaling factor.
• maximum_roughness_length::Float: The maximum roughness length value. Defaults to 1.6e-4.

SpecificHumidityFormulation(phase [, water_mole_fraction=1])

Return the formulation for computing specific humidity at an interface.

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;
                                  C₀ = 1.326e-5,
                                  C₁ = C₀ * 6.542e-3,
                                  C₂ = C₀ * 8.301e-6,
                                  C₃ = - C₀ * 4.84e-9])

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

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

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

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 non-condensing air, 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★ .\]

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.