Workspace

Workspace

List Brief
Workspace(object) A wrapper for the C implemented workspace.
get_default_workspace Return the current default workspace.
reset_default_workspace Reset the global default workspace.

Tensor

List Brief
HasTensor Query whether tensor has registered in current workspace.
CreateFiller Create the filler in the backend.
GetTensorName Query the name represented in current workspace.
SetTensorAlias Bind a alias to a existed tensor.
FeedTensor Feed the values to the given tensor.
FetchTensor Fetch the values of given tensor.
ResetTensor Reset the memory of given tensor.

Operator

List Brief
RunOperator Run the operator in the VM backend.

Graph

List Brief
CreateGraph Create the graph in the backend.
RunGraph Run the specific graph.

I/O

List Brief
Snapshot Snapshot tensors into a binary file.
Restore Restore tensors from a binary file.

API Reference

Wrappers for the Workspace of C++ backend.

Flexible API is provided to manage the global resources between the Python threads (quite different from C++).

class dragon.core.workspace.TensorPool

A wrapper to manage the reused tensors.

Tensors with the same scope will be reused by turns, and thus, unnecessary deconstructing is reduced.

Heuristically, five pools with different scopes are used:

  • ${LEAF}: A pool to reuse leaf tensors.
  • ${NUMPY}: A pool to reuse leaf tensors from numpy.
  • ${JOIN}: A pool to reuse RT(runtime) tensors required by forward-backward.
  • ${DETACH}: A pool to reuse RT(runtime) tensors required by forward-pass only.
  • ${REFERENCE}: A pool to reuse reshaped tensors(sharing contents).
get(scope='${DETACH}')

Return a unique name under the specified scope.

Parameters:scope (str, optional, default='${DETACH}') – The optional
Returns:The unique name can be used.
Return type:str
put(name)

Collect a unique name.

Parameters:name (str) – The name to collect.
class dragon.core.workspace.OperatorPool

A wrapper to manage the resource handle of operators.

Operators whose gradients is required will hold a resource handle.

We collect the handles according to the type of operator, as the size of resources varies greatly.

Handle will be released after the backward-pass automatically.

get(op_type)

Return a unique handle according to the op type.

Parameters:op_type (str) – The type of the operator.
Returns:The unique handle can be used.
Return type:str
put(handle)

Collect a unique handle.

Parameters:name (str) – The name to collect.
class dragon.core.workspace.Workspace(name='')

A wrapper for the C++ implemented workspace.

This class is a fusion of Workspace, Pool and tf.Graph.

We find that they work in a similar way while named differently.

get_collection(name, scope=None)

Return the specified collection.

Parameters:
  • name (str) – The key to the collection.
  • scope (str, optional) – The optional regex keyword.
Returns:

The collection list.

Return type:

list

get_collection_ref(name)

Return the reference of specified collection.

Parameters:name (str) – The key to the collection.
Returns:The collection list.
Return type:list
add_to_collection(name, value)

Add the value to the specified collection.

Parameters:
  • name (str) – The key to the collection.
  • value (object) – The value object.
Returns:

Return type:

None

add_to_collections(names, value)

Add the value to the specified collections.

Parameters:
  • name (sequence of str) – The key to the collections.
  • value (object) – The value object.
Returns:

Return type:

None

merge_from(other)

Merge a external workspace into self.

The other will not be reset until self is reset. Carefulness should be taken to associate with the workspaces.

Parameters:other (Workspace) – The given external workspace.
Returns:The self.
Return type:Workspace
as_default()

Switch self as the default workspace.

Call this method with the with keyword.

Once with is exited, the previous default will be set.

Returns:The self.
Return type:Workspace
clear()

Remove all the tensors.

Optionally call this method to clean the memories.

Returns:
Return type:None
dragon.core.workspace.get_default_workspace()

Return the current default workspace.

Returns:The default workspace.
Return type:Workspace
dragon.core.workspace.reset_default_workspace()

Reset the global default workspace.

Do not call this method to reset any instances.

Returns:
Return type:None
dragon.core.workspace.CreateGraph(graph_def)

Create the graph in current workspace.

Parameters:graph_def (GraphDef) – The definition of meta graph.
Returns:The graph name to run.
Return type:str
dragon.core.workspace.RunOperator(op_def, verbose=False)

Run the operator.

Parameters:
  • op_def (OperatorDef) – The definition of operator.
  • verbose (boolean) – Whether to print the definition.
Returns:

Return type:

None

dragon.core.workspace.HasTensor(tensor)

Query whether tensor has registered in current workspace.

Parameters:tensor (Tensor or str) – The tensor to query.
Returns:The query result.
Return type:boolean
dragon.core.workspace.CreateTensor(tensor)

Create the tensor in the backend.

Parameters:tensor (Tensor or str) – The tensor to create.
Returns:
Return type:None
dragon.core.workspace.CreateFiller(filler_def)

Create the filler in the backend.

Parameters:filler_def (TensorFiller) – The filler.
Returns:
Return type:None

See also

Tensor.Fill(*args, **kwargs) - How to fill a Tensor. [Caffe Style]

dragon.core.workspace.GetTensorName(tensor)

Query the name represented in current workspace.

Parameters:tensor (Tensor or str) – The tensor to query.
Returns:The real(inplace-optimized) name in the backend.
Return type:str

Notes

The query result may be different from the one used in the frontend.

dragon.core.workspace.SetTensorAlias(tensor, alias)

Bind a alias to a existed tensor.

