Internal

Contains a collection of support classes/functions/lists for the PRISM package.

exception prism._internal.FeatureWarning[source]

Generic warning raised for experimental features in PRISM.

General purpose warning class, raised whenever a feature is used that should be considered experimental. Its behavior and API are subject to change, or the entire feature may be removed without a deprecation period.

exception prism._internal.RequestError[source]

Generic exception raised for invalid action requests in the PRISM pipeline.

General purpose exception class, raised whenever a requested action cannot be executed due to it not being allowed or possible in the current state of the Pipeline instance.

exception prism._internal.RequestWarning[source]

Generic warning raised for (future) action requests in the PRISM pipeline that may not be useful.

General purpose warning class, raised whenever a requested action may not produce appropriate or expected results due to the current state of the Pipeline instance. It is also raised if an obtained result can lead to such an action in the future.

class prism._internal.CFilter(MPI_rank)[source]

Custom Filter class that only allows the controller rank to log messages to the logfile. Calls from worker ranks are ignored.

class prism._internal.PRISM_Comm(comm=None)[source]

Custom Intracomm class that automatically makes use of the ndarray buffers when using communications. Is functionally the same as the provided comm for everything else.

Other Parameters:
 comm (Intracomm object or None. Default: None) – The MPI intra-communicator to use in this PRISM_Comm instance. If None, use MPI.COMM_WORLD instead.
bcast(obj, root)[source]

Special broadcast method that automatically uses the appropriate method (bcast() or Bcast()) depending on the type of the provided obj.

Parameters:
  • obj (ndarray or object) – The object to broadcast to all MPI ranks. If ndarray, use Bcast(). If not, use bcast() instead.
  • root (int) – The MPI rank that broadcasts obj.
Returns:

obj (object) – The broadcasted obj.

gather(obj, root)[source]

Special gather method that automatically uses the appropriate method (gather() or Gatherv()) depending on the type of the provided obj.

Parameters:
  • obj (ndarray or object) – The object to gather from all MPI ranks. If ndarray, use Gatherv(). If not, use gather() instead.
  • root (int) – The MPI rank that gathers obj.
Returns:

obj (list or None) – If MPI rank is root, returns a list of the gathered objects. Else, returns None.

Warning

If some but not all MPI ranks use a NumPy array, this method will hang indefinitely. When gathering NumPy arrays, all arrays must have the same number of dimensions and the same shape, except for one axis.

class prism._internal.PRISM_Logger(*args, **kwargs)[source]

Special Logger class that allows for special filters to be set more easily.

class prism._internal.RFilter(MPI_rank)[source]

Custom Filter class that prepends the rank of the MPI process that calls it to the logging message. If the size of the used MPI intra-communicator is 1, this filter does nothing.

prism._internal.check_compatibility(emul_version)[source]

Checks if the provided emul_version is compatible with the current version of PRISM. Raises a RequestError if False and indicates which version of PRISM still supports the provided emul_version.

prism._internal.check_instance(instance, cls)[source]

Checks if provided instance has been initialized from a proper cls (sub)class. Raises a TypeError if instance is not an instance of cls.

Parameters:
  • instance (object) – Class instance that needs to be checked.
  • cls (class) – The class which instance needs to be properly initialized from.
Returns:

result (bool) – Bool indicating whether or not the provided instance was initialized from a proper cls (sub)class.

prism._internal.check_vals(values, name, *args)[source]

Checks if all values in provided input argument values with name meet all criteria given in args. If no criteria are given, it is checked if all values are finite. Returns values (0 or 1 in case of bool) if True and raises a ValueError or TypeError if False.

Parameters:
  • values (array_like of {int, float, str, bool}) – The values to be checked against all given criteria in args. It must be possible to convert values to a ndarray object.
  • name (str) – The name of the input argument, which is used in the error message if a criterion is not met.
  • args (tuple of {‘bool’, ‘float’, ‘int’, ‘neg’, ‘nneg’, ‘normal’, ‘npos’, ‘nzero’, ‘pos’, ‘str’}) – Sequence of strings determining the criteria that values must meet. If args is empty, it is checked if values are finite.
Returns:

return_values (array_like of {int, float, str}) – If args contained ‘bool’, returns 0s or 1s. Else, returns values.

Notes

If values contains integers, but args contains ‘float’, return_values will be cast as float.

prism._internal.convert_str_seq(seq)[source]

Converts a provided sequence to a string, removes all auxiliary characters from it, splits it up into individual elements and converts all elements back to integers, floats and/or strings.

The auxiliary characters are given by the aux_char_list list. One can add, change and remove characters from the list if required.

Parameters:seq (str or array_like) – The sequence that needs to be converted to individual elements. If array_like, seq is first converted to a string.
Returns:new_seq (list) – A list with all individual elements converted to integers, floats and/or strings.
prism._internal.delist(list_obj)[source]

Returns a copy of list_obj with all empty lists and tuples removed.

