`syft.generic.pointers.pointer_tensor`¶

Module Contents¶

class syft.generic.pointers.pointer_tensor.PointerTensor(location: AbstractWorker = None, id_at_location: Union[str, int] = None, owner: AbstractWorker = None, id: Union[str, int] = None, garbage_collect_data: bool = True, shape: FrameworkShapeType = None, point_to_attr: str = None, tags: List[str] = None, description: str = None)¶

Bases: syft.generic.pointers.object_pointer.ObjectPointer, syft.generic.tensor.AbstractTensor

A pointer to another tensor.

A PointerTensor forwards all API calls to the remote.PointerTensor objects point to tensors (as their name implies). They exist to mimic the entire API of a normal tensor, but instead of computing a tensor function locally (such as addition, subtraction, etc.) they forward the computation to a remote machine as specified by self.location. Specifically, every PointerTensor has a tensor located somewhere that it points to (they should never exist by themselves). Note that PointerTensor objects can point to both FrameworkTensor objects AND to other PointerTensor objects. Furthermore, the objects being pointed to can be on the same machine or (more commonly) on a different one. Note further that a PointerTensor does not know the nature how it sends messages to the tensor it points to (whether over socket, http, or some other protocol) as that functionality is abstracted in the AbstractWorker object in self.location.

Example

>>> import syft as sy
>>> hook = sy.TorchHook()
>>> bob = sy.VirtualWorker(id="bob")
>>> x = sy.Tensor([1,2,3,4,5])
>>> y = sy.Tensor([1,1,1,1,1])
>>> x_ptr = x.send(bob) # returns a PointerTensor, sends tensor to Bob
>>> y_ptr = y.send(bob) # returns a PointerTensor, sends tensor to Bob
>>> # executes command on Bob's machine
>>> z_ptr = x_ptr + y_ptr

fix_precision¶

float_precision¶

get_shape(self)¶: Request information about the shape to the remote worker

property shape(self)¶: This method returns the shape of the data being pointed to. This shape information SHOULD be cached on self._shape, but occasionally this information may not be present. If this is the case, then it requests the shape information from the remote object directly (which is inefficient and should be avoided).

property grad(self)¶

property data(self)¶

is_none(self)¶

clone(self)¶: Clone should keep ids unchanged, contrary to copy. We make the choice that a clone operation is local, and can’t affect the remote tensors, so garbage_collect_data is always False, both for the tensor cloned and the clone.

get_class_attributes(self)¶: Used for cloning (see AbtractTensor)

static create_pointer(tensor, location: AbstractWorker = None, id_at_location: str or int = None, register: bool = False, owner: AbstractWorker = None, ptr_id: str or int = None, garbage_collect_data=None, shape=None)¶

Creates a pointer to the “self” FrameworkTensor object.

This method is called on a FrameworkTensor object, returning a pointer to that object. This method is the CORRECT way to create a pointer, and the parameters of this method give all possible attributes that a pointer can be created with.

Parameters

location – The AbstractWorker object which points to the worker on which this pointer’s object can be found. In nearly all cases, this is self.owner and so this attribute can usually be left blank. Very rarely you may know that you are about to move the Tensor to another worker so you can pre-initialize the location attribute of the pointer to some other worker, but this is a rare exception.
id_at_location – A string or integer id of the tensor being pointed to. Similar to location, this parameter is almost always self.id and so you can leave this parameter to None. The only exception is if you happen to know that the ID is going to be something different than self.id, but again this is very rare and most of the time, setting this means that you are probably doing something you shouldn’t.
register – A boolean parameter (default False) that determines whether to register the new pointer that gets created. This is set to false by default because most of the time a pointer is initialized in this way so that it can be sent to someone else (i.e., “Oh you need to point to my tensor? let me create a pointer and send it to you” ). Thus, when a pointer gets created, we want to skip being registered on the local worker because the pointer is about to be sent elsewhere. However, if you are initializing a pointer you intend to keep, then it is probably a good idea to register it, especially if there is any chance that someone else will initialize a pointer to your pointer.
owner – A AbstractWorker parameter to specify the worker on which the pointer is located. It is also where the pointer is registered if register is set to True.
ptr_id – A string or integer parameter to specify the id of the pointer in case you wish to set it manually for any special reason. Otherwise, it will be set randomly.
garbage_collect_data – If true (default), delete the remote tensor when the pointer is deleted.

