rlContinuousGaussianActor

Stochastic Gaussian actor with a continuous action space for reinforcement learning agents

Since R2022a

Description

This object implements a function approximator to be used as a stochastic actor within a reinforcement learning agent with a continuous action space. A continuous Gaussian actor takes an environment observation as input and returns as output a random action sampled from a parametrized Gaussian probability distribution, thereby implementing a parametrized stochastic policy. After you create an rlContinuousGaussianActor object, use it to create a suitable agent, such as an rlACAgent or rlPGAgent agent. For more information on creating actors and critics, see Create Policies and Value Functions.

Creation

Syntax

actor = rlContinuousGaussianActor(net,observationInfo,actionInfo,ActionMeanOutputNames=meanOutLyrName,ActionStandardDeviationOutputNames=stdOutLyrName)

actor = rlContinuousGaussianActor(___,Name=Value)

Description

actor = rlContinuousGaussianActor(net,observationInfo,actionInfo,ActionMeanOutputNames=meanOutLyrName,ActionStandardDeviationOutputNames=stdOutLyrName) creates a Gaussian stochastic actor with a continuous action space using the deep neural network net as approximation model. Here, net must have two differently named output layers, each with as many elements as the number of dimensions of the action space, as specified in actionInfo. The two output layers must return the mean and standard deviation of each component of the action, respectively. The actor uses the output of these two layers, according to the names specified in the strings meanOutLyrName and stdOutLyrName, to represent the Gaussian probability distribution from which the action is sampled. This syntax sets the ObservationInfo and ActionInfo properties of actor to the input arguments observationInfo and actionInfo, respectively.

Note

actor does not enforce constraints set by the action specification. When using this actor in a different agent than SAC, you must enforce action space constraints within the environment.

actor = rlContinuousGaussianActor(___,Name=Value) specifies the names of the observation input layers or sets the UseDevice property using one or more name-value arguments. Use this syntax with any of the input argument combinations in the preceding syntax. Specify the input layer names to explicitly associate the layers of your network with specific environment channels. To specify the device where computations for actor are executed, set the UseDevice property, for example UseDevice="gpu".

Input Arguments

net — Deep neural network

array of Layer objects | layerGraph object | DAGNetwork object | SeriesNetwork object | dlNetwork object (preferred)

Deep neural network used as the underlying approximation model within the actor. It must have as many input layers as the number of environment observation channels (with each input layer receiving input from an observation channel). The network must have two differently named output layers each with as many elements as the number of dimensions of the action space, as specified in actionInfo. The two output layers return the mean and standard deviation of each component of the action. The actor uses the output of these two layers, according to the names specified in the strings meanOutLyrName and stdOutLyrName, to represent the Gaussian probability distribution from which the action is sampled.

Note

Since standard deviations must be nonnegative, the output layer that returns the standard deviations must be a softplus or ReLU layer, to enforce nonnegativity. Also, unless the actor is used in a SAC agent, the mean values must fall within the range of the action. Therefore, when you use the actor in a different agent than SAC, to scale the mean values to the output range, use a scaling layer as the output layer for the mean values, preceded by an hyperbolic tangent layer. SAC agents automatically read the action range from the UpperLimit and LowerLimit properties of the action specification and then internally scale the distribution and bounds the action. Therefore, if the actor must be used in a SAC agent, do not add any layer that scales or bounds the mean values output. For more information, see Soft Actor-Critic (SAC) Agent.

You can specify the network as one of the following:

• Array of Layer objects

• layerGraph object

• DAGNetwork object

• SeriesNetwork object

• dlnetwork object

Note

Among the different network representation options, dlnetwork is preferred, since it has built-in validation checks and supports automatic differentiation. If you pass another network object as an input argument, it is internally converted to a dlnetwork object. However, best practice is to convert other representations to dlnetwork explicitly before using them to create a critic or an actor for a reinforcement learning agent. You can do so using dlnet=dlnetwork(net), where net is any neural network object from the Deep Learning Toolbox™. The resulting dlnet is the dlnetwork object that you use for your critic or actor. This practice allows a greater level of insight and control for cases in which the conversion is not straightforward and might require additional specifications.

rlContinuousGaussianActor objects support recurrent deep neural networks.

The learnable parameters of the actor are the weights of the deep neural network. For a list of deep neural network layers, see List of Deep Learning Layers. For more information on creating deep neural networks for reinforcement learning, see Create Policies and Value Functions.

meanOutLyrName — Name of network output layer returning mean values of action

string | character vector

Name of the network output layer returning the mean values of the action, specified as a string or character vector. The actor uses this name to select the network output layer that returns the mean values of each element of the action channel. Therefore, within net, this layer must be named as indicated in meanOutLyrName.

Example: "meanActOutLyr"

stdOutLyrName — Name of network output layer returning standard deviations of action

string | character vector

