4.1. Component Base Class Reference

class rlgraph.components.component.Component(*sub_components, **kwargs)

Bases: rlgraph.utils.specifiable.Specifiable

Base class for a graph component (such as a layer, an entire function approximator, a memory, an optimizers, etc..).

A component can contain other components and/or its own graph-logic (e.g. tf ops). A component’s sub-components are connected to each other via in- and out-Sockets (similar to LEGO blocks and deepmind’s sonnet).

This base class implements the interface to add sub-components, create connections between different sub-components and between a sub-component and this one and between this component and an external component.

A component also has a variable registry, the ability to save the component’s structure and variable-values to disk, and supports adding its graph_fns to the overall computation graph.

add_components(*components, **kwargs)

Adds sub-components to this one.

Args:

components (List[Component]): The list of Component objects to be added into this one.

Keyword Args:

expose_apis (Optional[Set[str]]): An optional set of strings with API-methods of the child component

that should be exposed as the parent’s API via a simple wrapper API-method for the parent (that calls the child’s API-method).

#exposed_must_be_complete (bool): Whether the exposed API methods must be input-complete or not.

static assign_variable(ref, value)

Assigns a variable to a value.

Args:

ref (any): The variable to assign to. value (any): The value to use for the assignment.

Returns:

Optional[op]: None or the graph operation representing the assginment.

call_count = 0

call_times = []

check_input_completeness()

Checks whether this Component is “input-complete” and stores the result in self.input_complete. Input-completeness is reached (only once and then it stays that way) if all API-methods of this component (whose must_be_complete field is not set to False) have all their input Spaces defined.

Returns:

bool: Whether this Component is input_complete or not.

check_input_spaces(input_spaces, action_space=None)

Should check on the nature of all in-Sockets Spaces of this Component. This method is called automatically by the Model when all these Spaces are know during the Model’s build time.

Args:

input_spaces (Dict[str,Space]): A dict with Space/shape information.

keys=in-Socket name (str); values=the associated Space

action_space (Optional[Space]): The action Space of the Agent/GraphBuilder. Can be used to construct and

connect more Components (which rely on this information). This eliminates the need to pass the action Space information into many Components’ constructors.

check_variable_completeness()

Checks, whether this Component is input-complete AND all our sub-Components are input-complete. At that point, all variables are defined and we can run the _variables graph_fn.

Returns:

bool: Whether this Component is “variables-complete”.

copy(name=None, scope=None, device=None, trainable=None, reuse_variable_scope=None, reuse_variable_scope_for_sub_components=None)

Copies this component and returns a new component with possibly another name and another scope. The new component has its own variables (they are not shared with the variables of this component as they will be created after this copy anyway, during the build phase). and is initially not connected to any other component.

Args:

name (str): The name of the new Component. If None, use the value of scope. scope (str): The scope of the new Component. If None, use the same scope as this component. device (str): The device of the new Component. If None, use the same device as this one.

trainable (Optional[bool]): Whether to make all variables in this component trainable or not. Use None

for no specific preference.

reuse_variable_scope (Optional[str]): If not None, variables of the copy will be shared under this scope.

reuse_variable_scope_for_sub_components (Optional[str]): If not None, variables only of the sub-components

of the copy will be shared under this scope.

Returns:

Component: The copied component object.

create_summary(name, values, type_='histogram')

Creates a summary op (and adds it to the graph). Skips those, whose full name does not match self.summary_regexp.

Args:

name (str): The name for the summary. This has to match self.summary_regexp.

The name should not contain a “summary”-prefix or any global scope information (both will be added automatically by this method).

values (op): The op to summarize.

type_ (str): The summary type to create. Currently supported are:

“histogram”, “scalar” and “text”.

create_variables(input_spaces, action_space=None)

Should create all variables that are needed within this component, unless a variable is only needed inside a single _graph_fn-method, in which case, it should be created there. Variables must be created via the backend-agnostic self.get_variable-method.

Note that for different scopes in which this component is being used, variables will not(!) be shared.

Args:

