API

Package for generating realizations of surface elevation from a wave spectrum.

Can generate surfaces and time series. Includes intermediate representation as discrete complex amplitudes.

This is part of the JuliaOceanWaves ecosystem. The input spectra types are from WaveSpectra.jl.

TimeArray(amplitudes::ComplexAmplitudes, time; start=DateTime(0), dispersion=periodic)

Evaluate amplitudes at a single spatial point and return the resulting surface elevation as a TimeArray.

Unitful relative times are added to start. A vector of Dates.TimeType values, such as Date, DateTime, or Time, is preserved as the TimeArray timestamp axis and evaluated using elapsed time from its first value.

TimeArray(surface::WaveSurface; start=DateTime(0))

Convert a WaveSurface at a single spatial point to a TimeArray of surface elevation. The relative surface time axis is added to start.

ComplexAmplitudes(data, axis1, axis2)
ComplexAmplitudes(
    [rng::AbstractRNG,] spectrum::AbstractSpectrum,
    [axis1_spacing = nothing, axis2_spacing = nothing, randommethod = :complexamplitude]
)
ComplexAmplitudes(
    [rng::AbstractRNG,] spectrum::AbstractOmnidirectionalSpectrum,
    [spectral_spacing = nothing, randommethod = :complexamplitude];
    direction = 0°
)

Complex amplitude matrix with physical-unit axes.

The first axis is a spectral variable. The second axis is either another spectral variable (cartesian) or direction (polar).

Indexing returns a ComplexAmplitudes with all dimensions retained. Select by integer indices, by axis-name keywords, or by AxisArrays .. intervals.

The complex amplitudes can be constructed from a wave spectrum, which is assumed to be a variance spectrum. An omnidirectional spectrum produces a polar ComplexAmplitudes with one direction, specified by direction. Axis spacing may be a vector, number, or nothing. When nothing, spacing is inferred from the corresponding evenly spaced spectrum axis.

Two randomization methods are available:

• :complexamplitude (default) independently samples the real and imaginary components: $A = \sqrt{V}(X + iY)$, where $X, Y \sim \mathcal{N}(0, 1)$.
• :phase uses the spectrum-derived amplitude with a uniformly random phase: $A = \sqrt{2V}e^{i\phi}$, where $\phi \sim \mathcal{U}[0, 2\pi]$.

Here, $V$ is the variance in the corresponding discrete spectral bin. For example, for a given bin $j$ of variance spectrum $S(f)$, $V=S_j Δf_j$

A random number generator can be passed as the first argument, which can be useful for reproducible results.

WaveSurface(data, x, y, time)
WaveSurface(amplitudes::ComplexAmplitudes, x, y, time; dispersion=periodic)
WaveSurface(amplitudes::ComplexAmplitudes; x=nothing, y=nothing, time=nothing,
            dispersion=periodic)

Discrete wave-surface values with spatial axes x and y and temporal axis time.

WaveSurface behaves as a three-dimensional array indexed in (x, y, time). Indexing returns a WaveSurface with all dimensions retained. Select by integer indices, by x, y, and time keywords, or by AxisArrays .. intervals.

Convert a surface with singleton x and y axes to a TimeSeries TimeArray with TimeArray(surface).

Evaluate the real surface represented by amplitudes.

The surface is the sum of regular sinusoidal components real(A * cis(kx * x + ky * y - ω * t)). The negative sign on ω * t is the package's temporal sign convention.

Evaluate the surface on every combination of x, y, and time, with omitted coordinates set to zero. Return a WaveSurface with axes x, y, and time.

equal_energy_bins(f::AbstractVector, x::AbstractVector, n::Integer)
equal_energy_bins(f, xf::Number, n::Integer; n_points::Integer = max(4n + 1, 1025))

Divide f(x) into n bins with equal integral/area.

The function returns (edges, widths, centers, values), where edges are the bin edges, widths are the bin widths, centers are the midpoint locations of each bin, and values are the spectrum values at the bin centers. If f is a vector, the sample locations x must be provided. If f is callable, it is discretized over [0, xf] with n_points samples.

fft_surface(amplitudes::ComplexAmplitudes)

Generate a realization on the natural FFT grid.

Polar amplitudes must have one direction and an evenly spaced one-sided frequency or wavenumber axis starting at the first positive FFT frequency. Spatial polar amplitudes must point along positive x or positive y.

Cartesian amplitudes must be spatial, use full signed FFT wavenumber grids, and already be Hermitian. A positive-quadrant Cartesian grid is insufficient because its missing directional quadrants cannot be inferred.

surface_function(amplitudes::ComplexAmplitudes; dispersion=periodic)

Return a function accepting (x, y, time) that evaluates the real surface represented by amplitudes.

The surface is the sum of regular sinusoidal components real(A * cis(kx * x + ky * y - ω * t)). The negative sign on ω * t is the package's temporal sign convention.