Name of the network output layer returning the standard deviations of the action, specified as a string or character vector. The actor uses this name to select the network output layer that returns the standard deviations of each element of the action channel. Therefore, within net, this layer must be named as indicated in stdOutLyrName. Furthermore, to enforce nonnegativity of the returned standard deviations, this layer must be a softplus or ReLU layer.

Example: "stdActOutLyr"

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: UseDevice="gpu"

ObservationInputNames — Network input layers names corresponding to the environment observation channels

string array | cell array of strings | cell array of character vectors

Network input layers names corresponding to the environment observation channels, specified as a string array or a cell array of strings or character vectors. The function assigns, in sequential order, each environment observation channel specified in observationInfo to each layer whose name is specified in the array assigned to this argument. Therefore, the specified net input layers, ordered as indicated in this argument, must have the same data type and dimensions as the observation channels, as ordered in observationInfo.

Example: ObservationInputNames={"obsInLyr1_airspeed","obsInLyr2_altitude"}

Properties

ObservationInfo — Observation specifications

rlFiniteSetSpec object | rlNumericSpec object | array

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.

When you create the approximator object, the constructor function sets the ObservationInfo property to the input argument observationInfo.

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

Example: [rlNumericSpec([2 1]) rlFiniteSetSpec([3,5,7])]

ActionInfo — Action specifications

rlNumericSpec object

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

For this approximator object, only one action channel is allowed.

When you create the approximator object, the constructor function sets the ActionInfo property to the input argument actionInfo.

You can extract ActionInfo from an existing environment, approximator object, or agent using getActionInfo. You can also construct the specification manually using rlNumericSpec.

Example: rlNumericSpec([2 1])

Normalization — Normalization method

"none" (default) | string array

Normalization method, returned as an array in which each element (one for each input channel defined in the observationInfo and actionInfo properties, in that order) is one of the following values:

• "none" — Do not normalize the input.

• "rescale-zero-one" — Normalize the input by rescaling it to the interval between 0 and 1. The normalized input Y is (U–Min)./(UpperLimit–LowerLimit), where U is the nonnormalized input. Note that nonnormalized input values lower than LowerLimit result in normalized values lower than 0. Similarly, nonnormalized input values higher than UpperLimit result in normalized values higher than 1. Here, UpperLimit and LowerLimit are the corresponding properties defined in the specification object of the input channel.

• "rescale-symmetric" — Normalize the input by rescaling it to the interval between –1 and 1. The normalized input Y is 2(U–LowerLimit)./(UpperLimit–LowerLimit) – 1, where U is the nonnormalized input. Note that nonnormalized input values lower than LowerLimit result in normalized values lower than –1. Similarly, nonnormalized input values higher than UpperLimit result in normalized values higher than 1. Here, UpperLimit and LowerLimit are the corresponding properties defined in the specification object of the input channel.

Note

When you specify the Normalization property of rlAgentInitializationOptions, normalization is applied only to the approximator input channels corresponding to rlNumericSpec specification objects in which both the UpperLimit and LowerLimit properties are defined. After you create the agent, you can use setNormalizer to assign normalizers that use any normalization method. For more information on normalizer objects, see rlNormalizer.

Example: "rescale-symmetric"

UseDevice — Computation device used for training and simulation

"cpu" (default) | "gpu"

Computation device used to perform operations such as gradient computation, parameter update and prediction during training and simulation, specified as either "cpu" or "gpu".

The "gpu" option requires both Parallel Computing Toolbox™ software and a CUDA^® enabled NVIDIA^® GPU. For more information on supported GPUs see GPU Computing Requirements (Parallel Computing Toolbox).

You can use gpuDevice (Parallel Computing Toolbox) to query or select a local GPU device to be used with MATLAB^®.

Note

Training or simulating an agent on a GPU involves device-specific numerical round-off errors. Because of these errors, you can get different results on a GPU and on a CPU for the same operation.

To speed up training by using parallel processing over multiple cores, you do not need to use this argument. Instead, when training your agent, use an rlTrainingOptions object in which the UseParallel option is set to true. For more information about training using multicore processors and GPUs for training, see Train Agents Using Parallel Computing and GPUs.

Example: "gpu"

Learnables — Learnable parameters of approximator object

cell array of dlarray objects

Learnable parameters of the approximator object, specified as a cell array of dlarray objects. This property contains the learnable parameters of the approximation model used by the approximator object.

Example: {dlarray(rand(256,4)),dlarray(rand(256,1))}

State — State of approximator object

cell array of dlarray objects

State of the approximator object, specified as a cell array of dlarray objects. For dlnetwork-based models, this property contains the Value column of the State property table of the dlnetwork model. The elements of the cell array are the state of the recurrent neural network used in the approximator (if any), as well as the state for the batch normalization layer (if used).

For model types that are not based on a dlnetwork object, this property is an empty cell array, since these model types do not support states.

Example: {dlarray(rand(256,1)),dlarray(rand(256,1))}

Object Functions