Parameters:
  • tensor (Tensor or str) – The tensor to bind the alias.
  • alias (str) – The alias.
Returns:

Return type:

None

dragon.core.workspace.FetchTensor(tensor)

Fetch the values of given tensor.

Parameters:tensor (Tensor or str) – The tensor to fetch.
Returns:The values copied from the backend.
Return type:numpy.ndarray
dragon.core.workspace.FeedTensor(tensor, array, force_cpu=False, dtype=None)

Feed the values to the given tensor.

Parameters:
  • tensor (Tensor or str) – The tensor to feed.
  • array (array_like) – The values to feed.
  • force_cpu (boolean, optional, default=False) – Whether force to feed to cpu context.
  • dtype (str, optional) – The optional data type.
Returns:

Return type:

None

Examples

>>> import dragon
>>> a = dragon.Tensor().Variable()
>>> dragon.workspace.FeedTensor(a, 1)
>>> a_value = dragon.workspace.FetchTensor(a)
>>> a_value, a_value.dtype
>>> [ 1.], "float32"
>>> dragon.workspace.FeedTensor(a, [[1, 2, 3]], dtype='float16')
>>> a_value = a.get_value()
>>> a_value, a_value.dtype
>>> [[ 1.  2.  3.]], "float16"
dragon.core.workspace.ResetTensor(tensor)

Reset the memory of given tensor.

Parameters:tensor (Tensor or str) – The tensor to reset.
Returns:
Return type:None
dragon.core.workspace.RunGraph(
   graph_name,
   inputs=(),
   outputs=[],
   stage=None,
   return_outputs=True
)

Run the specific graph.

Parameters:
  • graph_name (str) – The name of the graph.
  • inputs (tuple) – The tensors(list) and corresponding values(list).
  • outputs (list of Tensor) – The outputs of the graph.
  • stage (str) – The preset custom stages. See stages.
  • return_outputs (boolean) – Whether to return the outputs.
Returns:

The outputs which are copied to numpy array.

Return type:

sequence of numpy.ndarray

See also

theano.function(*args, **kwargs) - How to make a graph. [Theano Style]

dragon.core.workspace.Backward(forward_ops, targets, input_grads=None, ignored_grads=None)

Compute the gradients of given input operators.

Parameters:
  • forward_ops (sequence of OperatorDef) – The referring ops to generate gradients.
  • targets (sequence or str) – The solving targets.
  • input_grads (sequence of str, optional) – The external input grads.
  • ignored_grads (sequence of str, optional) – The grads that are explicitly ignored.
Returns:

Return type:

None

dragon.core.workspace.Snapshot(
   tensors,
   filename,
   prefix='',
   suffix='.bin',
   format='pickle'
)

Serialize tensors into a binary file.

The filename is formatted as:

prefix + filename + suffix
Parameters:
  • tensors (list of Tensor or Tensor) – The tensors to be wrote.
  • filename (str) – The name of this binary file.
  • prefix (str, optional, default='') – The prefix of this binary file.
  • suffix (str, optional, default='.bin') – The suffix of this binary file.
  • format ({'pickle', 'caffe'}, optional) – The format of this binary file.
Returns:

Return type:

None

dragon.core.workspace.Restore(binary_file, format='pickle')

Restore tensors from a binary file.

Parameters:
  • binary_file (str) – The path of binary file.
  • format ({'pickle', 'caffe'}, optional) – The format of this binary file.
Returns:

Return type:

None

dragon.core.workspace.GetDummyName(basename, suffix='', domain='', zero_based=True)

Return a unique dummy name in current active workspace.

The dummy name will be formatted basename + suffix, or basename + _unique_index + suffix.

Names in the different domain could be same.

Parameters:
  • basename (str) – The basename.
  • suffix (str) – The optional suffix adding to basename.
  • domain (str) – The optional domain name.
  • zero_based (boolean) – Whether number the name from 0.
Returns:

The unique dummy name.

Return type:

str

class dragon.core.workspace.Workspace(name='')

A wrapper for the C++ implemented workspace.

This class is a fusion of Workspace, Pool and tf.Graph.

We find that they work in a similar way while named differently.

__init__(name='')

Construct a Workspace instance.

Parameters:name (str, optional, default='') – The optional workspace name.
Returns:A new workspace.
Return type:Workspace
get_collection(name, scope=None)

Return the specified collection.

Parameters:
  • name (str) – The key to the collection.
  • scope (str, optional) – The optional regex keyword.
Returns:

The collection list.

Return type:

list

get_collection_ref(name)

Return the reference of specified collection.

Parameters:name (str) – The key to the collection.
Returns:The collection list.
Return type:list
add_to_collection(name, value)

Add the value to the specified collection.

Parameters:
  • name (str) – The key to the collection.
  • value (object) – The value object.
Returns:

Return type:

None

add_to_collections(names, value)

Add the value to the specified collections.

Parameters:
  • name (sequence of str) – The key to the collections.
  • value (object) – The value object.
Returns:

Return type:

None

merge_from(other)

Merge a external workspace into self.

The other will not be reset until self is reset. Carefulness should be taken to associate with the workspaces.

Parameters:other (Workspace) – The given external workspace.
Returns:The self.
Return type:Workspace
as_default()

Switch self as the default workspace.

Call this method with the with keyword.

Once with is exited, the previous default will be set.

Returns:The self.
Return type:Workspace
clear()

Remove all the tensors.

Optionally call this method to clean the memories.

Returns:
Return type:None