Miscellaneous Utility Functions#

This module provides access to further Miscellaneous operations those didn’t quite fit in the other utility modules. Functions here can be moved to new utility modules if they grow in their own category. Proper announcements will be made in this case.

isnumber(x, real_only=False)[source]#

Check if a given variable x is a number, defined as: - integer - float - complex number - boolean

Parameters:

  • x – variable to be checked

  • real_only – if True, limit to the set of integers and floating point numbers.

Return type:

bool

isstring(s)[source]#

Check if s is a string-like variable, i.e. a string or a bytes object or encodable with ascii.

Parameters:

s – variable to be checked

Return type:

bool

isiterable(a)[source]#

Check if a is an iterable object.

Parameters:

a – variable to be checked

Return type:

bool

aggregate(configs, def_configs, in_place=False, deep_copy=False, keep_None=True)[source]#

Add default configurations to the passed configs dictionary, i.e., blindly (and recursively) combine the two dictionaries. This is a one-way merge from def_configs to configs only.

Parameters:

  • configs (dict) – a dictionary containing configurations to update

  • def_configs (dict)

  • in_place (bool) – if True overwrite configs (in place) otherwise return a COPY of configs with keys/values aggregate with those in def_configs.

  • deep_copy (bool) – if True deep copy of entries def_configs are merged with entries of configs, otherwise only shallow copies are taken. Deep copy is more relevant to compound objects.

  • keep_None (bool) – if True any keyed value in configs that is set to None will be kept, otherwise it will be overridden by the value associated with the corresponding key in def_configs

Raises:

  • ValueError if both configs and def_configs are None

  • TypeError if configs or def_configs are neither None or drerived from Python dict

Returns:

an updated version of configs with keys/values from both configs and def_configs.

aggregate_configurations(configs, def_configs, in_place=False, deep_copy=False, keep_None=True)#

Add default configurations to the passed configs dictionary, i.e., blindly (and recursively) combine the two dictionaries. This is a one-way merge from def_configs to configs only.

Parameters:

  • configs (dict) – a dictionary containing configurations to update

  • def_configs (dict)

  • in_place (bool) – if True overwrite configs (in place) otherwise return a COPY of configs with keys/values aggregate with those in def_configs.

  • deep_copy (bool) – if True deep copy of entries def_configs are merged with entries of configs, otherwise only shallow copies are taken. Deep copy is more relevant to compound objects.

  • keep_None (bool) – if True any keyed value in configs that is set to None will be kept, otherwise it will be overridden by the value associated with the corresponding key in def_configs

Raises:

  • ValueError if both configs and def_configs are None

  • TypeError if configs or def_configs are neither None or drerived from Python dict

Returns:

an updated version of configs with keys/values from both configs and def_configs.

print_configs(configs, header='', prefix='')[source]#

Print (to screen) elements of a configurations dictionary configs

Parameters:

configs (dict) – configurations dictionary

Header str header:

printed before all configurations

Prefix str prefix:

string added before all printed lines. Useful for nested configs

Raises:

AssertionError if parameters are not exactly the correct type, i.e. cast your header and prefix to strings beforehand.

path_is_accessible(path)[source]#

Test if the passed path (to a directory) is accessible; that is the user can save/write files under that folder/directory. This tests whether the path exists or is creatble.

Parameters:

path – path to folder/directory

Returns:

True if the path is writable, otherwise False

get_list_of_files(root_dir, recursive=False, return_abs=True, ignore_special_files=True, ignore_special_dirs=True, extension=None)[source]#

Retrieve a list of files in the passed root_dir, (and optionally in all sub-directories).

Parameters:

  • root_dir (str) – directory to start constructing sub-directories of.

  • recursive (bool) – if True, the passed files are found in subdirectories as well. Default is False.

  • return_abs (bool) – if True, returned paths are absolute, otherwise relative (to root_dir). Default is True.

  • ignore_special_files (bool) – if True this function ignores special files (starting with . or __ ). Default is True.

  • ignore_special_dirs (bool) – if True this function ignores any files under special directories (starting with . or __ ). Default is True.

  • extension (str) – if not None, only files with the given extension are returned.

