quimb.utils =========== .. py:module:: quimb.utils .. autoapi-nested-parse:: Misc utility functions. Attributes ---------- .. autoapisummary:: quimb.utils.last quimb.utils._CHECK_OPT_MSG quimb.utils.FOUND_TQDM quimb.utils.TREE_MAP_REGISTRY quimb.utils.TREE_APPLY_REGISTRY quimb.utils.TREE_ITER_REGISTRY quimb.utils.IS_CONTAINER_CACHE quimb.utils.TREE_MAPPER_CACHE quimb.utils.TREE_ITER_CACHE quimb.utils.TREE_APPLIER_CACHE quimb.utils.Leaf quimb.utils.NEUTRAL_STYLE Classes ------- .. autoapisummary:: quimb.utils.continuous_progbar quimb.utils.Verbosify quimb.utils.oset quimb.utils.LRU quimb.utils.ExponentialGeometricRollingDiffMean quimb.utils.Leaf Functions --------- .. autoapisummary:: quimb.utils.check_opt quimb.utils.find_library quimb.utils.raise_cant_find_library_function quimb.utils.deprecated quimb.utils.int2tup quimb.utils.ensure_dict quimb.utils.pairwise quimb.utils.print_multi_line quimb.utils.format_number_with_error quimb.utils.save_to_disk quimb.utils.load_from_disk quimb.utils.gen_bipartitions quimb.utils.tree_register_container quimb.utils.is_not_container quimb.utils._tmap_identity quimb.utils.tree_map quimb.utils.empty quimb.utils.tree_iter quimb.utils.nothing quimb.utils.tree_apply quimb.utils.is_leaf_object quimb.utils.tree_flatten quimb.utils.tree_unflatten quimb.utils.tree_map_tuple quimb.utils.tree_iter_tuple quimb.utils.tree_apply_tuple quimb.utils.tree_map_list quimb.utils.tree_iter_list quimb.utils.tree_apply_list quimb.utils.tree_map_dict quimb.utils.tree_iter_dict quimb.utils.tree_apply_dict quimb.utils.default_to_neutral_style quimb.utils.autocorrect_kwargs Module Contents --------------- .. py:data:: last .. py:data:: _CHECK_OPT_MSG :value: "Option `{}` should be one of {}, but got '{}'." .. py:function:: check_opt(name, value, valid) Check whether ``value`` takes one of ``valid`` options, and raise an informative error if not. .. py:function:: find_library(x) Check if library is installed. :param x: Name of library :type x: str :returns: If library is available. :rtype: bool .. py:function:: 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. :param x: Name of library :type x: str :param extra_msg: Make the function print this message as well, for additional information. :type extra_msg: str, optional :returns: A mock function that when called, raises an import error specifying the required library. :rtype: callable .. py:data:: FOUND_TQDM .. py:class:: continuous_progbar(*args, total=100, **kwargs) Bases: :py:obj:`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. :param args: Stopping point (and starting point if ``len(args) == 2``) of window within which to evaluate progress. :type args: (stop) or (start, stop) :param total: The number of steps to represent the continuous progress with. :type total: int :param kwargs: Supplied to ``tqdm.tqdm`` .. py:attribute:: range .. py:attribute:: step :value: 1 .. py:method:: cupdate(x) 'Continuous' update of progress bar. :param x: Current position within the range ``[self.start, self.stop]``. :type x: float .. py:function:: deprecated(fn, old_name, new_name) Mark a function as deprecated, and indicate the new name. .. py:function:: int2tup(x) .. py:function:: ensure_dict(x) Make sure ``x`` is a ``dict``, creating an empty one if ``x is None``. .. py:function:: pairwise(iterable) Iterate over each pair of neighbours in ``iterable``. .. py:function:: print_multi_line(*lines, max_width=None) Print multiple lines, with a maximum width. .. py:function:: 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. :param x: The value to print. :type x: float :param err: The error on ``x``. :type err: float :rtype: str .. rubric:: Examples >>> print_number_with_uncertainty(0.1542412, 0.0626653) '0.154(63)' >>> print_number_with_uncertainty(-128124123097, 6424) '-1.281241231(64)e+11' .. py:function:: save_to_disk(obj, fname, **dump_opts) Save an object to disk using joblib.dump. .. py:function:: load_from_disk(fname, **load_opts) Load an object form disk using joblib.load. .. py:class:: Verbosify(fn, highlight=None, mpi=False) Decorator for making functions print their inputs. Simply for illustrating a MPI example in the docs. .. py:attribute:: fn .. py:attribute:: highlight :value: None .. py:attribute:: mpi :value: False .. py:method:: __call__(*args, **kwargs) .. py:class:: 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. .. py:attribute:: __slots__ :value: ('_d',) .. py:attribute:: _d .. py:method:: _from_dict(d) :classmethod: .. py:method:: from_dict(d) :classmethod: Public method makes sure to copy incoming dictionary. .. py:method:: copy() .. py:method:: __deepcopy__(memo) .. py:method:: add(k) .. py:method:: discard(k) .. py:method:: remove(k) .. py:method:: clear() .. py:method:: update(*others) .. py:method:: union(*others) .. py:method:: intersection_update(*others) .. py:method:: intersection(*others) .. py:method:: difference_update(*others) .. py:method:: difference(*others) .. py:method:: popleft() .. py:method:: popright() .. py:attribute:: pop .. py:method:: __eq__(other) .. py:method:: __or__(other) .. py:method:: __ior__(other) .. py:method:: __and__(other) .. py:method:: __iand__(other) .. py:method:: __sub__(other) .. py:method:: __isub__(other) .. py:method:: __len__() .. py:method:: __iter__() .. py:method:: __contains__(x) .. py:method:: __repr__() .. py:class:: LRU(maxsize, *args, **kwds) Bases: :py:obj:`collections.OrderedDict` Least recently used dict, which evicts old items. Taken from python collections OrderedDict docs. .. py:attribute:: maxsize .. py:method:: __getitem__(key) x.__getitem__(y) <==> x[y] .. py:method:: __setitem__(key, value) Set self[key] to value. .. py:class:: ExponentialGeometricRollingDiffMean(factor=1 / 3, initial=1.0) .. py:attribute:: x_prev :value: None .. py:attribute:: dx :value: None .. py:attribute:: value :value: 1.0 .. py:attribute:: factor :value: 0.3333333333333333 .. py:method:: update(x) .. py:function:: gen_bipartitions(it) Generate all unique bipartitions of ``it``. Unique meaning ``(1, 2), (3, 4)`` is considered the same as ``(3, 4), (1, 2)``. .. py:data:: TREE_MAP_REGISTRY .. py:data:: TREE_APPLY_REGISTRY .. py:data:: TREE_ITER_REGISTRY .. py:function:: tree_register_container(cls, mapper, iterator, applier) Register a new container type for use with ``tree_map`` and ``tree_apply``. :param cls: The container type to register. :type cls: type :param mapper: A function that takes ``f``, ``tree`` and ``is_leaf`` and returns a new tree of type ``cls`` with ``f`` applied to all leaves. :type mapper: callable :param applier: A function that takes ``f``, ``tree`` and ``is_leaf`` and applies ``f`` to all leaves in ``tree``. :type applier: callable .. py:data:: IS_CONTAINER_CACHE .. py:function:: 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. .. py:function:: _tmap_identity(f, tree, is_leaf) .. py:data:: TREE_MAPPER_CACHE .. py:function:: tree_map(f, tree, is_leaf=is_not_container) Map ``f`` over all leaves in ``tree``, returning a new pytree. :param f: A function to apply to all leaves in ``tree``. :type f: callable :param tree: A nested sequence of tuples, lists, dicts and other objects. :type tree: pytree :param is_leaf: A function to determine if an object is a leaf, ``f`` is only applied to objects for which ``is_leaf(x)`` returns ``True``. :type is_leaf: callable :rtype: pytree .. py:function:: empty(tree, is_leaf) .. py:data:: TREE_ITER_CACHE .. py:function:: tree_iter(tree, is_leaf=is_not_container) Iterate over all leaves in ``tree``. :param f: A function to apply to all leaves in ``tree``. :type f: callable :param tree: A nested sequence of tuples, lists, dicts and other objects. :type tree: pytree :param is_leaf: A function to determine if an object is a leaf, ``f`` is only applied to objects for which ``is_leaf(x)`` returns ``True``. :type is_leaf: callable .. py:function:: nothing(f, tree, is_leaf) .. py:data:: TREE_APPLIER_CACHE .. py:function:: tree_apply(f, tree, is_leaf=is_not_container) Apply ``f`` to all leaves in ``tree``, no new pytree is built. :param f: A function to apply to all leaves in ``tree``. :type f: callable :param tree: A nested sequence of tuples, lists, dicts and other objects. :type tree: pytree :param is_leaf: A function to determine if an object is a leaf, ``f`` is only applied to objects for which ``is_leaf(x)`` returns ``True``. :type is_leaf: callable .. py:class:: Leaf .. py:attribute:: __slots__ :value: () .. py:method:: __repr__() .. py:data:: Leaf .. py:function:: is_leaf_object(x) .. py:function:: tree_flatten(tree, get_ref=False, is_leaf=is_not_container) Flatten ``tree`` into a list of leaves. :param tree: A nested sequence of tuples, lists, dicts and other objects. :type tree: pytree :param is_leaf: 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. :type is_leaf: callable :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. .. py:function:: tree_unflatten(objs, tree, is_leaf=is_leaf_object) Unflatten ``objs`` into a pytree of the same structure as ``tree``. :param objs: A sequence of objects to be unflattened into a pytree. :type objs: sequence :param tree: A nested sequence of tuples, lists, dicts and other objects, the objs will be inserted into a new pytree of the same structure. :type tree: pytree :param is_leaf: 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)``. :type is_leaf: callable :rtype: pytree .. py:function:: tree_map_tuple(f, tree, is_leaf) .. py:function:: tree_iter_tuple(tree, is_leaf) .. py:function:: tree_apply_tuple(f, tree, is_leaf) .. py:function:: tree_map_list(f, tree, is_leaf) .. py:function:: tree_iter_list(tree, is_leaf) .. py:function:: tree_apply_list(f, tree, is_leaf) .. py:function:: tree_map_dict(f, tree, is_leaf) .. py:function:: tree_iter_dict(tree, is_leaf) .. py:function:: tree_apply_dict(f, tree, is_leaf) .. py:data:: NEUTRAL_STYLE .. py:function:: default_to_neutral_style(fn) Wrap a function or method to use the neutral style by default. .. py:function:: 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. :param func: The function to decorate. :type func: callable, optional :param valid_kwargs: The valid keyword arguments for ``func``, if not given these are inferred from the function signature. :type valid_kwargs: sequence[str], optional