Tools & utilities¶

Assets¶

veros.tools.assets.get_assets(asset_id, asset_file, skip_md5=False)[source]¶

Handles automatic download and verification of external assets (such as forcing files).

By default, assets are stored in $HOME/.veros/assets (can be overwritten by setting VEROS_ASSET_DIR environment variable to the desired location).

Parameters:

asset_id (str) – Identifier of the collection of assets. Should be unique for each setup.
asset_file (str) – JSON file containing URLs and (optionally) MD5 hashsums of each asset.
skip_md5 (bool) – Whether to skip MD5 checksum validation (useful for huge asset files)

Returns:

A dict-like mapping of each asset to file name on disk. Assets are downloaded lazily.

Example

>>> assets = get_assets('mysetup', 'assets.json')
>>> assets['forcing']
"/home/user/.veros/assets/mysetup/mysetup_forcing.h5",
    "initial_conditions": "/home/user/.veros/assets/mysetup/initial.h5"
}

In this case, assets.json contains:

{
    "forcing": {
        "url": "https://mywebsite.com/veros_assets/mysetup_forcing.h5",
        "md5": "ef3be0a58782771c8ee5a6d0206b87f6"
    },

    "initial_conditions": {
        "url": "https://mywebsite.com/veros_assets/initial.h5",
        "md5": "d1b4e0e199d7a5883cf7c88d3d6bcb28"
    }
}

Setup tools¶

veros.tools.setup.interpolate(coords, var, interp_coords, missing_value=None, fill=True, kind='linear')[source]¶

Interpolate globally defined data to a different (regular) grid.

Parameters:

coords – Tuple of coordinate arrays for each dimension.
var (ndarray of dim (nx1, …, nxd)) – Variable data to interpolate.
interp_coords – Tuple of coordinate arrays to interpolate to.
missing_value (optional) – Value denoting cells of missing data in var. Is replaced by NaN before interpolating. Defaults to None, which means no replacement is taking place.
fill (bool, optional) – Whether NaN values should be replaced by the nearest finite value after interpolating. Defaults to True.
kind (str, optional) – Order of interpolation. Supported are nearest and linear (default).

Returns:

ndarray containing the interpolated values on the grid spanned by interp_coords.

veros.tools.setup.fill_holes(data)[source]¶: A simple inpainting function that replaces NaN values in data with the nearest finite value.

veros.tools.setup.get_periodic_interval(current_time, cycle_length, rec_spacing, n_rec)[source]¶

Used for linear interpolation between periodic time intervals.

One common application is the interpolation of external forcings that are defined at discrete times (e.g. one value per month of a standard year) to the current time step.

Parameters:

current_time (float) – Time to interpolate to.
cycle_length (float) – Total length of one periodic cycle.
rec_spacing (float) – Time spacing between each data record.
n_rec (int) – Total number of records available.

Returns:

Indices and weights for the interpolated record array.

Return type:

tuple containing (n1, f1), (n2, f2)

Example

The following interpolates a record array data containing 12 monthly values to the current time step:

>>> year_in_seconds = 60. * 60. * 24. * 365.
>>> current_time = 60. * 60. * 24. * 45. # mid-february
>>> print(data.shape)
(360, 180, 12)
>>> (n1, f1), (n2, f2) = get_periodic_interval(current_time, year_in_seconds, year_in_seconds / 12, 12)
>>> data_at_current_time = f1 * data[..., n1] + f2 * data[..., n2]

veros.tools.setup.make_cyclic(longitude, array=None, wrap=360.0)[source]¶

Create a cyclic version of a longitude array and (optionally) another array.

Parameters:

longitude (ndarray) – Longitude array of shape (nlon, …).
array (ndarray) – Another array that is to be made cyclic of shape (nlon, …).
wrap (float) – Wrapping value, defaults to 360 (degrees).

Returns:

Tuple containing (cyclic_longitudes, cyclic_array) if array is given, otherwise just the ndarray cyclic_longitudes of shape (2 * nlon, …).

veros.tools.setup.get_coastline_distance(coords, coast_mask, spherical=False, radius=None, num_candidates=None)[source]¶

Calculate the (approximate) distance of each water cell from the nearest coastline.

Parameters:

coords (tuple of ndarrays) – Tuple containing x and y (longitude and latitude) coordinate arrays of shape (nx, ny).
coast_mask (ndarray) – Boolean mask indicating whether a cell is a land cell (must be same shape as coordinate arrays).
spherical (bool) – Use spherical instead of Cartesian coordinates. When this is True, cyclical boundary conditions are used, and the resulting distances are only approximate. Cells are pre-sorted by Euclidean lon-lat distance, and great circle distances are calculated for the first num_candidates elements. Defaults to False.
radius (float) – Radius of spherical coordinate system. Must be given when spherical is True.
num_candidates (int) – Number of candidates to calculate great circle distances for for each water cell. The higher this value, the more accurate the returned distances become when spherical is True. Defaults to the square root of the number of coastal cells.

