motornet.nets.layers#

class motornet_tf.nets.layers.GRUNetwork(*args, **kwargs)#

Bases: Network

A GRU network acting as a controller to the plant. The last layer of the network is a tensorflow.keras.layers.Dense dense layer containing n_muscles * k units, with k being the number of inputs a single muscle takes (as defined by the muscle_type that the plant object uses), and n_muscles the number of muscles that the plant contains.

Parameters:

plant – A motornet.plants.plants.Plant object class or subclass. This is the plant that the Network will control.
n_units – Integer or list, the number of GRUs per layer. If only one layer is created, then this can be an integer.
n_hidden_layers – Integer, the number of hidden layers of GRUs that the network will implement.
activation – String or activation function from tensorflow. The activation function used as non-linearity for all GRUs.
kernel_regularizer – Float, the kernel regularization weight for the GRUs.
recurrent_regularizer – Float, the recurrent regularization weight for the GRUs.
hidden_noise_sd – Float, the standard deviation of the gaussian noise process applied to GRU hidden activity.
output_bias_initializer – A tensorflow.keras.initializers instance to initialize the biases of the last layer of the network (i.e., the output layer).
output_kernel_initializer – A tensorflow.keras.initializers instance to initialize the kernels of the last layer of the network (i.e., the output layer).
**kwargs – This is passed to the parent tensorflow.keras.layers.Layer class as-is.

build(input_shapes)#

Creates the variables of the layer (for subclass implementers).

This is a method that implementers of subclasses of Layer or Model can override if they need a state-creation step in-between layer instantiation and layer call. It is invoked automatically before the first execution of call().

This is typically used to create the weights of Layer subclasses (at the discretion of the subclass implementer).

Parameters:: input_shape – Instance of TensorShape, or list of instances of TensorShape if the layer expects a list of inputs (one instance per input).

forward_pass(inputs, states)#

Performs the forward pass computation.

Parameters:

inputs – Tensor, inputs to the first layer of the network.
states – List of tensor arrays representing the states of each layer operating on a state (state-based layers).

Returns:

A tensor array, the output of the last layer to use as the motor command, or excitation to the plant.
A list of the new hidden states of the GRU layers.
A dictionary of the new hidden states of the GRU layers.

get_initial_state(inputs=None, batch_size: int = 1, dtype=tf.float32)#

Creates the initial states for the first timestep of the network training procedure. This method provides the states for the full Network class, that is the default states from the Network.get_base_initial_state() method followed by the states specific to this subclass.

Parameters:

inputs – The joint state from which the other state values are inferred. This is passed as-is to the motornet.plants.plants.Plant.get_initial_state() method, and therefore obeys the structure documented there.
batch_size – Integer, the batch size defining the size of each state’s first dimension.
dtype – A dtype from the tensorflow.dtypes module.

Returns:

A list containing the output of the Network.get_base_initial_state() method, followed by the hidden states of each GRU layer as tensor arrays.

get_save_config()#

Gets the base configuration from the motornet.nets.layers.Network.get_base_config() method, and adds the configuration information specific to the GRUNetwork class to that dictionary. These are:

The standard deviation of the gaussian noise process to the GRU hidden activity.

The kernel regularizer weight.

The recurrent regularizer weight.

The number of GRU units per hidden layer. If there are several layers, this will be a list.

The number of hidden GRU layers.

The name of the activation function used as non-linearity for the hidden GRU layers.

Returns:: A dictionary containing the object instance’s full configuration.

class motornet_tf.nets.layers.Network(*args, **kwargs)#

Bases: Layer

Base class for controller Network objects. It implements a network whose function is to control the plant provided as input at initialization. This object can be subclassed to implement virtually anything that tensorflow can implement as a deep neural network, so long as it abides by the state structure used in motornet (see below for details).

Parameters:

plant – A motornet.plants.plants.Plant object class or subclass. This is the plant that the Network will control.
proprioceptive_noise_sd – Float, the standard deviation of the gaussian noise process for the proprioceptive feedback loop. The gaussian noise process is a normal distribution centered on 0.
visual_noise_sd – Float, the standard deviation of the random noise process for the visual feedback loop. The random process is a normal distribution centered on 0.
n_ministeps – Integer, the number of timesteps that the plant is simulated forward for each forward pass of the deep neural network. For instance, if the (global) timestep size is 1 ms, and n_ministeps is 5, then the plant will be simulated for every 0.2 ms timesteps, with the excitatory drive from the controller only being updated every 1 ms.
**kwargs – This is passed to the parent tensorflow.keras.layers.Layer class as-is.