input_spaces (Dict[str,Space]): A dict with Space/shape information.

keys=in-Socket name (str); values=the associated Space

action_space (Optional[Space]): The action Space of the Agent/GraphBuilder. Can be used to construct and

connect more Components (which rely on this information). This eliminates the need to pass the action Space information into many Components’ constructors.

get_all_sub_components(list_=None, level_=0)

Returns all sub-Components (including self) sorted by their nesting-level (… grand-children before children before parents).

Args:

list_ (Optional[List[Component]])): A list of already collected components to append to. level_ (int): The slot indicating the Component level depth in list_ at which we are currently.

Returns:

List[Component]: A list with all the sub-components in self and self itself.

get_number_of_allowed_inputs(api_method_name)

Returns the number of allowed input args for a given API-method.

Args:

api_method_name (str): The API-method to analyze.

Returns:

Tuple[int,int]: A tuple with the range (lower/upper bound) of allowed input args for the given API-method.

An upper bound of None means that the API-method accepts any number of input args equal or larger than the lower bound.

get_parents()

Returns a list of parent and grand-parents of this component.

Returns:

List[Component]: A list (may be empty if this component has no parents) of all parent and grand-parents.

get_sub_component_by_global_scope(scope)

Returns a sub-Component (or None if not found) by scope. The sub-coponent’s scope should be given as global scope of the sub-component (not local scope with respect to this Component).

Args:

scope (str): The global scope of the sub-Component we are looking for.

Returns:

Component: The sub-Component with the given global scope if found, None if not found.

get_sub_component_by_name(name)

Returns a sub-Component (or None if not found) by its name (local scope). The sub-Component must be a direct sub-Component of self.

Args:

name (str): The name (local scope) of the sub-Component we are looking for.

Returns:

Component: The sub-Component with the given name if found, None if not found.

Raises:

RLGraphError: If a sub-Component by that name could not be found.

get_variable(name='', shape=None, dtype='float', initializer=None, trainable=True, from_space=None, add_batch_rank=False, add_time_rank=False, time_major=False, flatten=False, local=False, use_resource=False)

Generates or returns a variable to use in the selected backend. The generated variable is automatically registered in this component’s (and all parent components’) variable-registry under its global-scoped name.

Args:

name (str): The name under which the variable is registered in this component.

shape (Optional[tuple]): The shape of the variable. Default: empty tuple.

dtype (Union[str,type]): The dtype (as string) of this variable.

initializer (Optional[any]): Initializer for this variable.

trainable (bool): Whether this variable should be trainable. This will be overwritten, if the Component

has its own trainable property set to either True or False.

from_space (Optional[Space,str]): Whether to create this variable from a Space object

(shape and dtype are not needed then). The Space object can be given directly or via the name of the in-Socket holding the Space.

add_batch_rank (Optional[bool,int]): If True and from_space is given, will add a 0th (1st) rank (None) to

the created variable. If it is an int, will add that int instead of None. Default: False.

add_time_rank (Optional[bool,int]): If True and from_space is given, will add a 1st (0th) rank (None) to

the created variable. If it is an int, will add that int instead of None. Default: False.

time_major (bool): Only relevant if both add_batch_rank and add_time_rank are True.

Will make the time-rank the 0th rank and the batch-rank the 1st rank. Otherwise, batch-rank will be 0th and time-rank will be 1st. Default: False.

flatten (bool): Whether to produce a FlattenedDataOp with auto-keys.

local (bool): Whether the variable must not be shared across the network.

Default: False.

use_resource (bool): Whether to use the new tf resource-type variables.

Default: False.

Returns:

DataOp: The actual variable (dependent on the backend) or - if from

a ContainerSpace - a FlattenedDataOp or ContainerDataOp depending on the Space.

get_variables(*names, **kwargs)

Utility method to get one or more component variable(s) by name(s).

Args:

names (List[str]): Lookup name strings for variables. None for all.

Keyword Args:

collections (set): A set of collections to which the variables have to belong in order to be returned here.

Default: tf.GraphKeys.TRAINABLE_VARIABLES

