Missed TensorFlow Dev Summit? Check out the video playlist. Watch recordings

tf_agents.agents.SacAgent

View source on GitHub

A SAC Agent.

Inherits From: TFAgent

tf_agents.agents.SacAgent(
    *args, **kwargs
)

Used in the notebooks

Used in the tutorials

Args:

  • time_step_spec: A TimeStep spec of the expected time_steps.
  • action_spec: A nest of BoundedTensorSpec representing the actions.
  • critic_network: A function critic_network((observations, actions)) that returns the q_values for each observation and action.
  • actor_network: A function actor_network(observation, action_spec) that returns action distribution.
  • actor_optimizer: The optimizer to use for the actor network.
  • critic_optimizer: The default optimizer to use for the critic network.
  • alpha_optimizer: The default optimizer to use for the alpha variable.
  • actor_loss_weight: The weight on actor loss.
  • critic_loss_weight: The weight on critic loss.
  • alpha_loss_weight: The weight on alpha loss.
  • actor_policy_ctor: The policy class to use.
  • critic_network_2: (Optional.) A tf_agents.network.Network to be used as the second critic network during Q learning. The weights from critic_network are copied if this is not provided.
  • target_critic_network: (Optional.) A tf_agents.network.Network to be used as the target critic network during Q learning. Every target_update_period train steps, the weights from critic_network are copied (possibly withsmoothing via target_update_tau) to target_critic_network. If target_critic_network is not provided, it is created by making a copy of critic_network, which initializes a new network with the same structure and its own layers and weights. Performing a Network.copy does not work when the network instance already has trainable parameters (e.g., has already been built, or when the network is sharing layers with another). In these cases, it is up to you to build a copy having weights that are not shared with the original critic_network, so that this can be used as a target network. If you provide a target_critic_network that shares any weights with critic_network, a warning will be logged but no exception is thrown.
  • target_critic_network_2: (Optional.) Similar network as target_critic_network but for the critic_network_2. See documentation for target_critic_network. Will only be used if 'critic_network_2' is also specified.
  • target_update_tau: Factor for soft update of the target networks.
  • target_update_period: Period for soft update of the target networks.
  • td_errors_loss_fn: A function for computing the elementwise TD errors loss.
  • gamma: A discount factor for future rewards.
  • reward_scale_factor: Multiplicative scale for the reward.
  • initial_log_alpha: Initial value for log_alpha.
  • target_entropy: The target average policy entropy, for updating alpha. The default value is negative of the total number of actions.
  • gradient_clipping: Norm length to clip gradients.
  • debug_summaries: A bool to gather debug summaries.
  • summarize_grads_and_vars: If True, gradient and network variable summaries will be written during training.
  • train_step_counter: An optional counter to increment every time the train op is run. Defaults to the global_step.
  • name: The name of this agent. All variables in this module will fall under that name. Defaults to the class name.

Attributes:

  • action_spec: TensorSpec describing the action produced by the agent.

  • collect_data_spec: Returns a Trajectory spec, as expected by the collect_policy.

  • collect_policy: Return a policy that can be used to collect data from the environment.

  • debug_summaries

  • name: Returns the name of this module as passed or determined in the ctor.

    NOTE: This is not the same as the self.name_scope.name which includes parent module names.

  • name_scope: Returns a tf.name_scope instance for this class.

  • policy: Return the current policy held by the agent.

  • submodules: Sequence of all sub-modules.

    Submodules are modules which are properties of this module, or found as properties of modules which are properties of this module (and so on).

a = tf.Module()
b = tf.Module()
c = tf.Module()
a.b = b
b.c = c
assert list(a.submodules) == [b, c]
assert list(b.submodules) == [c]
assert list(c.submodules) == []
  • summaries_enabled
  • summarize_grads_and_vars
  • time_step_spec: Describes the TimeStep tensors expected by the agent.

  • train_argspec: TensorSpec describing extra supported kwargs to train().

  • train_sequence_length: The number of time steps needed in experience tensors passed to train.

    Train requires experience to be a Trajectory containing tensors shaped [B, T, ...]. This argument describes the value of T required.

    For example, for non-RNN DQN training, T=2 because DQN requires single transitions.

    If this value is None, then train can handle an unknown T (it can be determined at runtime from the data). Most RNN-based agents fall into this category.

  • train_step_counter

  • trainable_variables: Sequence of trainable variables owned by this module and its submodules.

  • variables: Sequence of variables owned by this module and its submodules.