Returns

A FrameworkTensor[PointerTensor] pointer to self. Note that this object itself will likely be wrapped by a FrameworkTensor wrapper.

move(self, location)¶

remote_send(self, destination, change_location=False)¶: Request the worker where the tensor being pointed to belongs to send it to destination. For instance, if C holds a pointer, ptr, to a tensor on A and calls ptr.remote_send(B), C will hold a pointer to a pointer on A which points to the tensor on B. If change_location is set to True, the original pointer will point to the moved object. Considering the same example as before with ptr.remote_send(B, change_location=True): C will hold a pointer to the tensor on B. We may need to be careful here because this pointer will have 2 references pointing to it.

remote_get(self)¶

get(self, user=None, reason: str = '', deregister_ptr: bool = True)¶

Requests the tensor/chain being pointed to, be serialized and return

Since PointerTensor objects always point to a remote tensor (or chain of tensors, where a chain is simply a linked-list of tensors linked via their .child attributes), this method will request that the tensor/chain being pointed to be serialized and returned from this function.

Note

This will typically mean that the remote object will be removed/destroyed. To just bring a copy back to the local worker, call .copy() before calling .get().

Parameters

user (obj, optional) – user credentials to perform authentication process.
reason (str, optional) – a description of why the data scientist wants to see it.
deregister_ptr (bool, optional) – this determines whether to deregister this pointer from the pointer’s owner during this method. This defaults to True because the main reason people use this method is to move the tensor from the remote machine to the local one, at which time the pointer has no use.

Returns

An AbstractTensor object which is the tensor (or chain) that this object used to point to #on a remote machine.

attr(self, attr_name)¶

dim(self)¶

fix_prec(self, *args, **kwargs)¶

Send a command to remote worker to transform a tensor to fix_precision

Returns: A pointer to an FixPrecisionTensor

float_prec(self, *args, **kwargs)¶

Send a command to remote worker to transform a fix_precision tensor back to float_precision

Returns: A pointer to a Tensor

share(self, *args, **kwargs)¶

Send a command to remote worker to additively share a tensor

Returns: A pointer to an AdditiveSharingTensor

keep(self, *args, **kwargs)¶

Send a command to remote worker to keep a promise

Returns: A pointer to a Tensor

value(self, *args, **kwargs)¶

Send a command to remote worker to get the result generated by a promise.

Returns: A pointer to a Tensor

share_(self, *args, **kwargs)¶

Send a command to remote worker to additively share inplace a tensor

Returns: A pointer to an AdditiveSharingTensor

set_garbage_collect_data(self, value)¶

item(self)¶: Raising error with a message to be using .get instead of .item

__eq__(self, other)¶

static simplify(worker: AbstractWorker, ptr: PointerTensor)¶

This function takes the attributes of a PointerTensor and saves them in a dictionary :param worker: the worker doing the serialization :type worker: AbstractWorker :param ptr: a PointerTensor :type ptr: PointerTensor

Returns: a tuple holding the unique attributes of the pointer
Return type: tuple

Examples

data = simplify(ptr)

static detail(worker: AbstractWorker, tensor_tuple: tuple)¶

This function reconstructs a PointerTensor given it’s attributes in form of a dictionary. We use the spread operator to pass the dict data as arguments to the init method of PointerTensor :param worker: the worker doing the deserialization :param tensor_tuple: a tuple holding the attributes of the PointerTensor

Returns: a PointerTensor
Return type: PointerTensor

Examples

ptr = detail(data)

static bufferize(worker: AbstractWorker, ptr: PointerTensor)¶

static unbufferize(worker: AbstractWorker, protobuf_tensor: PointerTensorPB)¶

syft.generic.pointers.pointer_tensor¶

Module Contents¶

`syft.generic.pointers.pointer_tensor`¶