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 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.
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
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_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 theCFilter
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 returnedPRISM_Logger
instance is a child of the basePRISM_Logger
created withset_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 basePRISM_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 createdPRISM_Logger
instance.- name (str or None. Default: None) – The name of the
-
prism._internal.
getRLogger
(name=None)[source]¶ Creates a
PRISM_Logger
instance with name, adds theRFilter
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 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)[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:
-
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.
set_base_logger
(filename=None)[source]¶ Initializes the base
PRISM_Logger
, from which all otherPRISM_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.