quimb.utils

Misc utility functions.

Attributes

Classes

continuous_progbar

A continuous version of tqdm, so that it can be updated with a float

Verbosify

Decorator for making functions print their inputs. Simply for

oset

An ordered set which stores elements as the keys of dict (ordered as of

LRU

Least recently used dict, which evicts old items. Taken from python

Leaf

Functions

check_opt(name, value, valid)

Check whether value takes one of valid options, and raise an

find_library(x)

Check if library is installed.

raise_cant_find_library_function(x[, extra_msg])

Return function to flag up a missing necessary library.

deprecated(fn, old_name, new_name)

Mark a function as deprecated, and indicate the new name.

int2tup(x)

ensure_dict(x)

Make sure x is a dict, creating an empty one if x is None.

pairwise(iterable)

Iterate over each pair of neighbours in iterable.

print_multi_line(*lines[, max_width])

Print multiple lines, with a maximum width.

format_number_with_error(x, err)

Given x with error err, format a string showing the relevant

save_to_disk(obj, fname, **dump_opts)

Save an object to disk using joblib.dump.

load_from_disk(fname, **load_opts)

Load an object form disk using joblib.load.

gen_bipartitions(it)

Generate all unique bipartitions of it. Unique meaning

tree_register_container(cls, mapper, iterator, applier)

Register a new container type for use with tree_map and

is_not_container(x)

The default function to determine if an object is a leaf. This simply

_tmap_identity(f, tree, is_leaf)

tree_map(f, tree[, is_leaf])

Map f over all leaves in tree, returning a new pytree.

empty(tree, is_leaf)

tree_iter(tree[, is_leaf])

Iterate over all leaves in tree.

nothing(f, tree, is_leaf)

tree_apply(f, tree[, is_leaf])

Apply f to all leaves in tree, no new pytree is built.

is_leaf_object(x)

tree_flatten(tree[, get_ref, is_leaf])

Flatten tree into a list of leaves.

tree_unflatten(objs, tree[, is_leaf])

Unflatten objs into a pytree of the same structure as tree.

tree_map_tuple(f, tree, is_leaf)

tree_iter_tuple(tree, is_leaf)

tree_apply_tuple(f, tree, is_leaf)

tree_map_list(f, tree, is_leaf)

tree_iter_list(tree, is_leaf)

tree_apply_list(f, tree, is_leaf)

tree_map_dict(f, tree, is_leaf)

tree_iter_dict(tree, is_leaf)

tree_apply_dict(f, tree, is_leaf)

default_to_neutral_style(fn)

Wrap a function or method to use the neutral style by default.

autocorrect_kwargs([func, valid_kwargs])

A decorator that suggests the right keyword arguments if you get them

Module Contents

quimb.utils.last
quimb.utils._CHECK_OPT_MSG = "Option `{}` should be one of {}, but got '{}'."
quimb.utils.check_opt(name, value, valid)[source]

Check whether value takes one of valid options, and raise an informative error if not.

quimb.utils.find_library(x)[source]

Check if library is installed.

Parameters:

x (str) – Name of library

Returns:

If library is available.

Return type:

bool

quimb.utils.raise_cant_find_library_function(x, extra_msg=None)[source]

Return function to flag up a missing necessary library.

This is simplify the task of flagging optional dependencies only at the point at which they are needed, and not earlier.

Parameters:
  • x (str) – Name of library

  • extra_msg (str, optional) – Make the function print this message as well, for additional information.

Returns:

A mock function that when called, raises an import error specifying the required library.

Return type:

callable

quimb.utils.FOUND_TQDM
class quimb.utils.continuous_progbar(*args, total=100, **kwargs)[source]

Bases: tqdm.tqdm

A continuous version of tqdm, so that it can be updated with a float within some pre-given range, rather than a number of steps.

Parameters:
  • args ((stop) or (start, stop)) – Stopping point (and starting point if len(args) == 2) of window within which to evaluate progress.

  • total (int) – The number of steps to represent the continuous progress with.

  • kwargs – Supplied to tqdm.tqdm

cupdate(x)[source]

‘Continuous’ update of progress bar.

Parameters:

x (float) – Current position within the range [self.start, self.stop].

quimb.utils.deprecated(fn, old_name, new_name)[source]

Mark a function as deprecated, and indicate the new name.

quimb.utils.int2tup(x)[source]
quimb.utils.ensure_dict(x)[source]

Make sure x is a dict, creating an empty one if x is None.

quimb.utils.pairwise(iterable)[source]

Iterate over each pair of neighbours in iterable.

quimb.utils.print_multi_line(*lines, max_width=None)[source]

Print multiple lines, with a maximum width.

quimb.utils.format_number_with_error(x, err)[source]

Given x with error err, format a string showing the relevant digits of x with two significant digits of the error bracketed, and overall exponent if necessary.

Parameters:
  • x (float) – The value to print.

  • err (float) – The error on x.

Return type:

str

Examples

>>> print_number_with_uncertainty(0.1542412, 0.0626653)
'0.154(63)'
>>> print_number_with_uncertainty(-128124123097, 6424)
'-1.281241231(64)e+11'
quimb.utils.save_to_disk(obj, fname, **dump_opts)[source]

Save an object to disk using joblib.dump.

quimb.utils.load_from_disk(fname, **load_opts)[source]

Load an object form disk using joblib.load.

class quimb.utils.Verbosify(fn, highlight=None, mpi=False)[source]

Decorator for making functions print their inputs. Simply for illustrating a MPI example in the docs.

__call__(*args, **kwargs)[source]
class quimb.utils.oset(it=())[source]

An ordered set which stores elements as the keys of dict (ordered as of python 3.6). ‘A few times’ slower than using a set directly for small sizes, but makes everything deterministic.

__slots__ = ('_d',)
classmethod _from_dict(d)[source]
classmethod from_dict(d)[source]

Public method makes sure to copy incoming dictionary.

copy()[source]
__deepcopy__(memo)[source]
add(k)[source]
discard(k)[source]
remove(k)[source]
clear()[source]
update(*others)[source]
union(*others)[source]
intersection_update(*others)[source]
intersection(*others)[source]
difference_update(*others)[source]
difference(*others)[source]
popleft()[source]
popright()[source]
pop[source]
__eq__(other)[source]

Return self==value.

__or__(other)[source]
__ior__(other)[source]
__and__(other)[source]
__iand__(other)[source]
__sub__(other)[source]
__isub__(other)[source]
__len__()[source]
__iter__()[source]
__contains__(x)[source]
__repr__()[source]

Return repr(self).

class quimb.utils.LRU(maxsize, *args, **kwds)[source]

Bases: collections.OrderedDict

Least recently used dict, which evicts old items. Taken from python collections OrderedDict docs.

__getitem__(key)[source]

x.__getitem__(y) <==> x[y]

__setitem__(key, value)[source]

Set self[key] to value.

quimb.utils.gen_bipartitions(it)[source]

Generate all unique bipartitions of it. Unique meaning (1, 2), (3, 4) is considered the same as (3, 4), (1, 2).

quimb.utils.TREE_MAP_REGISTRY
quimb.utils.TREE_APPLY_REGISTRY
quimb.utils.TREE_ITER_REGISTRY
quimb.utils.tree_register_container(cls, mapper, iterator, applier)[source]

Register a new container type for use with tree_map and tree_apply.

Parameters:
  • cls (type) – The container type to register.

  • mapper (callable) – A function that takes f, tree and is_leaf and returns a new tree of type cls with f applied to all leaves.

  • applier (callable) – A function that takes f, tree and is_leaf and applies f to all leaves in tree.

quimb.utils.IS_CONTAINER_CACHE
quimb.utils.is_not_container(x)[source]

The default function to determine if an object is a leaf. This simply checks if the object is an instance of any of the registered container types.

quimb.utils._tmap_identity(f, tree, is_leaf)[source]
quimb.utils.TREE_MAPPER_CACHE
quimb.utils.tree_map(f, tree, is_leaf=is_not_container)[source]

Map f over all leaves in tree, returning a new pytree.

Parameters:
  • f (callable) – A function to apply to all leaves in tree.

  • tree (pytree) – A nested sequence of tuples, lists, dicts and other objects.

  • is_leaf (callable) – A function to determine if an object is a leaf, f is only applied to objects for which is_leaf(x) returns True.

Return type:

pytree

quimb.utils.empty(tree, is_leaf)[source]
quimb.utils.TREE_ITER_CACHE
quimb.utils.tree_iter(tree, is_leaf=is_not_container)[source]

Iterate over all leaves in tree.

Parameters:
  • f (callable) – A function to apply to all leaves in tree.

  • tree (pytree) – A nested sequence of tuples, lists, dicts and other objects.

  • is_leaf (callable) – A function to determine if an object is a leaf, f is only applied to objects for which is_leaf(x) returns True.

quimb.utils.nothing(f, tree, is_leaf)[source]
quimb.utils.TREE_APPLIER_CACHE
quimb.utils.tree_apply(f, tree, is_leaf=is_not_container)[source]

Apply f to all leaves in tree, no new pytree is built.

Parameters:
  • f (callable) – A function to apply to all leaves in tree.

  • tree (pytree) – A nested sequence of tuples, lists, dicts and other objects.

  • is_leaf (callable) – A function to determine if an object is a leaf, f is only applied to objects for which is_leaf(x) returns True.

class quimb.utils.Leaf
__slots__ = ()
__repr__()[source]

Return repr(self).

quimb.utils.Leaf
quimb.utils.is_leaf_object(x)[source]
quimb.utils.tree_flatten(tree, get_ref=False, is_leaf=is_not_container)[source]

Flatten tree into a list of leaves.

Parameters:
  • tree (pytree) – A nested sequence of tuples, lists, dicts and other objects.

  • is_leaf (callable) – A function to determine if an object is a leaf, only objects for which is_leaf(x) returns True are returned in the flattened list.

Returns:

  • objs (list) – The flattened list of leaf objects.

  • (ref_tree) (pytree) – If get_ref is True, a reference tree, with leaves of type Leaf, is returned which can be used to reconstruct the original tree.

quimb.utils.tree_unflatten(objs, tree, is_leaf=is_leaf_object)[source]

Unflatten objs into a pytree of the same structure as tree.

Parameters:
  • objs (sequence) – A sequence of objects to be unflattened into a pytree.

  • tree (pytree) – A nested sequence of tuples, lists, dicts and other objects, the objs will be inserted into a new pytree of the same structure.

  • is_leaf (callable) – A function to determine if an object is a leaf, only objects for which is_leaf(x) returns True will have the next item from objs inserted. By default checks for the Leaf object inserted by tree_flatten(..., get_ref=True).

Return type:

pytree

quimb.utils.tree_map_tuple(f, tree, is_leaf)[source]
quimb.utils.tree_iter_tuple(tree, is_leaf)[source]
quimb.utils.tree_apply_tuple(f, tree, is_leaf)[source]
quimb.utils.tree_map_list(f, tree, is_leaf)[source]
quimb.utils.tree_iter_list(tree, is_leaf)[source]
quimb.utils.tree_apply_list(f, tree, is_leaf)[source]
quimb.utils.tree_map_dict(f, tree, is_leaf)[source]
quimb.utils.tree_iter_dict(tree, is_leaf)[source]
quimb.utils.tree_apply_dict(f, tree, is_leaf)[source]
quimb.utils.NEUTRAL_STYLE
quimb.utils.default_to_neutral_style(fn)[source]

Wrap a function or method to use the neutral style by default.

quimb.utils.autocorrect_kwargs(func=None, valid_kwargs=None)[source]

A decorator that suggests the right keyword arguments if you get them wrong. Useful for functions with many specific options.

Parameters:
  • func (callable, optional) – The function to decorate.

  • valid_kwargs (sequence[str], optional) – The valid keyword arguments for func, if not given these are inferred from the function signature.