Parameters:list_obj (list) – A list object that requires its empty list/tuple elements to be removed.
Returns:delisted_copy (list) – Copy of list_obj with all empty lists/tuples removed.
prism._internal.docstring_append(addendum, join='')[source]

Custom decorator that allows a given string addendum to be appended to the docstring of the target function, separated by a given string join.

prism._internal.docstring_copy(source)[source]

Custom decorator that allows the docstring of a function source to be copied to the target function.

prism._internal.docstring_substitute(*args, **kwargs)[source]

Custom decorator that allows either given positional arguments args or keyword arguments kwargs to be substituted into the docstring of the target function.

prism._internal.get_PRISM_File(prism_hdf5_file)[source]

Returns a class definition PRISM_File(mode, emul_s=None, **kwargs).

This class definition is a specialized version of the File class with the filename automatically set to prism_hdf5_file and added logging to the constructor and destructor methods.

Parameters:prism_hdf5_file (str) – Absolute path to the master HDF5-file that is used in a Pipeline instance.
Returns:PRISM_File (class) – Definition of the class PRISM_File(mode, emul_s=None, **kwargs).
prism._internal.get_formatter()[source]

Returns a Formatter object containing the default logging formatting.

prism._internal.get_handler(filename)[source]

Returns a Handler object containing the default logging handling settings.

prism._internal.get_info()[source]

Prints a string that gives an overview of all information relevant to the PRISM package distribution.

prism._internal.getCLogger(name=None)[source]

Creates a PRISM_Logger instance with name, adds the CFilter to it and returns it.

prism._internal.getLogger(name=None, filters=None)[source]

Creates a PRISM_Logger instance with name and adds the provided filters to it. The returned PRISM_Logger instance is a child of the base PRISM_Logger created with set_base_logger(), but has its name changed (such that the parent name does not show up in the log-file).

Other Parameters:
 
  • name (str or None. Default: None) – The name of the PRISM_Logger instance to create. If None, initialize the base PRISM_Logger instead.
  • filters (list of str or None. Default: None) – List of strings naming the filters that must be applied to the created PRISM_Logger instance. If None, no filters will be applied.
Returns:

logger (PRISM_Logger object) – The created PRISM_Logger instance.

prism._internal.getRLogger(name=None)[source]

Creates a PRISM_Logger instance with name, adds the RFilter to it and returns it.

prism._internal.import_cmaps(cmap_dir)[source]

Reads in custom colormaps from a provided directory cmap_dir, transforms them into LinearSegmentedColormap objects and registers them in the cm module. Both the imported colormap and its reversed version will be registered.

This function is called automatically when PRISM is imported.

Parameters:cmap_dir (str) – Relative or absolute path to the directory that contains custom colormap files. A colormap file can be a NumPy binary file (‘.npy’ or ‘.npz’) or any text file.

Notes

All colormap files in cmap_dir must have names starting with ‘cm_’. The resulting colormaps will have the name of their file without the prefix and extension.

prism._internal.move_logger(working_dir)[source]

Moves the base PRISM_Logger from the current working directory to the given working_dir, and then restarts it again.

Parameters:working_dir (str) – String containing the directory the log-file needs to be moved to.
prism._internal.np_array(obj, *args, **kwargs)[source]

Returns np.array(obj, *args, copy=False, **kwargs).

prism._internal.raise_error(err_msg, err_type=<class 'Exception'>, logger=None)[source]

Raises a given error err_msg of type err_type and logs the error using the provided logger.

Parameters:

err_msg (str) – The message included in the error.

Other Parameters:
 
  • err_type (Exception subclass. Default: Exception) – The type of error that needs to be raised.
  • logger (Logger object or None. Default: None) – The logger to which the error message must be written. If None, the RootLogger logger is used instead.
prism._internal.raise_warning(warn_msg, warn_type=<class 'UserWarning'>, logger=None, stacklevel=1)[source]

Raises a given warning warn_msg of type warn_type and logs the warning using the provided logger.

Parameters:

warn_msg (str) – The message included in the warning.

Other Parameters:
 
  • warn_type (Warning subclass. Default: UserWarning) – The type of warning that needs to be raised.
  • logger (Logger object or None. Default: None) – The logger to which the warning message must be written. If None, the RootLogger logger is used instead.
  • stacklevel (int. Default: 1) – The stack level of the warning message at the location of this function call. The actual used stack level is increased by one.
prism._internal.rprint(*args, **kwargs)[source]

Custom print() function that prepends the rank of the MPI process that calls it to the message if the size of the intra-communicator is more than 1. Takes the same input arguments as the normal print() function.

prism._internal.set_base_logger(filename=None)[source]

Initializes the base PRISM_Logger, from which all other PRISM_Logger instances are derived.

Other Parameters:
 filename (str or None. Default: None) – String containing the name of the log-file that is opened. If None, a new log-file will be created.