Main Content

rlSACAgent

Soft actor-critic (SAC) reinforcement learning agent

Since R2020b

expand all in page

Description

The soft actor-critic (SAC) algorithm is a model-free, online, off-policy, actor-critic reinforcement learning method. The SAC algorithm computes an optimal policy that maximizes both the long-term expected reward and the entropy of the policy. The policy entropy is a measure of policy uncertainty given the state. A higher entropy value promotes more exploration. Maximizing both the reward and the entropy balances exploration and exploitation of the environment. The action space can only be continuous.

For more information, see Soft Actor-Critic (SAC) Agents.

For more information on the different types of reinforcement learning agents, see Reinforcement Learning Agents.

Creation

Syntax

agent = rlSACAgent(observationInfo,actionInfo)
agent = rlSACAgent(observationInfo,actionInfo,initOptions)
agent = rlSACAgent(actor,critics)
agent = rlSACAgent(___,agentOptions)

Description

Create Agent from Observation and Action Specifications

example

agent = rlSACAgent(observationInfo,actionInfo) creates a SAC agent for an environment with the given observation and action specifications, using default initialization options. The actor and critics in the agent use default deep neural networks built using the observation specification observationInfo and action specification actionInfo. The ObservationInfo and ActionInfo properties of agent are set to the observationInfo and actionInfo input arguments, respectively.

example

agent = rlSACAgent(observationInfo,actionInfo,initOptions) creates a SAC agent with deep neural networks configured using the specified initialization options (initOptions).

Create Agent from Actor and Critic

example

agent = rlSACAgent(actor,critics) creates a SAC agent with the specified actor and critic networks and default agent options.

Specify Agent Options

agent = rlSACAgent(___,agentOptions) sets the AgentOptions property for any of the previous syntaxes.

Input Arguments

expand all

Agent initialization options, specified as an rlAgentInitializationOptions object.

Actor that implements the policy, specified as an rlContinuousGaussianActor function approximator object. For more information on creating actor approximators, see Create Policies and Value Functions.

Note

A SAC agent automatically reads the action range from the UpperLimit and LowerLimit properties of the action specification (which is used to create the actor), and then internally scales the distribution and bounds the action. Therefore, do not add a tanhLayer as the last nonlinear layer in the mean output path. If you bound the mean value output directly (for example by adding a tanhLayer right before the output), the agent does not calculate the entropy of the probability density distribution correctly. Note that you must still add a softplus or ReLU layer to the standard deviations path to enforce nonnegativity. For more information, see Soft Actor-Critic (SAC) Agents.

Critic, specified as one of the following:

  • rlQValueFunction object — Create a SAC agent with a single Q-value function.

  • Two-element row vector of rlQValueFunction objects — Create a SAC agent with two critic value functions. The two critic must be unique rlQValueFunction objects with the same observation and action specifications. The critics can either have different structures or the same structure but with different initial parameters.

For a SAC agent, each critic must be a single-output rlQValueFunction object that takes both the action and observations as inputs.

For more information on creating critics, see Create Policies and Value Functions.

Properties

expand all

Observation specifications, specified as an rlFiniteSetSpec or rlNumericSpec object or an array containing a mix of such objects. Each element in the array defines the properties of an environment observation channel, such as its dimensions, data type, and name.

If you create the agent by specifying an actor and critic, the value of ObservationInfo matches the value specified in the actor and critic objects.

You can extract observationInfo from an existing environment or agent using getObservationInfo. You can also construct the specifications manually using rlFiniteSetSpec or rlNumericSpec.

Action specifications, specified as an rlNumericSpec object. This object defines the properties of the environment action channel, such as its dimensions, data type, and name.

Note

Only one action channel is allowed.

If you create the agent by specifying an actor and critic, the value of ActionInfo matches the value specified in the actor and critic objects.

You can extract actionInfo from an existing environment or agent using getActionInfo. You can also construct the specification manually using rlFiniteSetSpec or rlNumericSpec.

Agent options, specified as an rlSACAgentOptions object.

If you create a SAC agent with default actor and critic that use recurrent neural networks, the default value of AgentOptions.SequenceLength is 32.