Returns:

a list containing absolute (or relative) under the given root_dir.

Raises:

IOError: If the passed path/directory does not exist

get_list_of_subdirectories(root_dir, ignore_root=False, return_abs=False, ignore_special=True, recursive=True)[source]#

Retrieve a list of sub-directories .

Parameters:

  • root_dir (str) – directory to start constructing sub-directories of.

  • ignore_root (bool) – if True, the passed root_dir is ignored in the returned list. Default is False.

  • return_ab (bool) – if True, returned paths are absolute, otherwise relative (to root_dir). Default is False.

  • ignore_special (bool) – if True, this function ignores special files (starting with . or __ ). Default is True.

  • recursive (bool) – if True, search subdirectories recursively. Default is True.

Returns:

A list containing subdirectories under the given root_dir; the subdires are absolute paths or relative paths based the passed root. If root_dir has no subdirectories, the list is empty.

Raises:

IOError: If the passed path/directory does not exist

try_file_name(directory, file_prefix, extension)[source]#

In directory, search for smallest i such that f”{file_prefix}_{i}.{extension}” does not exist and return said file name.

Parameters:

  • directory (str) – directory to search in.

  • file_prefix (str) – file name prefix.

  • extension (str) – file name extension.

Return type:

str

validate_Cartesian_grid(grid, points_as_rows=True, points_ndim_test=True)[source]#

Given a 1D/2D Numpy array characterizing a (Cartesian representation of a ) model grid, validate the shape, and create a two-dimensional numpy array with each row/column (based on points_as_rows) representing one coordinate point. Additionally, The repeatition of coordinates means multiple prognostic variables are considered by the model; This function finds indexes corresponding to each of the prognostic variables and make sure they are layed out in a reasonable fashion:

  • all prognostic variables are consecutive to each other, or

  • the whole grid is layed out for each prognostic variable.

Parameters:

  • grid – The model grid; this is an iterable (list/array/etc.) to be casted as a numpy array.

  • points_as_rows (bool) – used only for grids in 2D or more. If True, each row (after casting in an np array) is regarded as a single grid point. Thus, the number of columns is taken as the space dimension. Note that the default behaviour in all implemented simulation model is to provide points as rows, though a flag needs to go there to control it.

  • points_ndim_test (bool) – if True assert that the number of grid points exceed the number of dimensions; this requires the number of grid points in 1D system to be at least 2, etc.

Returns:

  • grid: validated model grid (either 1D or 2D Numpy array based on the input (passed) grid)

  • prog_vars_indexes: a list containing indexes of the prognostic variables;

    each entry is a numpy array holding indexes of one prognostic variable.

Raises:
  • TypeError is raised if grid cannot be casted into a numpy array or if the array doesn’t hold

    coordinates of one/two dimensional cartesian system

  • AssertionError is raised if points_ndim_test is True and number of points does not

    satisfy the test indicated above.

Remarks:

  • Number of gridpoints must be more than the dimensionality of the coordinate system.

  • The coordinate system dimension is assumed to be the minimum of rows/columns of the passed grid;

    Transposition is carried out if needed

gridpoint_to_index(coord, grid, return_all=False)[source]#
Lookup coordinates coord in the rows of grid and return the first index

(or all) found in the rows of grid.

Parameters:

  • coord – a scalar (for 1d grids) or a tuple/list of length equal to the number of columns in grid

  • grid – a 2D numpy array representing the cartesian grid. Each row is a set of coordinates (x, y, …)

  • return_all (bool) – if True all matching indices are returned, otherwise only the first found index is returned.

Returns:

integer index of the first (if return_all is True) or a numpy array of all indices (if return_all is False) of matching coordinates in grid to the passed ccord. None is returned if no matching coordinates are found.