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