autoray.lazy.core
¶
Core lazy array functionality.
Module Contents¶
Classes¶
Get a compiled (by python |
|
A singleton object to use as a placeholder in a LazyArray. |
|
A lazy array representing a node in a computational graph. |
Functions¶
Check if |
|
|
Parse a pytree of lazy arrays into a queue of nodes, sorted by depth. |
|
Generate each unique computational node. Use |
|
Generate each unique computational node, from leaves to root. I.e. a |
|
Compute the value of one or more lazy arrays. All nodes that are |
|
Fold constant arrays - everything not dependent on |
|
Write the source code of an unravelled version of the computational |
|
|
|
Recursively search for |
Recursively evaluate LazyArray instances in tuples, lists and dicts. |
|
|
|
|
|
|
|
|
|
|
|
|
Recursively stringify LazyArray instances in tuples, lists and dicts. |
Check if we are currently sharing a cache -- thread specific. |
|
Return the most recent sharing cache -- thread specific. |
|
|
|
|
Context in which intermediate results are shared. |
|
|
|
|
|
Decorator to mark a function as being lazy cacheable. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Create a |
|
Create a |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Infer the shape of a possibly nested list/tuple object. |
|
|
|
|
|
|
|
|
|
|
|
|
Attributes¶
- autoray.lazy.core._EMPTY_DICT¶
- autoray.lazy.core.get_depth¶
- autoray.lazy.core.get_data¶
- autoray.lazy.core.to_queue(lz)[source]¶
Parse a pytree of lazy arrays into a queue of nodes, sorted by depth. This is useful for traversing the computational graph of multiple outputs in topological order.
- autoray.lazy.core.descend(lz)[source]¶
Generate each unique computational node. Use
ascend
if you need to visit children before parents.- Parameters:
lz (pytree of LazyArray) – The output node(s) of the computational graph to descend.
- Yields:
LazyArray
- autoray.lazy.core.ascend(lz)[source]¶
Generate each unique computational node, from leaves to root. I.e. a topological ordering of the computational graph. Moreover, the nodes are visited ‘deepest first’.
- Parameters:
lz (pytree of LazyArray) – The output node(s) of the computational graph to ascend to.
- Yields:
LazyArray
- autoray.lazy.core.compute(lz)[source]¶
Compute the value of one or more lazy arrays. All nodes that are computed clear any references to their function, arguments and dependencies, and store the result in their
_data
attribute.- Parameters:
lz (pytree of LazyArray) – The output node(s) of the computational graph to compute.
- Returns:
The computed value(s) of the lazy array(s).
- Return type:
array or tuple of array
- autoray.lazy.core.compute_constants(lz, variables)[source]¶
Fold constant arrays - everything not dependent on
variables
- into the graph.
- autoray.lazy.core.get_source(lz, params=None)[source]¶
Write the source code of an unravelled version of the computational graph, injecting required runtime objects into
params
.
- class autoray.lazy.core.Function(inputs, outputs, fold_constants=True)[source]¶
Get a compiled (by python
compile
), function that performs the computational graph corresponding toinputs
->outputs
. The signature of the function isfunc(input_arrays) -> output_arrays
. As an intermediate step, the computational graph is traced to a flattened source code string.- Parameters:
See also
- __slots__ = ('_in_names', '_out_names', '_out_tree', '_source', '_code', '_locals')¶
- class autoray.lazy.core.Placeholder[source]¶
A singleton object to use as a placeholder in a LazyArray.
- __slots__ = ()¶
- autoray.lazy.core.PLACEHOLDER¶
- class autoray.lazy.core.LazyArray(backend, fn, args, kwargs, shape, deps=None)[source]¶
A lazy array representing a node in a computational graph.
- Parameters:
backend (str) – The backend of the array were it to be computed. This can be
None
but this may cause problems when propagating information about which functions to import to child nodes.fn (callable) – The function to call to compute the array, presumable imported from
backend
. This can beNone
if the array already has data (e.g. is an input).args (tuple) – The positional arguments to pass to
fn
, which might beLazyArray
instances.kwargs (dict) – The keyword arguments to pass to
fn
, which might beLazyArray
instances.shape (tuple) – The shape of the array that
fn(*args, **kwargs)
will return, or the shape of the array thatdata
has.deps (tuple, optional) – The
LazyArray
instances thatfn(*args, **kwargs)
depends on. If not specified, these will be automatically found fromargs
andkwargs
, specifying them manually is slightly more efficient.
- property fn¶
The function to use to compute this array.
- property fn_name¶
The name of the function to use to compute this array.
- property args¶
The positional arguments to the function to use to compute this array.
- property kwargs¶
The keyword arguments to the function to use to compute this array.
- property shape¶
- property ndim¶
- property size¶
- property backend¶
- property deps¶
A tuple of the dependencies, other LazyArray instances, of this array.
- property depth¶
The maximum distance to any input array in the computational graph.
- property T¶
- property H¶
- property real¶
- property imag¶
- __slots__ = ('_backend', '_fn', '_args', '_kwargs', '_shape', '_data', '_deps', '_depth')¶
- __array_ufunc__¶
- to(fn, args=None, kwargs=None, backend=None, shape=None, deps=None)[source]¶
Create a new
LazyArray
, by default propagating backend, shape, and deps from the the current LazyArray.
- _materialize()[source]¶
Recursively compute all required args and kwargs for this node before computing itself and dereferencing dependencies. Note using this to materialize a large computation from scratch should be avoided due to the recursion limit, use
x.compute()
instead.
- compute()[source]¶
Compute the value of this lazy array, clearing any references to the function, arguments and dependencies, and storing the result in the
_data
attribute as well as returning it.Unlike
self._materialize()
this avoids deep recursion.
- get_function(variables, fold_constants=True)[source]¶
Get a compiled function that computes
fn(arrays)
, withfn
describing the computational graph of thisLazyArray
andarrays
corresponding to the downstreamLazyArray
nodesvariables
.- Parameters:
variables (sequence of LazyArray) – Input nodes whose data can change between calls.
fold_constants (bool, optional) – Compute all intermediates which do not depend on
variables
prior to compilation.
- Returns:
fn – Function with signature
fn(arrays)
.- Return type:
callable
- show(filler=' ', max_lines=None, max_depth=None)[source]¶
Show the computational graph as a nested directory structure.
- history_num_nodes()[source]¶
Return the number of unique computational nodes in the history of this
LazyArray
.
- history_size_footprint(include_inputs=True)[source]¶
Get the combined size of intermediates at each step of the computation. Note this assumes that intermediates are immediately garbage collected when they are no longer required.
- Parameters:
include_inputs (bool, optional) – Whether to include the size of the inputs in the computation. If
True
It is assumed they can be garbage collected once used but are all present at the beginning of the computation.
- history_peak_size(include_inputs=True)[source]¶
Get the peak combined intermediate size of this computation.
- Parameters:
include_inputs (bool, optional) – Whether to include the size of the inputs in the computation. If
True
It is assumed they can be garbage collected once used but are all present at the beginning of the computation.
- history_total_size()[source]¶
The the total size of all unique arrays in the computational graph, possibly relevant e.g. for back-propagation algorithms.
- history_stats(fn)[source]¶
Compute aggregate statistics about the computational graph.
- Parameters:
fn (callable or str) – Function to apply to each node in the computational graph. If a string, one of ‘count’, ‘sizein’, ‘sizeout’ can be used to count the number of nodes, the total size of the inputs, or the total size of each output respectively.
- Returns:
stats – Dictionary mapping function names to the aggregate statistics.
- Return type:
dict
- autoray.lazy.core._materialize_dispatch¶
- autoray.lazy.core.maybe_materialize(x)[source]¶
Recursively evaluate LazyArray instances in tuples, lists and dicts.
- autoray.lazy.core._stringify_dispatch¶
- autoray.lazy.core.stringify(x, params)[source]¶
Recursively stringify LazyArray instances in tuples, lists and dicts.
- autoray.lazy.core._SHARING_STACK¶
- autoray.lazy.core.currently_sharing()[source]¶
Check if we are currently sharing a cache – thread specific.
- autoray.lazy.core.get_sharing_cache()[source]¶
Return the most recent sharing cache – thread specific.
Context in which intermediate results are shared.
Note that intermediate LazyArray instances (which can reference actual data) will not be garbage collected until 1. this context exits, and 2. the yielded cache is garbage collected (if it was captured).
- Parameters:
cache (dict) – If specified, a user-stored dict in which intermediate lazy arrays will be stored. This can be used to interleave sharing contexts.
- Returns:
cache – A dictionary in which sharing results are stored. If ignored, sharing results will be garbage collected when this context is exited. This dict can be passed to another context to resume sharing.
- Return type:
dict
- autoray.lazy.core.lazy_cache(fn_name, hasher=None)[source]¶
Decorator to mark a function as being lazy cacheable.
- Parameters:
fn_name (str) – The name to use for the function in the cache.
hasher (callable) – A function with signature
hasher(fn_name, *args, **kwargs)
that returns a hashable key for the cache. If not specified, the default is to usehash_args_kwargs
.
- autoray.lazy.core._DTYPES_REAL_EQUIV¶
- autoray.lazy.core._DTYPES_COMPLEX_EQUIV¶
- autoray.lazy.core.Variable(shape, backend=None)[source]¶
Create a
LazyArray
from a shape only, representing a leaf node in the computational graph. It can only act as a placeholder for data.