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.

Misc

List Brief
Snapshot Snapshot tensors into a binary file.
Restore Restore tensors from a binary file.
SwitchWorkspace Switch to the specific Workspace.
MoveWorkspace Move the source workspace into the target workspace.
ResetWorkspace Reset the specific workspace.
ClearWorkspace Clear the specific workspace.
LogMetaGraph Log the meta graph.
ExportMetaGraph Export the meta graph into a file under specific folder.

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

Bases: object

We apply the TensorPool to manage the reused tensors.

Tensors with the same scope in the pool will be reused by turns, which speeds up the whole system by reducing the unnecessary deconstructing.

Heuristically, we have used 5 pools with different scopes:

  • scope(Leaf): A Pool to reuse leaf tensors.
  • scope(NumPy): A pool to reuse leaf tensors from numpy.
  • scope(Join): A pool to reuse RT(runtime) tensors required by forward-backward.
  • scope(Detach): A pool to reuse RT(runtime) tensors required by forward only.
  • scope(Reference): A pool to reuse reshaped tensors(sharing contents).
get(scope='${DETACH}')
put(name)
class dragon.core.workspace.OperatorPool

Bases: object

Operators whose gradients is required will hold a resource handle, which is also called Anchor in the backend.

We apply this pool to collect the handles according to the type of operator, as the mem size of temporal resources varies greatly.

The resource handle will be released after the gradient flow automatically.

get(op_type)
put(op_name)
class dragon.core.workspace.Workspace(name='')

Bases: dragon.libdragon.Workspace

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_ref(name)
get_collection(name, scope=None)
add_to_collection(name, value)
add_to_collections(names, value)
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.GetFillerType(tensor)

Get the filler type of specific tensor.

It is useful if you want to tag some tensors,

e.g. tag with numpy, and get to initialize them lazily.

Parameters:tensor (Tensor or str) – The tensor to query.
Returns:The filler type.
Return type:str
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.LogMetaGraph(graph_def)

Log the meta graph.

Parameters:graph_def (GraphDef) – The definition of meta graph.
Returns:
Return type:None
dragon.core.workspace.ExportMetaGraph(graph_def)

Export the meta graph into a file under specific folder.

You can set the exporting prefix by config.ExportMetaGraph(prefix).

Parameters:graph_def (GraphDef) – The definition of meta graph.
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

Notes

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