Methods

actor_loss

View source

actor_loss(
    time_steps, weights=None
)

Computes the actor_loss for SAC training.

Args:

  • time_steps: A batch of timesteps.
  • weights: Optional scalar or elementwise (per-batch-entry) importance weights.

Returns:

  • actor_loss: A scalar actor loss.

alpha_loss

View source

alpha_loss(
    time_steps, weights=None
)

Computes the alpha_loss for EC-SAC training.

Args:

  • time_steps: A batch of timesteps.
  • weights: Optional scalar or elementwise (per-batch-entry) importance weights.

Returns:

  • alpha_loss: A scalar alpha loss.

critic_loss

View source

critic_loss(
    time_steps, actions, next_time_steps, td_errors_loss_fn, gamma=1.0,
    reward_scale_factor=1.0, weights=None, training=False
)

Computes the critic loss for SAC training.

Args:

  • time_steps: A batch of timesteps.
  • actions: A batch of actions.
  • next_time_steps: A batch of next timesteps.
  • td_errors_loss_fn: A function(td_targets, predictions) to compute elementwise (per-batch-entry) loss.
  • gamma: Discount for future rewards.
  • reward_scale_factor: Multiplicative factor to scale rewards.
  • weights: Optional scalar or elementwise (per-batch-entry) importance weights.
  • training: Whether this loss is being used for training.

Returns:

  • critic_loss: A scalar critic loss.

initialize

View source

initialize()

Initializes the agent.

Returns:

An operation that can be used to initialize the agent.

Raises:

  • RuntimeError: If the class was not initialized properly (super.__init__ was not called).

train

View source

train(
    experience, weights=None, **kwargs
)

Trains the agent.

Args:

  • experience: A batch of experience data in the form of a Trajectory. The structure of experience must match that of self.collect_data_spec. All tensors in experience must be shaped [batch, time, ...] where time must be equal to self.train_step_length if that property is not None.
  • weights: (optional). A Tensor, either 0-D or shaped [batch], containing weights to be used when calculating the total train loss. Weights are typically multiplied elementwise against the per-batch loss, but the implementation is up to the Agent.
  • **kwargs: Any additional data as declared by self.train_argspec.

Returns:

A LossInfo loss tuple containing loss and info tensors.

  • In eager mode, the loss values are first calculated, then a train step is performed before they are returned.
  • In graph mode, executing any or all of the loss tensors will first calculate the loss value(s), then perform a train step, and return the pre-train-step LossInfo.

Raises:

  • TypeError: If experience is not type Trajectory. Or if experience does not match self.collect_data_spec structure types.
  • ValueError: If experience tensors' time axes are not compatible with self.train_sequence_length. Or if experience does not match self.collect_data_spec structure.
  • ValueError: If the user does not pass **kwargs matching self.train_argspec.
  • RuntimeError: If the class was not initialized properly (super.__init__ was not called).

with_name_scope

@classmethod
with_name_scope(
    cls, method
)

Decorator to automatically enter the module name scope.

class MyModule(tf.Module):
  @tf.Module.with_name_scope
  def __call__(self, x):
    if not hasattr(self, 'w'):
      self.w = tf.Variable(tf.random.normal([x.shape[1], 64]))
    return tf.matmul(x, self.w)

Using the above module would produce tf.Variables and tf.Tensors whose names included the module name:

mod = MyModule()
mod(tf.ones([8, 32]))
# ==> <tf.Tensor: ...>
mod.w
# ==> <tf.Variable ...'my_module/w:0'>

Args:

  • method: The method to wrap.

Returns:

The original method wrapped such that it enters the module's name scope.