[rllib] example and docs on how to use parametric actions with DQN / PG algorithms (#3384)

doc/source/rllib-models.rst

@@ -110,6 +110,43 @@ Custom models should subclass the common RLlib `model class <https://github.com/
 
 For a full example of a custom model in code, see the `Carla RLlib model <https://github.com/ray-project/ray/blob/master/python/ray/rllib/examples/carla/models.py>`__ and associated `training scripts <https://github.com/ray-project/ray/tree/master/python/ray/rllib/examples/carla>`__. You can also reference the `unit tests <https://github.com/ray-project/ray/blob/master/python/ray/rllib/test/test_nested_spaces.py>`__ for Tuple and Dict spaces, which show how to access nested observation fields.
 
+Custom Recurrent Models
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Instead of using the ``use_lstm: True`` option, it can be preferable use a custom recurrent model. This provides more control over postprocessing of the LSTM output and can also allow the use of multiple LSTM cells to process different portions of the input. The only difference from a normal custom model is that you have to define ``self.state_init``, ``self.state_in``, and ``self.state_out``. You can refer to the existing `lstm.py <https://github.com/ray-project/ray/blob/master/python/ray/rllib/models/lstm.py>`__ model as an example to implement your own model:
+
+
+.. code-block:: python
+
+    class MyCustomLSTM(Model):
+        def _build_layers_v2(self, input_dict, num_outputs, options):
+            # Some initial layers to process inputs, shape [BATCH, OBS...].
+            features = some_hidden_layers(input_dict["obs"])
+
+            # Add back the nested time dimension for tf.dynamic_rnn, new shape
+            # will be [BATCH, MAX_SEQ_LEN, OBS...].
+            last_layer = add_time_dimension(features, self.seq_lens)
+
+            # Setup the LSTM cell (see lstm.py for an example)
+            lstm = rnn.BasicLSTMCell(256, state_is_tuple=True)
+            self.state_init = ...
+            self.state_in = ...
+            lstm_out, lstm_state = tf.nn.dynamic_rnn(
+                lstm,
+                last_layer,
+                initial_state=...,
+                sequence_length=self.seq_lens,
+                time_major=False,
+                dtype=tf.float32)
+            self.state_out = list(lstm_state)
+
+            # Drop the time dimension again so back to shape [BATCH, OBS...].
+            # Note that we retain the zero padding (see issue #2992).
+            last_layer = tf.reshape(lstm_out, [-1, cell_size])
+            logits = linear(last_layer, num_outputs, "action",
+                            normc_initializer(0.01))
+            return logits, last_layer
+
 Custom Preprocessors
 --------------------
 
@@ -188,6 +225,53 @@ Then, you can create an agent with your custom policy graph by:
 
 In this example we overrode existing methods of the existing DDPG policy graph, i.e., `_build_q_network`, `_build_p_network`, `_build_action_network`, `_build_actor_critic_loss`, but you can also replace the entire graph class entirely.
 
+Variable-length / Parametric Action Spaces
+------------------------------------------
+
+Custom models can be used to work with environments where (1) the set of valid actions varies per step, and/or (2) the number of valid actions is very large, as in `OpenAI Five <https://neuro.cs.ut.ee/the-use-of-embeddings-in-openai-five/>`__ and `Horizon <https://arxiv.org/abs/1811.00260>`__. The general idea is that the meaning of actions can be completely conditioned on the observation, that is, the ``a`` in ``Q(s, a)`` is just a token in ``[0, MAX_AVAIL_ACTIONS)`` that only has meaning in the context of ``s``. This works with algorithms in the `DQN and policy-gradient families <rllib-env.html>`__ and can be implemented as follows:
+
+1. The environment should return a mask and/or list of valid action embeddings as part of the observation for each step. To enable batching, the number of actions can be allowed to vary from 1 to some max number:
+
+.. code-block:: python
+
+   class MyParamActionEnv(gym.Env):
+       def __init__(self, max_avail_actions):
+           self.action_space = Discrete(max_avail_actions)
+           self.observation_space = Dict({
+               "action_mask": Box(0, 1, shape=(max_avail_actions, )),
+               "avail_actions": Box(-1, 1, shape=(max_avail_actions, action_embedding_sz)),
+               "real_obs": ...,
+           })
+
+2. A custom model can be defined that can interpret the ``action_mask`` and ``avail_actions`` portions of the observation. Here the model computes the action logits via the dot product of some network output and each action embedding. Invalid actions can be masked out of the softmax by scaling the probability to zero:
+
+.. code-block:: python
+
+    class MyParamActionModel(Model):
+        def _build_layers_v2(self, input_dict, num_outputs, options):
+            avail_actions = input_dict["obs"]["avail_actions"]
+            action_mask = input_dict["obs"]["action_mask"]
+
+            output = FullyConnectedNetwork(
+                input_dict["obs"]["real_obs"], num_outputs=action_embedding_sz)
+
+            # Expand the model output to [BATCH, 1, EMBED_SIZE]. Note that the
+            # avail actions tensor is of shape [BATCH, MAX_ACTIONS, EMBED_SIZE].
+            intent_vector = tf.expand_dims(output, 1)
+
+            # Shape of logits is [BATCH, MAX_ACTIONS].
+            action_logits = tf.reduce_sum(avail_actions * intent_vector, axis=2)
+
+            # Mask out invalid actions (use tf.float32.min for stability)
+            inf_mask = tf.maximum(tf.log(action_mask), tf.float32.min)
+            masked_logits = inf_mask + action_logits
+
+            return masked_logits, last_layer
+
+
+Depending on your use case it may make sense to use just the masking, just action embeddings, or both. For a runnable example of this in code, check out `parametric_action_cartpole.py <https://github.com/ray-project/ray/blob/master/python/ray/rllib/examples/parametric_action_cartpole.py>`__. Note that since masking introduces ``tf.float32.min`` values into the model output, this technique might not work with all algorithm options. For example, algorithms might crash if they incorrectly process the ``tf.float32.min`` values. The cartpole example has working configurations for DQN and several policy gradient algorithms.
+
+
 Model-Based Rollouts
 --------------------