Python package to interact with Sofar wave data

These details have not been verified by PyPI

Project links

Project description

description: | API documentation for modules: ocean_science_utilities, ocean_science_utilities.filecache, ocean_science_utilities.filecache.cache_object, ocean_science_utilities.filecache.filecache, ocean_science_utilities.filecache.remote_resources, ocean_science_utilities.interpolate, ocean_science_utilities.interpolate.dataarray, ocean_science_utilities.interpolate.dataframe, ocean_science_utilities.interpolate.dataset, ocean_science_utilities.interpolate.general, ocean_science_utilities.interpolate.geometry, ocean_science_utilities.interpolate.nd_interp, ocean_science_utilities.interpolate.spline, ocean_science_utilities.tool_log, ocean_science_utilities.tools, ocean_science_utilities.tools.grid, ocean_science_utilities.tools.math, ocean_science_utilities.tools.solvers, ocean_science_utilities.tools.time, ocean_science_utilities.tools.time_integration, ocean_science_utilities.wavephysics, ocean_science_utilities.wavephysics.balance, ocean_science_utilities.wavephysics.balance.balance, ocean_science_utilities.wavephysics.balance.dissipation, ocean_science_utilities.wavephysics.balance.factory, ocean_science_utilities.wavephysics.balance.generation, ocean_science_utilities.wavephysics.balance.jb23_tail_stress, ocean_science_utilities.wavephysics.balance.jb23_wind_input, ocean_science_utilities.wavephysics.balance.romero_wave_breaking, ocean_science_utilities.wavephysics.balance.solvers, ocean_science_utilities.wavephysics.balance.source_term, ocean_science_utilities.wavephysics.balance.st4_swell_dissipation, ocean_science_utilities.wavephysics.balance.st4_wave_breaking, ocean_science_utilities.wavephysics.balance.st4_wind_input, ocean_science_utilities.wavephysics.balance.st6_wave_breaking, ocean_science_utilities.wavephysics.balance.st6_wind_input, ocean_science_utilities.wavephysics.balance.stress, ocean_science_utilities.wavephysics.balance.wam_tail_stress, ocean_science_utilities.wavephysics.balance.wind_inversion, ocean_science_utilities.wavephysics.fluidproperties, ocean_science_utilities.wavephysics.roughness, ocean_science_utilities.wavephysics.train_wind_estimate, ocean_science_utilities.wavephysics.windestimate, ocean_science_utilities.wavespectra, ocean_science_utilities.wavespectra.estimators, ocean_science_utilities.wavespectra.estimators.estimate, ocean_science_utilities.wavespectra.estimators.loglikelyhood, ocean_science_utilities.wavespectra.estimators.mem, ocean_science_utilities.wavespectra.estimators.mem2, ocean_science_utilities.wavespectra.estimators.utils, ocean_science_utilities.wavespectra.operations, ocean_science_utilities.wavespectra.parametric, ocean_science_utilities.wavespectra.spectrum, ocean_science_utilities.wavespectra.timeseries, ocean_science_utilities.wavetheory, ocean_science_utilities.wavetheory.constants, ocean_science_utilities.wavetheory.lineardispersion, ocean_science_utilities.wavetheory.linearkinematics, ocean_science_utilities.wavetheory.wavetheory_tools.

lang: en

classoption: oneside geometry: margin=1in papersize: a4

linkcolor: blue links-as-notes: true ...