call(inputs, states=None, **kwargs)#

The logic for a single simulation step. This performs a single forward pass through the network, and passes the network output as excitation signals (motor commands) to the plant object to simulate movement.

Parameters:

inputs – Dictionary of tensor arrays. At the very least, this should contain a “inputs” key mapped to a tensor array, which will be passed as-is to the network’s input layer. Additional keys will be passed as **kwargs to the plant call.
states – List, contains all the states of the plant, and of the network if any exist. The state order in the list follows the same convention as the get_initial_states() method.
kwargs – For backward compatibility only.

Returns:

A dictionary containing the new states.
A list containing the new states in the same order convention as the get_initial_states() method. While this output is redundant to the user, it is necessary for tensorflow to process the network over time.

abstract forward_pass(inputs, states)#

Performs the forward pass through the network layers to obtain the motor commands that will then be passed on to the plant.

Parameters:

inputs – Tensor, inputs to the first layer of the network.
states – List of tensor arrays, containing the states of each layer operating on a state.

Returns:

A tensor array, the output of the last layer to use as the motor command, or excitation to the plant.
A list of the new states inherent to potential layers operating on a state.
A dictionary of the new states inherent to potential layers operating on a state.

Raises:

NotImplementedError – If this method is not overwritten by a subclass object.

classmethod from_config(config)#

Creates a layer from its config.

This method is the reverse of get_config, capable of instantiating the same layer from the config dictionary. It does not handle layer connectivity (handled by Network), nor weights (handled by set_weights).

Parameters:: config – A Python dictionary, typically the output of get_config.
Returns:: A layer instance.

get_base_config()#

Gets the object instance’s base configuration. This is the set of configuration entries that will be useful for any Network class or subclass. This method should be called by the get_save_config() method. Users wanting to save additional configuration entries specific to a Network subclass should then do so in the get_save_config() method, using this method’s output dictionary as a base.

Returns:: A dictionary containing the network’s proprioceptive and visual noise standard deviation and delay, and the number of muscles and ministeps.

get_base_initial_state(inputs=None, batch_size: int = 1, dtype=tf.float32)#

Creates the base initial states for the first timestep of the network training procedure. This method provides the base states for the default Network class, in the order listed below:

joint state

cartesian state

muscle state

geometry state

proprioception feedback array

visual feedback array

excitation state

This method should be called in the get_initial_state() method to provide a base for the output of that method.

Parameters:

inputs – The joint state from which the other state values are inferred. This is passed as-is to the motornet.plants.plants.Plant.get_initial_state() method, and therefore obeys the structure documented there.
batch_size – Integer, the batch size defining the size of each state’s first dimension.
dtype – A dtype from the tensorflow.dtypes module.

Returns:

A list of the states as tensor arrays in the order listed above.

get_initial_state(inputs=None, batch_size: int = 1, dtype=tf.float32)#

Creates the initial states for the first timestep of the network training procedure. This method provides the states for the full Network class, that is the default states from the get_base_initial_state() method followed by the states specific to a potential subclass. This method should be overwritten by subclassing objects, and used to add new states specific to that subclass.

Parameters:

inputs – The joint state from which the other state values are inferred. This is passed as-is to the motornet.plants.plants.Plant.get_initial_state() method, and therefore obeys the logic documented there.
batch_size – Integer, the batch size defining the size of each state’s first dimension.
dtype – A dtype from the tensorflow.dtypes module.

Returns:

By default, this method returns the output of the get_base_initial_state() method, that is a list of the states as tensor arrays.

get_save_config()#

Gets the Network object’s configuration as a dictionary. This method should be overwritten by subclass objects, and used to add configuration entries specific to that subclass.

Returns:: By default, this method returns the output of the get_base_config() method.

motornet_tf.nets.layers.recttanh(x)#: A rectified hyperbolic tangent activation function.