Utilities (utils)

Provide utilities for processing and logging as well as common mathematical function and algorithms.

Processing and monitoring

Progress(task_length[, num_checkpts, ...])

Progress status of tasks.

setup_logger()

Return the root logger formatted with elapsed time and piped to stdout.

clean_warning_format(message, category, ...)

Clean warning message format.

restore_warnings(captured_warnings)

Emit captured warnings.

mpi_compute(data_array, mapping[, comm, ...])

Multiprocess mapping of data with optional progress bar.

Mathematics

const_function(const)

Return a constant function with arbitrary arguments.

normalise_vector(vector_array)

Normalise vector(s).

binary_search(func, a, b[, maxnum, precision])

Binary seach for all zeros of a function in a real interval.

covar_to_corr(covar)

Convert a covariance matrix to its correlation matrix.

mat_logdet(matrix)

Calculate logarithm of the determinant of a matrix.

PositiveDefinitenessWarning

Emit a warning when a matrix is not positive definite.

is_positive_definite(matrix)

Check the positive definiteness of a square matrix by attempting a Cholesky decomposition.

class harmonia.utils.Progress(task_length, num_checkpts=4, process_name=None, logger=None, comm=None, root=0)[source]

Progress status of tasks.

This is an alternative to tqdm for cases where progress is not uniform and only needs to be infrequently reported to a logger. If multiple parallel processes exist, progress status is only reported for the first and last of them.

Parameters:

  • task_length (int) – Total number of tasks.

  • num_checkpts (int, optional) – Number of checkpoints for reporting progress (default is 4).

  • process_name (str or None, optional) – If not None (default), this is the process name to be logged.

  • logger (logging.Logger or None, optional) – Logger. If None (default), a print statement is issued.

  • comm (mpi4py.MPI.Comm or None, optional) – MPI communicator (default is None).

  • root (int, optional) – Root process number (default is 0).

Variables:

  • process_name (str or None, optional) – If not None (default), this is the process name to be logged.

  • task_length (int) – Total number of tasks.

  • progress_checkpts (float) – Scheduled progress check points, 0 < progress_checkpts <= 1.

  • last_checkpt (int) – Index of the last passed checkpoint, 0 <= last_checkpt <= num_checkpts.

Examples

>>> ntasks = 100
>>> p = Progress(ntasks, process_name='null test')
>>> for task_idx in range(ntasks):
...     p.report(task_idx)
Progress for the single 'null test' process: 25% computed.
Progress for the single 'null test' process: 50% computed.
Progress for the single 'null test' process: 75% computed.
Progress for the single 'null test' process: 100% computed.
report(current_position)[source]

Report the current position in the tasks.

Parameters:

current_position (int) – Index of the current position in the tasks (starting from 0).

harmonia.utils.setup_logger()[source]

Return the root logger formatted with elapsed time and piped to stdout.

Returns:

logger – Formatted root logger.

Return type:

logging.Logger

harmonia.utils.clean_warning_format(message, category, filename, lineno, line=None)[source]

Clean warning message format.

Parameters:

  • message, category, filename, lineno (str) – Warning message, warning catagory, origin filename, line number.

  • line (str or None, optional) – Source code line to be included in the warning message (default is None).

Returns:

Warning message format.

Return type:

str

harmonia.utils.restore_warnings(captured_warnings)[source]

Emit captured warnings.

Parameters:

captured_warnings (list of warnings.WarningMessage) – List of recorded warnings as returned by warnings.catch_warnings(record=True).

harmonia.utils.mpi_compute(data_array, mapping, comm=None, root=0, process_name=None, update_rate=None)[source]

Multiprocess mapping of data with optional progress bar.

For each map to be applied, the input data array is scattered over the first axis for computation on difference process, and the computed results are gathered in the exact structure of the input data array on the root process.

Parameters:

  • data_array (array_like) – Data array.

  • mapping (callable) – Mapping to be applied.

  • comm (mpi4py.MPI.Comm or None, optional) – MPI communicator. If None, no multiprocessing is performed.

  • root (int, optional) – Rank of the process taken as the root process (default is 0).

  • process_name (str or None) – If None (default), no progress bar is displayed; else this is the process name to be displayed.

  • update_rate (int or None, optional) – If not None (default), this is the progress bar update rate (in inverse seconds). Has no effect if process_name is not provided.

Returns:

output_array – Output data processed from mapping. Returns None for process ranks other than root.

Return type:

array_like or None

harmonia.utils.const_function(const)[source]

Return a constant function with arbitrary arguments.

Parameters:

const (float) – Constant value.

Returns:

Constant function.

Return type:

callable

Binary seach for all zeros of a function in a real interval.

Parameters:

  • func (callable) – Function whose zeros are to be found.

  • a, b (float) – Interval end points, a < b.

  • maxnum (int or None, optional) – Maximum number of zeros needed from below (default is None).

  • precision (float, optional) – Desired absolute precision of the zeros (default is 1.e-8).

Returns:

roots – Possible roots.

Return type:

float numpy.ndarray or None

Raises:

ValueError – If the initial interval covers only one point (a == b).

harmonia.utils.covar_to_corr(covar)[source]

Convert a covariance matrix to its correlation matrix.

Parameters:

covar (complex, array_like) – Covariance matrix.

Returns:

corr – Correlation matrix.

Return type:

numpy.ndarray

harmonia.utils.mat_logdet(matrix)[source]

Calculate logarithm of the determinant of a matrix.

Parameters:

matrix (float or complex, array_like) – Matrix.

Returns:

log_det – Logarithm of the matrix determinant.

Return type:

float

exception harmonia.utils.PositiveDefinitenessWarning[source]

Emit a warning when a matrix is not positive definite.

harmonia.utils.is_positive_definite(matrix)[source]

Check the positive definiteness of a square matrix by attempting a Cholesky decomposition.

Parameters:

matrix (float or complex, array_like) – Matrix.

Returns:

Positive definiteness.

Return type:

bool