custom_scope_separator (str): The separator to use in the returned dict for scopes.

Default: ‘/’.

global_scope (bool): Whether to use keys in the returned dict that include the global-scopes of the

Variables. Default: False.

Returns:

dict: A dict mapping variable names to their get_backend variables.

get_variables_by_name(*names, **kwargs)

Retrieves this components variables by name.

Args:

names (List[str]): List of names of Variable to return.

Keyword Args:

custom_scope_separator (str): The separator to use in the returned dict for scopes.

Default: ‘/’.

global_scope (bool): Whether to use keys in the returned dict that include the global-scopes of the

Variables. Default: False.

Returns:

dict: Dict containing the requested names as keys and variables as values.

propagate_scope(sub_component)

Fixes all the sub-Component’s (and its sub-Component’s) global_scopes.

Args:

sub_component (Optional[Component]): The sub-Component object whose global_scope needs to be updated.

Use None for this Component itself.

propagate_sub_component_properties(properties, component=None)

Recursively updates properties of component and its sub-components.

Args:

properties (dict): Dict with names of properties and their values to recursively update

sub-components with.

component (Optional([Component])): Component to recursively update. Uses self if None.

propagate_summary(key_)

Propagates a single summary op of this Component to its parents’ summaries registries.

Args:

key_ (str): The lookup key for the summary to propagate.

propagate_variables(keys=None)

Propagates all variable from this Component to its parents’ variable registries.

Args:

keys (Optional[List[str]]): An optional list of variable names to propagate. Should only be used in

internal, recursive calls to this same method.

static read_variable(variable, indices=None)

Reads a variable.

Args:

variable (DataOp): The variable whose value to read. indices (Optional[np.ndarray,tf.Tensor]): Indices (if any) to fetch from the variable.

Returns:

any: Variable values.

register_api_methods_and_graph_fns()

Detects all methods of the Component that should be registered as API-methods for this Component and complements self.api_methods and self.api_method_inputs. Goes by the @api decorator before each API-method or graph_fn that should be auto-thin-wrapped by an API-method.

register_variables(*variables)

Adds already created Variables to our registry. This could be useful if the variables are not created by our own self.get_variable method, but by some backend-specific object (e.g. tf.layers). Also auto-creates summaries (regulated by self.summary_regexp) for the given variables.

Args:

# TODO check if we warp PytorchVariable variables (Union[PyTorchVariable, SingleDataOp]): The Variable objects to register.

remove_sub_component_by_name(name)

Removes a sub-component from this one by its name. Thereby sets the parent_component property of the removed Component to None. Raises an error if the sub-component does not exist.

Args:

name (str): The name of the sub-component to be removed.

Returns:

Component: The removed component.

static reset_profile()

Sets profiling values to 0.

static scatter_update_variable(variable, indices, updates)

Updates a variable. Optionally returns the operation depending on the backend.

Args:

variable (any): Variable to update. indices (array): Indices to update. updates (any): Update values.

Returns:

Optional[op]: The graph operation representing the update (or None).

sub_component_by_name(scope_name)

Returns a sub-component of this component by its name.

Args:

scope_name (str): Name of the component. This is typically its scope.

Returns:

Component: Sub-component if it exists.

Raises:

ValueError: Error if no sub-component with this name exists.

when_input_complete(input_spaces=None, action_space=None, device=None, summary_regexp=None)

Wrapper that calls both self.check_input_spaces and self.create_variables in sequence and passes the dict with the input_spaces for each argument (key=arg name) and the action_space as parameter.

Args:

input_spaces (Optional[Dict[str,Space]]): A dict with Space/shape information.

keys=in-argument name (str); values=the associated Space. Use None to take self.api_method_inputs instead.

action_space (Optional[Space]): The action Space of the Agent/GraphBuilder. Can be used to construct and connect

more Components (which rely on this information). This eliminates the need to pass the action Space information into many Components’ constructors.

device (str): The device to use for the variables generated.

summary_regexp (Optional[str]): A regexp (str) that defines, which summaries should be generated

and registered.