Tensor Wrapper

class TensorToolbox.core.TensorWrapper(f, X, params=None, W=None, twtype='array', data=None, dtype=<type 'object'>, store_file='', store_object=None, store_freq=None, store_overwrite=False, empty=False, maxprocs=None, marshal_f=True)

A tensor wrapper is a data structure W that given a multi-dimensional scalar function f(X,params), and a set of coordinates {{x1}_i1,{x2}_i2,..,{xd}_id} indexed by the multi index {i1,..,id}, let you access f(x1_i1,..,xd_id) by W[i1,..,id]. The function evaluations are performed “as needed” and stored for future accesses.

Parameters:

• f – multi-dimensional scalar function of type f(x,params), x being a list.
• X (list) – list of arrays with coordinates for each dimension
• params (tuple) – parameters to be passed to function f
• W (list) – list of arrays with weights for each dimension
• twtype (string) – ‘array’ values are stored whenever computed, ‘view’ values are never stored and function f is always called
• data (dict) – initialization data of the Tensor Wrapper (already computed entries)
• dtype (type) – type of output to be expected from f
• store_file (str) – file where to store the data
• store_object (object) – a storable object that must be stored in place of the TensorWrapper
• store_freq (bool) – how frequently to store the TensorWrapper (seconds)
• store_overwrite (bool) – whether to overwrite pre-existing files.
• empty (bool) – Creates an instance without initializing it. All the content can be initialized using the setstate() function.
• maxprocs (int) – Number of processors to be used in the function evaluation (MPI)
• marshal_f (bool) – whether to marshal the function or not

Several shape parameters are used by the TensorWrapper in order to keep track of reshaping and slicings, without affecting the underlying shape of the tensor which is always preserved. The following table lists the existing shapes and their meaning.

Shape attribute/function	Applied transformations (ordered)	Description
get_global_shape()	None	The original shape of the tensor. This shape can be modified only through a refinement of the grid using the function refine().
get_view_shape()	VIEW	The particular view of the tensor, defined by the view in TensorWrapper.maps set active using set_active_view().
get_extended_shape()	VIEW, QUANTICS	The shape of the extended tensor in order to allow for the quantics folding with basis TensorWrapper.Q.
get_ghost_shape()	VIEW, QUANTICS, RESHAPE	The shape of the tensor reshaped using reshape(). If a Quantics folding is pre-applied, then the reshape is on the extended shape.
get_shape()	VIEW, QUANTICS, RESHAPE, FIX_IDXS	The shape of the tensor with fix_indices() and release_indices(). This is the view that is always used when the tensor is accessed through the function __getitem__() (i.e. TW[...])

__getitem__(idxs_in)

extended_is_view(idxs)

Returns:True if the idxs is in the view shape. False if it is outside

fix_indices(idxs, dims)

Fix some of the indices in the tensor wrapper and reshape/resize it accordingly. The internal storage of the data is still done with respect to the global indices, but once some indices are fixed, the TensorWrapper can be accessed using just the remaining free indices.

Parameters:

• idxs (list) – list of indices to be fixed
• dims (list) – list of dimensions to which the indices refer to

get_extended_ndim()

If the quantics folding has been performed on the current view, then this returns the number of dimensions of the extended tensor to the next power of Q. If the folding has not been performed, this returns an error.

get_extended_shape()

If the quantics folding has been performed on the current view, then this returns the shape of the extended tensor to the next power of Q. If the folding has not been performed, this returns the view shape.

get_extended_size()

If the quantics folding has been performed on the current view, then this returns the size of the extended tensor to the next power of Q. If the folding has not been performed, this returns an error.

get_ghost_ndim()

If the ghost_shape is set for this view, then it returns the number of dimensions obtained after quantics folding by the function set_Q() or after reshaping by the function reshape(). Otherwise the number of dimensions of the view is returned.

get_ghost_shape()

If the ghost_shape is set for this view, then it returns the shape obtained after quantics folding by the function set_Q() or after reshaping by the function reshape(). Otherwise the shape of the extended shape is returned.

get_ghost_size()

If the ghost_shape is set for this view, then it returns the size obtained after quantics folding by the function set_Q() or after reshaping by the function reshape(). Otherwise the size of the view is returned.

get_global_ndim()

Always returns the ndim of the underlying tensor

get_global_shape()

Always returns the shape of the underlying tensor

get_global_size()

Always returns the size of the underlying tensor

get_ndim()

Always returns the number of dimensions of the tensor view

get_shape()

Always returns the shape of the actual tensor view