Namespace `ocean_science_utilities` {#id}

Namespace `ocean_science_utilities.filecache` {#id}

Sub-modules

ocean_science_utilities.filecache.cache_object
ocean_science_utilities.filecache.filecache
ocean_science_utilities.filecache.remote_resources

Module `ocean_science_utilities.filecache.cache_object` {#id}

Contents: Simple file caching routines that automatically cache remote files locally for use.

Authors: Pieter Bart Smit

Classes:

FileCache, main class implementing the Caching structure. Should not directly be invoked. Instead, fetching/cache creation is controlled by a set of function defined below

Functions:

Functions

Function `do_nothing` {#id}

def do_nothing(
    *arg,
    **kwargs
) ‑> Optional[bool]

Null function for convenience.

:param arg: :param kwargs: :return:

Function `parse_directive` {#id}

def parse_directive(
    unparsed_uri: str
) ‑> Tuple[str, dict]

unparsed_uris take the form:

[ directive=option ; ... directive=option ] ":" [scheme] "://" [path]

e.g for amazon s3 where we want to perform validation and post
    processing on entries:

    validate=grib;postprocess=grib:s3://bucket/key

or without cache directives

    s3://bucket/key

This function seperates the directive/option pairs into a directove dictionary, and a valid uri, i.e.

        validate=grib;postprocess=grib:s3://bucket/key

becomes

directive = { "validate":"grib", "postprocess":"grib}
uri = s3://bucket/key

The parsing is really simple.

:param unparsed_uri: uri possibly containing cache directives :return:

Function `parse_directives` {#id}

def parse_directives(
    raw_uris: List[str]
) ‑> Tuple[List[str], List[dict]]

Classes

Class `CacheMiss` {#id}

class CacheMiss(
    uri: str,
    filepath: str,
    filename: str,
    allow_for_missing_files: bool,
    post_process_function: Callable[[str], Optional[bool]],
    download_function: Callable[[str, str], Optional[bool]] = <function do_nothing>
)

Data class for Cache miss.

Class variables

Variable `allow_for_missing_files` {#id}

Type: bool

Variable `filename` {#id}

Type: str

Variable `filepath` {#id}

Type: str

Variable `post_process_function` {#id}

Type: Callable[[str], Optional[bool]]

Variable `uri` {#id}

Type: str

Methods

Method `download_function` {#id}

def download_function(
    *arg,
    **kwargs
) ‑> Optional[bool]

Null function for convenience.

:param arg: :param kwargs: :return:

Class `FileCache` {#id}

class FileCache(
    path: str = '~/temporary_roguewave_files/filecache/',
    size_GB: Union[float, int] = 5,
    do_cache_eviction_on_startup: bool = False,
    resources: Optional[List[ocean_science_utilities.filecache.remote_resources.RemoteResource]] = None,
    parallel: bool = True,
    allow_for_missing_files: bool = True
)

Simple file caching class that when given an URI locally stores the file in the cache directory and returns the path to the file. The file remains in storage until the cache directory exceeds a prescribed size, in which case files with oldest access/modified dates get deleted first until everything fits in the cache again. Any time a file is accessed it's modified date gets updated so that often used files automaticall remain in cache.

The files are stored locally in the directory specified on class initialization, as:

[path]/CACHE_PREFIX + md5_hash_of_URI + CACHE_POSTFIX

The pre- and post fix are added so we have an easy pattern to distinguish cache files from other files.

Methods

getitem(keys) : accept a simgle uri_key or a list of URI's and returns filepaths to local copies thereof. You would typically use the cache[keys] notation instead of the dunder method.
purge() clear all contents of the cache (destructive, deletes all local files).

Usage -----=

cache = FileCache() list_of_local_file_names = cache[ [list of URI's ] ]

do stuff with file

...

Initialize Cache :param path: path to store cache. If path does not exist it will be created. :param size_GB: Maximum size of the cache in GiB. If cache exceeds the size, then files with oldest access/modified dates get deleted until everthing fits in the cache again. Fractional values (floats) are allowed. :param do_cache_eviction_on_startup: whether we ensure the cache size conforms to the given size on startup. If set to true, a cache directory that exceeds the maximum size will be reduced to max size. Set to False by default in which case an error occurs. The latter to prevent eroneously evicting files from a cache that was previously created on purpose with a larger size that the limit.

Class variables

Variable `CACHE_FILE_POSTFIX` {#id}

Variable `CACHE_FILE_PREFIX` {#id}

Methods

Method `get_cache_misses` {#id}

def get_cache_misses(
    self,
    uris: List[str],
    directives: List[Dict[str, str]]
) ‑> List[ocean_science_utilities.filecache.cache_object.CacheMiss]

Function to get all cache misses and return a list of CacheMiss objects needed to download the misses from remote resources.

This function also perform validates on potential cache hits if a relevant validation function is set and validation is requested through a directive.

:param uris: list of uris stripped of directives :param directives: list of directives per uri (empty dict if none) :return: list of cache misses

Method `in_cache` {#id}

def in_cache(
    self,
    unparsed_uris
) ‑> List[bool]

Method `purge` {#id}

def purge(
    self
) ‑> None

Delete all the files in the cache. :return: None

Method `remove` {#id}

def remove(
    self,
    unparsed_uri: str
) ‑> None

Remove an entry from the cache :param unparsed_uri: uri :return: None

Method `remove_directive_function` {#id}

def remove_directive_function(
    self,
    directive: str,
    name: str
)

Method `set_directive_function` {#id}

def set_directive_function(
    self,
    directive,
    name,
    function: Callable[[str], Optional[bool]]
)

Class `FileCacheConfig` {#id}

class FileCacheConfig(
    size_gb: Union[float, int] = 5,
    parallel: bool = True,
    allow_for_missing_files: bool = True,
    path: str = '~/temporary_roguewave_files/filecache/'
)

Instance variables

Variable `allow_for_missing_files` {#id}

Type: bool

Variable `max_size` {#id}

Type: Union[float, int]

Variable `max_size_bytes` {#id}

Type: int

Variable `name` {#id}

Type: str

Variable `parallel` {#id}

Type: bool

Methods

Method `config_exists` {#id}

def config_exists(
    self
) ‑> bool

Method `load_config` {#id}

def load_config(
    self
) ‑> None

Module `ocean_science_utilities.filecache.filecache` {#id}

Contents: Simple file caching routines to interact with a file cache.

Authors: Pieter Bart Smit

Functions:

filepaths(), given URI's return a filepath to the locally stored version
exists(), does a cache with a given name exists
create_cache(), create a cache with a given name and custom properties.
delete_cache(), delete files associated with the cache.
delete_default(), delete files associated with the default cache.
delete_files(), remove entries from a given cache.
_get_cache, get Cache object corresponding to the name (for internal use only)

Functions

Function `create_cache` {#id}

def create_cache(
    cache_name: str,
    cache_path: str = '~/temporary_roguewave_files/filecache/',
    cache_size_GB: Union[float, int] = 5,
    do_cache_eviction_on_startup: bool = False,
    download_in_parallel=True,
    resources: Optional[List[ocean_science_utilities.filecache.remote_resources.RemoteResource]] = None
) ‑> None

Create a file cache. Created caches must have unique names and cache_paths.

:param cache_name: name for the cache to be created. This name is used to retrieve files from the cache. :param cache_path: path to store cache. If path does not exist it will be created. :param cache_size_GB: Maximum size of the cache in GiB. If cache exceeds the size, then files with oldest access/modified dates get deleted until everthing fits in the cache again. Fractional values (floats) are allowed. :param do_cache_eviction_on_startup: do_cache_eviction_on_startup: whether we ensure the cache size conforms to the given size on startup. If set to true, a cache directory that exceeds the maximum size will be reduced to max size. Set to False by default in which case an error occurs. The latter to prevent eroneously evicting files from a cache that was previously created on purpose with a larger size that the limit. :param download_in_parallel: Download in paralel from resource. Per default 10 worker threads are created.

:return:

Function `delete_cache` {#id}

def delete_cache(
    cache_name
)

Delete all files associated with a cache and remove cache from available caches.

To note: all files are deleted, but the folder itself is not.

:param cache_name: Name of the cache to be deleted :return:

Function `delete_default` {#id}

def delete_default()

Clean up the default cache.

:return:

Function `delete_files` {#id}

def delete_files(
    uris: Union[str, Iterable[str]],
    cache_name: Optional[str] = None,
    error_if_not_in_cache: bool = True
) ‑> None

Remove given key(s) from the cache.

:param uris: list of keys to remove :param cache_name: name of initialized cache. :return:

Function `exists` {#id}

def exists(
    cache_name: str
) ‑> bool

Check if the cache name already exists.

:param cache_name: name for the cache to be created. This name is used to retrieve files from the cache. :return: True if exists, False otherwise

Function `filepaths` {#id}

def filepaths(
    uris: Union[List[str], str],
    cache_name: Optional[str] = None
) ‑> Union[List[str], Tuple[List[str], List[bool]]]

Return the full file path to locally stored objects corresponding to the given URI.

:param uris: List of uris, or a single uri :param cache_name: name of the cache to use. If None, a default cache will be initialized automatically (if not initialized) and used. :param return_cache_hits: return whether or not the files were already in cache or downloaded from the remote source (cache hit or miss).

:return: List Absolute paths to the locally stored versions corresponding to the list of URI's. IF return_cache_hits=True, additionally return a list of cache hits as the second entry of the return tuple.

Function `get_cache` {#id}

def get_cache(
    cache_name: Optional[str]
) ‑> ocean_science_utilities.filecache.cache_object.FileCache

Get a valid cache object, error if the name does not exist.

:param cache_name: Name of the cache :return: Cache object

Function `remove_directive_function` {#id}

def remove_directive_function(
    directive: str,
    name: str,
    cache_name=None
) ‑> None

EMPTY Doc String.

:directive: :name: :cache_name:

:return: None

Function `set` {#id}

def set(
    name,
    value,
    cache_name: Optional[str] = None
) ‑> None

Set cache value.

:name: :value: :param cache_name:

:return: None

Function `set_directive_function` {#id}

def set_directive_function(
    directive: str,
    name: str,
    post_process_function: Union[Callable[[str], None], Callable[[str], bool]],
    cache_name=None
) ‑> None

EMPTY Doc String.

:directive: :name: :post_process_function: :cache_name:

:return: None

Module `ocean_science_utilities.filecache.remote_resources` {#id}

Contents: Logic to interact with different type of resources.

Authors: Pieter Bart Smit

Classes:

_RemoteResourceUriNotFound, exception when a URI does not exist on a remote resource.
RemoteResource, abstract base class defining a remote resource (s3,http etc)
RemoteResourceS3, class that implements logic to fetch files from s3
RemoteResourceHTTPS, class that implements logic to fetch files using https

Classes

Class `RemoteResource` {#id}

class RemoteResource

Abstract class defining the resource protocol used for remote retrieval. It contains just two methods that need to be implemented:

download return a function that can download from the resource given a uri and filepath
method to check if the uri is a valid uri for the given resource.

Descendants

ocean_science_utilities.filecache.remote_resources.RemoteResourceHTTPS
ocean_science_utilities.filecache.remote_resources.RemoteResourceLocal

Class variables

Variable `URI_PREFIX` {#id}

Methods

Method `download` {#id}

def download(
    self
) ‑> Callable[[str, str], bool]

Return a function that takes uri (first argument) and filepath (second argument), and downloads the given uri to the given filepath. Return True on Success. Raise _RemoteResourceUriNotFound if URI does not exist on the resource.

Method `valid_uri` {#id}

def valid_uri(
    self,
    uri: str
) ‑> bool

Check if the uri is valid for the given resource :param uri: Uniform Resource Identifier. :return: True or False

Class `RemoteResourceHTTPS` {#id}

class RemoteResourceHTTPS

Abstract class defining the resource protocol used for remote retrieval. It contains just two methods that need to be implemented:

download return a function that can download from the resource given a uri and filepath
method to check if the uri is a valid uri for the given resource.

Ancestors (in MRO)

ocean_science_utilities.filecache.remote_resources.RemoteResource

Class variables

Variable `URI_PREFIX` {#id}

Class `RemoteResourceLocal` {#id}

class RemoteResourceLocal

Abstract class defining the resource protocol used for remote retrieval. It contains just two methods that need to be implemented:

download return a function that can download from the resource given a uri and filepath
method to check if the uri is a valid uri for the given resource.

Ancestors (in MRO)

ocean_science_utilities.filecache.remote_resources.RemoteResource

Class variables

Variable `URI_PREFIX` {#id}

Namespace `ocean_science_utilities.interpolate` {#id}

Sub-modules

ocean_science_utilities.interpolate.dataarray
ocean_science_utilities.interpolate.dataframe
ocean_science_utilities.interpolate.dataset
ocean_science_utilities.interpolate.general
ocean_science_utilities.interpolate.geometry
ocean_science_utilities.interpolate.nd_interp
ocean_science_utilities.interpolate.spline

Module `ocean_science_utilities.interpolate.dataarray` {#id}

Functions

Function `interpolate_track_data_arrray` {#id}

def interpolate_track_data_arrray(
    data_array: xarray.core.dataarray.DataArray,
    tracks: Dict[str, numpy.ndarray],
    independent_variable: Optional[str] = None,
    periodic_coordinates: Optional[Dict[str, float]] = None,
    period_data: Optional[float] = None,
    discont: Optional[float] = None
) ‑> xarray.core.dataarray.DataArray

Interpolate a data array from a dataset at given points in N-dimensions.

The interpolation function takes care of the following edge cases not covered by standard xarray interpolation:

Interpolation along cyclic dimensions (e.g. Longitude interpolating across prime- or anti-meridian)
Interpolation of cyclic data. E.g. directions.
Interpolation near non-existing values (e.g. NaN values representing land).

When these are covered by standard xarray interpolation we should definitely switch.

:param data_array: xarray data array.

:param _points: dictionary with data_array coordinate names as keys and a np array with N entries. With coordiantes lat/lon: { lat: [ lat0, lat1 ,lat2, .., 10] lon: [ [lon0 ,lon1,lon2, .., lonN] time: [t0,t1,t2, ... tN] } where the points we are interolating are formed by the tuples [ (t[0],lat[0],lon[0]), .... (t[1],lat[N],lon[N]), ]

:param independent_variable: coordinate that is used to parametrize the points, usually time. This variable is used as the output coordinate for the returned data array. If None and 'time' is a valid coordinate 'time' is used, otherwise it defaults to whatever the first returned coordinate is from data_array.dims

:param periodic_coordinates: Dictonary that contains as keys the coordinate names of cyclic coordinates, and as value the cyclic length of the coordinate.

:param period_data: Cyclic length of the data. If data is not cyclic this is set to None (default).

:param fractional_cyclic_range: range of the cyclic data expressed as a fraciton of the cyclic lenght. E.g for angles in [-pi,pi] with cyclic length 2*pi we would give [-0.5,0.5]. Defaults to [0,1].

:return: A data array of interpolated values with as coordinates the specified independent coordinate (usually time).

Module `ocean_science_utilities.interpolate.dataframe` {#id}

Functions

Function `interpolate_dataframe_time` {#id}

def interpolate_dataframe_time(
    dataframe: pandas.core.frame.DataFrame,
    new_time: numpy.ndarray
) ‑> pandas.core.frame.DataFrame

A function to interpolate data in a dataframe. We need this function to be able to interpolate wrapped variables (e.g.longitudes and directions).

Module `ocean_science_utilities.interpolate.dataset` {#id}

Functions

Function `interpolate_at_points` {#id}

def interpolate_at_points(
    data_set: xarray.core.dataset.Dataset,
    points: Dict[str, numpy.ndarray],
    independent_variable: Optional[str] = None,
    periodic_coordinates: Optional[Dict[str, float]] = None,
    periodic_data: Optional[Dict[Hashable, Tuple[float, float]]] = None
) ‑> xarray.core.dataset.Dataset

Function `interpolate_dataset` {#id}

def interpolate_dataset(
    data_set: xarray.core.dataset.Dataset,
    geometry: Union[ocean_science_utilities.interpolate.geometry._Geometry, Sequence[numpy.ndarray], Sequence[Sequence], Sequence[numbers.Number], Mapping],
    periodic_coordinates: Optional[Dict[str, float]] = None,
    periodic_data: Optional[Dict[Hashable, Tuple[float, float]]] = None,
    time_variable_in_dataset: str = 'time',
    longitude_variable_in_dataset: str = 'longitude',
    latitude_variable_in_dataset: str = 'latitude'
) ‑> Dict[str, pandas.core.frame.DataFrame]

Function `interpolate_dataset_along_axis` {#id}

def interpolate_dataset_along_axis(
    coordinate_value: Union[xarray.core.dataarray.DataArray, numpy.ndarray],
    data_set: xarray.core.dataset.Dataset,
    coordinate_name: str = 'time',
    periodic_data: Optional[Mapping[Hashable, Tuple[int, int]]] = None,
    periodic_coordinates: Optional[Dict] = None,
    nearest_neighbour=False
) ‑> xarray.core.dataset.Dataset

Function `interpolate_dataset_grid` {#id}

def interpolate_dataset_grid(
    coordinates: Dict[str, Union[xarray.core.dataarray.DataArray, numpy.ndarray]],
    data_set: xarray.core.dataset.Dataset,
    periodic_data: Optional[Mapping[Hashable, Tuple[int, int]]] = None,
    longitude_variable_in_dataset: str = 'longitude',
    nearest_neighbour: bool = False
) ‑> Optional[xarray.core.dataset.Dataset]

Function `tracks_as_dataset` {#id}

def tracks_as_dataset(
    time,
    drifter_tracks: Mapping[Hashable, pandas.core.frame.DataFrame]
) ‑> xarray.core.dataarray.DataArray

Module `ocean_science_utilities.interpolate.general` {#id}

Functions

Function `interpolate_periodic` {#id}

def interpolate_periodic(
    xp: numpy.ndarray,
    fp: numpy.ndarray,
    x: numpy.ndarray,
    x_period: Optional[float] = None,
    fp_period: Optional[float] = None,
    fp_discont: Optional[float] = None,
    left: float = nan,
    right: float = nan
) ‑> numpy.ndarray

Interpolation function that works with periodic domains and periodic ranges :param xp: :param fp: :param x: :param x_period: :param fp_period: :param fp_discont: :return:

Function `interpolation_weights_1d` {#id}

def interpolation_weights_1d(
    xp: numpy.ndarray,
    x: numpy.ndarray,
    indices: numpy.ndarray,
    period: Optional[float] = None,
    extrapolate_left: bool = True,
    extrapolate_right: bool = True,
    nearest_neighbour: bool = False
) ‑> numpy.ndarray

Find the weights for the linear interpolation problem given a set of indices such that:

        xp[indices[0,:]] <= x[:] < xp[indices[1,:]]

Indices are assumed to be as returned by "enclosing_points_1d" (see roguewave.tools.grid).

Returns weights (nx,2) to perform the one-dimensional piecewise linear interpolation to a function given at discrete datapoints xp and evaluated at x. Say that at all xp we have for the function values fp, the interpolation would then be

f = fp[ Indices[1,:] ]  *  weights[1,:] +
    fp[ Indices[2,:] ]  *  weights[2,:]

:param xp: :param x: :param indices: :param period: :return:

Module `ocean_science_utilities.interpolate.geometry` {#id}

Functions

Function `convert_to_cluster_stack` {#id}

def convert_to_cluster_stack(
    geometry: Union[ocean_science_utilities.interpolate.geometry._Geometry, Sequence[numpy.ndarray], Sequence[Sequence], Sequence[numbers.Number], Mapping],
    time: numpy.ndarray
) ‑> ocean_science_utilities.interpolate.geometry.ClusterStack

Function `convert_to_track_set` {#id}

def convert_to_track_set(
    geometry: Union[ocean_science_utilities.interpolate.geometry._Geometry, Sequence[numpy.ndarray], Sequence[Sequence], Sequence[numbers.Number], Mapping],
    time: numpy.ndarray
) ‑> ocean_science_utilities.interpolate.geometry.TrackSet

Classes

Class `Cluster` {#id}

class Cluster(
    points: Mapping[str, ocean_science_utilities.interpolate.geometry.SpatialPoint]
)

A cluster is a set of points, each identified by unique id.

Ancestors (in MRO)

ocean_science_utilities.interpolate.geometry._Geometry

Class variables

Variable `points` {#id}

Type: Mapping[str, ocean_science_utilities.interpolate.geometry.SpatialPoint]

Instance variables

Variable `ids` {#id}

Type: Sequence[str]

Variable `latitude` {#id}

Type: numpy.ndarray

Variable `longitude` {#id}

Type: numpy.ndarray

Static methods

`Method from_lat_lon_arrays` {#id}

def from_lat_lon_arrays(
    lats: List[float],
    lons: List[float]
)

Class `ClusterStack` {#id}

class ClusterStack(
    time: numpy.ndarray,
    clusters: Sequence[ocean_science_utilities.interpolate.geometry.Cluster]
)

A cluster timestack is a stack of clusters in time, e.g. a cluster of spotters as it evolves in time.

Ancestors (in MRO)

ocean_science_utilities.interpolate.geometry._Geometry

Class variables

Variable `clusters` {#id}

Type: Sequence[ocean_science_utilities.interpolate.geometry.Cluster]

Variable `time` {#id}

Type: numpy.ndarray

Static methods

`Method from_track_set` {#id}

def from_track_set(
    track_set: TrackSet,
    time
)

Methods

Method `as_track_set` {#id}

def as_track_set(
    self
) ‑> ocean_science_utilities.interpolate.geometry.TrackSet

Class `SpaceTimePoint` {#id}

class SpaceTimePoint(
    latitude: float,
    longitude: float,
    id: str,
    time: datetime.datetime
)

SpaceTimePoint(latitude: float, longitude: float, id: str, time: datetime.datetime)

Ancestors (in MRO)

ocean_science_utilities.interpolate.geometry.SpatialPoint
ocean_science_utilities.interpolate.geometry._Geometry

Class variables

Variable `time` {#id}

Type: datetime.datetime

Static methods

`Method from_spatial_point` {#id}

def from_spatial_point(
    point: ocean_science_utilities.interpolate.geometry.SpatialPoint,
    time: datetime.datetime
)

Class `SpatialPoint` {#id}

class SpatialPoint(
    latitude: float,
    longitude: float,
    id: str
)

SpatialPoint(latitude: float, longitude: float, id: str)

Ancestors (in MRO)

ocean_science_utilities.interpolate.geometry._Geometry

Descendants

ocean_science_utilities.interpolate.geometry.SpaceTimePoint

Class variables

Variable `id` {#id}

Type: str

Variable `latitude` {#id}

Type: float

Variable `longitude` {#id}

Type: float

Instance variables

Variable `is_valid` {#id}

Type: bool

Class `Track` {#id}

class Track(
    points: List[ocean_science_utilities.interpolate.geometry.SpaceTimePoint],
    id
)

A track is the drift track of a single buoy in time

Ancestors (in MRO)

ocean_science_utilities.interpolate.geometry._Geometry

Instance variables

Variable `latitude` {#id}

Type: numpy.ndarray

Variable `longitude` {#id}

Type: numpy.ndarray

Variable `time` {#id}

Type: numpy.ndarray

Static methods

`Method from_arrays` {#id}

def from_arrays(
    latitude,
    longitude,
    time,
    id
) ‑> ocean_science_utilities.interpolate.geometry.Track

`Method from_spotter` {#id}

def from_spotter(
    spotter_id,
    spotter
)

Methods

Method `interpolate` {#id}

def interpolate(
    self,
    target_time
) ‑> ocean_science_utilities.interpolate.geometry.Track

Class `TrackSet` {#id}

class TrackSet(
    tracks: Mapping[str, ocean_science_utilities.interpolate.geometry.Track]
)

A collection of tracks is a set of tracks for multiple buoys.

Ancestors (in MRO)

ocean_science_utilities.interpolate.geometry._Geometry

Class variables

Variable `tracks` {#id}

Type: Mapping[str, ocean_science_utilities.interpolate.geometry.Track]

Static methods

`Method from_cluster` {#id}

def from_cluster(
    cluster: ocean_science_utilities.interpolate.geometry.Cluster,
    time: numpy.ndarray
) ‑> ocean_science_utilities.interpolate.geometry.TrackSet

`Method from_clusters` {#id}

def from_clusters(
    cluster_time_stack: ClusterStack
)

`Method from_spotters` {#id}

def from_spotters(
    spotters: Mapping
)

Methods

Method `as_cluster_time_stack` {#id}

def as_cluster_time_stack(
    self,
    time
)

Method `interpolate` {#id}

def interpolate(
    self,
    time
) ‑> ocean_science_utilities.interpolate.geometry.TrackSet

Module `ocean_science_utilities.interpolate.nd_interp` {#id}

Classes

Class `NdInterpolator` {#id}

class NdInterpolator(
    get_data: Callable[[List[numpy.ndarray], List[int]], numpy.ndarray],
    data_coordinates: Sequence[Tuple[str, numpy.ndarray[Any, Any]]],
    data_shape: Tuple[int, ...],
    interp_coord_names: List[str],
    interp_index_coord_name: str,
    data_periodic_coordinates: Dict[str, float],
    data_period: Optional[float] = None,
    data_discont: Optional[float] = None,
    nearest_neighbour: bool = False
)

Instance variables

Variable `data_is_periodic` {#id}

Type: bool

Variable `data_ndims` {#id}

Type: int

Variable `interp_coord_dim_indices` {#id}

Type: List[int]

Variable `interp_index_coord_index` {#id}

Type: int

Variable `interp_ndims` {#id}

Type: int

Variable `interpolating_coordinates` {#id}

Type: List[Tuple[str, numpy.ndarray]]

Variable `output_index_coord_index` {#id}

Type: int

Variable `output_ndims` {#id}

Type: int

Variable `output_passive_coord_dim_indices` {#id}

Type: Tuple[int, ...]

Variable `passive_coord_dim_indices` {#id}

Type: List[int]

Variable `passive_coordinate_names` {#id}

Type: List[str]

Methods

Method `coordinate_period` {#id}

def coordinate_period(
    self,
    coordinate_name: str
) ‑> Optional[float]

Method `interpolate` {#id}

def interpolate(
    self,
    points: Dict[str, numpy.ndarray]
) ‑> numpy.ndarray

:param self: :param points:

:return:

Method `output_indexing_broadcast` {#id}

def output_indexing_broadcast(
    self,
    slicer: slice
) ‑> Tuple[Any, ...]

Method `output_indexing_full` {#id}

def output_indexing_full(
    self,
    slicer: slice
) ‑> Tuple[slice, ...]

Method `output_shape` {#id}

def output_shape(
    self,
    number_of_points: int
) ‑> numpy.ndarray

Module `ocean_science_utilities.interpolate.spline` {#id}

Contents: Routines to generate a (monotone) cubic spline interpolation for 1D arrays.

Authors: Pieter Bart Smit

Functions:

cubic_spline(), method to create a (monotone) cubic spline

Functions

Function `cubic_spline` {#id}

def cubic_spline(
    x: numpy.ndarray,
    y: numpy.ndarray,
    monotone_interpolation: bool = False,
    frequency_axis=-1
) ‑> scipy.interpolate._cubic.CubicSpline

Construct a cubic spline, optionally monotone.

:param x: array_like, shape (n,) 1-D array containing values of the independent variable. Values must be real, finite and in strictly increasing order. :param y: array_like, shape (...,n) set of m 1-D arrays containing values of the dependent variable. Y can have an arbitrary set of leading dimensions, but the last dimension has the be equal in size to X. Values must be real, finite and in strictly increasing order along the last dimension. (Y is assumed monotone).

:param monotone_interpolation: :return:

Function `monotone_cubic_spline_coeficients` {#id}

def monotone_cubic_spline_coeficients(
    x: numpy.ndarray,
    Y: numpy.ndarray
) ‑> numpy.ndarray

Construct the spline coeficients. :param x: array_like, shape (n,) 1-D array containing values of the independent variable. Values must be real, finite and in strictly increasing order. :param Y: array_like, shape (m,n) set of m 1-D arrays containing values of the dependent variable. For each of the m rows an independent spline will be constructed. Values must be real, finite and in strictly increasing order. (Y is assumed monotone). :param monotone: :return:

Module `ocean_science_utilities.tool_log` {#id}

Functions

Function `set_level` {#id}

def set_level(
    level: int
) ‑> None

Function `set_log_to_console` {#id}

def set_log_to_console(
    level: int = 20
) ‑> None

Function `set_log_to_file` {#id}

def set_log_to_file(
    filename: str,
    level: int = 20
) ‑> None

Namespace `ocean_science_utilities.tools` {#id}

Sub-modules

ocean_science_utilities.tools.grid
ocean_science_utilities.tools.math
ocean_science_utilities.tools.solvers
ocean_science_utilities.tools.time
ocean_science_utilities.tools.time_integration

Module `ocean_science_utilities.tools.grid` {#id}

Functions

Function `enclosing_points_1d` {#id}

def enclosing_points_1d(
    xp: numpy.ndarray,
    x: numpy.ndarray,
    regular_xp: bool = False,
    period: Optional[float] = None
) ‑> numpy.ndarray

Find surrounding indices for value x[j] in vector xp such that xp[i-1] <= x[j] < xp[i]

To note for non-periodic sequences values outside of xp require special attention- specifically: for x < xp[0]: we have x[x<xp[0]] < xp[indices[1,:]], and indices[0,:] is undefined (clipped to 0).

for x >= xp[-1]:
    we have x[x>=xp[-1]] >= xp[indices[0,:]], and indices[1,:] is
    undefined (clipped to nx).

Parameters

:param x: 1-D array_like of length nx The x-coordinates at which to evaluate the interpolated values with nx entries.

:param xp: 1-D sequence of floats The x-coordinates of the data points with nxp entries.

:return: [2 by nx] np array of integer (dtype='int64') indices such that xp[indices[0,:]] <= x[:] < xp[indices[1,:]] with the exception of points x outside of the domain of xp.

Function `midpoint_rule_step` {#id}

def midpoint_rule_step(
    frequency: numpy.ndarray
) ‑> numpy.ndarray

Module `ocean_science_utilities.tools.math` {#id}

Functions

Function `wrapped_difference` {#id}

def wrapped_difference(
    delta: numpy.ndarray,
    period=6.283185307179586,
    discont=None
) ‑> numpy.ndarray

Calculate the wrapped difference for a given delta for a periodic variable. E.g. if the difference between two angles measured in degrees is 359 we map this to -1.

Per default the output range is set to [-1/2, 1/2] * period so that the discontinuous wrapping point is set to 1/2 * period. If desired the discontinuity can be mapped anywhere in the 0 to period domain, such that the output will be restricted to [discontinuity - period, discontinuity].

:param delta: periodic variable to map to output domain. :param period: period :param discont: location of the discontinuity (if None, set to period/2) :return: delta in the desired periodic domain.

Module `ocean_science_utilities.tools.solvers` {#id}

Functions

Function `fixed_point_iteration` {#id}

def fixed_point_iteration(
    function: Callable[[~_T], ~_T],
    guess: ~_T,
    bounds=(-inf, inf),
    configuration: Optional[ocean_science_utilities.tools.solvers.Configuration] = None,
    caller: Optional[str] = None
) ‑> ~_T

Fixed point iteration on a vector function. We want to solve the parallal problem x=F(x) where x is a vector. Instead of looping over each problem and solving them individualy using e.g. scipy solvers, we gain some efficiency by evaluating F in parallel, and doing the iteration ourselves. Only worthwhile if F is the expensive part and/or x is large.

:param function: :param guess: :param max_iter: :param atol: :param rtol: :param caller: :return:

Classes

Class `Configuration` {#id}

class Configuration(
    atol: float = 0.0001,
    rtol: float = 0.0001,
    max_iter: int = 100,
    aitken_acceleration: bool = True,
    fraction_of_points: float = 1,
    error_if_not_converged: bool = False,
    numerical_derivative_stepsize: float = 0.0001,
    use_numba: bool = True
)

Configuration(atol: float = 0.0001, rtol: float = 0.0001, max_iter: int = 100, aitken_acceleration: bool = True, fraction_of_points: float = 1, error_if_not_converged: bool = False, numerical_derivative_stepsize: float = 0.0001, use_numba: bool = True)

Class variables

Variable `aitken_acceleration` {#id}

Type: bool

Variable `atol` {#id}

Type: float

Variable `error_if_not_converged` {#id}

Type: bool

Variable `fraction_of_points` {#id}

Type: float

Variable `max_iter` {#id}

Type: int

Variable `numerical_derivative_stepsize` {#id}

Type: float

Variable `rtol` {#id}

Type: float

Variable `use_numba` {#id}

Type: bool

Module `ocean_science_utilities.tools.time` {#id}

Authors: Pieter Bart Smit

Functions

Function `date_from_dateint` {#id}

def date_from_dateint(
    t: int
) ‑> datetime.datetime

unpack a datetime from a date given as an integer in the form "yyyymmdd" or "yymmdd" e.g. 20221109 for 2022-11-09 or 221109 for 2022-11-09

Function `datetime64_to_timestamp` {#id}

def datetime64_to_timestamp(
    time: Sequence[numpy.datetime64]
) ‑> Sequence[numpy.datetime64]

Function `datetime_from_time_and_date_integers` {#id}

def datetime_from_time_and_date_integers(
    date_int: int,
    time_int: int,
    as_datetime64=False
) ‑> Union[datetime.datetime, ForwardRef(None), numpy.datetime64, numpy.ndarray[Any, numpy.dtype[numpy.datetime64]]]

Convert a date and time given as integed encoded in the form "yyyymmdd" and "hhmm" or "hhmmss" to a datetime :param date_int: integer of the form yyyymmdd :param time_int: time of the form "hhmm" or "hhmmss" :return:

Function `datetime_to_iso_time_string` {#id}

def datetime_to_iso_time_string(
    time: Union[str, float, int, datetime.datetime, numpy.datetime64, Sequence[Union[str, float, int, datetime.datetime, numpy.datetime64]], ForwardRef(None)]
) ‑> Optional[str]

Function `time_from_timeint` {#id}

def time_from_timeint(
    t: int
) ‑> datetime.timedelta

unpack a timedelta from a time given as an integer in the form "hhmmss" e.g. 201813 for 20:18:13

Function `to_datetime64` {#id}

def to_datetime64(
    time
) ‑> Union[ForwardRef(None), numpy.datetime64, numpy.ndarray[Any, numpy.dtype[numpy.datetime64]]]

Convert time input to numpy np.ndarrays. :param time: :return:

Function `to_datetime_utc` {#id}

def to_datetime_utc(
    time: Union[str, float, int, datetime.datetime, numpy.datetime64, Sequence[Union[str, float, int, datetime.datetime, numpy.datetime64]]]
) ‑> Union[datetime.datetime, Sequence[datetime.datetime], ForwardRef(None)]

Output datetimes are garantueed to be in the UTC timezone. For timezone naive input the timezone is assumed to be UTC. None as input is translated to None as output to allow for cases where time is optional. Note that the implementation works with heterogeneous sequences.

:param time: Time, is either a valid scalar time type or a sequence of time types. :return: If the input is a sequence, the output is a sequence of datetimes, otherwise it is a scalar datetime.

Module `ocean_science_utilities.tools.time_integration` {#id}

Functions

Function `complex_response` {#id}

def complex_response(
    normalized_frequency: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    order: int,
    number_of_implicit_points: int = 1
) ‑> numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]]

The frequency complex response factor of the numerical integration scheme with given order and number of implicit points.

:param normalized_frequency: Frequency normalized with the sampling frequency to calculate response factor at :param order: Order of the returned Newton-Coates integration approximation. :param number_of_implicit_points: number of future points in the integration stencil. :return: complex np.typing.NDArray of same length as the input frequency containing the response factor at the given frequencies

Function `cumulative_distance` {#id}

def cumulative_distance(
    latitudes: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    longitudes: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]]
) ‑> Tuple[numpy.ndarray[Any, numpy.dtype[+ScalarType]], numpy.ndarray[Any, numpy.dtype[+ScalarType]]]

Function `evaluate_polynomial` {#id}

def evaluate_polynomial(
    poly: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    x: int
) ‑> int

Eval a polynomial at location x. :param poly: polynomial coeficients [a_0, a_1, ..., a_[order+1]] :param x: location to evaluate the polynomial/ :return: value of the polynomial at the location

Function `integrate` {#id}

def integrate(
    time: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    signal: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    order=4,
    n=1,
    start_value=0.0
) ‑> numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]]

Cumulatively integrate the given discretely sampled signal in time using a Newton-Coases like formulation of requested order and layout. Note that higher order methods are only used in regions where the timestep is constant across the integration stencil- otherwise we fall back to the trapezoidal rule which can handle variable timesteps. A small amount of jitter (<1%) in timesteps is permitted though (and effectively ignored).

NOTE: by default we start at 0.0 - which in general means that for a zero-mean process we will pick up a random offset that will need to be corracted afterwards. (out is not zero-mean).

:param time: ndarray of length nt containing the elapsed time in seconds. :param signal: ndarray of length nt containing the signal to be integrated :param order: Order of the returned Newton-Coates integration approximation. :param n: number of future points in the integration stencil. :param start_value: Starting value of the integrated signal. :return: NDARRAY of length nt that contains the integrated signal that starts at the requested start_value.

Function `integrated_lagrange_base_polynomial_coef` {#id}

def integrated_lagrange_base_polynomial_coef(
    order: int,
    base_polynomial_index: int
) ‑> numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]]

Calculate the polynomial coefficents of the integrated base polynomial.

:param order: polynomial order of the interated base_polynomial. :param base_polynomial_index: which of the base polynomials to calculate :return: set of polynomial coefficients [ a_0, a_1, ..., a_[order-1], 0 ]

Function `integrated_response_factor_spectral_tail` {#id}

def integrated_response_factor_spectral_tail(
    tail_power: int,
    start_frequency: int,
    end_frequency: int,
    sampling_frequency: int,
    frequency_delta: Optional[int] = None,
    order: int = 4,
    transition_frequency: Optional[int] = None
) ‑> numpy.ndarray

Function `integration_stencil` {#id}

def integration_stencil(
    order: int,
    number_of_implicit_points: int = 1
) ‑> numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]]

Find the Newton-Coastes like- integration stencil given the desired order and the number of "implicit" points. Specicially, let the position z at instance t[j-1] be known, and we wish to approximate z at time t[j], where t[j] - t[j-1] = dt for all j, given the velocities w[j]. This implies we solve

    dz
   ---- = w    ->    z[j] = z[j-1] + dz     with dz = Integral[w] ~ dt * F[w]
    dt

To solve the integral we use Newton-Coates like approximation and express w(t) as a function of points w[j+i], where i = -m-1 ... n-1 using a Lagrange Polynomial. Specifically we consider points in the past and future as we anticipate we can buffer w values in any application.

In this framework the interval of interest lies between j-1, and j (i=0 and 1).

j-m-1  ...  j-2  j-1   j   j+1  ...  j+n-1
  |    |    |    |----|    |    |    |

The number of points used will be refered to ast the order = n+m+1. The number of points with i>=0 will be referred to as the number of implicit points, so tha n = number_of_implicit_points. The number of points i<0 is the number of explicit points m = order - n - 1.

This function calculates the weights such that

dz = weights[0] w[j-m] + ... + weights[m-1] w[j-1] + weights[m] w[j] + ... weights[order-1] w[j+n-1]

:param order: Order of the returned Newton-Coates set of coefficients. :param number_of_implicit_points: number of points for which i>0 :return: Numpy array of length Order with the weights.

Function `lagrange_base_polynomial_coef` {#id}

def lagrange_base_polynomial_coef(
    order: int,
    base_polynomial_index: int
) ‑> numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]]

We consider the interpolation of Y[0] Y[1] ... Y[order] spaced 1 apart at 0, 1,... point_index, ... order in terms of the Lagrange polynomial:

Y[x] = L_0[x] Y[0] + L_1[x] Y[1] + .... L_order[x] Y[order].

Here each of the lagrange polynomial coefficients L_n is expressed as a polynomial in x

L_n = a_0 x**(order-1) + a_1 x**(order-2) + ... a_order

where the coeficients may be found from the standard definition of the base polynomial (e.g. for L_0)

  ( x - x_1) * ... * (x - x_order )         ( x- 1) * (x-2) * ... * (x - order)

L_0 = ------------------------------------ = ------------------------------------- (x_0 -x_1) * .... * (x_0 - x_order) -1 * -2 * .... * -order

where the right hand side follows after substituting x_n = n (i.e. 1 spacing). This function returns the set of coefficients [ a_0, a_1, ..., a_order ].

:param order: order of the base polynomials. :param base_polynomial_index: which of the base polynomials to calculate :return: set of polynomial coefficients [ a_0, a_1, ..., a_order ]

Namespace `ocean_science_utilities.wavephysics` {#id}

Sub-modules

ocean_science_utilities.wavephysics.balance
ocean_science_utilities.wavephysics.fluidproperties
ocean_science_utilities.wavephysics.roughness
ocean_science_utilities.wavephysics.train_wind_estimate
ocean_science_utilities.wavephysics.windestimate

Namespace `ocean_science_utilities.wavephysics.balance` {#id}

Sub-modules

ocean_science_utilities.wavephysics.balance.balance
ocean_science_utilities.wavephysics.balance.dissipation
ocean_science_utilities.wavephysics.balance.factory
ocean_science_utilities.wavephysics.balance.generation
ocean_science_utilities.wavephysics.balance.jb23_tail_stress
ocean_science_utilities.wavephysics.balance.jb23_wind_input
ocean_science_utilities.wavephysics.balance.romero_wave_breaking
ocean_science_utilities.wavephysics.balance.solvers
ocean_science_utilities.wavephysics.balance.source_term
ocean_science_utilities.wavephysics.balance.st4_swell_dissipation
ocean_science_utilities.wavephysics.balance.st4_wave_breaking
ocean_science_utilities.wavephysics.balance.st4_wind_input
ocean_science_utilities.wavephysics.balance.st6_wave_breaking
ocean_science_utilities.wavephysics.balance.st6_wind_input
ocean_science_utilities.wavephysics.balance.stress
ocean_science_utilities.wavephysics.balance.wam_tail_stress
ocean_science_utilities.wavephysics.balance.wind_inversion

Module `ocean_science_utilities.wavephysics.balance.balance` {#id}

Classes

Class `SourceTermBalance` {#id}

class SourceTermBalance(
    generation: ocean_science_utilities.wavephysics.balance.generation.WindGeneration,
    disspipation: ocean_science_utilities.wavephysics.balance.dissipation.Dissipation
)

Instance variables

Variable `get_parameters` {#id}

Type: Dict

Methods

Method `evaluate_bulk_imbalance` {#id}

def evaluate_bulk_imbalance(
    self,
    wind_speed: xarray.core.dataarray.DataArray,
    wind_direction: xarray.core.dataarray.DataArray,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum,
    time_derivative_spectrum: Optional[ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum] = None
) ‑> xarray.core.dataarray.DataArray

Method `evaluate_imbalance` {#id}

def evaluate_imbalance(
    self,
    wind_speed: xarray.core.dataarray.DataArray,
    wind_direction: xarray.core.dataarray.DataArray,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum,
    time_derivative_spectrum: Optional[ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum] = None
) ‑> xarray.core.dataarray.DataArray

Method `update_parameters` {#id}

def update_parameters(
    self,
    parameters: Mapping
)

Module `ocean_science_utilities.wavephysics.balance.dissipation` {#id}

Classes

Class `Dissipation` {#id}

class Dissipation(
    parameters
)

Helper class that provides a standard way to create an ABC using inheritance.

Ancestors (in MRO)

ocean_science_utilities.wavephysics.balance.source_term.SourceTerm
abc.ABC

Descendants

ocean_science_utilities.wavephysics.balance.romero_wave_breaking.RomeroWaveBreaking
ocean_science_utilities.wavephysics.balance.st4_wave_breaking.ST4WaveBreaking
ocean_science_utilities.wavephysics.balance.st6_wave_breaking.ST6WaveBreaking

Class variables

Variable `name` {#id}

Methods

Method `bulk_rate` {#id}

def bulk_rate(
    self,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum
) ‑> xarray.core.dataarray.DataArray

Method `mean_direction_degrees` {#id}

def mean_direction_degrees(
    self,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum
)

Method `rate` {#id}

def rate(
    self,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum
) ‑> xarray.core.dataarray.DataArray

Method `update_parameters` {#id}

def update_parameters(
    self,
    parameters: Mapping
)

Module `ocean_science_utilities.wavephysics.balance.factory` {#id}

Functions

Function `create_balance` {#id}

def create_balance(
    generation_par: Literal['st6', 'st4', 'jb23'] = 'st4',
    dissipation_par: Literal['st6', 'st4', 'romero'] = 'st4',
    generation_args: Dict = {},
    dissipation_args: Dict = {}
) ‑> ocean_science_utilities.wavephysics.balance.balance.SourceTermBalance

Function `create_breaking_dissipation` {#id}

def create_breaking_dissipation(
    breaking_parametrization: Literal['st6', 'st4', 'romero'] = 'st6',
    **kwargs
) ‑> ocean_science_utilities.wavephysics.balance.dissipation.Dissipation

Function `create_wind_source_term` {#id}

def create_wind_source_term(
    wind_parametrization: Literal['st6', 'st4', 'jb23'] = 'st4',
    **kwargs
)

Module `ocean_science_utilities.wavephysics.balance.generation` {#id}

Classes

Class `WindGeneration` {#id}

class WindGeneration(
    parmaters
)

Helper class that provides a standard way to create an ABC using inheritance.

Ancestors (in MRO)

ocean_science_utilities.wavephysics.balance.source_term.SourceTerm
abc.ABC

Descendants

ocean_science_utilities.wavephysics.balance.st4_swell_dissipation.SwellDissipation
ocean_science_utilities.wavephysics.balance.st4_wind_input.ST4WindInput
ocean_science_utilities.wavephysics.balance.st6_wind_input.ST6WindInput

Class variables

Variable `name` {#id}

Methods

Method `bulk_rate` {#id}

def bulk_rate(
    self,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum,
    speed: xarray.core.dataarray.DataArray,
    direction: xarray.core.dataarray.DataArray,
    roughness_length: Optional[xarray.core.dataarray.DataArray] = None,
    wind_speed_input_type: Literal['u10', 'friction_velocity', 'ustar'] = 'u10'
) ‑> xarray.core.dataarray.DataArray

Method `drag` {#id}

def drag(
    self,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum,
    speed: xarray.core.dataarray.DataArray,
    direction: xarray.core.dataarray.DataArray,
    roughness_length: Optional[xarray.core.dataarray.DataArray] = None,
    wind_speed_input_type: Literal['u10', 'friction_velocity', 'ustar'] = 'u10'
)

Method `friction_velocity` {#id}

def friction_velocity(
    self,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum,
    u10: xarray.core.dataarray.DataArray,
    direction: xarray.core.dataarray.DataArray,
    roughness_length: Optional[xarray.core.dataarray.DataArray] = None
) ‑> xarray.core.dataarray.DataArray

Method `rate` {#id}

def rate(
    self,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum,
    speed: xarray.core.dataarray.DataArray,
    direction: xarray.core.dataarray.DataArray,
    roughness_length: Optional[xarray.core.dataarray.DataArray] = None,
    wind_speed_input_type: Literal['u10', 'friction_velocity', 'ustar'] = 'u10',
    **kwargs
) ‑> xarray.core.dataarray.DataArray

Method `roughness` {#id}

def roughness(
    self,
    speed: xarray.core.dataarray.DataArray,
    direction: xarray.core.dataarray.DataArray,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum,
    roughness_length_guess: Optional[xarray.core.dataarray.DataArray] = None,
    wind_speed_input_type: Literal['u10', 'friction_velocity', 'ustar'] = 'u10'
) ‑> xarray.core.dataarray.DataArray

Method `stress` {#id}

def stress(
    self,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum,
    speed: xarray.core.dataarray.DataArray,
    direction: xarray.core.dataarray.DataArray,
    roughness_length: Optional[xarray.core.dataarray.DataArray] = None,
    wind_speed_input_type: Literal['u10', 'friction_velocity', 'ustar'] = 'u10'
) ‑> xarray.core.dataset.Dataset

Method `tail_stress` {#id}

def tail_stress(
    self,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum,
    speed: xarray.core.dataarray.DataArray,
    direction: xarray.core.dataarray.DataArray,
    roughness_length: Optional[xarray.core.dataarray.DataArray] = None,
    wind_speed_input_type: Literal['u10', 'friction_velocity', 'ustar'] = 'u10'
) ‑> xarray.core.dataset.Dataset

Method `update_parameters` {#id}

def update_parameters(
    self,
    parameters: Mapping
)

Module `ocean_science_utilities.wavephysics.balance.jb23_tail_stress` {#id}

Functions

Function `celerity` {#id}

def celerity(
    wavenumber,
    gravitational_acceleration,
    surface_tension
)

Function `dispersion` {#id}

def dispersion(
    wavenumber,
    gravitational_acceleration,
    surface_tension
)

Function `group_velocity` {#id}

def group_velocity(
    wavenumber,
    gravitational_acceleration,
    surface_tension
)

Function `log_bounds_wavenumber` {#id}

def log_bounds_wavenumber(
    roughness_length,
    friction_velocity,
    parameters
)

Find the lower bound of the integration domain for JB2022.

:param friction_velocity: :param effective_charnock: :param vonkarman_constant: :param wave_age_tuning_parameter: :param gravitational_acceleration: :return:

Function `miles_mu` {#id}

def miles_mu(
    log_wavenumber,
    roughness_length,
    friction_velocity,
    parameters
)

Function `miles_mu_cutoff` {#id}

def miles_mu_cutoff(
    log_wavenumber,
    roughness_length,
    friction_velocity,
    parameters
)

Function `saturation_spectrum_parametrization` {#id}

def saturation_spectrum_parametrization(
    wavenumbers,
    energy_at_starting_wavenumber,
    starting_wavenumber,
    friction_velocity,
    parameters
)

Saturation spectrum accordin to the VIERS model (adapted from JB2023)

:param wavenumbers: set of wavenumbers :param energy_at_starting_wavenumber: variance density as a function of wavenumber, scaled such that int(e(k) dk = variance. This varies from Peter's work who uses an energy E such that e = E*k with k the wavenumber which originates from a transfer to polar coordinates of the 2d wavenumber spectrum.

:param gravitational_acceleration: gravitational :param surface_tension: :param friction_velocity: :return:

Function `tail_stress_parametrization_jb23` {#id}

def tail_stress_parametrization_jb23(
    variance_density: numpy.ndarray,
    wind: Tuple[numpy.ndarray, numpy.ndarray, str],
    depth: numpy.ndarray,
    roughness_length: numpy.ndarray,
    spectral_grid: Dict[str, numpy.ndarray],
    parameters: Mapping
) ‑> Tuple[Union[float, numpy.ndarray], Union[float, numpy.ndarray]]

Function `three_wave_starting_wavenumber` {#id}

def three_wave_starting_wavenumber(
    friction_velocity,
    parameters
)

Starting wavenumber for the capilary-gravity part. See JB2023, eq 41 and 42. :param gravitational_acceleration: :param surface_tension: :param friction_velocity: :return:

Function `upper_limit_wavenumber_equilibrium_range` {#id}

def upper_limit_wavenumber_equilibrium_range(
    friction_velocity,
    parameters
)

Upper limit eq. range :param gravitational_acceleration: :param surface_tension: :param friction_velocity: :return:

Function `wavenumber_grid` {#id}

def wavenumber_grid(
    starting_wavenumber,
    roughness_length,
    friction_velocity,
    parameters
)

Function `wind_input_tail` {#id}

def wind_input_tail(
    wavenumbers,
    roughness_length,
    friction_velocity,
    tail_spectrum,
    parameters
)

Function `wind_stress_tail` {#id}

def wind_stress_tail(
    wavenumbers,
    roughness_length,
    friction_velocity,
    tail_spectrum,
    parameters
)

Module `ocean_science_utilities.wavephysics.balance.jb23_wind_input` {#id}

Classes

Class `JB23WaveGenerationParameters` {#id}

class JB23WaveGenerationParameters(
    *args,
    **kwargs
)

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

Ancestors (in MRO)

builtins.dict

Class variables

Variable `air_density` {#id}

Type: float

Variable `air_viscosity` {#id}

Type: float

Variable `charnock_constant` {#id}

Type: float

Variable `charnock_maximum_roughness` {#id}

Type: float

Variable `elevation` {#id}

Type: float

Variable `gravitational_acceleration` {#id}

Type: float

Variable `growth_parameter_betamax` {#id}

Type: float

Variable `non_linear_effect_strength` {#id}

Type: float

Variable `surface_tension` {#id}

Type: float

Variable `viscous_stress_parameter` {#id}

Type: float

Variable `vonkarman_constant` {#id}

Type: float

Variable `water_density` {#id}

Type: float

Variable `wave_age_tuning_parameter` {#id}

Type: float

Variable `width_factor` {#id}

Type: float

Class `JB23WindInput` {#id}

class JB23WindInput(
    parameters: Optional[ocean_science_utilities.wavephysics.balance.jb23_wind_input.JB23WaveGenerationParameters] = None
)

Helper class that provides a standard way to create an ABC using inheritance.

Ancestors (in MRO)

ocean_science_utilities.wavephysics.balance.st4_wind_input.ST4WindInput
ocean_science_utilities.wavephysics.balance.generation.WindGeneration
ocean_science_utilities.wavephysics.balance.source_term.SourceTerm
abc.ABC

Class variables

Variable `name` {#id}

Static methods

`Method default_parameters` {#id}

def default_parameters() ‑> ocean_science_utilities.wavephysics.balance.jb23_wind_input.JB23WaveGenerationParameters

Module `ocean_science_utilities.wavephysics.balance.romero_wave_breaking` {#id}

Functions

Function `breaking_probability` {#id}

def breaking_probability(
    directional_saturation,
    wavenumber,
    saturation_threshold,
    breaking_probability_constant,
    number_of_frequencies,
    number_of_directions
)

Function `romero_dissipation_breaking` {#id}

def romero_dissipation_breaking(
    variance_density: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    depth: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    spectral_grid,
    parameters
)

Function `romero_saturation` {#id}

def romero_saturation(
    variance_density: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    group_velocity: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    wavenumber: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    number_of_frequencies: int,
    number_of_directions: int
)

Classes

Class `RomeroWaveBreaking` {#id}

class RomeroWaveBreaking(
    parameters: Optional[ocean_science_utilities.wavephysics.balance.romero_wave_breaking.RomeroWaveBreakingParameters] = None
)

Helper class that provides a standard way to create an ABC using inheritance.

Ancestors (in MRO)

ocean_science_utilities.wavephysics.balance.dissipation.Dissipation
ocean_science_utilities.wavephysics.balance.source_term.SourceTerm
abc.ABC

Class variables

Variable `name` {#id}

Static methods

`Method default_parameters` {#id}

def default_parameters() ‑> ocean_science_utilities.wavephysics.balance.romero_wave_breaking.RomeroWaveBreakingParameters

Class `RomeroWaveBreakingParameters` {#id}

class RomeroWaveBreakingParameters(
    *args,
    **kwargs
)

Ancestors (in MRO)

builtins.dict

Class variables

Variable `breaking_probability_constant` {#id}

Type: float

Variable `gravitational_acceleration` {#id}

Type: float

Variable `saturation_breaking_constant` {#id}

Type: float

Variable `saturation_integrated_threshold` {#id}

Type: float

Variable `saturation_threshold` {#id}

Type: float

Module `ocean_science_utilities.wavephysics.balance.solvers` {#id}

Functions

Function `numba_fixed_point_iteration` {#id}

def numba_fixed_point_iteration(
    function,
    guess,
    args,
    bounds=(-inf, inf)
) ‑> ~_T

:param function: :param guess: :param max_iter: :param atol: :param rtol: :param caller: :return:

Function `numba_newton_raphson` {#id}

def numba_newton_raphson(
    function,
    guess,
    function_arguments,
    hard_bounds=(-inf, inf),
    max_iterations=100,
    aitken_acceleration=True,
    atol=0.0001,
    rtol=0.0001,
    numerical_stepsize=0.0001,
    verbose=False,
    error_on_max_iter=True,
    relative_stepsize=False,
    name='',
    under_relaxation=0.9
)

Module `ocean_science_utilities.wavephysics.balance.source_term` {#id}

Classes

Class `SourceTerm` {#id}

class SourceTerm(
    parameters: Optional[Any]
)

Helper class that provides a standard way to create an ABC using inheritance.

Ancestors (in MRO)

abc.ABC

Descendants

ocean_science_utilities.wavephysics.balance.dissipation.Dissipation
ocean_science_utilities.wavephysics.balance.generation.WindGeneration

Instance variables

Variable `parameters` {#id}

Type: numba.typed.typeddict.Dict

Static methods

`Method default_parameters` {#id}

def default_parameters() ‑> MutableMapping

Methods

Method `spectral_grid` {#id}

def spectral_grid(
    self,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum
) ‑> Dict[str, numpy.ndarray]

Module `ocean_science_utilities.wavephysics.balance.st4_swell_dissipation` {#id}

Functions

Function `st4_crictical_reynolds_number` {#id}

def st4_crictical_reynolds_number(
    swell_dissipation_coefficients: Dict[str, float],
    significant_wave_height: xarray.core.dataarray.DataArray
) ‑> xarray.core.dataarray.DataArray

Function `st4_dissipation_factor_grant_maddsen` {#id}

def st4_dissipation_factor_grant_maddsen(
    roughness: xarray.core.dataarray.DataArray,
    significant_amplitude: xarray.core.dataarray.DataArray,
    swell_dissipation_coefficients: Dict[str, float],
    water: ocean_science_utilities.wavephysics.fluidproperties.FluidProperties = <ocean_science_utilities.wavephysics.fluidproperties.FluidProperties object>
) ‑> xarray.core.dataarray.DataArray

Function `st4_significant_orbital_velocity` {#id}

def st4_significant_orbital_velocity(
    variance_density: xarray.core.dataarray.DataArray,
    radian_frequency: xarray.core.dataarray.DataArray,
    wavenumber: xarray.core.dataarray.DataArray,
    depth: xarray.core.dataarray.DataArray
) ‑> xarray.core.dataarray.DataArray

Function `st4_swell_dissipation` {#id}

def st4_swell_dissipation(
    speed: xarray.core.dataarray.DataArray,
    mutual_angle: xarray.core.dataarray.DataArray,
    variance_density: xarray.core.dataarray.DataArray,
    roughness: xarray.core.dataarray.DataArray,
    significant_amplitude: xarray.core.dataarray.DataArray,
    wave_reynolds_number: xarray.core.dataarray.DataArray,
    critical_reynolds_number: xarray.core.dataarray.DataArray,
    wavenumber: xarray.core.dataarray.DataArray,
    angular_frequency: xarray.core.dataarray.DataArray,
    significant_orbital_velocity: xarray.core.dataarray.DataArray,
    swell_dissipation_coefficients: Dict[str, float],
    gravitational_acceleration: float,
    air: ocean_science_utilities.wavephysics.fluidproperties.FluidProperties = <ocean_science_utilities.wavephysics.fluidproperties.FluidProperties object>,
    water: ocean_science_utilities.wavephysics.fluidproperties.FluidProperties = <ocean_science_utilities.wavephysics.fluidproperties.FluidProperties object>
) ‑> xarray.core.dataarray.DataArray

Function `st4_swell_dissipation_factor` {#id}

def st4_swell_dissipation_factor(
    speed: xarray.core.dataarray.DataArray,
    significant_orbital_velocity: xarray.core.dataarray.DataArray,
    roughness: xarray.core.dataarray.DataArray,
    significant_amplitude: xarray.core.dataarray.DataArray,
    mutual_angle: xarray.core.dataarray.DataArray,
    swell_dissipation_coefficients: Dict[str, float],
    water: ocean_science_utilities.wavephysics.fluidproperties.FluidProperties
) ‑> xarray.core.dataarray.DataArray

Function `st4_wave_reynolds_number` {#id}

def st4_wave_reynolds_number(
    significant_orbital_velocity: xarray.core.dataarray.DataArray,
    significant_amplitude: xarray.core.dataarray.DataArray,
    air: ocean_science_utilities.wavephysics.fluidproperties.FluidProperties = <ocean_science_utilities.wavephysics.fluidproperties.FluidProperties object>
) ‑> xarray.core.dataarray.DataArray

Classes

Class `SwellDissipation` {#id}

class SwellDissipation(
    gravitational_acceleration: float = 9.81,
    swell_dissipation_coefficients: Optional[Dict[str, float]] = None,
    **kwargs
)

Helper class that provides a standard way to create an ABC using inheritance.

Ancestors (in MRO)

ocean_science_utilities.wavephysics.balance.generation.WindGeneration
ocean_science_utilities.wavephysics.balance.source_term.SourceTerm
abc.ABC

Methods

Method `rate` {#id}

def rate(
    self,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum,
    speed: xarray.core.dataarray.DataArray,
    direction: xarray.core.dataarray.DataArray,
    roughness_length: xarray.core.dataarray.DataArray,
    wind_speed_input_type: Literal['u10', 'friction_velocity', 'ustar'] = 'u10',
    air: ocean_science_utilities.wavephysics.fluidproperties.FluidProperties = <ocean_science_utilities.wavephysics.fluidproperties.FluidProperties object>,
    water: ocean_science_utilities.wavephysics.fluidproperties.FluidProperties = <ocean_science_utilities.wavephysics.fluidproperties.FluidProperties object>,
    memoized: Optional[Dict[str, Any]] = None
) ‑> xarray.core.dataarray.DataArray

Method `rate_U10` {#id}

def rate_U10(
    self,
    speed: xarray.core.dataarray.DataArray,
    direction: xarray.core.dataarray.DataArray,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum,
    roughness_length: xarray.core.dataarray.DataArray,
    air: ocean_science_utilities.wavephysics.fluidproperties.FluidProperties = <ocean_science_utilities.wavephysics.fluidproperties.FluidProperties object>,
    water: ocean_science_utilities.wavephysics.fluidproperties.FluidProperties = <ocean_science_utilities.wavephysics.fluidproperties.FluidProperties object>,
    memoized: Optional[Dict[str, Any]] = None
) ‑> xarray.core.dataarray.DataArray

Method `rate_friction_velocity` {#id}

def rate_friction_velocity(
    self,
    speed: xarray.core.dataarray.DataArray,
    direction: xarray.core.dataarray.DataArray,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum,
    roughness_length: xarray.core.dataarray.DataArray,
    air: ocean_science_utilities.wavephysics.fluidproperties.FluidProperties = <ocean_science_utilities.wavephysics.fluidproperties.FluidProperties object>,
    water: ocean_science_utilities.wavephysics.fluidproperties.FluidProperties = <ocean_science_utilities.wavephysics.fluidproperties.FluidProperties object>,
    memoized: Optional[Dict[str, Any]] = None
) ‑> xarray.core.dataarray.DataArray

Module `ocean_science_utilities.wavephysics.balance.st4_wave_breaking` {#id}

Functions

Function `st4_band_integrated_saturation` {#id}

def st4_band_integrated_saturation(
    variance_density: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    group_velocity: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    wavenumber: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    radian_direction: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    direction_step: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    number_of_frequencies: int,
    number_of_directions: int,
    integration_width_degrees: int,
    cosine_power=2
)

Function `st4_cumulative_breaking` {#id}

def st4_cumulative_breaking(
    variance_density: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    saturation: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    radian_frequency: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    group_velocity: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    wave_speed: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    radian_direction: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    direction_step: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    frequency_step: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    saturation_threshold: float,
    cumulative_breaking_constant: float,
    cumulative_breaking_max_relative_frequency: float,
    number_of_frequencies: int,
    number_of_directions: int
)

:param saturation: :param radian_frequency: :param group_velocity: :param wave_speed: :param radian_direction: :param direction_step: :param frequency_step: :param saturation_threshold: :param cumulative_breaking_max_relative_frequency: :param number_of_frequencies: :param number_of_directions: :return:

Function `st4_dissipation_breaking` {#id}

def st4_dissipation_breaking(
    variance_density: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    depth: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    spectral_grid,
    parameters
)

Function `st4_saturation_breaking` {#id}

def st4_saturation_breaking(
    variance_density,
    band_integrated_saturation,
    radian_frequency,
    number_of_frequencies,
    number_of_directions,
    saturation_breaking_constant,
    saturation_breaking_directional_control,
    saturation_threshold
)

Classes

Class `ST4WaveBreaking` {#id}

class ST4WaveBreaking(
    parameters: Optional[ocean_science_utilities.wavephysics.balance.st4_wave_breaking.ST4WaveBreakingParameters] = None
)

Helper class that provides a standard way to create an ABC using inheritance.

Ancestors (in MRO)

ocean_science_utilities.wavephysics.balance.dissipation.Dissipation
ocean_science_utilities.wavephysics.balance.source_term.SourceTerm
abc.ABC

Class variables

Variable `name` {#id}

Static methods

`Method default_parameters` {#id}

def default_parameters() ‑> ocean_science_utilities.wavephysics.balance.st4_wave_breaking.ST4WaveBreakingParameters

Class `ST4WaveBreakingParameters` {#id}

class ST4WaveBreakingParameters(
    *args,
    **kwargs
)

Ancestors (in MRO)

builtins.dict

Class variables

Variable `cumulative_breaking_constant` {#id}

Type: float

Variable `cumulative_breaking_max_relative_frequency` {#id}

Type: float

Variable `saturation_breaking_constant` {#id}

Type: float

Variable `saturation_breaking_directional_control` {#id}

Type: float

Variable `saturation_cosine_power` {#id}

Type: float

Variable `saturation_integration_width_degrees` {#id}

Type: float

Variable `saturation_threshold` {#id}

Type: float

Module `ocean_science_utilities.wavephysics.balance.st4_wind_input` {#id}

Classes

Class `ST4WaveGenerationParameters` {#id}

class ST4WaveGenerationParameters(
    *args,
    **kwargs
)

Ancestors (in MRO)

builtins.dict

Class variables

Variable `air_density` {#id}

Type: float

Variable `air_viscosity` {#id}

Type: float

Variable `charnock_constant` {#id}

Type: float

Variable `charnock_maximum_roughness` {#id}

Type: float

Variable `elevation` {#id}

Type: float

Variable `gravitational_acceleration` {#id}

Type: float

Variable `growth_parameter_betamax` {#id}

Type: float

Variable `viscous_stress_parameter` {#id}

Type: float

Variable `vonkarman_constant` {#id}

Type: float

Variable `water_density` {#id}

Type: float

Variable `wave_age_tuning_parameter` {#id}

Type: float

Class `ST4WindInput` {#id}

class ST4WindInput(
    parameters: Optional[ocean_science_utilities.wavephysics.balance.st4_wind_input.ST4WaveGenerationParameters] = None
)

Helper class that provides a standard way to create an ABC using inheritance.

Ancestors (in MRO)

ocean_science_utilities.wavephysics.balance.generation.WindGeneration
ocean_science_utilities.wavephysics.balance.source_term.SourceTerm
abc.ABC

Descendants

ocean_science_utilities.wavephysics.balance.jb23_wind_input.JB23WindInput

Class variables

Variable `name` {#id}

Static methods

`Method default_parameters` {#id}

def default_parameters() ‑> ocean_science_utilities.wavephysics.balance.st4_wind_input.ST4WaveGenerationParameters

Module `ocean_science_utilities.wavephysics.balance.st6_wave_breaking` {#id}

Functions

Function `st6_cumulative` {#id}

def st6_cumulative(
    variance_density,
    relative_saturation_exceedence,
    spectral_grid,
    parameters
)

Function `st6_dissipation` {#id}

def st6_dissipation(
    variance_density,
    depth,
    spectral_grid,
    parameters
)

Function `st6_inherent` {#id}

def st6_inherent(
    variance_density,
    relative_saturation_exceedence,
    spectral_grid,
    parameters
)

Classes

Class `ST6WaveBreaking` {#id}

class ST6WaveBreaking(
    parameters: Optional[ocean_science_utilities.wavephysics.balance.st6_wave_breaking.ST6WaveBreakingParameters] = None
)

Helper class that provides a standard way to create an ABC using inheritance.

Ancestors (in MRO)

ocean_science_utilities.wavephysics.balance.dissipation.Dissipation
ocean_science_utilities.wavephysics.balance.source_term.SourceTerm
abc.ABC

Class variables

Variable `name` {#id}

Static methods

`Method default_parameters` {#id}

def default_parameters() ‑> ocean_science_utilities.wavephysics.balance.st6_wave_breaking.ST6WaveBreakingParameters

Class `ST6WaveBreakingParameters` {#id}

class ST6WaveBreakingParameters(
    *args,
    **kwargs
)

Ancestors (in MRO)

builtins.dict

Class variables

Variable `a1` {#id}

Type: float

Variable `a2` {#id}

Type: float

Variable `p1` {#id}

Type: float

Variable `p2` {#id}

Type: float

Variable `saturation_threshold` {#id}

Type: float

Module `ocean_science_utilities.wavephysics.balance.st6_wind_input` {#id}

Classes

Class `ST6WaveGenerationParameters` {#id}

class ST6WaveGenerationParameters(
    *args,
    **kwargs
)

Ancestors (in MRO)

builtins.dict

Class variables

Variable `air_density` {#id}

Type: float

Variable `charnock_constant` {#id}

Type: float

Variable `charnock_maximum_roughness` {#id}

Type: float

Variable `elevation` {#id}

Type: float

Variable `friction_velocity_scaling` {#id}

Type: float

Variable `gravitational_acceleration` {#id}

Type: float

Variable `vonkarman_constant` {#id}

Type: float

Variable `water_density` {#id}

Type: float

Class `ST6WindInput` {#id}

class ST6WindInput(
    parameters: Optional[ocean_science_utilities.wavephysics.balance.st6_wind_input.ST6WaveGenerationParameters] = None
)

Helper class that provides a standard way to create an ABC using inheritance.

Ancestors (in MRO)

ocean_science_utilities.wavephysics.balance.generation.WindGeneration
ocean_science_utilities.wavephysics.balance.source_term.SourceTerm
abc.ABC

Class variables

Variable `name` {#id}

Static methods

`Method default_parameters` {#id}

def default_parameters() ‑> ocean_science_utilities.wavephysics.balance.st6_wind_input.ST6WaveGenerationParameters

Module `ocean_science_utilities.wavephysics.balance.stress` {#id}

Module `ocean_science_utilities.wavephysics.balance.wam_tail_stress` {#id}

Functions

Function `integrate_tail_frequency_distribution` {#id}

def integrate_tail_frequency_distribution(
    lower_bound,
    effective_charnock,
    vonkarman_constant,
    wave_age_tuning_parameter
)

Integrate the tail of the distributions. We are integrating

np.log(Z(Y))Z(Y)**4 / Y for Y0 <= Y <= 1

where

Y = u_* / wavespeed Z = charnock * Y**2 * np.exp( vonkarman_constant / ( Y + wave_age_tuning_parameter)

The boundaries of the integral are defined as the point where the critical height is at the surface (Y=1) and the point where Z >= 1 ( Y = Y0).

We follow section 5 in the WAM documentation (see below). And introduce x = np.log(Y)

so that we integrate in effect over

np.log(Z(x))Z(x)**4 x0 <= x <= 0

We find x0 as the point where Z(x0) = 0.

REFERENCE:

IFS DOCUMENTATION – Cy47r1 Operational implementation 30 June 2020 - PART VII

:param effective_charnock: :param vonkarman_constant: :param wave_age_tuning_parameter: :return:

Function `log_dimensionless_critical_height` {#id}

def log_dimensionless_critical_height(
    x,
    charnock_constant,
    vonkarman_constant,
    wave_age_tuning_parameter
)

Dimensionless Critical Height according to Janssen (see IFS Documentation). :param x: :param charnock_constant: :param vonkarman_constant: :param wave_age_tuning_parameter: :return:

Function `tail_stress_parametrization_wam` {#id}

def tail_stress_parametrization_wam(
    variance_density,
    wind,
    depth,
    roughness_length,
    spectral_grid,
    parameters
)

Module `ocean_science_utilities.wavephysics.balance.wind_inversion` {#id}

Functions

Function `spectral_time_derivative_in_active_region` {#id}

def spectral_time_derivative_in_active_region(
    time_derivative_spectrum: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    generation: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    spectral_grid
)

Function `windspeed_and_direction_from_spectra` {#id}

def windspeed_and_direction_from_spectra(
    balance: ocean_science_utilities.wavephysics.balance.balance.SourceTermBalance,
    guess_u10: xarray.core.dataarray.DataArray,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum,
    jacobian: bool = False,
    jacobian_parameters: Optional[List[str]] = None,
    time_derivative_spectrum: Optional[ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum] = None,
    direction_iteration: bool = False
) ‑> xarray.core.dataset.Dataset

:param bulk_rate: :param guess_u10: :param guess_direction: :param spectrum: :return:

Module `ocean_science_utilities.wavephysics.fluidproperties` {#id}

Classes

Class `FluidProperties` {#id}

class FluidProperties(
    density: Union[xarray.core.dataarray.DataArray, float],
    temperature: Union[xarray.core.dataarray.DataArray, float],
    kinematic_viscosity: Union[xarray.core.dataarray.DataArray, float],
    vonkarman_constant: Union[xarray.core.dataarray.DataArray, float],
    surface_tension: Union[xarray.core.dataarray.DataArray, float]
)

Instance variables

Variable `kinematic_surface_tension` {#id}

Module `ocean_science_utilities.wavephysics.roughness` {#id}

Functions

Function `charnock_roughness_length` {#id}

def charnock_roughness_length(
    friction_velocity: xarray.core.dataarray.DataArray,
    **kwargs
) ‑> xarray.core.dataarray.DataArray

Function `charnock_roughness_length_from_u10` {#id}

def charnock_roughness_length_from_u10(
    speed,
    **kwargs
) ‑> xarray.core.dataarray.DataArray

Function `drag_coefficient` {#id}

def drag_coefficient(
    u10: xarray.core.dataarray.DataArray,
    roughness: xarray.core.dataarray.DataArray,
    **kwargs
) ‑> xarray.core.dataarray.DataArray

Function `drag_coefficient_charnock` {#id}

def drag_coefficient_charnock(
    speed,
    elevation=10,
    charnock_constant: float = 0.012,
    air: ocean_science_utilities.wavephysics.fluidproperties.FluidProperties = <ocean_science_utilities.wavephysics.fluidproperties.FluidProperties object>,
    viscous_constant: float = 0.0
)

Function `drag_coefficient_wu` {#id}

def drag_coefficient_wu(
    speed
)

Function `janssen_roughness_length` {#id}

def janssen_roughness_length(
    friction_velocity: xarray.core.dataarray.DataArray,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum,
    balance: ocean_science_utilities.wavephysics.balance.balance.SourceTermBalance,
    wind_direction: Optional[xarray.core.dataarray.DataArray] = None
)

Function `janssen_roughness_length_from_u10` {#id}

def janssen_roughness_length_from_u10(
    friction_velocity: xarray.core.dataarray.DataArray,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum,
    balance: ocean_science_utilities.wavephysics.balance.balance.SourceTermBalance,
    wind_direction: Optional[xarray.core.dataarray.DataArray] = None,
    **kwargs
)

Function `roughness_wu` {#id}

def roughness_wu(
    speed,
    elevation=10,
    air: ocean_science_utilities.wavephysics.fluidproperties.FluidProperties = <ocean_science_utilities.wavephysics.fluidproperties.FluidProperties object>
)

Module `ocean_science_utilities.wavephysics.train_wind_estimate` {#id}

Functions

Function `calibrate_wind_estimate_from_balance` {#id}

def calibrate_wind_estimate_from_balance(
    balance: ocean_science_utilities.wavephysics.balance.balance.SourceTermBalance,
    parameter_names: List[str],
    target_u10: xarray.core.dataarray.DataArray,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum,
    loss_function=None,
    velocity_scale=None,
    params=None,
    time_derivative_spectrum: Optional[ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum] = None,
    direction_iteration=False
)

Function `calibrate_wind_estimate_from_spectrum` {#id}

def calibrate_wind_estimate_from_spectrum(
    method,
    target_u10: xarray.core.dataarray.DataArray,
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencySpectrum,
    parameter_names: Optional[List[str]] = None,
    loss_function=None,
    velocity_scale=None,
    bounds=None,
    params=None
)

Function `create_metric` {#id}

def create_metric(
    name,
    weights=None
)

Function `create_weighted_metric` {#id}

def create_weighted_metric(
    name,
    binsize,
    number_of_bins,
    target
)

Function `huber` {#id}

def huber(
    target,
    actual,
    jacobian_actual=None,
    weights=None
)

Function `mae` {#id}

def mae(
    target,
    actual,
    jacobian_actual=None,
    weights=None
)

Function `prep_data` {#id}

def prep_data(
    spectrum: ocean_science_utilities.wavespectra.spectrum.WaveSpectrum,
    target_u10: xarray.core.dataarray.DataArray,
    threshold=(-inf, inf)
)

Function `rmse` {#id}

def rmse(
    target,
    actual,
    jacobian_actual=None,
    weights=None
)

Module `ocean_science_utilities.wavephysics.windestimate` {#id}

Contents: Wind Estimator

Authors: Pieter Bart Smit

Functions

Function `equilibrium_range_values` {#id}

def equilibrium_range_values(
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencySpectrum,
    method: Literal['peak', 'mean'],
    fmax=1.25,
    power=4,
    number_of_bins=20
) ‑> Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

:param spectrum: :param method: :param fmax: :param power: :param number_of_bins: :return:

Function `estimate_u10_from_source_terms` {#id}

def estimate_u10_from_source_terms(
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum,
    balance: ocean_science_utilities.wavephysics.balance.balance.SourceTermBalance,
    time_derivative_spectrum=None,
    direction_iteration=False,
    **kwargs
) ‑> xarray.core.dataset.Dataset

Function `estimate_u10_from_spectrum` {#id}

def estimate_u10_from_spectrum(
    spectrum: Union[ocean_science_utilities.wavespectra.spectrum.FrequencySpectrum, ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum],
    method: Literal['peak', 'mean'] = 'peak',
    fmax=0.5,
    power=4,
    directional_spreading_constant=2.5,
    phillips_constant_beta=0.012,
    vonkarman_constant=0.4,
    grav=9.81,
    number_of_bins=20,
    direction_convention: Literal['coming_from_clockwise_north', 'going_to_counter_clockwise_east'] = 'going_to_counter_clockwise_east',
    **kwargs
) ‑> xarray.core.dataset.Dataset

Function `friction_velocity` {#id}

def friction_velocity(
    spectrum: ocean_science_utilities.wavespectra.spectrum.FrequencySpectrum,
    method: Literal['peak', 'mean'] = 'peak',
    fmax: float = 0.5,
    power: float = 4,
    directional_spreading_constant: float = 2.5,
    beta: float = 0.012,
    grav: float = 9.81,
    number_of_bins: int = 20
) ‑> xarray.core.dataset.Dataset

:param spectrum: :param method: :param fmax: :param power: :param directional_spreading_constant: :param beta: :param grav: :param number_of_bins: :return:

Namespace `ocean_science_utilities.wavespectra` {#id}

Sub-modules

ocean_science_utilities.wavespectra.estimators
ocean_science_utilities.wavespectra.operations
ocean_science_utilities.wavespectra.parametric
ocean_science_utilities.wavespectra.spectrum
ocean_science_utilities.wavespectra.timeseries

Namespace `ocean_science_utilities.wavespectra.estimators` {#id}

Sub-modules

ocean_science_utilities.wavespectra.estimators.estimate
ocean_science_utilities.wavespectra.estimators.loglikelyhood
ocean_science_utilities.wavespectra.estimators.mem
ocean_science_utilities.wavespectra.estimators.mem2
ocean_science_utilities.wavespectra.estimators.utils

Module `ocean_science_utilities.wavespectra.estimators.estimate` {#id}

Functions

Function `estimate_directional_distribution` {#id}

def estimate_directional_distribution(
    a1: numpy.ndarray,
    b1: numpy.ndarray,
    a2: numpy.ndarray,
    b2: numpy.ndarray,
    direction: numpy.ndarray,
    method: Literal['mem', 'mem2'] = 'mem2',
    **kwargs
) ‑> numpy.ndarray

Construct a 2D directional distribution based on the directional moments and a spectral reconstruction method.

:param number_of_directions: length of the directional vector for the 2D spectrum. Directions returned are in degrees

:param method: Choose a method in ['mem','mem2'] mem: maximum entrophy (in the Boltzmann sense) method Lygre, A., & Krogstad, H. E. (1986). Explicit expression and fast but tends to create narrow spectra anderroneous secondary peaks.

mem2: use entrophy (in the Shannon sense) to maximize. Likely
best method see- Benoit, M. (1993).

REFERENCES: Benoit, M. (1993). Practical comparative performance survey of methods used for estimating directional wave spectra from heave-pitch-roll data. In Coastal Engineering 1992 (pp. 62-75).

Lygre, A., & Krogstad, H. E. (1986). Maximum entropy estimation of the directional distribution in ocean wave spectra. Journal of Physical Oceanography, 16(12), 2052-2060.

Function `estimate_directional_spectrum_from_moments` {#id}

def estimate_directional_spectrum_from_moments(
    e: numpy.ndarray,
    a1: numpy.ndarray,
    b1: numpy.ndarray,
    a2: numpy.ndarray,
    b2: numpy.ndarray,
    direction: numpy.ndarray,
    method: Literal['mem', 'mem2'] = 'mem2',
    **kwargs
) ‑> numpy.ndarray

Construct a 2D directional distribution based on the directional moments and a spectral reconstruction method.

:param number_of_directions: length of the directional vector for the 2D spectrum. Directions returned are in degrees

mem2: use entrophy (in the Shannon sense) to maximize. Likely
best method see- Benoit, M. (1993).

REFERENCES: Benoit, M. (1993). Practical comparative performance survey of methods used for estimating directional wave spectra from heave-pitch-roll data. In Coastal Engineering 1992 (pp. 62-75).

Lygre, A., & Krogstad, H. E. (1986). Maximum entropy estimation of the directional distribution in ocean wave spectra. Journal of Physical Oceanography, 16(12), 2052-2060.

Module `ocean_science_utilities.wavespectra.estimators.loglikelyhood` {#id}

Functions

Function `log_likelyhood` {#id}

def log_likelyhood(
    directions_radians: numpy.ndarray,
    a1: numpy.ndarray,
    b1: numpy.ndarray,
    a2: numpy.ndarray,
    b2: numpy.ndarray,
    progress,
    **kwargs
) ‑> numpy.ndarray

Module `ocean_science_utilities.wavespectra.estimators.mem` {#id}

Functions

Function `mem` {#id}

def mem(
    directions_radians: numpy.ndarray,
    a1: numpy.ndarray,
    b1: numpy.ndarray,
    a2: numpy.ndarray,
    b2: numpy.ndarray,
    progress,
    **kwargs
) ‑> numpy.ndarray

Function `numba_mem` {#id}

def numba_mem(
    directions_radians: numpy.ndarray,
    a1: float,
    b1: float,
    a2: float,
    b2: float
) ‑> numpy.ndarray

This function uses the maximum entropy method by Lygre and Krogstadt (1986,JPO) to estimate the directional shape of the spectrum. Enthropy is defined in the Boltzmann sense (log D)

Lygre, A., & Krogstad, H. E. (1986). Maximum entropy estimation of the directional distribution in ocean wave spectra. Journal of Physical Oceanography, 16(12), 2052-2060.

:param directions_radians: 1d array of wave directions in radians, length[number_of_directions]. (going to, anti-clockswise from east)

:param a1: 1d array of cosine directional moment as function of frequency, length [number_of_frequencies]

:param b1: 1d array of sine directional moment as function of frequency, length [number_of_frequencies]

:param a2: 1d array of double angle cosine directional moment as function of frequency, length [number_of_frequencies]

:param b2: 1d array of double angle sine directional moment as function of frequency, length [number_of_frequencies]

:return: array with shape [number_of_frequencies,number_of_direction] representing the directional distribution of the waves at each frequency.

Maximize the enthrophy of the solution with entrophy defined as:

   integrate log(D) over directions

such that the resulting distribution D reproduces the observed moments.

:return: Directional distribution as a np array

Note that: d1 = a1; d2 =b1; d3 = a2 and d4=b2 in the defining equations 10.

Module `ocean_science_utilities.wavespectra.estimators.mem2` {#id}

Implementation of the "MEM2" method:

see Kim1995:

Kim, T., Lin, L. H., & Wang, H. (1995). Application of maximum entropy method
to the real sea data. In Coastal Engineering 1994 (pp. 340-355).

link: <https://icce-ojs-tamu.tdl.org/icce/index.php/icce/article/download/4967/4647>
(working as of May 29, 2022)

and references therein.

Functions

Function `initial_value` {#id}

def initial_value(
    a1: numpy.ndarray,
    b1: numpy.ndarray,
    a2: numpy.ndarray,
    b2: numpy.ndarray
)

Initial guess of the Lagrange Multipliers according to the "MEM AP2" approximation found im Kim1995

:param a1: moment a1 :param b1: moment b1 :param a2: moment a2 :param b2: moment b2 :return: initial guess of the lagrange multipliers, with the same leading dimensions as input.

Function `mem2` {#id}

def mem2(
    directions_radians: numpy.ndarray,
    a1: numpy.ndarray,
    b1: numpy.ndarray,
    a2: numpy.ndarray,
    b2: numpy.ndarray,
    progress_bar: numba_progress.progress.ProgressBar = None,
    solution_method='newton',
    solver_config=None
) ‑> numpy.ndarray

:param directions_radians: :param a1: :param b1: :param a2: :param b2: :param solution_method: :return:

Function `mem2_directional_distribution` {#id}

def mem2_directional_distribution(
    lagrange_multiplier,
    direction_increment,
    twiddle_factors
) ‑> numpy.ndarray

Given the solution for the Lagrange multipliers- reconstruct the directional distribution. :param lagrange_multiplier: the lagrange multipliers :param twiddle_factors: [sin theta, cost theta, sin 2theta, cos 2theta] as a 4 by ndir array :param direction_increment: directional stepsize used in the integration, nd-array :return: Directional distribution arrasy as a function of directions

Function `mem2_jacobian` {#id}

def mem2_jacobian(
    lagrange_multiplier,
    twiddle_factors,
    direction_increment,
    jacobian
)

Calculate the jacobian of the constraint equations. The resulting jacobian is a square and positive definite matrix

:param lambdas: the lagrange multipliers :param twiddle_factors: [sin theta, cost theta, sin 2theta, cos 2theta] as a 4 by ndir array :param direction_increment: directional stepsize used in the integration, nd-array

:return: a 4 by 4 matrix that is the Jacobian of the constraint equations.

Function `mem2_newton` {#id}

def mem2_newton(
    directions_radians: numpy.ndarray,
    a1: numpy.ndarray,
    b1: numpy.ndarray,
    a2: numpy.ndarray,
    b2: numpy.ndarray,
    progress_bar: numba_progress.progress.ProgressBar = None,
    config: numba.typed.typeddict.Dict = None,
    approximate: bool = False
) ‑> numpy.ndarray

Return the directional distribution that maximizes Shannon [ - D log(D) ] enthrophy constrained by given observed directional moments.

:param directions_radians: 1d array of wave directions in radians, length[number_of_directions]

:param a1: 1d array of cosine directional moment as function of position and frequency, shape = ( number_of_points,number_of_frequencies)

:param b1: 1d array of sine directional moment as function of position and frequency, shape = ( number_of_points,number_of_frequencies)

:param a2: 1d array of double angle cosine directional moment as function of position and frequency, shape = ( number_of_points,number_of_frequencies)

:param b2: 1d array of double angle sine directional moment as function of position and frequency, shape = ( number_of_points,number_of_frequencies)

:param progress_bar: Progress bar instance if updates are desired.

:return: array with shape [ numbrt_of_points, number_of_frequencies, number_of_direction ] representing the directional distribution of the waves at each frequency.

Maximize the enthrophy of the solution with entrophy defined as:

   integrate - D * log(D) over directions

such that the resulting distribution D reproduces the observed moments.

Function `mem2_newton_solver` {#id}

def mem2_newton_solver(
    moments: numpy.ndarray,
    guess: numpy.ndarray,
    direction_increment: numpy.ndarray,
    twiddle_factors: numpy.ndarray,
    config=None,
    approximate=False
) ‑> numpy.ndarray

Newton iteration to find the solution to the non-linear system of constraint equations defining the lagrange multipliers in the MEM2 method. Because the Lagrange multipliers enter the equations as exponents the system can be unstable to solve numerically.

:param moments: the normalized directional moments [a1,b1,a2,b2] :param guess: first guess for the lagrange multipliers (ndarray, length 4) :param direction_increment: directional stepsize used in the integration, nd-array :param twiddle_factors: [sin theta, cost theta, sin 2theta, cos 2theta] as a 4 by ndir array :param config: numerical settings, see description at NUMERICS at top of file. :param approximate: whether or not to use the approximate relations. :return:

Function `mem2_scipy_root_finder` {#id}

def mem2_scipy_root_finder(
    directions_radians: numpy.ndarray,
    a1: numpy.ndarray,
    b1: numpy.ndarray,
    a2: numpy.ndarray,
    b2: numpy.ndarray,
    progress,
    **kwargs
) ‑> numpy.ndarray

Return the directional distribution that maximizes Shannon [ - D log(D) ] enthrophy constrained by given observed directional moments,

:param directions_radians: 1d array of wave directions in radians, length[number_of_directions]

:param a1: 1d array of cosine directional moment as function of frequency, length [number_of_frequencies]

:param b1: 1d array of sine directional moment as function of frequency, length [number_of_frequencies]

:param a2: 1d array of double angle cosine directional moment as function of frequency, length [number_of_frequencies]

:param b2: 1d array of double angle sine directional moment as function of frequency, length [number_of_frequencies]

:return: array with shape [number_of_frequencies,number_of_direction] representing the directional distribution of the waves at each frequency.

Maximize the enthrophy of the solution with entrophy defined as:

   integrate - D * log(D) over directions

such that the resulting distribution D reproduces the observed moments.

Function `moment_constraints` {#id}

def moment_constraints(
    lambdas,
    twiddle_factors,
    moments,
    direction_increment
)

Construct the nonlinear equations we need to solve for lambda. The constrainst are the difference between the desired moments a1,b1,a2,b2 and the moment calculated from the current distribution guess and for a perfect fit should be 0.

To note: we differ from Kim et al here who formulate the constraints using unnormalized equations. Here we opt to use the normalized version as that allows us to cast the error / or mismatch directly in terms of an error in the moments.

:param lambdas: the lagrange multipliers :param twiddle_factors: [sin theta, cost theta, sin 2theta, cos 2theta] as a 4 by ndir array :param moments: [a1,b1,a2,b2] :param direction_increment: directional stepsize used in the integration, nd-array :return: array (length=4) with the difference between desired moments and those calculated from the current approximate distribution

Function `solve_cholesky` {#id}

def solve_cholesky(
    matrix,
    rhs
)

Solve using cholesky decomposition according to the Cholesky–Banachiewicz algorithm. See: https://en.wikipedia.org/wiki/Cholesky_decomposition#The_Cholesky_algorithm

Module `ocean_science_utilities.wavespectra.estimators.utils` {#id}

Functions

Function `get_constraint_matrix` {#id}

def get_constraint_matrix(
    directions_radians: numpy.ndarray
) ‑> numpy.ndarray

Define the matrix M that can be used in the matrix product M@D (with D the directional distribution) such that:

    M@D = [1,a1,b1,a2,b2]^T

with a1,b1 etc the directional moments at a given frequency.

:param directions_radians: array of radian directions :return:

Function `get_direction_increment` {#id}

def get_direction_increment(
    directions_radians: numpy.ndarray
) ‑> numpy.ndarray

calculate the stepsize used for midpoint integration. The directions represent the center of the interval - and we want to find the dimensions of the interval (difference between the preceeding and succsesive midpoint).

:param directions_radians: array of radian directions :return: array of radian intervals

Function `get_rhs` {#id}

def get_rhs(
    a1: numpy.ndarray,
    b1: numpy.ndarray,
    a2: numpy.ndarray,
    b2: numpy.ndarray
) ‑> numpy.ndarray

Define the matrix rhs that for each row contains the directional moments at a given frequency:

These rows are use as the "right hand side" in the linear constraints (see get_constraint_matrix)

:param a1: 1d array of cosine directional moment as function of frequency, length [number_of_frequencies]

:param b1: 1d array of sine directional moment as function of frequency, length [number_of_frequencies]

:param a2: 1d array of double angle cosine directional moment as function of frequency, length [number_of_frequencies]

:param b2: 1d array of double angle sine directional moment as function of frequency, length [number_of_frequencies]

:return: array ( number of frequencies by 5) that for each row contains the directional moments at a given frequency

Module `ocean_science_utilities.wavespectra.operations` {#id}

Functions

Function `concatenate_spectra` {#id}

def concatenate_spectra(
    spectra: Sequence[~_T],
    dim=None,
    keys=None,
    **kwargs
) ‑> ~_T

Concatenate along the given dimension. If the dimension does not exist a new dimension will be created. Under the hood this calls the concat function of xarray. Named arguments to that function can be applied here as well.

If dim is set to None - we first flatten the spectral objects - and then join along the flattened dimension.

:param spectra: A sequence of Frequency Spectra/Frequency Direction Spectra :param dim: the dimension to concatenate along :return: New combined spectral object.

Function `integrate_spectral_data` {#id}

def integrate_spectral_data(
    dataset: xarray.core.dataarray.DataArray,
    dims: Union[Literal['frequency', 'direction'], Sequence[Literal['frequency', 'direction']]]
) ‑> xarray.core.dataarray.DataArray

Function `numba_directionally_integrate_spectral_data` {#id}

def numba_directionally_integrate_spectral_data(
    data: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    grid: Dict[str, numpy.ndarray]
)

Function `numba_integrate_spectral_data` {#id}

def numba_integrate_spectral_data(
    data: numpy.ndarray[typing.Any, numpy.dtype[+ScalarType]],
    grid: Dict[str, numpy.ndarray]
) ‑> float

Module `ocean_science_utilities.wavespectra.parametric` {#id}

Functions

Function `create_directional_shape` {#id}

def create_directional_shape(
    shape: Literal['raised_cosine'],
    mean_direction_degrees: float = 0,
    width_degrees: float = 30
) ‑> ocean_science_utilities.wavespectra.parametric.DirectionalShape

Function `create_frequency_shape` {#id}

def create_frequency_shape(
    shape: Literal['pm', 'jonswap', 'phillips', 'gaussian'],
    peak_frequency_hertz: float,
    m0: float = 1,
    **kwargs
) ‑> ocean_science_utilities.wavespectra.parametric.FrequencyShape

Function `create_parametric_frequency_direction_spectrum` {#id}

def create_parametric_frequency_direction_spectrum(
    frequency_hertz: numpy.ndarray,
    peak_frequency_hertz: float,
    significant_wave_height: float,
    frequency_shape: Literal['pm', 'jonswap', 'phillips', 'gaussian'] = 'jonswap',
    direction_degrees: Optional[numpy.ndarray] = None,
    direction_shape: Literal['raised_cosine'] = 'raised_cosine',
    mean_direction_degrees: float = 0.0,
    width_degrees: float = 30,
    depth: float = inf,
    time: Optional[datetime.datetime] = None,
    latitude: Optional[float] = None,
    longitude: Optional[float] = None,
    **kwargs
) ‑> ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum

Create a parametrized directional frequency spectrum according to a given frequency (Jonswap, PM) or directional (raised_cosine) distribution.

:param frequency_hertz: Frequencies to resolve :param peak_frequency_hertz: Desired peak frequency of the spectrum :param significant_wave_height: Significant wave height of the spectrum :param frequency_shape: The frequency shape, currently supported are: frequency_shape="pm": for pierson_moskowitz frequency_shape="jonswap" [default]: for Jonswap :param direction_degrees: Directions to resolve the spectrum. If None [default] 36 directions spanning the circle are used [ 0 , 360 ) :param direction_shape: shape of the directional distribution. Currently only a raised cosine distribution is supported. :param mean_direction_degrees: mean direction of the waves. 0 degrees (due east) is the default. :param width_degrees: width of the spectrum (according to Kuik). 30 degrees is the default. :param depth: mean depth at the location of the spectrum (optional) Does not affect returned spectral values in any way, but is used as the depth in the returned spectral object (and may affect e.g. wavenumber calculations.) :param time: timestamp of the spectrum. Optional. Merely an annotation on the returned object. :param latitude: latitude of the spectrum. Optional. Merely an annotation on the returned object. :param longitude: latitude of the spectrum. Optional. Merely an annotation on the returned object.

:return: FrequencyDirectionSpectrum object.

Function `create_parametric_frequency_spectrum` {#id}

def create_parametric_frequency_spectrum(
    frequency_hertz: numpy.ndarray,
    peak_frequency_hertz: float,
    significant_wave_height: float,
    frequency_shape: Literal['pm', 'jonswap', 'phillips', 'gaussian'] = 'jonswap',
    depth: float = inf,
    time: Optional[datetime.datetime] = None,
    latitude: Optional[float] = None,
    longitude: Optional[float] = None,
    **kwargs
) ‑> ocean_science_utilities.wavespectra.spectrum.FrequencySpectrum

Function `create_parametric_spectrum` {#id}

def create_parametric_spectrum(
    frequency_hertz: numpy.ndarray,
    frequency_shape: Literal['pm', 'jonswap', 'phillips', 'gaussian'],
    peak_frequency_hertz: float,
    significant_wave_height: float,
    direction_degrees: Optional[numpy.ndarray] = None,
    direction_shape: Literal['raised_cosine'] = 'raised_cosine',
    mean_direction_degrees: float = 0.0,
    width_degrees: float = 30.0,
    depth: float = inf,
    time: Optional[datetime.datetime] = None,
    latitude: Optional[float] = None,
    longitude: Optional[float] = None
) ‑> ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum

Deprecated - use create_parametric_frequency_direction_spectrum instead

Classes

Class `DirectionalShape` {#id}

class DirectionalShape

Helper class that provides a standard way to create an ABC using inheritance.

Ancestors (in MRO)

abc.ABC

Descendants

ocean_science_utilities.wavespectra.parametric.RaisedCosine

Methods

Method `values` {#id}

def values(
    self,
    direction_degrees: numpy.ndarray
) ‑> numpy.ndarray

Class `FrequencyShape` {#id}

class FrequencyShape

Helper class that provides a standard way to create an ABC using inheritance.

Ancestors (in MRO)

abc.ABC

Descendants

ocean_science_utilities.wavespectra.parametric.GaussianSpectrum
ocean_science_utilities.wavespectra.parametric.JonswapSpectrum
ocean_science_utilities.wavespectra.parametric.PhillipsSpectrum
ocean_science_utilities.wavespectra.parametric.PiersonMoskowitzSpectrum

Methods

Method `values` {#id}

def values(
    self,
    frequency_hertz: numpy.ndarray
) ‑> numpy.ndarray

Class `GaussianSpectrum` {#id}

class GaussianSpectrum(
    peak_frequency_hertz: float,
    m0: float = 1,
    **kwargs
)

Helper class that provides a standard way to create an ABC using inheritance.

Ancestors (in MRO)

ocean_science_utilities.wavespectra.parametric.FrequencyShape
abc.ABC

Methods

Method `values` {#id}

def values(
    self,
    frequency_hertz: numpy.ndarray
) ‑> numpy.ndarray

Class `JonswapSpectrum` {#id}

class JonswapSpectrum(
    peak_frequency_hertz: float,
    m0: float = 1,
    **kwargs
)

Helper class that provides a standard way to create an ABC using inheritance.

Ancestors (in MRO)

ocean_science_utilities.wavespectra.parametric.FrequencyShape
abc.ABC

Methods

Method `alpha` {#id}

def alpha(
    self,
    m0: float
) ‑> float

Method `values` {#id}

def values(
    self,
    frequency_hertz: numpy.ndarray
) ‑> numpy.ndarray

Jonswap variance-density spectrum with frequency in Hz as dependant variable. See e.g. Holthuijsen "Waves in Oceanic Water."

:param frequency: frequency in Hz (scalar or array) :param peak_frequency: peak frequency in Hz :param alpha: Phillips constant (default 0.0081) :param g: gravitational acceleration (default 9.81) :return:

Class `PhillipsSpectrum` {#id}

class PhillipsSpectrum(
    peak_frequency_hertz: float,
    m0: float = 1,
    **kwargs
)

Helper class that provides a standard way to create an ABC using inheritance.

Ancestors (in MRO)

ocean_science_utilities.wavespectra.parametric.FrequencyShape
abc.ABC

Methods

Method `alpha` {#id}

def alpha(
    self,
    m0: float
) ‑> float

Method `values` {#id}

def values(
    self,
    frequency_hertz: numpy.ndarray
) ‑> numpy.ndarray

Phillips variance-density spectrum with frequency in Hz as dependent variable.

:return:

Class `PiersonMoskowitzSpectrum` {#id}

class PiersonMoskowitzSpectrum(
    peak_frequency_hertz: float,
    m0: float = 1,
    **kwargs
)

Helper class that provides a standard way to create an ABC using inheritance.

Ancestors (in MRO)

ocean_science_utilities.wavespectra.parametric.FrequencyShape
abc.ABC

Methods

Method `alpha` {#id}

def alpha(
    self,
    m0: float
) ‑> float

Method `values` {#id}

def values(
    self,
    frequency_hertz: numpy.ndarray
) ‑> numpy.ndarray

Pierson Moskowitz variance-density spectrum with frequency in Hz as dependant variable. See e.g. Holthuijsen "Waves in Oceanic Water."

Class `RaisedCosine` {#id}

class RaisedCosine(
    mean_direction_degrees: float = 0,
    width_degrees: float = 28.64
)

Helper class that provides a standard way to create an ABC using inheritance.

Ancestors (in MRO)

ocean_science_utilities.wavespectra.parametric.DirectionalShape
abc.ABC

Static methods

`Method power` {#id}

def power(
    width_degrees: float
) ‑> float

Methods

Method `values` {#id}

def values(
    self,
    direction_degrees: numpy.ndarray
) ‑> numpy.ndarray

Module `ocean_science_utilities.wavespectra.spectrum` {#id}

Functions

Function `create_1d_spectrum` {#id}

def create_1d_spectrum(
    frequency: numpy.ndarray,
    variance_density: numpy.ndarray,
    time: Union[numpy.ndarray, float],
    latitude: Union[numpy.ndarray, float],
    longitude: Union[numpy.ndarray, float],
    a1: Optional[numpy.ndarray] = None,
    b1: Optional[numpy.ndarray] = None,
    a2: Optional[numpy.ndarray] = None,
    b2: Optional[numpy.ndarray] = None,
    depth: Union[numpy.ndarray, float] = inf,
    dims=('time', 'frequency')
) ‑> ocean_science_utilities.wavespectra.spectrum.FrequencySpectrum

Function `create_2d_spectrum` {#id}

def create_2d_spectrum(
    frequency: numpy.ndarray,
    direction: numpy.ndarray,
    variance_density: numpy.ndarray,
    time,
    latitude: Union[numpy.ndarray, float, ForwardRef(None)],
    longitude: Union[numpy.ndarray, float, ForwardRef(None)],
    dims=('time', 'frequency', 'direction'),
    depth: Union[numpy.ndarray, float] = inf
) ‑> ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum

:param frequency: :param direction: :param variance_density: :param time: :param latitude: :param longitude: :param dims: :param depth: :return:

Function `create_spectrum_dataset` {#id}

def create_spectrum_dataset(
    dims,
    variables
) ‑> xarray.core.dataset.Dataset

Function `cumulative_frequency_interpolation_1d_variable` {#id}

def cumulative_frequency_interpolation_1d_variable(
    interpolation_frequency,
    dataset: xarray.core.dataset.Dataset,
    **kwargs
)

To interpolate the spectrum we first calculate a cumulative density function from the spectrum (which is essentialya pdf). We then interpolate the CDF function with a spline and differentiate the result.

:param interpolation_frequency: :param dataset: :return:

Function `fill_zeros_or_nan_in_tail` {#id}

def fill_zeros_or_nan_in_tail(
    spectrum: ocean_science_utilities.wavespectra.spectrum.WaveSpectrum,
    power=None,
    tail_energy=None,
    tail_bounds=None
) ‑> ocean_science_utilities.wavespectra.spectrum.FrequencySpectrum

Function `load_spectrum_from_netcdf` {#id}

def load_spectrum_from_netcdf(
    filename_or_obj
) ‑> Union[ocean_science_utilities.wavespectra.spectrum.FrequencySpectrum, ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum]

Load a spectrum from netcdf file :param filename_or_obj: :return:

Classes

Class `DatasetWrapper` {#id}

class DatasetWrapper(
    dataset: xarray.core.dataset.Dataset
)

A class that wraps a dataset object and passes through some of its primary functionality (get/set etc.). Used here mostly to make explicit what parts of the Dataset interface we actually expose in frequency objects. Note that we do not claim- or try to obtain completeness here. If full capabilities of the dataset object are needed we can simple operate directly on the dataset object itself.

Descendants

ocean_science_utilities.wavespectra.spectrum.WaveSpectrum

Methods

Method `coords` {#id}

def coords(
    self
) ‑> xarray.core.coordinates.DatasetCoordinates

Method `copy` {#id}

def copy(
    self,
    deep=True
)

Method `isel` {#id}

def isel(
    self,
    *args,
    **kwargs
)

Method `keys` {#id}

def keys(
    self
)

Method `sel` {#id}

def sel(
    self,
    *args,
    method='nearest'
)

Class `FrequencyDirectionSpectrum` {#id}

class FrequencyDirectionSpectrum(
    dataset: xarray.core.dataset.Dataset
)

Ancestors (in MRO)

ocean_science_utilities.wavespectra.spectrum.WaveSpectrum
ocean_science_utilities.wavespectra.spectrum.DatasetWrapper

Instance variables

Variable `direction` {#id}

Type: xarray.core.dataarray.DataArray

Variable `direction_step` {#id}

Type: xarray.core.dataarray.DataArray

Variable `number_of_directions` {#id}

Type: int

Variable `radian_direction` {#id}

Type: xarray.core.dataarray.DataArray

Methods

Method `as_frequency_spectrum` {#id}

def as_frequency_spectrum(
    self
)

Method `differentiate` {#id}

def differentiate(
    self,
    coordinate=None,
    **kwargs
) ‑> ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum

Method `spectrum_1d` {#id}

def spectrum_1d(
    self
)

Will be depricated :return:

Class `FrequencySpectrum` {#id}

class FrequencySpectrum(
    dataset: xarray.core.dataset.Dataset
)

Ancestors (in MRO)

ocean_science_utilities.wavespectra.spectrum.WaveSpectrum
ocean_science_utilities.wavespectra.spectrum.DatasetWrapper

Methods

Method `as_frequency_direction_spectrum` {#id}

def as_frequency_direction_spectrum(
    self,
    number_of_directions,
    method: Literal['mem', 'mem2'] = 'mem2',
    solution_method='scipy'
) ‑> ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum

Method `down_sample` {#id}

def down_sample(
    self,
    frequencies
)

Method `interpolate` {#id}

def interpolate(
    self: FrequencySpectrum,
    coordinates,
    extrapolation_value=0.0,
    nearest_neighbour=False
) ‑> ocean_science_utilities.wavespectra.spectrum.FrequencySpectrum

:param coordinates: :return:

Method `interpolate_frequency` {#id}

def interpolate_frequency(
    self: FrequencySpectrum,
    new_frequencies: Union[xarray.core.dataarray.DataArray, numpy.ndarray],
    extrapolation_value=0.0,
    method: Literal['nearest', 'linear', 'spline'] = 'linear',
    **kwargs
) ‑> ocean_science_utilities.wavespectra.spectrum.FrequencySpectrum

Class `WaveSpectrum` {#id}

class WaveSpectrum(
    dataset: xarray.core.dataset.Dataset
)

Ancestors (in MRO)

ocean_science_utilities.wavespectra.spectrum.DatasetWrapper

Descendants

ocean_science_utilities.wavespectra.spectrum.FrequencyDirectionSpectrum
ocean_science_utilities.wavespectra.spectrum.FrequencySpectrum

Class variables

Variable `angular_convention` {#id}

Variable `angular_units` {#id}

Variable `bulk_properties` {#id}

Variable `frequency_units` {#id}

Variable `spectral_density_units` {#id}

Instance variables

Variable `A1` {#id}

Type: xarray.core.dataarray.DataArray

:return: Fourier moment cos(theta)

Variable `A2` {#id}

Type: xarray.core.dataarray.DataArray

:return: Fourier moment cos(2*theta)

Variable `B1` {#id}

Type: xarray.core.dataarray.DataArray

:return: Fourier moment sin(theta)

Variable `B2` {#id}

Type: xarray.core.dataarray.DataArray

:return: Fourier moment sin(2*theta)

Variable `a1` {#id}

Type: xarray.core.dataarray.DataArray

:return: normalized Fourier moment cos(theta)

Variable `a2` {#id}

Type: xarray.core.dataarray.DataArray

:return: normalized Fourier moment cos(2*theta)

Variable `b1` {#id}

Type: xarray.core.dataarray.DataArray

:return: normalized Fourier moment sin(theta)

Variable `b2` {#id}

Type: xarray.core.dataarray.DataArray

:return: normalized Fourier moment sin(2*theta)

Variable `coords_space_time` {#id}

Type: Mapping[str, xarray.core.dataarray.DataArray]

Variable `coords_spectral` {#id}

Type: Mapping[str, xarray.core.dataarray.DataArray]

Variable `depth` {#id}

Type: xarray.core.dataarray.DataArray

Variable `dims` {#id}

Type: List[str]

Variable `dims_space_time` {#id}

Type: List[str]

Variable `dims_spectral` {#id}

Type: List[str]

Variable `e` {#id}

Type: xarray.core.dataarray.DataArray

:return: 1D spectral values (directionally integrated spectrum). Equivalent to self.spectral_values if this is a 1D spectrum.

Variable `frequency` {#id}

Type: xarray.core.dataarray.DataArray

:return: Frequencies (Hz)

Variable `frequency_step` {#id}

Type: xarray.core.dataarray.DataArray

Variable `group_velocity` {#id}

Type: xarray.core.dataarray.DataArray

Variable `latitude` {#id}

Type: xarray.core.dataarray.DataArray

:return: latitudes

Variable `longitude` {#id}

Type: xarray.core.dataarray.DataArray

:return: longitudes

Variable `mean_direction_per_frequency` {#id}

Type: xarray.core.dataarray.DataArray

Variable `mean_period` {#id}

Type: xarray.core.dataarray.DataArray

Variable `mean_spread_per_frequency` {#id}

Type: xarray.core.dataarray.DataArray

Variable `ndims` {#id}

Type: int

Variable `number_of_frequencies` {#id}

Type: int

:return: number of frequencies

Variable `number_of_spectra` {#id}

Variable `peak_wavenumber` {#id}

Type: xarray.core.dataarray.DataArray

Variable `radian_frequency` {#id}

Type: xarray.core.dataarray.DataArray

:return: Radian frequency

Variable `saturation_spectrum` {#id}

Type: xarray.core.dataarray.DataArray

Variable `significant_waveheight` {#id}

Type: xarray.core.dataarray.DataArray

Variable `slope_spectrum` {#id}

Type: xarray.core.dataarray.DataArray

Variable `spectral_values` {#id}

Type: xarray.core.dataarray.DataArray

:return: Spectral levels

Variable `time` {#id}

Type: xarray.core.dataarray.DataArray

:return: Time

Variable `values` {#id}

Type: numpy.ndarray

Get the raw np representation of the wave spectrum :return: Numpy ndarray of the wave spectrum.

Variable `variance_density` {#id}

Type: xarray.core.dataarray.DataArray

:return: Time

Variable `wavelength` {#id}

Type: xarray.core.dataarray.DataArray

Variable `wavenumber` {#id}

Type: xarray.core.dataarray.DataArray

Determine the wavenumbers for the frequencies in the spectrum. Note that since the dispersion relation depends on depth the returned wavenumber array has the dimensions associated with the depth array by the frequency dimension.

:return: wavenumbers

Variable `wavenumber_density` {#id}

Type: xarray.core.dataarray.DataArray

Variable `zero_crossing_period` {#id}

Type: xarray.core.dataarray.DataArray

Methods

Method `bandpass` {#id}

def bandpass(
    self,
    fmin: float = 0,
    fmax: float = inf
)

Method `bulk_variables` {#id}

def bulk_variables(
    self
) ‑> xarray.core.dataset.Dataset

Method `cdf` {#id}

def cdf(
    self
) ‑> xarray.core.dataarray.DataArray

:return:

Method `drop_invalid` {#id}

def drop_invalid(
    self
)

Method `extrapolate_tail` {#id}

def extrapolate_tail(
    self,
    end_frequency,
    power=None,
    tail_energy=None,
    tail_bounds=None,
    tail_moments=None,
    tail_frequency=None
) ‑> ocean_science_utilities.wavespectra.spectrum.FrequencySpectrum

Extrapolate the tail using the given power :param end_frequency: frequency to extrapolate to :param power: power to use. If None, a best fit -4 or -5 tail is used. :return:

Method `fillna` {#id}

def fillna(
    self,
    value=0.0
)

Method `flatten` {#id}

def flatten(
    self,
    flattened_coordinate='linear_index'
)

Serialize the non-spectral dimensions creating a single leading dimension without a coordinate.

Method `frequency_moment` {#id}

def frequency_moment(
    self,
    power: int,
    fmin=0,
    fmax=inf
) ‑> xarray.core.dataarray.DataArray

Calculate a "frequency moment" over the given range. A frequency moment here refers to the integral:

        Integral-over-frequency-range[ e(f) * f**power ]

:param power: power of the frequency :param fmin: minimum frequency :param fmax: maximum frequency :return: frequency moment

Method `hm0` {#id}

def hm0(
    self,
    fmin=0,
    fmax=inf
) ‑> xarray.core.dataarray.DataArray

Significant wave height estimated from the spectrum, i.e. waveheight h estimated from variance m0. Common notation in literature.

:param fmin: minimum frequency :param fmax: maximum frequency :return: Significant wave height

Method `interpolate` {#id}

def interpolate(
    self,
    coordinates: Dict[str, Union[xarray.core.dataarray.DataArray, numpy.ndarray]],
    extrapolation_value: float = 0.0
)

Method `interpolate_frequency` {#id}

def interpolate_frequency(
    self,
    new_frequencies: Union[xarray.core.dataarray.DataArray, numpy.ndarray],
    extrapolation_value: float = 0.0
)

Method `is_invalid` {#id}

def is_invalid(
    self
) ‑> xarray.core.dataarray.DataArray

Method `is_valid` {#id}

def is_valid(
    self
) ‑> xarray.core.dataarray.DataArray

Method `m0` {#id}

def m0(
    self,
    fmin=0,
    fmax=inf
) ‑> xarray.core.dataarray.DataArray

Zero order frequency moment. Also referred to as variance or energy.

:param fmin: minimum frequency :param fmax: maximum frequency :return: variance/energy

Method `m1` {#id}

def m1(
    self,
    fmin=0,
    fmax=inf
) ‑> xarray.core.dataarray.DataArray

First order frequency moment. Primarily used in calculating a mean period measure (Tm01)

:param fmin: minimum frequency :param fmax: maximum frequency :return: first order frequency moment.

Method `m2` {#id}

def m2(
    self,
    fmin=0,
    fmax=inf
) ‑> xarray.core.dataarray.DataArray

Second order frequency moment. Primarily used in calculating the zero crossing period (Tm02)

:param fmin: minimum frequency :param fmax: maximum frequency :return: Second order frequency moment.

Method `mean` {#id}

def mean(
    self,
    dim,
    skipna=False
)

Calculate the mean value of the spectrum along the given dimension. :param dim: dimension to average over :param skipna: whether or not to "skip" nan values; if True behaves as np.nanmean :return:

Method `mean_a1` {#id}

def mean_a1(
    self,
    fmin=0,
    fmax=inf
)

Method `mean_a2` {#id}

def mean_a2(
    self,
    fmin=0,
    fmax=inf
)

Method `mean_b1` {#id}

def mean_b1(
    self,
    fmin=0,
    fmax=inf
)

Method `mean_b2` {#id}

def mean_b2(
    self,
    fmin=0,
    fmax=inf
)

Method `mean_direction` {#id}

def mean_direction(
    self,
    fmin=0,
    fmax=inf
)

Method `mean_directional_spread` {#id}

def mean_directional_spread(
    self,
    fmin=0,
    fmax=inf
)

Method `mean_squared_slope` {#id}

def mean_squared_slope(
    self,
    fmin=0,
    fmax=inf
) ‑> xarray.core.dataarray.DataArray

Method `multiply` {#id}

def multiply(
    self,
    array: numpy.ndarray,
    dimensions: Optional[List[str]] = None,
    inplace: bool = False
)

Multiply the variance density with the given np array. Broadcasting is performed automatically if dimensions are provided. If no dimensions are provided the array needs to have the exact same shape as the variance density array.

:param array: Array to multiply with variance density :param dimension: Dimensions of the array :return: self

Method `peak_angular_frequency` {#id}

def peak_angular_frequency(
    self,
    fmin=0,
    fmax=inf
) ‑> xarray.core.dataarray.DataArray

Peak frequency of the spectrum, i.e. frequency at which the spectrum obtains its maximum.

:param fmin: minimum frequency :param fmax: maximum frequency :return: peak frequency

Method `peak_direction` {#id}

def peak_direction(
    self,
    fmin=0,
    fmax=inf
) ‑> xarray.core.dataarray.DataArray

Method `peak_directional_spread` {#id}

def peak_directional_spread(
    self,
    fmin=0,
    fmax=inf
) ‑> xarray.core.dataarray.DataArray

Method `peak_frequency` {#id}

def peak_frequency(
    self,
    fmin=0.0,
    fmax=inf,
    use_spline=False,
    **kwargs
) ‑> xarray.core.dataarray.DataArray

Peak frequency of the spectrum, i.e. frequency at which the spectrum obtains its maximum.

:param fmin: minimum frequency :param fmax: maximum frequency :param use_spline: Use a spline based interpolation and determine peak frequency from the spline. This allows for a continuous estimate of the peak frequency. WARNING: if True the fmin and fmax paramteres are IGNORED :return: peak frequency

Method `peak_index` {#id}

def peak_index(
    self,
    fmin: float = 0,
    fmax: float = inf
) ‑> xarray.core.dataarray.DataArray

Index of the peak frequency of the 1d spectrum within the given range :param fmin: minimum frequency :param fmax: maximum frequency :return: peak indices

Method `peak_period` {#id}

def peak_period(
    self,
    fmin=0,
    fmax=inf,
    use_spline=False,
    **kwargs
) ‑> xarray.core.dataarray.DataArray

Peak period of the spectrum, i.e. period at which the spectrum obtains its maximum.

:param fmin: minimum frequency :param fmax: maximum frequency :return: peak period

Method `peak_wave_speed` {#id}

def peak_wave_speed(
    self
) ‑> xarray.core.dataarray.DataArray

Method `save_as_netcdf` {#id}

def save_as_netcdf(
    self,
    path
)

Method `shape` {#id}

def shape(
    self
)

Method `space_time_shape` {#id}

def space_time_shape(
    self
)

Method `spectral_shape` {#id}

def spectral_shape(
    self
)

Method `std` {#id}

def std(
    self,
    dim: str,
    skipna: bool = False
)

Calculate the standard deviation of the spectrum along the given dimension. :param dim: dimension to calculate standard deviation over :param skipna: whether or not to "skip" nan values; if True behaves as np.nanstd :return:

Method `sum` {#id}

def sum(
    self,
    dim: str,
    skipna: bool = False
)

Calculate the sum value of the spectrum along the given dimension. :param dim: dimension to sum over :param skipna: whether or not to "skip" nan values; if True behaves as np.nansum :return:

Method `tm01` {#id}

def tm01(
    self,
    fmin=0,
    fmax=inf
) ‑> xarray.core.dataarray.DataArray

Mean period, estimated as the inverse of the center of mass of the spectral curve under the 1d spectrum.

:param fmin: minimum frequency :param fmax: maximum frequency :return: Mean period

Method `tm02` {#id}

def tm02(
    self,
    fmin=0,
    fmax=inf
) ‑> xarray.core.dataarray.DataArray

Zero crossing period based on Rice's spectral estimate.

:param fmin: minimum frequency :param fmax: maximum frequency :return: Zero crossing period

Method `wave_age` {#id}

def wave_age(
    self,
    windspeed
)

Method `wave_speed` {#id}

def wave_speed(
    self
) ‑> xarray.core.dataarray.DataArray

:return:

Method `where` {#id}

def where(
    self,
    condition: xarray.core.dataarray.DataArray
)

Module `ocean_science_utilities.wavespectra.timeseries` {#id}

Functions

Function `create_fourier_amplitudes` {#id}

def create_fourier_amplitudes(
    component,
    spectrum: ocean_science_utilities.wavespectra.spectrum.WaveSpectrum,
    frequencies,
    seed=None
)

Function `surface_timeseries` {#id}

def surface_timeseries(
    component: Literal['u', 'v', 'w', 'x', 'y', 'z'],
    sampling_frequency: float,
    signal_length: int,
    spectrum: ocean_science_utilities.wavespectra.spectrum.WaveSpectrum,
    seed: Optional[int] = None
) ‑> Tuple[numpy.ndarray[Any, numpy.dtype[+ScalarType]], numpy.ndarray[Any, numpy.dtype[+ScalarType]]]

Create a timeseries for from a given power spectral density.

:param component: Wave component to create a timeseries for: u,v,w,x,y,z. :param sampling_frequency: Sampling frequency of output signal in Hertz :param signal_length: Length of output signal :param spectrum: Input power spectrum :param seed: Input seed for the random number generator. :return:

Namespace `ocean_science_utilities.wavetheory` {#id}

Sub-modules

ocean_science_utilities.wavetheory.constants
ocean_science_utilities.wavetheory.lineardispersion
ocean_science_utilities.wavetheory.linearkinematics
ocean_science_utilities.wavetheory.wavetheory_tools

Module `ocean_science_utilities.wavetheory.constants` {#id}

Module `ocean_science_utilities.wavetheory.lineardispersion` {#id}

Contents: Routines to calculate (inverse) linear dispersion relation and some related quantities such as phase and group velocity. NOTE: the effect of surface currents is currently not included in these calculations.

The implementation uses numba to speed up calculations. Consequently, all functions are compiled to machine code, but the first call to a function will be slow. Subsequent calls will be much faster.

Authors: Pieter Bart Smit

Functions:

intrinsic_dispersion_relation(), calculate angular frequency for a given wavenumber and depth
inverse_intrinsic_dispersion_relation(), calculate wavenumber for a given angularfrequency and depth
intrinsic_group_velocity(), calculate the group velocity given wave number and depth
phase_velocity(), calculate the phase velocity given wave number and depth
ratio_of_group_to_phase_velocity, calculate the ratio of group to phase velocity given wave number and depth
jacobian_wavenumber_to_radial_frequency(), calculate the Jacobian of the wavenumber to radial frequency transformation
jacobian_radial_frequency_to_wavenumber(), calculate the Jacobian of the radial frequency to wavenumber transformation

Functions

Function `c` {#id}

def c(
    k: numpy.ndarray,
    depth: Union[numbers.Real, numpy.ndarray],
    grav=9.81
) ‑> numpy.ndarray

:param k: Wavenumber (rad/m) :param depth: Depth (m) :param grav: Gravitational acceleration (m/s^2) :return:

Function `cg` {#id}

def cg(
    k: numpy.ndarray,
    depth: Union[numbers.Real, numpy.ndarray],
    grav=9.81
) ‑> numpy.ndarray

:param k: Wavenumber (rad/m) :param depth: Depth (m) :param grav: Gravitational acceleration (m/s^2) :return:

Function `intrinsic_dispersion_relation` {#id}

def intrinsic_dispersion_relation(
    k: numpy.ndarray,
    dep: Union[numbers.Real, numpy.ndarray],
    grav: float = 9.81
) ‑> numpy.ndarray

The intrinsic dispersion relation for linear waves in water of constant depth that relates the specific angular frequency to a given wavenumber and depth in a reference frame following mean ambient flow.

Wavenumber may be a scalar or a numpy array. The function always returns a numpy array. If depth is specified as a numpy array it must have the same shape as the wavenumber array.

:param k: Wavenumber (rad/m) :param depth: Depth (m) :param grav: Gravitational acceleration (m/s^2) :return: Intrinsic angular frequency (rad/s)

Function `intrinsic_group_velocity` {#id}

def intrinsic_group_velocity(
    k: numpy.ndarray,
    depth: Union[numbers.Real, numpy.ndarray],
    grav=9.81
) ‑> numpy.ndarray

:param k: Wavenumber (rad/m) :param depth: Depth (m) :param grav: Gravitational acceleration (m/s^2) :return:

Function `inverse_intrinsic_dispersion_relation` {#id}

def inverse_intrinsic_dispersion_relation(
    angular_frequency: Union[numbers.Real, numpy.ndarray],
    dep: Union[numbers.Real, numpy.ndarray],
    grav: float = 9.81,
    maximum_number_of_iterations: int = 10,
    tolerance: float = 0.001
) ‑> numpy.ndarray

Find wavenumber k for a given radial frequency w using Newton Iteration. Exit when either maximum number of iterations is reached, or tolerance is achieved. Typically only 1 to 2 iterations are needed.

:param w: radial frequency :param dep: depth in meters :param grav: gravitational acceleration :param maximum_number_of_iterations: maximum number of iterations :param tolerance: relative accuracy :return: The wavenumber as a numpy array.

Function `jacobian_radial_frequency_to_wavenumber` {#id}

def jacobian_radial_frequency_to_wavenumber(
    k: numpy.ndarray,
    depth: Union[numbers.Real, numpy.ndarray],
    grav=9.81
) ‑> numpy.ndarray

:param k: Wavenumber (rad/m) :param depth: Depth (m) :param grav: Gravitational acceleration (m/s^2) :return:

Function `jacobian_wavenumber_to_radial_frequency` {#id}

def jacobian_wavenumber_to_radial_frequency(
    k: numpy.ndarray,
    depth: Union[numbers.Real, numpy.ndarray],
    grav=9.81
) ‑> numpy.ndarray

:param k: Wavenumber (rad/m) :param depth: Depth (m) :param grav: Gravitational acceleration (m/s^2) :return:

Function `k` {#id}

def k(
    angular_frequency: Union[numbers.Real, numpy.ndarray],
    dep: Union[numbers.Real, numpy.ndarray],
    grav: float = 9.81,
    maximum_number_of_iterations: int = 10,
    tolerance: float = 0.001
) ‑> numpy.ndarray

Function `n` {#id}

def n(
    k: numpy.ndarray,
    depth: Union[numbers.Real, numpy.ndarray],
    grav
) ‑> numpy.ndarray

:param k: Wavenumber (rad/m) :param depth: Depth (m) :param grav: Gravitational acceleration (m/s^2) :return:

Function `phase_velocity` {#id}

def phase_velocity(
    k: numpy.ndarray,
    depth: Union[numbers.Real, numpy.ndarray],
    grav=9.81
) ‑> numpy.ndarray

:param k: Wavenumber (rad/m) :param depth: Depth (m) :param grav: Gravitational acceleration (m/s^2) :return:

Function `ratio_group_velocity_to_phase_velocity` {#id}

def ratio_group_velocity_to_phase_velocity(
    k: numpy.ndarray,
    depth: Union[numbers.Real, numpy.ndarray],
    grav
) ‑> numpy.ndarray

:param k: Wavenumber (rad/m) :param depth: Depth (m) :param grav: Gravitational acceleration (m/s^2) :return:

Function `w` {#id}

def w(
    k: numpy.ndarray,
    dep: Union[numbers.Real, numpy.ndarray],
    grav: float = 9.81
) ‑> numpy.ndarray

Wavenumber may be a scalar or a numpy array. The function always returns a numpy array. If depth is specified as a numpy array it must have the same shape as the wavenumber array.

:param k: Wavenumber (rad/m) :param depth: Depth (m) :param grav: Gravitational acceleration (m/s^2) :return: Intrinsic angular frequency (rad/s)

Module `ocean_science_utilities.wavetheory.linearkinematics` {#id}

Functions

Function `horizontal_particle_velocity_amplitude` {#id}

def horizontal_particle_velocity_amplitude(
    surface_amplitude: numpy.ndarray,
    k: numpy.ndarray,
    z: numpy.ndarray,
    depth: Union[numbers.Real, numpy.ndarray],
    surface_elevation: int = 0,
    grav: float = 9.81
) ‑> numpy.ndarray

:param surface_amplitude: Surface amplitude (m) :param k: Wavenumber (rad/m) :param z: Depth (m) :param depth: Depth (m) :param direction: Direction (rad) :param grav: Gravitational acceleration (m/s^2) :return:

Function `particle_velocity_amplitude_x` {#id}

def particle_velocity_amplitude_x(
    surface_amplitude: numpy.ndarray,
    direction: numpy.ndarray,
    k: numpy.ndarray,
    z: numpy.ndarray,
    depth: Union[numbers.Real, numpy.ndarray],
    surface_elevation: int = 0,
    grav: float = 9.81
)

Function `particle_velocity_amplitude_y` {#id}

def particle_velocity_amplitude_y(
    surface_amplitude: numpy.ndarray,
    direction: numpy.ndarray,
    k: numpy.ndarray,
    z: numpy.ndarray,
    depth: Union[numbers.Real, numpy.ndarray],
    surface_elevation: int = 0,
    grav: float = 9.81
)

Function `particle_velocity_amplitude_z` {#id}

def particle_velocity_amplitude_z(
    surface_amplitude: numpy.ndarray,
    k: numpy.ndarray,
    z: numpy.ndarray,
    depth: Union[numbers.Real, numpy.ndarray],
    surface_elevation: int = 0,
    grav: float = 9.81
)

:param surface_amplitude: Surface amplitude (m) :param k: Wavenumber (rad/m) :param z: Depth (m) :param depth: Depth (m) :param grav: Gravitational acceleration (m/s^2) :return:

Function `pressure_amplitude` {#id}

def pressure_amplitude(
    surface_amplitude: numpy.ndarray,
    k: numpy.ndarray,
    z: numpy.ndarray,
    depth: Union[numbers.Real, numpy.ndarray],
    surface_elevation: int = 0,
    grav: float = 9.81,
    density=1024.0
)

:param surface_amplitude: Surface amplitude (m) :param k: Wavenumber (rad/m) :param z: Depth (m) :param depth: Depth (m) :param grav: Gravitational acceleration (m/s^2) :return:

Function `s_coordinate` {#id}

def s_coordinate(
    z: numpy.ndarray,
    depth: Union[numbers.Real, numpy.ndarray],
    surface_elevation: int = 0
)

:param k: Wavenumber (rad/m) :param z: Depth (m) :param depth: Depth (m) :param direction: Direction (rad) :param grav: Gravitational acceleration (m/s^2) :return:

Function `vertical_particle_velocity_amplitude` {#id}

def vertical_particle_velocity_amplitude(
    surface_amplitude: numpy.ndarray,
    k: numpy.ndarray,
    z: numpy.ndarray,
    depth: Union[numbers.Real, numpy.ndarray],
    surface_elevation: int = 0,
    grav: float = 9.81
) ‑> numpy.ndarray

Module `ocean_science_utilities.wavetheory.wavetheory_tools` {#id}

Functions

Function `atleast_1d` {#id}

def atleast_1d(
    x
) ‑> numpy.ndarray

Function `atleast_2d` {#id}

def atleast_2d(
    x
) ‑> numpy.ndarray

Function `overloaded_atleast_1d` {#id}

def overloaded_atleast_1d(
    x
)

Function `overloaded_atleast_2d` {#id}

def overloaded_atleast_2d(
    x
)

Generated by pdoc 0.10.0 (https://pdoc3.github.io).

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

0.0.1

Aug 14, 2023

This version

0.0.0

Aug 14, 2023

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ocean_science_utils-0.0.0.tar.gz (176.5 kB view hashes)

Uploaded Aug 14, 2023 Source

Built Distribution

ocean_science_utils-0.0.0-py3-none-any.whl (148.7 kB view hashes)

Uploaded Aug 14, 2023 Python 3

Hashes for ocean_science_utils-0.0.0.tar.gz

Hashes for ocean_science_utils-0.0.0.tar.gz
Algorithm	Hash digest
SHA256	`510a06fad4b1322b590ad716b07ff5006b45a020e061e3915f2d88f020f7bcdf`
MD5	`45907e15f69531f0256951eacbf090f9`
BLAKE2b-256	`b873c5f60a83740fa6035ad81f42946dd2f3dbdc02167140104998f276a40cc3`

Hashes for ocean_science_utils-0.0.0-py3-none-any.whl

Hashes for ocean_science_utils-0.0.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`dc80bdad08fc6bb2fc64025b033032a9b41fb803a66cf277f8e1fe74fe790ada`
MD5	`b4109b0a5e37e063844790383ce5195f`
BLAKE2b-256	`086b505073bc51d2e6503bc9d2fa7e6bfee27efb8460502148ebeecccbbfef35`

ocean-science-utils 0.0.0

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

Namespace ocean_science_utilities {#id}

Sub-modules

Namespace ocean_science_utilities.filecache {#id}

Sub-modules

Module ocean_science_utilities.filecache.cache_object {#id}

Authors: Pieter Bart Smit

Functions

Function do_nothing {#id}

Function parse_directive {#id}

Function parse_directives {#id}

Classes

Class CacheMiss {#id}

Class variables

Variable allow_for_missing_files {#id}

Variable filename {#id}

Variable filepath {#id}

Variable post_process_function {#id}

Variable uri {#id}

Methods

Method download_function {#id}

Class FileCache {#id}

do stuff with file

Class variables

Variable CACHE_FILE_POSTFIX {#id}

Variable CACHE_FILE_PREFIX {#id}

Methods

Method get_cache_misses {#id}

Method in_cache {#id}

Method purge {#id}

Method remove {#id}

Method remove_directive_function {#id}

Method set_directive_function {#id}

Class FileCacheConfig {#id}

Instance variables

Variable allow_for_missing_files {#id}

Variable max_size {#id}

Variable max_size_bytes {#id}

Variable name {#id}

Variable parallel {#id}

Methods

Method config_exists {#id}

Method load_config {#id}

Module ocean_science_utilities.filecache.filecache {#id}

Authors: Pieter Bart Smit

Functions

Function create_cache {#id}

Function delete_cache {#id}

Function delete_default {#id}

Function delete_files {#id}

Function exists {#id}

Function filepaths {#id}

Function get_cache {#id}

Function remove_directive_function {#id}

Function set {#id}

Function set_directive_function {#id}

Module ocean_science_utilities.filecache.remote_resources {#id}

Authors: Pieter Bart Smit

Classes

Class RemoteResource {#id}

Descendants

Class variables

Variable URI_PREFIX {#id}

Methods

Method download {#id}

Method valid_uri {#id}

Class RemoteResourceHTTPS {#id}

Ancestors (in MRO)

Class variables

Variable URI_PREFIX {#id}

Class RemoteResourceLocal {#id}

Ancestors (in MRO)

Namespace `ocean_science_utilities` {#id}

Namespace `ocean_science_utilities.filecache` {#id}

Module `ocean_science_utilities.filecache.cache_object` {#id}

Function `do_nothing` {#id}

Function `parse_directive` {#id}

Function `parse_directives` {#id}

Class `CacheMiss` {#id}

Variable `allow_for_missing_files` {#id}

Variable `filename` {#id}

Variable `filepath` {#id}

Variable `post_process_function` {#id}

Variable `uri` {#id}

Method `download_function` {#id}

Class `FileCache` {#id}

Variable `CACHE_FILE_POSTFIX` {#id}

Variable `CACHE_FILE_PREFIX` {#id}

Method `get_cache_misses` {#id}

Method `in_cache` {#id}

Method `purge` {#id}

Method `remove` {#id}

Method `remove_directive_function` {#id}

Method `set_directive_function` {#id}

Class `FileCacheConfig` {#id}

Variable `allow_for_missing_files` {#id}

Variable `max_size` {#id}

Variable `max_size_bytes` {#id}

Variable `name` {#id}

Variable `parallel` {#id}

Method `config_exists` {#id}

Method `load_config` {#id}

Module `ocean_science_utilities.filecache.filecache` {#id}

Function `create_cache` {#id}

Function `delete_cache` {#id}

Function `delete_default` {#id}

Function `delete_files` {#id}

Function `exists` {#id}

Function `filepaths` {#id}

Function `get_cache` {#id}

Function `remove_directive_function` {#id}

Function `set` {#id}

Function `set_directive_function` {#id}

Module `ocean_science_utilities.filecache.remote_resources` {#id}

Class `RemoteResource` {#id}

Variable `URI_PREFIX` {#id}

Method `download` {#id}

Method `valid_uri` {#id}

Class `RemoteResourceHTTPS` {#id}

Variable `URI_PREFIX` {#id}

Class `RemoteResourceLocal` {#id}

Variable `URI_PREFIX` {#id}

Namespace `ocean_science_utilities.interpolate` {#id}

Module `ocean_science_utilities.interpolate.dataarray` {#id}

Function `interpolate_track_data_arrray` {#id}

Module `ocean_science_utilities.interpolate.dataframe` {#id}

Function `interpolate_dataframe_time` {#id}

Module `ocean_science_utilities.interpolate.dataset` {#id}

Function `interpolate_at_points` {#id}

Function `interpolate_dataset` {#id}

Function `interpolate_dataset_along_axis` {#id}

Function `interpolate_dataset_grid` {#id}

Function `tracks_as_dataset` {#id}

Module `ocean_science_utilities.interpolate.general` {#id}

Function `interpolate_periodic` {#id}

Function `interpolation_weights_1d` {#id}

Module `ocean_science_utilities.interpolate.geometry` {#id}

Function `convert_to_cluster_stack` {#id}

Function `convert_to_track_set` {#id}

Class `Cluster` {#id}

Variable `points` {#id}

Variable `ids` {#id}

Variable `latitude` {#id}

Variable `longitude` {#id}

`Method from_lat_lon_arrays` {#id}

Class `ClusterStack` {#id}

Variable `clusters` {#id}

Variable `time` {#id}

`Method from_track_set` {#id}

Method `as_track_set` {#id}

Class `SpaceTimePoint` {#id}

Variable `time` {#id}