rlACAgent	Actor-critic (AC) reinforcement learning agent
rlPGAgent	Policy gradient (PG) reinforcement learning agent
rlPPOAgent	Proximal policy optimization (PPO) reinforcement learning agent
rlSACAgent	Soft actor-critic (SAC) reinforcement learning agent
getAction	Obtain action from agent, actor, or policy object given environment observations
evaluate	Evaluate function approximator object given observation (or observation-action) input data
gradient	(Not recommended) Evaluate gradient of function approximator object given observation and action input data
accelerate	(Not recommended) Option to accelerate computation of gradient for approximator object based on neural network
getLearnableParameters	Obtain learnable parameter values from agent, function approximator, or policy object
setLearnableParameters	Set learnable parameter values of agent, function approximator, or policy object
setModel	Set approximation model in function approximator object
getModel	Get approximation model from function approximator object

Examples

Create Continuous Gaussian Actor

Create an observation specification object (or alternatively use getObservationInfo to extract the specification object from an environment). For this example, define the observation space as a continuous six-dimensional space, so that there is a single observation channel that carries a column vector containing five doubles.

obsInfo = rlNumericSpec([5 1]);

Create an action specification object (or alternatively use getActionInfo to extract the specification object from an environment). For this example, define the action space as a continuous three-dimensional space, so that the action channel carries a column vector containing three doubles, each between -10 and 10.

actInfo = rlNumericSpec([3 1], ...
    LowerLimit=-10, ...
    UpperLimit=10);

A continuous Gaussian actor implements a parametrized stochastic policy for a continuous action space. 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.

Note that standard deviations must be nonnegative and mean values must fall within the range of the action. Therefore the output layer that returns the standard deviations must be a softplus or ReLU layer, to enforce nonnegativity, while the output layer that returns the mean values must be a scaling layer immediately preceded by a tahnLayer, to scale the mean values to the output range. However, if you are going to use the actor within a SAC agent, do not add a tanhLayer and a scalingLayer as the last two nonlinear layer in the mean output path. For more information see Soft Actor-Critic (SAC) Agent.

For this example the environment has only one observation channel and therefore the network has only one input layer. 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, and 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 and output layers with the appropriate environment channel.

% Common input path layers
comPath = [ 
    featureInputLayer( ...
        prod(obsInfo.Dimension), ...
        Name="comInLyr");
    fullyConnectedLayer(prod(actInfo.Dimension));
    reluLayer(Name="comPathOutLyr")
    ];

% Path layers for mean value 
% Using scalingLayer to scale range from (-1,1) to (-10,10)
meanPath = [ 
    fullyConnectedLayer(prod(actInfo.Dimension),Name="meanPathInLyr");

    % DO NOT USE following lines if actor is used for a SAC agent
    tanhLayer;
    scalingLayer(Name="meanActOutLyr",Scale=actInfo.UpperLimit) 

    ];

% Path layers for standard deviations
% Using softplus layer to make them non negative
sdevPath = [ 
    fullyConnectedLayer(prod(actInfo.Dimension),Name="stdPathInLyr");
    softplusLayer(Name="stdActOutLyr") 
    ];

Assemble dlnetwork object.

net = dlnetwork();
net = addLayers(net,comPath);
net = addLayers(net,meanPath);
net = addLayers(net,sdevPath);

Connect layers.

net = connectLayers(net,"comPathOutLyr","meanPathInLyr/in");
net = connectLayers(net,"comPathOutLyr","stdPathInLyr/in");

Plot the network.

plot(net)

Initialize network and display the number of learnable parameters (weights).

net = initialize(net);
summary(net)

   Initialized: true

   Number of learnables: 42

   Inputs:
      1   'comInLyr'   5 features

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

actor = rlContinuousGaussianActor(net, obsInfo, actInfo, ...
    ActionMeanOutputNames="meanActOutLyr",...
    ActionStandardDeviationOutputNames="stdActOutLyr",...
    ObservationInputNames="comInLyr");

To check your actor, use getAction to return an action from a random observation vector, using the current network weights.

act = getAction(actor,{rand(obsInfo.Dimension)}); 

Display the action.

act{1}

ans = 3x1 single column vector

   -7.6919
    6.0897
    9.1692

Each of the three elements of the action vector is a random sample from the stochastic distribution with mean and standard deviation provided, as a function of the current observation, by the neural network. To return the Gaussian distribution of the action, given an observation, use evaluate.

dist = evaluate(actor,{rand(obsInfo.Dimension)});

Display the vector of mean values.

dist{1}

ans = 3x1 single column vector

   -6.1829
    3.6141
    8.2286

Display the vector of standard deviations.

dist{2}

ans = 3x1 single column vector

    0.8991
    0.9065
    0.7513

You can now use the actor (along with a critic) to create an agent for the environment described by the given specification objects. Examples of agents that can work with continuous action and observation spaces, and use a continuous Gaussian actor, are rlACAgent, rlPGAgent, rlSACAgent, rlPPOAgent, and rlTRPOAgent.

For more information on creating approximator objects such as actors and critics, see Create Policies and Value Functions.

Version History

Introduced in R2022a