get_size()

Always returns the size of the tensor view

get_view_ndim()

Always returns the ndim of the current view

get_view_shape()

Always returns the shape of the current view

get_view_size()

Always returns the size of the current view

ghost_to_global(idxs)

This maps the index from the current ghost shape of the view to the global shape.

Parameters:idxs_in (list) – list of indices to be transformed

Note

no slicing is admitted here. Preprocess idxs with expand_idxs() if slicing is required.

ghost_to_view(idxs)

This maps the index from the current ghost shape of the view to the view shape.

Parameters:idxs_in (list) – list of indices to be transformed

Note

no slicing is admitted here. Preprocess idxs with expand_idxs() if slicing is required.

global_to_ghost(idxs)

This maps the index from the global shape to the ghost shape.

Parameters:idxs (list) – list of indices to be transformed

Note

no slicing is admitted here. Preprocess idxs with expand_idxs() if slicing is required.

For TensorWrapper() A, this corresponds to:

>>> A.view_to_ghost( A.global_to_view( idxs ) )

global_to_view(idxs)

This maps the index from the global shape to the view shape.

Parameters:idxs (tuple) – tuple representing an index to be transformed.

Note

no slicing is admitted here. Preprocess idxs with expand_idxs() if slicing is required.

Note

this returns an error if the idxs do not belong to the index mapping of the current view.

refine(X_new, tol=None)

Refine the global discretization. The new discretization must contain the old one.

This function takes care of updating all the indices in the global view as well in all the other views.

Parameters:

• X_new (list) – list of coordinates of the new refinement
• tol (float) – tolerance for the matching of coordinates

Warning

Any existing reshaping of the views is discarded.

release_indices()

Release all the indices in the tensor wrapper which were fixed using fix_indices().

reset_ghost_shape()

Reset the shape of the tensor erasing the reshape and quantics foldings.

reset_shape()

Reset the shape of the tensor erasing the reshape and quantics foldings.

reshape(newshape)

Reshape the tensor. The number of items in the new shape must be consistent with get_extended_size(), i.e. with the number of items in the extended quantics size or the view size if Q is not set for this view.

This will unset any fixed index for the current view set using fix_indices().

Parameters:newshape (list) – new shape to be applied to the tensor.

set_Q(Q)

Set the quantics folding base for the current view.

This will unset any fixed index for the current view set using fix_indices().

Parameters:Q (int) – folding base.

set_active_view(view)

Set a view among the ones in self.maps.

Parameters:view (str) – name of the view to be set as active

set_active_weights(flag)

Set whether to use the weights or not.

Parameters:flag (bool) – If True the items returned by the Tensor Wrapper will be weighted according to the weights provided at construction time. If False the original values of the function will be returned.

set_view(view, X_map, tol=None)

Set or add a view to self.maps. This resest all the existing reshape parameters in existing views.

Parameters:

• view (str) – name of the view to be added
• X_map (list) – list of coordinates of the new view
• tol (float) – tolerance for the matching of coordinates

set_weights(W)

Set a new list of weights for the tensor :param list W: list of np.ndarray with weights for each dimension

shape_to_ghost(idxs_in)

This maps the index from the current shape of the view (fixed indices) to the ghost shape.

Parameters:idxs_in (list) – list of indices to be transformed

Note

slicing is admitted here.

shape_to_global(idxs)

This maps the index from the current shape of the view to the global shape.

Parameters:idxs_in (list) – list of indices to be transformed

Note

no slicing is admitted here. Preprocess idxs with expand_idxs() if slicing is required.

shape_to_view(idxs)

This maps the index from the current shape of the view to the view shape.

Parameters:idxs_in (list) – list of indices to be transformed

Note

no slicing is admitted here. Preprocess idxs with expand_idxs() if slicing is required.

to_v_0_3_0(store_location)

Upgrade to v0.3.0

Parameters:filename (string) – path to the filename. This must be the main filename with no extension.

view_to_ghost(idxs)

This maps the index from the view to the ghost shape.

Parameters:idxs (list) – list of indices to be transformed

Note

no slicing is admitted here. Preprocess idxs with expand_idxs() if slicing is required.

Note

this returns an error if the ghost shape is obtained by quantics folding, because the one view index can be pointing to many indices in the folding.

view_to_global(idxs)

This maps the index in view to the global indices of the full tensor wrapper.

Parameters:idxs_in (list) – list of indices to be transformed

Note

no slicing is admitted here. Preprocess idxs with expand_idxs() if slicing is required.