Returns:

ndarray of shape (nx, ny) indicating the distance to the nearest land cell (0 if cell is land).

Example

The following returns coastal distances of all T cells for a spherical Veros setup.

>>> coords = npx.meshgrid(vs.xt[2:-2], vs.yt[2:-2], indexing='ij')
>>> dist = tools.get_coastline_distance(coords, vs.kbot > 0, spherical=True, radius=settings.radius)

veros.tools.setup.get_uniform_grid_steps(total_length, stepsize)[source]¶

Get uniform grid step sizes in an interval.

Parameters:

total_length (float) – total length of the resulting grid
stepsize (float) – grid step size

Returns:

ndarray of grid steps

Example

>>> uniform_steps = uniform_grid_setup(6., 0.25)
>>> uniform_steps
[ 0.25,  0.25,  0.25,  0.25,  0.25,  0.25,  0.25,  0.25,  0.25,
  0.25,  0.25,  0.25,  0.25,  0.25,  0.25,  0.25,  0.25,  0.25,
  0.25,  0.25,  0.25,  0.25,  0.25,  0.25 ]

veros.tools.setup.get_stretched_grid_steps(n_cells, total_length, minimum_stepsize, stretching_factor=2.5, two_sided_grid=False, refine_towards='upper')[source]¶

Computes stretched grid steps for regional and global domains with either one or two-sided stretching using a hyperbolic tangent stretching function.

Parameters:

n_cells (int) – Number of grid points.
total_length (float) – Length of the grid interval to be covered (sum of the resulting grid steps).
minimum_stepsize (float) – Grid step size on the lower end of the interval.
stretching_factor (float, optional) – Coefficient of the tanh stretching function. The higher this value, the more abrupt the step sizes change.
two_sided_grid (bool, optional) – If set to True, the resulting grid will be symmetrical around the center. Defaults to False.
refine_towards ('upper' or 'lower', optional) – The side of the interval that is to be refined. Defaults to ‘upper’.

Returns:

ndarray of shape (n_cells) containing grid steps.

Examples

>>> dyt = get_stretched_grid_steps(14, 180, 5)
>>> dyt
[  5.10517337   5.22522948   5.47813251   5.99673813   7.00386752
   8.76808565  11.36450896  14.34977676  16.94620006  18.71041819
  19.71754758  20.2361532   20.48905624  20.60911234]
>>> dyt.sum()
180.0

>>> dyt = get_stretched_grid_steps(14, 180, 5, stretching_factor=4.)
>>> dyt
[  5.00526979   5.01802837   5.06155549   5.20877528   5.69251688
   7.14225176  10.51307232  15.20121339  18.57203395  20.02176884
  20.50551044  20.65273022  20.69625734  20.70901593]
>>> dyt.sum()
180.0

veros.tools.setup.get_vinokur_grid_steps(n_cells, total_length, lower_stepsize, upper_stepsize=None, two_sided_grid=False, refine_towards='upper')[source]¶

Computes stretched grid steps for regional and global domains with either one or two-sided stretching using Vinokur stretching.

This stretching function minimizes discretization errors on finite difference grids.

Parameters:

n_cells (int) – Number of grid points.
total_length (float) – Length of the grid interval to be covered (sum of the resulting grid steps).
lower_stepsize (float) – Grid step size on the lower end of the interval.
upper_stepsize (float or None, optional) – Grid step size on the upper end of the interval. If not given, the one-sided version of the algorithm is used (that enforces zero curvature on the upper end).
two_sided_grid (bool, optional) – If set to True, the resulting grid will be symmetrical around the center. Defaults to False.
refine_towards ('upper' or 'lower', optional) – The side of the interval that is to be refined. Defaults to ‘upper’.

Returns:

ndarray of shape (n_cells) containing grid steps.

Reference:: Vinokur, Marcel, On One-Dimensional Stretching Functions for Finite-Difference Calculations, Journal of Computational Physics. 50, 215, 1983.

Examples

>>> dyt = get_vinokur_grid_steps(14, 180, 5, two_sided_grid=True)
>>> dyt
[ 18.2451554   17.23915939  15.43744632  13.17358802  10.78720589
   8.53852027   6.57892471   6.57892471   8.53852027  10.78720589
  13.17358802  15.43744632  17.23915939  18.2451554 ]
>>> dyt.sum()
180.

>>> dyt = get_vinokur_grid_steps(14, 180, 5, upper_stepsize=10)
>>> dyt
[  5.9818365    7.3645667    8.92544833  10.61326984  12.33841985
  13.97292695  15.36197306  16.3485688   16.80714121  16.67536919
  15.97141714  14.78881918  13.27136448  11.57887877 ]
>>> dyt.sum()
180.