PECANS Utilities

Configuration utilities

exception pecans.utilities.config.ConfigurationError[source]

An error that represents something wrong in the PECANS configuration.

This should be raised specifically if there is something wrong with what the user has given in the config file.

pecans.utilities.config.get_domain_size_from_config(config: dict, all_dims=False)[source]

Helper function that reads the domain size (as a tuple) from a configuration object.

Parameters:

  • config (BetterConfig) – the configuration object to read the domain size from.

  • all_dims (bool) – whether to include just non-zero dimensions (False, default) or all dimensions (True)

Returns:

the shape of the domain, as a tuple with 1, 2, or 3 elements depending if the domain is 1-, 2-, or 3- D.

Return type:

tuple of int

pecans.utilities.config.load_config_file(config_file)[source]

Reads a configuration file and returns a BetterConfig instance representing it

This function automatically instantiates a BetterConfig instance, sets it to parse values into Python literals (including tuples or dicts) :param config_file: the file to read. :type config_file: str or list :return: the BetterConfig object

Domain utilities

pecans.utilities.domain_utilities.compute_coordinates_from_config(config, as_vectors=True)[source]

Calculates the x, y, and z coordinate vectors in kilometers from the origin based on the configuration.

Parameters:

  • config (BetterConfig) – the BetterConfig instance representing the model configuration

  • as_vectors (bool) – whether to return the coordinates as vectors (True, default) or full arrays (False)

Returns:

the x, y, and z coordinates as 1D numpy arrays

Return type:

three numpy.ndarray

pecans.utilities.domain_utilities.coord_arrays_to_vecs(X, Y=None, Z=None)[source]

Convert coordinate arrays to vectors

The reverse operation of coord_vecs_to_arrays(), this takes representations of the model coordinates as arrays (where there is an individual model coordinate for every model box) and returns the vector form.

Parameters:

  • X (numpy.ndarray) – the x-coordinate array

  • Y (numpy.ndarray) – the y-coordinate array

  • Z (numpy.ndarray) – the z-coordinate array

Returns:

the coordinate vectors

Return type:

three numpy.ndarray vectors

pecans.utilities.domain_utilities.coord_vecs_to_arrays(x, y=None, z=None)[source]

Convert coordinate vectors to arrays

In some cases it makes sense to represent the model domain coordinates as vectors, since the domain boxes follow cartesian coordinates, i.e. all boxes along M[0,:,:] will have the same x-coordinate. However, in some cases we need an individual coordinate for every box. This converts the coordinate vectors to the latter representation.

Parameters:

  • x (numpy.ndarray) – the x-coordinates, as a vector

  • y (numpy.ndarray) – the y-coordinates, as a vector

  • z (numpy.ndarray) – the z-coordinates, as a vector

Returns:

the coordinates in array form

Return type:

three numpy.ndarray

IO Utilities

pecans.utilities.io_utils.pretty_print_matrix(A, name='A')[source]

Prints a numpy matrix to the terminal in a human-readable way (provided it isn’t too large)

Parameters:

  • A (numpy.ndarray) – The matrix to print

  • name (str) – a name to print before the matrix, default is “A”, e.g. would print “A = …”, useful to distinguish multiple matrices from each other.

Returns:

none

General utilities

pecans.utilities.general_utils.ensure_n_args_to_return(n_args, args_iterable, fill_val=None)[source]

Create a tuple of arguments to return that is guaranteed to have a certain number of elements

Since Python does tuple expansion, you can return a tuple from a function and have each element of the tuple expanded into individual return values. For example:

def return_tuple():
    return ('a','b','c')

x, y, z = return_tuple()

would put 'a' into x, 'b' into y, and 'c' into z. However, this means that there must be exactly one or three variables to receive the output of return_tuple(), i.e. x, y = return_tuple() would fail. This can be a problem if a function is trying to return a dynamic number of values, since it means the call would have to account for that. This function will create a tuple with a guaranteed number of values.

Parameters:

  • n_args (int) – how many return values you want the tuple to contain

  • args_iterable (list or tuple) – an iterable (currently only tuples and lists supported) that contains <= n_args elements to return.

  • fill_val (any) – optional, the value to append to the returned tuple to fill it out. Default is None.

Returns:

the tuple form of args_iterable with exactly n_args elements

Return type:

tuple

pecans.utilities.general_utils.gaussian(center_x, sigma_x, x, center_y=None, sigma_y=None, y=None, center_z=None, sigma_z=None, z=None, normalized=True)[source]

Compute a Gaussian curve. Currently only implemented for 1D

Parameters:

  • center (float) – the center point in the same coordinates as x, y, and z

  • sigma (float) – the sigma width in the same units as x, y, and z

  • x (numpy.ndarray) – the x-coordinate to compute the Gaussian along.

  • y (numpy.ndarray) – the y-coordinate to compute the Gaussian along.

  • z (numpy.ndarray) – the z-coordinate to compute the Gaussian along.

  • normalized (bool) – whether or not to normalize the gaussian so that its area is 1. Default is True.

Returns:

an array of size nx-by-ny-by-nz.

Return type:

numpy.ndarray.