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`
`NEUTRAL_STYLE`

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
`ExponentialGeometricRollingDiffMean`
`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

range¶

step = 1¶

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.

fn¶

highlight = None¶

mpi = False¶

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

_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]¶

__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]¶

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.

maxsize¶

__getitem__(key)[source]¶: x.__getitem__(y) <==> x[y]

__setitem__(key, value)[source]¶: Set self[key] to value.

class quimb.utils.ExponentialGeometricRollingDiffMean(factor=1 / 3, initial=1.0)[source]¶

x_prev = None¶

dx = None¶

value = 1.0¶

factor = 0.3333333333333333¶

update(x)[source]¶

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]¶

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]¶

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.