Experience buffer, specified as an rlReplayMemory object. During training the agent stores each of its experiences (S,A,R,S',D) in a buffer. Here:

  • S is the current observation of the environment.

  • A is the action taken by the agent.

  • R is the reward for taking action A.

  • S' is the next observation after taking action A.

  • D is the is-done signal after taking action A.

Option to use exploration policy when selecting actions, specified as a one of the following logical values.

  • true — Use the base agent exploration policy when selecting actions in sim and generatePolicyFunction. In this case, the agent selects its actions by sampling its probability distribution, the policy is therefore stochastic and the agent explores its observation space.

  • false — Use the base agent greedy policy (the action with maximum likelihood) when selecting actions in sim and generatePolicyFunction. In this case, the simulated agent and generated policy behave deterministically.

Note

This option affects only simulation and deployment; it does not affect training.

Sample time of agent, specified as a positive scalar or as -1. Setting this parameter to -1 allows for event-based simulations. The value of SampleTime matches the value specified in AgentOptions.

Within a Simulink® environment, the RL Agent block in which the agent is specified to execute every SampleTime seconds of simulation time. If SampleTime is -1, the block inherits the sample time from its parent subsystem.

Within a MATLAB® environment, the agent is executed every time the environment advances. In this case, SampleTime is the time interval between consecutive elements in the output experience returned by sim or train. If SampleTime is -1, the time interval between consecutive elements in the returned output experience reflects the timing of the event that triggers the agent execution.

Object Functions

trainTrain reinforcement learning agents within a specified environment
simSimulate trained reinforcement learning agents within specified environment
getActionObtain action from agent, actor, or policy object given environment observations
getActorExtract actor from reinforcement learning agent
setActorSet actor of reinforcement learning agent
getCriticExtract critic from reinforcement learning agent
setCriticSet critic of reinforcement learning agent
generatePolicyFunctionGenerate MATLAB function that evaluates policy of an agent or policy object

Examples

collapse all

Open Live Script

Create environment and obtain observation and action specifications. For this example, load the environment used in the example Train DDPG Agent to Control Double Integrator System. The observation from the environment is a vector containing the position and velocity of a mass. The action is a scalar representing a force, applied to the mass, ranging continuously from -2 to 2 Newton.

env = rlPredefinedEnv("DoubleIntegrator-Continuous");
obsInfo = getObservationInfo(env);
actInfo = getActionInfo(env);

The agent creation function initializes the actor and critic networks randomly. Ensure reproducibility by fixing the seed of the random generator.

rng(0)

Create a SAC agent from the environment observation and action specifications.

agent = rlSACAgent(obsInfo,actInfo);

To check your agent, use getAction to return the action from a random observation.

getAction(agent,{rand(obsInfo(1).Dimension)})
ans = 1x1 cell array
    {[0.0546]}

You can now test and train the agent within the environment. You can also use getActor and getCritic to extract the actor and critic, respectively, and getModel to extract the approximator model (by default a deep neural network) from the actor or critic.

Open Live Script

Create an environment with a continuous action space and obtain its observation and action specifications. For this example, load the environment used in the example Train DDPG Agent to Control Double Integrator System. The observation from the environment is a vector containing the position and velocity of a mass. The action is a scalar representing a force, applied to the mass, ranging continuously from -2 to 2 Newton.

env = rlPredefinedEnv("DoubleIntegrator-Continuous");
obsInfo = getObservationInfo(env);
actInfo = getActionInfo(env);

Create an agent initialization option object, specifying that each hidden fully connected layer in the network must have 128 neurons.

initOpts = rlAgentInitializationOptions(NumHiddenUnit=128);

The agent creation function initializes the actor and critic networks randomly. Ensure reproducibility by fixing the seed of the random generator.

rng(0)

Create a SAC agent from the environment observation and action specifications using the initialization options.

agent = rlSACAgent(obsInfo,actInfo,initOpts);

Extract the deep neural network from the actor.

actorNet = getModel(getActor(agent));

Extract the deep neural networks from the two critics. Note that getModel(critics) only returns the first critic network.

critics = getCritic(agent);
criticNet1 = getModel(critics(1));
criticNet2 = getModel(critics(2));

Display the layers of the first critic network, and verify that each hidden fully connected layer has 128 neurons.

criticNet1.Layers
ans = 
  9x1 Layer array with layers:

     1   'concat'        Concatenation     Concatenation of 2 inputs along dimension 1
     2   'relu_body'     ReLU              ReLU
     3   'fc_body'       Fully Connected   128 fully connected layer
     4   'body_output'   ReLU              ReLU
     5   'input_1'       Feature Input     2 features
     6   'fc_1'          Fully Connected   128 fully connected layer
     7   'input_2'       Feature Input     1 features
     8   'fc_2'          Fully Connected   128 fully connected layer
     9   'output'        Fully Connected   1 fully connected layer

Plot the networks of the actor and of the second critic, and display the number of weights.

plot(layerGraph(actorNet))

Figure contains an axes object. The axes object contains an object of type graphplot.

summary(actorNet)
   Initialized: true

   Number of learnables: 17.1k

   Inputs:
      1   'input_1'   2 features

plot(layerGraph(criticNet2))

Figure contains an axes object. The axes object contains an object of type graphplot.

summary(criticNet2)
   Initialized: true

   Number of learnables: 33.6k

   Inputs:
      1   'input_1'   2 features
      2   'input_2'   1 features

To check your agent, use getAction to return the action from a random observation.

getAction(agent,{rand(obsInfo(1).Dimension)})
ans = 1x1 cell array
    {[-0.9867]}

You can now test and train the agent within the environment.

Open Live Script

Create an environment and obtain observation and action specifications. For this example, load the environment used in the example Train DDPG Agent to Control Double Integrator System. The observations from the environment is a vector containing the position and velocity of a mass. The action is a scalar representing a force, applied to the mass, ranging continuously from -2 to 2 Newton.

env = rlPredefinedEnv("DoubleIntegrator-Continuous");
obsInfo = getObservationInfo(env);
actInfo = getActionInfo(env);

Define bounds on the action. The SAC agent automatically uses these values to internally scale the distribution and bound the action properly.

actInfo.LowerLimit=-2;
actInfo.UpperLimit=2;

SAC agents use two Q-value function critics. A Q-value function critic takes the current observation and an action as inputs and returns a single scalar as output (the estimated discounted cumulative long-term reward for taking the action from the state corresponding to the current observation, and following the policy thereafter).

To model the parametrized Q-value function within the critics, use a neural network with two input layers (one for the observation channel, as specified by obsInfo, and the other for the action channel, as specified by actInfo) and one output layer (which returns the scalar value). Note that prod(obsInfo.Dimension) and prod(actInfo.Dimension) return the number of dimensions of the observation and action spaces, respectively, regardless of whether they are arranged as row vectors, column vectors, or matrices.

Define each network path as an array of layer objects. Assign names to the input and output layers of each path. These names allow you to connect the paths and then later explicitly associate the network input layers with the appropriate environment channel.

% Observation path
obsPath = [
    featureInputLayer(prod(obsInfo.Dimension),Name="obsPathIn")
    fullyConnectedLayer(32)
    reluLayer
    fullyConnectedLayer(16,Name="obsPathOut")
    ];

% Action path
actPath = [
    featureInputLayer(prod(actInfo.Dimension),Name="actPathIn")
    fullyConnectedLayer(32)
    reluLayer
    fullyConnectedLayer(16,Name="actPathOut")
    ];

% Common path
commonPath = [
    concatenationLayer(1,2,Name="concat")
    reluLayer
    fullyConnectedLayer(1)
    ];

% Add layers to layergraph object
criticNet = layerGraph;
criticNet = addLayers(criticNet,obsPath);
criticNet = addLayers(criticNet,actPath);
criticNet = addLayers(criticNet,commonPath);

% Connect layers
criticNet = connectLayers(criticNet,"obsPathOut","concat/in1");
criticNet = connectLayers(criticNet,"actPathOut","concat/in2");

To initialize the network weights differently for the two critics, create two different dlnetwork objects. You must do this because the agent constructor function does not accept two identical critics.

criticNet1 = dlnetwork(criticNet);
criticNet2 = dlnetwork(criticNet);

Display the number of weights.

summary(criticNet1)
   Initialized: true

   Number of learnables: 1.2k

   Inputs:
      1   'obsPathIn'   2 features
      2   'actPathIn'   1 features

Create the two critics using the two networks with different weights and the names of the input layers. Alternatively, if you use exactly the same network with the same weights, you must explicitly initialize the network each time (to make sure weights are initialized differently) before passing it to rlQValueFunction. To do so, use initialize.

critic1 = rlQValueFunction(criticNet1,obsInfo,actInfo, ...
    ActionInputNames="actPathIn",ObservationInputNames="obsPathIn");

critic2 = rlQValueFunction(criticNet2,obsInfo,actInfo, ...
    ActionInputNames="actPathIn",ObservationInputNames="obsPathIn");

For more information about value function approximators, see rlQValueFunction.

Check the critics with a random observation and action input.

getValue(critic1,{rand(obsInfo.Dimension)},{rand(actInfo.Dimension)})
ans = single
    -0.1330

getValue(critic2,{rand(obsInfo.Dimension)},{rand(actInfo.Dimension)})
ans = single
    -0.1526

SAC agents use a parametrized stochastic policy, which for continuous action spaces is implemented by a continuous Gaussian actor. This actor takes an observation as input and returns as output a random action sampled from a Gaussian probability distribution.

To approximate the mean values and standard deviations of the Gaussian distribution, you must use a neural network with two output layers, each having as many elements as the dimension of the action space. One output layer must return a vector containing the mean values for each action dimension. The other must return a vector containing the standard deviation for each action dimension.

The SAC agent automatically reads the action range from the UpperLimit and LowerLimit properties of actInfo (which is used to create the actor), and then internally scales the distribution and bounds the action.

Therefore, do not add a tanhLayer as the last nonlinear layer in the mean output path. If you bound the mean value output directly (for example by adding a tanhLayer right before the output), the agent does not calculate the entropy of the probability density distribution correctly. Note that you must still add a softplus or ReLU layer to the standard deviations path to enforce nonnegativity. For more information, see Soft Actor-Critic (SAC) Agents.

Define each network path as an array of layer objects, and assign names to the input and output layers of each path.

% Define common input path
commonPath = [
    featureInputLayer(prod(obsInfo.Dimension),Name="netObsIn")
    fullyConnectedLayer(32)
    reluLayer(Name="CommonRelu")
    ];

% Define path for mean value
meanPath = [
    fullyConnectedLayer(32,Name="meanIn")
    reluLayer
    fullyConnectedLayer(16)
    reluLayer
    fullyConnectedLayer(prod(actInfo.Dimension),Name="MeanOut")
    ];

% Define path for standard deviation
stdPath = [
    fullyConnectedLayer(32,Name="stdIn")
    reluLayer
    fullyConnectedLayer(16)
    reluLayer
    fullyConnectedLayer(prod(actInfo.Dimension))
    softplusLayer(Name="StandardDeviationOut")
    ];

% Add layers to layerGraph object 
actorNet = layerGraph(commonPath);
actorNet = addLayers(actorNet,meanPath);
actorNet = addLayers(actorNet,stdPath);

% Connect layers
actorNet = connectLayers(actorNet,"CommonRelu","meanIn/in");
actorNet = connectLayers(actorNet,"CommonRelu","stdIn/in");

% Convert to dlnetwork and display the number of weights.
actorNet = dlnetwork(actorNet);
summary(actorNet)
   Initialized: true

   Number of learnables: 3.2k

   Inputs:
      1   'netObsIn'   2 features

Create the actor using actorNet, the observation and action specification objects, and the names of the input and output layers.

actor = rlContinuousGaussianActor(actorNet, obsInfo, actInfo, ...
    ActionMeanOutputNames="MeanOut",...
    ActionStandardDeviationOutputNames="StandardDeviationOut",...
    ObservationInputNames="netObsIn");

For more information about continuous Gaussian actors approximators, see rlContinuousGaussianActor.

Check your actor with a random input observation.

getAction(actor,{rand(obsInfo.Dimension)})
ans = 1x1 cell array
    {[-0.8205]}

Specify training options for the critics.

criticOptions = rlOptimizerOptions( ...
    Optimizer="adam", ...
    LearnRate=1e-3,... 
    GradientThreshold=1, ...
    L2RegularizationFactor=2e-4);

Specify training options for the actor.

actorOptions = rlOptimizerOptions( ...
    Optimizer="adam", ...
    LearnRate=1e-3,...
    GradientThreshold=1, ...
    L2RegularizationFactor=1e-5);

Specify agent options, including training options for actor and critics.

agentOptions = rlSACAgentOptions;
agentOptions.SampleTime = env.Ts;
agentOptions.DiscountFactor = 0.99;
agentOptions.TargetSmoothFactor = 1e-3;
agentOptions.ExperienceBufferLength = 1e6;
agentOptions.MiniBatchSize = 32;

agentOptions.CriticOptimizerOptions = criticOptions;
agentOptions.ActorOptimizerOptions = actorOptions;

Create the SAC agent using actor, critics, and options.

agent = rlSACAgent(actor,[critic1 critic2],agentOptions)
agent = 
  rlSACAgent with properties:

        ExperienceBuffer: [1x1 rl.replay.rlReplayMemory]
            AgentOptions: [1x1 rl.option.rlSACAgentOptions]
    UseExplorationPolicy: 1
         ObservationInfo: [1x1 rl.util.rlNumericSpec]
              ActionInfo: [1x1 rl.util.rlNumericSpec]
              SampleTime: 0.1000

To check your agent, use getAction to return the action from a random observation.

getAction(agent,{rand(obsInfo(1).Dimension)})
ans = 1x1 cell array
    {[0.4490]}

You can now test and train the agent within the environment.

Open Live Script

For this example, load the environment used in the example Train DDPG Agent to Control Double Integrator System. The observations from the environment is a vector containing the position and velocity of a mass. The action is a scalar representing a force, applied to the mass, ranging continuously from -2 to 2 Newton.

env = rlPredefinedEnv("DoubleIntegrator-Continuous");
obsInfo = getObservationInfo(env);
actInfo = getActionInfo(env);

SAC agents use two Q-value function critics. To model the parametrized Q-value function within the critics, use a recurrent neural network, which must have two input layers one output layer.

Define each network path as an array of layer objects, and assign names to the input and output layers of each path. To create a recurrent neural network, use sequenceInputLayer as the input layer and include an lstmLayer as one of the other network layers.

% Define observation path
obsPath = [
    sequenceInputLayer(prod(obsInfo.Dimension),Name="obsIn")
    fullyConnectedLayer(40)
    reluLayer
    fullyConnectedLayer(30,Name = "obsOut")
    ];

% Define action path
actPath = [
    sequenceInputLayer(prod(actInfo.Dimension),Name="actIn")
    fullyConnectedLayer(30,Name="actOut")
    ];

% Define common path
commonPath = [
    concatenationLayer(1,2,Name="cat")
    lstmLayer(16)
    reluLayer
    fullyConnectedLayer(1)
    ];

% Add layers to layergraph object
criticNet = layerGraph(obsPath);
criticNet = addLayers(criticNet,actPath);
criticNet = addLayers(criticNet,commonPath);

% Connect paths
criticNet = connectLayers(criticNet,"obsOut","cat/in1");
criticNet = connectLayers(criticNet,"actOut","cat/in2");

To initialize the network weights differently for the two critics, create two different dlnetwork objects. You must do this because if the agent constructor function does not accept two identical critics.

criticNet1 = dlnetwork(criticNet);
criticNet2 = dlnetwork(criticNet);

Display the number of weights.

summary(criticNet1)
   Initialized: true

   Number of learnables: 6.3k

   Inputs:
      1   'obsIn'   Sequence input with 2 dimensions
      2   'actIn'   Sequence input with 1 dimensions

Create the two critics using the two networks with different weights. Use the same network structure for both critics. The SAC agent initializes the two networks using different default parameters.

critic1 = rlQValueFunction(criticNet1,obsInfo,actInfo);
critic2 = rlQValueFunction(criticNet2,obsInfo,actInfo);

Check the critics with a random observation and action input.

getValue(critic1,{rand(obsInfo.Dimension)},{rand(actInfo.Dimension)})
ans = single
    -0.0508

getValue(critic2,{rand(obsInfo.Dimension)},{rand(actInfo.Dimension)})
ans = single
    0.0762

Since the critic has a recurrent network, the actor must have a recurrent network too.

Do not add a tanhLayer or scalingLayer in the mean output path. The SAC agent internally transforms the unbounded Gaussian distribution to the bounded distribution to compute the probability density function and entropy properly. However, add a softplus or ReLU layer to the standard deviations path to enforce nonnegativity,

Define each network path as an array of layer objects and specify a name for the input and output layers, so you can later explicitly associate them with the appropriate channel.

% Define common path
commonPath = [
    sequenceInputLayer(prod(obsInfo.Dimension),Name="obsIn")
    fullyConnectedLayer(400)
    lstmLayer(8)
    reluLayer(Name="CommonOut")];

meanPath = [
    fullyConnectedLayer(300,Name="MeanIn")
    reluLayer
    fullyConnectedLayer(prod(actInfo.Dimension),Name="Mean")
    ];

stdPath = [
    fullyConnectedLayer(300,Name="StdIn")
    reluLayer
    fullyConnectedLayer(prod(actInfo.Dimension))
    softplusLayer(Name="StandardDeviation")
    ];

actorNet = layerGraph(commonPath);
actorNet = addLayers(actorNet,meanPath);
actorNet = addLayers(actorNet,stdPath);

actorNet = connectLayers(actorNet,"CommonOut","MeanIn/in");
actorNet = connectLayers(actorNet,"CommonOut","StdIn/in");

% Convert to dlnetwork and display the number of weights.
actorNet = dlnetwork(actorNet);
summary(actorNet)
   Initialized: true

   Number of learnables: 20.2k

   Inputs:
      1   'obsIn'   Sequence input with 2 dimensions

Create the actor using actorNet, the observation and action specification objects, and the names of the input and output layers.

actor = rlContinuousGaussianActor(actorNet, obsInfo, actInfo, ...
    ActionMeanOutputNames="Mean",...
    ActionStandardDeviationOutputNames="StandardDeviation",...
    ObservationInputNames="obsIn");

Check your actor with a random input observation.

getAction(actor,{rand(obsInfo.Dimension)})
ans = 1x1 cell array
    {[-0.6304]}

Specify training options for the critics.

criticOptions = rlOptimizerOptions( ...
    Optimizer = "adam", LearnRate = 1e-3,... 
    GradientThreshold = 1, L2RegularizationFactor = 2e-4);

Specify training options for the actor.

actorOptions = rlOptimizerOptions( ...
    Optimizer = "adam", LearnRate = 1e-3,...
    GradientThreshold = 1, L2RegularizationFactor = 1e-5);

Specify agent options. To use a recurrent neural network, you must specify a SequenceLength greater than 1.

agentOptions = rlSACAgentOptions;
agentOptions.SampleTime = env.Ts;
agentOptions.DiscountFactor = 0.99;
agentOptions.TargetSmoothFactor = 1e-3;
agentOptions.ExperienceBufferLength = 1e6;
agentOptions.SequenceLength = 32;
agentOptions.MiniBatchSize = 32;

Create SAC agent using actor, critics, and options.

agent = rlSACAgent(actor,[critic1 critic2],agentOptions);

To check your agent, use getAction to return the action from a random observation.

getAction(agent,{rand(obsInfo.Dimension)})
ans = 1x1 cell array
    {[-0.8774]}

To evaluate the agent using sequential observations, use the sequence length (time) dimension. For example, obtain actions for a sequence of 9 observations.

[action,state] = getAction(agent, ...
    {rand([obsInfo.Dimension 1 9])});

Display the action corresponding to the seventh element of the observation.

action = action{1};
action(1,1,1,7)
ans = 0.5114

You can now test and train the agent within the environment.

Version History

Introduced in R2020b

See Also

Apps

Functions

Objects

Blocks

Topics