Internal¶
Contains a collection of support classes/functions/lists for the PRISM package.
-
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 thendarray
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 thisPRISM_Comm
instance. If None, useMPI.COMM_WORLD
instead.-
bcast
(obj, root)[source]¶ Special broadcast method that automatically uses the appropriate method (
bcast()
orBcast()
) depending on the type of the provided obj.Parameters: Returns: obj (object) – The broadcasted obj.
-
gather
(obj, root)[source]¶ Special gather method that automatically uses the appropriate method (
gather()
orGatherv()
) depending on the type of the provided obj.Parameters: Returns: obj (list or None) – If MPI rank is root, returns a list of the gathered objects. Else, returns None.
Notes
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.
RFilter
(MPI_rank)[source]¶ Custom
Filter
class that prepends the rank of the MPI process that calls it to the logging message.
-
class
prism._internal.
RLogger
(*args, **kwargs)[source]¶ Custom
Logger
class that uses theRFilter
if the size of the intra-communicator is more than 1.
-
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
orTypeError
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.
- 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
-
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_info
()[source]¶ Prints a string that gives an overview of all information relevant to the PRISM package distribution.
-
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 thecm
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, filename)[source]¶ Moves the logging file filename 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.
- filename (str) – String containing the name of the log-file that needs to be moved.
-
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:
-
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, theRootLogger
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.
- warn_type (
-
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 normalprint()
function.
-
prism._internal.
start_logger
(filename=None, mode='w')[source]¶ Opens a logging file called filename in the current working directory, opened with mode and starts the logger.
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.
- mode ({‘r’, ‘r+’, ‘w’, ‘w-‘/’x’, ‘a’}. Default: ‘w’) – String indicating how the log-file needs to be opened.