quimb.utils

Misc utility functions.

Attributes

last
_CHECK_OPT_MSG
FOUND_TQDM
TREE_MAP_REGISTRY
TREE_APPLY_REGISTRY
TREE_ITER_REGISTRY
IS_CONTAINER_CACHE
TREE_MAPPER_CACHE
TREE_ITER_CACHE
TREE_APPLIER_CACHE
Leaf

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
RollingDiffMean	Tracker for the absolute rolling mean of diffs between values, to
ExponentialGeometricRollingDiffMean	Track the absolute rolling mean of diffs between values, weighted in a
Leaf

Functions

check_opt(name, value, valid)	Check whether value takes one of valid options, and raise an
parse_info_extras() → dict)	For functions that take an optional info dict, this function
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
gen_bipartitions_balanced_first(it)	Generate all unique bipartitions of it, yield most balanced ones
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)
autocorrect_kwargs([func, valid_kwargs])	A decorator that suggests the right keyword arguments if you get them
hash_kwargs_to_int(→ int)	Hash a set of keyword arguments to a deterministic integer, which can be

Module Contents

quimb.utils.last

quimb.utils._CHECK_OPT_MSG = "Option `{}` should be one of {}, but got '{}'."

quimb.utils.check_opt(name, value, valid)

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

quimb.utils.parse_info_extras(info=None, default=()) → dict

For functions that take an optional info dict, this function populates which quantities to compute based on the keys of info. If info is None, nothing is inserted, if info == {}, all default keys are inserted, but if info is a dict with some keys, only those keys will remain, assuming they specify a manual subset.

quimb.utils.find_library(x)

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)

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)

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

range

step = 1

cupdate(x)

‘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)

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

quimb.utils.int2tup(x)

quimb.utils.ensure_dict(x)

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

quimb.utils.pairwise(iterable)

Iterate over each pair of neighbours in iterable.

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

Print multiple lines, with a maximum width.

quimb.utils.format_number_with_error(x, err)

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)

Save an object to disk using joblib.dump.

quimb.utils.load_from_disk(fname, **load_opts)

Load an object form disk using joblib.load.

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

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

fn

highlight = None

mpi = False

__call__(*args, **kwargs)

class quimb.utils.oset(it=())

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',)

_d

classmethod _from_dict(d)

classmethod from_dict(d)

Public method makes sure to copy incoming dictionary.

copy()

__deepcopy__(memo)

add(k)

discard(k)

remove(k)

clear()

update(*others)

union(*others)

intersection_update(*others)

intersection(*others)

difference_update(*others)

difference(*others)

popleft()

popright()

pop

__eq__(other)

__or__(other)

__ior__(other)

__and__(other)

__iand__(other)

__sub__(other)

__isub__(other)

__len__()

__iter__()

__contains__(x)

__repr__()

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

Bases: collections.OrderedDict

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

maxsize

__getitem__(key)

Return self[key].

__setitem__(key, value)

Set self[key] to value.

class quimb.utils.RollingDiffMean(size=16)

Tracker for the absolute rolling mean of diffs between values, to assess effective convergence.

size = 16

diffs = []

last_y = None

dxsum = 0.0

update(y)

absmeandiff()

class quimb.utils.ExponentialGeometricRollingDiffMean(factor=1 / 3, initial=1.0)

Track the absolute rolling mean of diffs between values, weighted in a exponentially decaying geometric fashion.

y_prev = None

x_prev = None

dy = None

value = 1.0

factor = 0.3333333333333333

update(y, x=None)

quimb.utils.gen_bipartitions(it)

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

quimb.utils.gen_bipartitions_balanced_first(it)

Generate all unique bipartitions of it, yield most balanced ones first. Unique up to swapping the two sites.

Parameters:

it (iterable) – The items to bipartition.

Yields:

(left, right) (tuple) – A bipartition of the items, with the most balanced ones first.

quimb.utils.TREE_MAP_REGISTRY

quimb.utils.TREE_APPLY_REGISTRY

quimb.utils.TREE_ITER_REGISTRY

quimb.utils.tree_register_container(cls, mapper, iterator, applier)

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)

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)

quimb.utils.TREE_MAPPER_CACHE

quimb.utils.tree_map(f, tree, is_leaf=is_not_container)

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)

quimb.utils.TREE_ITER_CACHE

quimb.utils.tree_iter(tree, is_leaf=is_not_container)

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)

quimb.utils.TREE_APPLIER_CACHE

quimb.utils.tree_apply(f, tree, is_leaf=is_not_container)

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__()

quimb.utils.Leaf

quimb.utils.is_leaf_object(x)

quimb.utils.tree_flatten(tree, get_ref=False, is_leaf=is_not_container)

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)

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)

quimb.utils.tree_iter_tuple(tree, is_leaf)

quimb.utils.tree_apply_tuple(f, tree, is_leaf)

quimb.utils.tree_map_list(f, tree, is_leaf)

quimb.utils.tree_iter_list(tree, is_leaf)

quimb.utils.tree_apply_list(f, tree, is_leaf)

quimb.utils.tree_map_dict(f, tree, is_leaf)

quimb.utils.tree_iter_dict(tree, is_leaf)

quimb.utils.tree_apply_dict(f, tree, is_leaf)

quimb.utils.autocorrect_kwargs(func=None, valid_kwargs=None)

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.

quimb.utils.hash_kwargs_to_int(**kwargs) → int

Hash a set of keyword arguments to a deterministic integer, which can be used for seeding random number generators in tests, for example, allowing a varying but reproducible seed.