motornet.nets.losses#
This module implements custom tensorflow.python.keras.losses.Loss
objects that are useful for motor control.
Note
There are a couple naming conventions that this module employs:
Regularizer
indicates the penalization is applied to the value of the model’s output, not the error between the model’s output and a user-fed label.xDx
indicates that both the value and the derivative of the passed input is penalized, with the derivative loss scaled by a used-defined deriv_weight scalar compared to the value.
- class motornet_tf.nets.losses.ClippedPositionLoss(target_size: float, name: str = 'position', reduction='auto')#
Bases:
LossFunctionWrapper
Applies a L1 penalty to positional error between the model’s output positional state
x
and a user-fed label positiony
:xp, _ = np.split(x, 2, axis=-1) # remove velocity from the positional state yp, _ = np.split(y, 2, axis=-1) loss = np.reduce_mean(np.abs(xp - yp))
If the radial distance to the desired position is less than a user-defined radius (target size), the loss is clipped to be 0.
Note
The positional error does not include velocity, hence the use of
np.split
to extract position from the state array.- Parameters:
target_size – Float, the radius around the desired position within which the position loss is clipped to 0.
name – String, the name (label) to give to the compounded loss object. This is used to print, plot, and save losses during training.
reduction – The reduction method used. The default value is
tensorflow.python.keras.utils.losses_utils.ReductionV2.AUTO
. See the Tensoflow documentation for more details.
- class motornet_tf.nets.losses.CompoundedLoss(losses: list | tuple, loss_weights: list | tuple, name: str = 'compounded_loss', reduction='auto')#
Bases:
LossFunctionWrapper
Wraps several losses into a single loss object, creating a composite loss that sums the loss value of each subloss. Each subloss’s contribution can be weighted by a constant scalar value.
- Parameters:
losses – List or tuple of loss objects.
loss_weights – List or tuple of float scalars indicating the weight of the corresponding loss in the losses argument provided above.
name – String, the name (label) to give to the compounded loss object. This is used to print, plot, and save losses during training.
reduction – The reduction method used. The default value is
tensorflow.python.keras.utils.losses_utils.ReductionV2.AUTO
. See the Tensorflow documentation for more details.
- class motornet_tf.nets.losses.L2ActivationL1MuscleVelIndLoss(max_iso_force: float, activation_weight: float, deriv_weight: float, name: str = 'l2_activation_muscle_vel', reduction='auto')#
Bases:
LossFunctionWrapper
Applies a L2 penalty to muscle activation and an L1 penalty to muscle velocity. Must be applied to the muscle state output state. The L2 penalty on muscle activation is normalized by the maximum isometric force of each muscle. If
a
is the normalized muscle activation anddx
the muscle velocity, then the penalty would evaluate at:loss = activation_weight * tf.reduce_mean(a ** 2) + deriv_weight * tf.reduce_mean(tf.abs(dx))
- Parameters:
max_iso_force – Float or list, the maximum isometric force of each muscle in the order they are declared in the
motornet.plants.plants.Plant
object class or subclass.activation_weight – Float, the weight of the activation’s penalty compared to the value itself.
deriv_weight – Float, the weight of the derivative’s penalty compared to the value itself.
name – String, the name (label) to give to the compounded loss object. This is used to print, plot, and save losses during training.
reduction – The reduction method used. The default value is
tensorflow.python.keras.utils.losses_utils.ReductionV2.AUTO
. See the Tensoflow documentation for more details.
- class motornet_tf.nets.losses.L2ActivationLoss(max_iso_force, name: str = 'l2_activation', reduction='auto')#
Bases:
LossFunctionWrapper
Applies a L2 penalty to muscle activation. Must be applied to the muscle state output state. The L2 penalty is normalized by the maximum isometric force of each muscle.
- Parameters:
max_iso_force – Float or list, the maximum isometric force of each muscle in the order they are declared in the
motornet.plants.plants.Plant
object class or subclass.name – String, the name (label) to give to the compounded loss object. This is used to print, plot, and save losses during training.
reduction – The reduction method used. The default value is
tensorflow.python.keras.utils.losses_utils.ReductionV2.AUTO
. See the Tensorflow documentation for more details.
- class motornet_tf.nets.losses.L2ActivationMuscleVelLoss(max_iso_force: float, deriv_weight: float, name: str = 'l2_activation_muscle_vel', reduction='auto')#
Bases:
LossFunctionWrapper
Applies a L2 penalty to muscle activation and muscle velocity. Must be applied to the muscle state output state. The L2 penalty on muscle activation is normalized by the maximum isometric force of each muscle. If
a
is the normalized muscle activation anddx
the muscle velocity, then the penalty would evaluate at:loss = tf.reduce_mean(a ** 2) + deriv_weight * tf.reduce_mean(dx ** 2)
- Parameters:
max_iso_force – Float or list, the maximum isometric force of each muscle in the order they are declared in the
motornet.plants.plants.Plant
object class or subclass.deriv_weight – Float, the weight of the derivative’s penalty compared to the value itself.
name – String, the name (label) to give to the compounded loss object. This is used to print, plot, and save losses during training.
reduction – The reduction method used. The default value is
tensorflow.python.keras.utils.losses_utils.ReductionV2.AUTO
. See the Tensoflow documentation for more details.
- class motornet_tf.nets.losses.L2Regularizer(name: str = 'l2_regularizer', reduction='auto')#
Bases:
LossFunctionWrapper
Applies a L2 penalty to the model’s output values. For instance, if we label an output value
x
, then the penalty would evaluate at:loss = np.reduce_mean(x ** 2)
- Parameters:
name – String, the name (label) to give to the compounded loss object. This is used to print, plot, and save losses during training.
reduction – The reduction method used. The default value is
tensorflow.python.keras.utils.losses_utils.ReductionV2.AUTO
. See the Tensoflow documentation for more details.
- class motornet_tf.nets.losses.L2xDxActivationLoss(max_iso_force: float, deriv_weight: float, dt: float, name: str = 'l2_xdx_activation', reduction='auto')#
Bases:
LossFunctionWrapper
Applies a L2 penalty to muscle activation and its derivative. Must be applied to the
muscle state
output state. The L2 penalty is normalized by the maximum isometric force of each muscle. If we label normalized muscle activationa
, and its derivativeda
, then the penalty would evaluate at:loss = np.reduce_mean(a ** 2) + deriv_weight * np.reduce_mean(da ** 2)
- Parameters:
max_iso_force – Float or list, the maximum isometric force of each muscle in the order they are declared in the
motornet.plants.plants.Plant
object class or subclass.deriv_weight – Float, the weight of the derivative’s penalty compared to the value itself.
dt – Float, the size of a single timestep. This is used to calculate derivatives using Euler’s method.
name – String, the name (label) to give to the compounded loss object. This is used to print, plot, and save losses during training.
reduction – The reduction method used. The default value is
tensorflow.python.keras.utils.losses_utils.ReductionV2.AUTO
. See the Tensoflow documentation for more details.
- class motornet_tf.nets.losses.L2xDxRegularizer(deriv_weight: float, dt: float, name: str = 'gru_regularizer', reduction='auto')#
Bases:
LossFunctionWrapper
Applies a L2 penalty to the model’s output values and value derivatives. For instance, if we label an output value
x
, and its derivativedx
, then the penalty would evaluate at:loss = np.reduce_mean(x ** 2) + deriv_weight * np.reduce_mean(dx ** 2)
- Parameters:
deriv_weight – Float, the weight of the derivative’s penalty compared to the value itself.
dt – Float, the size of a single timestep. This is used to calculate derivatives using Euler’s method.
name – String, the name (label) to give to the compounded loss object. This is used to print, plot, and save losses during training.
reduction – The reduction method used. The default value is
tensorflow.python.keras.utils.losses_utils.ReductionV2.AUTO
. See the Tensoflow documentation for more details.
- class motornet_tf.nets.losses.PositionLoss(name: str = 'position', reduction='auto')#
Bases:
LossFunctionWrapper
Applies a L1 penalty to positional error between the model’s output positional state
x
and a user-fed label positiony
:xp, _ = np.split(x, 2, axis=-1) # remove velocity from the positional state yp, _ = np.split(y, 2, axis=-1) loss = np.reduce_mean(np.abs(xp - yp))
Note
The positional error does not include velocity, hence the use of
np.split
to extract position from the state array.- Parameters:
name – String, the name (label) to give to the compounded loss object. This is used to print, plot, and save losses during training.
reduction – The reduction method used. The default value is
tensorflow.python.keras.utils.losses_utils.ReductionV2.AUTO
. See the Tensoflow documentation for more details.
- class motornet_tf.nets.losses.RecurrentActivityRegularizer(network, recurrent_weight: float, activity_weight: float, name: str = 'recurrent_activity', reduction='auto')#
Bases:
LossFunctionWrapper
Applies a L2 penalty to the model’s recurrent activity and hidden activity values. For instance, if we label the recurrent activity
f
, and the hidden activityh
, then the penalty would evaluate at:loss = recurrent_weight * f + activity_weight * np.reduce_mean(h ** 2)
The variable f was calculated according to the recurrent regularization method proposed in [1] but adapted for GRU units.
References
[1] Sussillo, D., Churchland, M., Kaufman, M. et al. A neural network that finds a naturalistic solution for the production of muscle activity. Nat Neurosci 18, 1025–1033 (2015). https://doi.org/10.1038/nn.4042
- Parameters:
network –
motornet.nets.layers.Network
object class or subclass. The Network object must be the one being trained. This is used to fetch the weight values of the layer indexed 1.recurrent_weight – Float, the weight of the penalization for the recurrent activity values.
activity_weight – Float, the weight of the penalization for the hidden activity values.
name – String, the name (label) to give to the compounded loss object. This is used to print, plot, and save losses during training.
reduction – The reduction method used. The default value is
tensorflow.python.keras.utils.losses_utils.ReductionV2.AUTO
. See the Tensorflow documentation for more details.