Actualizar README.md

README.md

@@ -1,92 +1,138 @@
-# `dm_control`: The DeepMind Control Suite and Package
+# `dm_control`: Google DeepMind Infrastructure for Physics-Based Simulation.
 
-# ![all domains](all_domains.png)
+Google DeepMind's software stack for physics-based simulation and Reinforcement
+Learning environments, using MuJoCo physics.
 
-This package contains:
+An **introductory tutorial** for this package is available as a Colaboratory
+notebook:
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/google-deepmind/dm_control/blob/main/tutorial.ipynb)
 
-- A set of Python Reinforcement Learning environments powered by the MuJoCo
-  physics engine. See the `suite` subdirectory.
+## Overview
 
-- Libraries that provide Python bindings to the MuJoCo physics engine.
+This package consists of the following "core" components:
 
-If you use this package, please cite our accompanying accompanying [tech report](https://arxiv.org/abs/1801.00690).
+-   [`dm_control.mujoco`]: Libraries that provide Python bindings to the MuJoCo
+    physics engine.
 
-## Installation and requirements
+-   [`dm_control.suite`]: A set of Python Reinforcement Learning environments
+    powered by the MuJoCo physics engine.
 
-Follow these steps to install `dm_control`:
+-   [`dm_control.viewer`]: An interactive environment viewer.
 
-1. Download MuJoCo Pro 1.50 from the download page on the [MuJoCo website](http://www.mujoco.org/).
-   MuJoCo Pro must be installed before `dm_control`, since `dm_control`'s
-   install script generates Python [`ctypes`](https://docs.python.org/2/library/ctypes.html)
-   bindings based on MuJoCo's header files. By default, `dm_control` assumes
-   that the MuJoCo Zip archive is extracted as `~/.mujoco/mjpro150`.
+Additionally, the following components are available for the creation of more
+complex control tasks:
 
-2. Install the `dm_control` Python package by running
-   `pip install git+git://github.com/deepmind/dm_control.git`
-   (PyPI package coming soon) or by cloning the repository and running
-   `pip install /path/to/dm_control/`
-   At installation time, `dm_control` looks for the MuJoCo headers from Step 1
-   in `~/.mujoco/mjpro150/include`, however this path can be configured with the
-   `headers-dir` command line argument.
+-   [`dm_control.mjcf`]: A library for composing and modifying MuJoCo MJCF
+    models in Python.
 
-3. Install a license key for MuJoCo, required by `dm_control` at runtime. See
-   the [MuJoCo license key page](https://www.roboti.us/license.html) for further
-   details. By default, `dm_control` looks for the MuJoCo license key file at
-   `~/.mujoco/mjkey.txt`.
+-   `dm_control.composer`: A library for defining rich RL environments from
+    reusable, self-contained components.
 
-4. If the license key (e.g. `mjkey.txt`) or the shared library provided by
-   MuJoCo Pro (e.g. `libmujoco150.so` or `libmujoco150.dylib`) are installed at
-   non-default paths, specify their locations using the `MJKEY_PATH` and
-   `MJLIB_PATH` environment variables respectively.
+-   [`dm_control.locomotion`]: Additional libraries for custom tasks.
 
-## Additional instructions for Linux
+-   [`dm_control.locomotion.soccer`]: Multi-agent soccer tasks.
 
-Install `GLFW` and `GLEW` through your Linux distribution's package manager.
-For example, on Debian and Ubuntu, this can be done by running
-`sudo apt-get install libglfw3 libglew2.0`.
+If you use this package, please cite our accompanying [publication]:
 
-## Additional instructions for Homebrew users on macOS
-
-1. The above instructions using `pip` should work, provided that you
-   use a Python interpreter that is installed by Homebrew (rather than the
-   system-default one).
-
-2. To get OpenGL working, install the `glfw` package from Homebrew by running
-   `brew install glfw`.
-
-3. Before running, the `DYLD_LIBRARY_PATH` environment variable needs to be
-   updated with the path to the GLFW library. This can be done by running
-   `export DYLD_LIBRARY_PATH=$(brew --prefix)/lib:$DYLD_LIBRARY_PATH`.
-
-## Control Suite quickstart
-
-```python
-from dm_control import suite
-import numpy as np
+```
+@article{tunyasuvunakool2020,
+         title = {dm_control: Software and tasks for continuous control},
+         journal = {Software Impacts},
+         volume = {6},
+         pages = {100022},
+         year = {2020},
+         issn = {2665-9638},
+         doi = {https://doi.org/10.1016/j.simpa.2020.100022},
+         url = {https://www.sciencedirect.com/science/article/pii/S2665963820300099},
+         author = {Saran Tunyasuvunakool and Alistair Muldal and Yotam Doron and Salvador Arturo Ortiz Gonzalez 
+                   Siqi Liu and Steven Bohez and Josh Merel and Tom Erez and
+                   Timothy Lillicrap and Nicolas Heess and Yuval Tassa},
+}
+```
 
-# Load one task:
-env = suite.load(domain_name="cartpole", task_name="swingup")
+## Installation
 
-# Iterate over a task set:
-for domain_name, task_name in suite.BENCHMARKING:
-  env = suite.load(domain_name, task_name)
+Install `dm_control` from PyPI by running
 
-# Step through an episode and print out reward, discount and observation.
-action_spec = env.action_spec()
-time_step = env.reset()
-while not time_step.last():
-  action = np.random.uniform(action_spec.minimum,
-                             action_spec.maximum,
-                             size=action_spec.shape)
-  time_step = env.step(action)
-  print(time_step.reward, time_step.discount, time_step.observation)
+```sh
+pip install dm_control
 ```
 
-See our [tech report](https://arxiv.org/abs/1801.00690) for further details.
+> **Note**: **`dm_control` cannot be installed in "editable" mode** (i.e. `pip
+> install -e`).
+>
+> While `dm_control` has been largely updated to use the pybind11-based bindings
+> provided via the `mujoco` package, at this time it still relies on some legacy
+> components that are automatically generated from MuJoCo header files in a way
+> that is incompatible with editable mode. Attempting to install `dm_control` in
+> editable mode will result in import errors like:
+>
+> ```
+> ImportError: cannot import name 'constants' from partially initialized module 'dm_control.mujoco.wrapper.mjbindings' ...
+> ```
+>
+> The solution is to `pip uninstall dm_control` and then reinstall it without
+> the `-e` flag.
+
+## Versioning
+
+Starting from version 1.0.0, we adopt semantic versioning.
+
+Prior to version 1.0.0, the `dm_control` Python package was versioned `0.0.N`,
+where `N` was an internal revision number that increased by an arbitrary amount
+at every single Git commit.
+
+If you want to install an unreleased version of `dm_control` directly from our
+repository, you can do so by running `pip install
+git+https://github.com/google-deepmind/dm_control.git`.
+
+## Rendering
+
+The MuJoCo Python bindings support three different OpenGL rendering backends:
+EGL (headless, hardware-accelerated), GLFW (windowed, hardware-accelerated), and
+OSMesa (purely software-based). At least one of these three backends must be
+available in order render through `dm_control`.
+
+*   Hardware rendering with a windowing system is supported via GLFW and GLEW.
+    On Linux these can be installed using your distribution's package manager.
+    For example, on Debian and Ubuntu, this can be done by running `sudo apt-get
+    install libglfw3 libglew2.0`. Please note that:
+
+    -   [`dm_control.viewer`] can only be used with GLFW.
+    -   GLFW will not work on headless machines.
+
+*   "Headless" hardware rendering (i.e. without a windowing system such as X11)
+    requires [EXT_platform_device] support in the EGL driver. Recent Nvidia
+    drivers support this. You will also need GLEW. On Debian and Ubuntu, this
+    can be installed via `sudo apt-get install libglew2.0`.
+
+*   Software rendering requires GLX and OSMesa. On Debian and Ubuntu these can
+    be installed using `sudo apt-get install libgl1-mesa-glx libosmesa6`.
+
+By default, `dm_control` will attempt to use GLFW first, then EGL, then OSMesa.
+You can also specify a particular backend to use by setting the `MUJOCO_GL=`
+environment variable to `"glfw"`, `"egl"`, or `"osmesa"`, respectively. When
+rendering with EGL, you can also specify which GPU to use for rendering by
+setting the environment variable `MUJOCO_EGL_DEVICE_ID=` to the target GPU ID.
 
-## Illustration video
-
-Below is a video montage of solved Control Suite tasks, with reward
-visualisation enabled.
+## Additional instructions for Homebrew users on macOS
 
-[![Video montage](https://img.youtube.com/vi/rAai4QzcYbs/0.jpg)](https://www.youtube.com/watch?v=rAai4QzcYbs)
+1.  The above instructions using `pip` should work, provided that you use a
+    Python interpreter that is installed by Homebrew (rather than the
+    system-default one).
+
+2.  Before running, the `DYLD_LIBRARY_PATH` environment variable needs to be
+    updated with the path to the GLFW library. This can be done by running
+    `export DYLD_LIBRARY_PATH=$(brew --prefix)/lib:$DYLD_LIBRARY_PATH`.
+
+[EXT_platform_device]: https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_platform_device.txt
+[Releases page on the MuJoCo GitHub repository]: https://github.com/google-deepmind/mujoco/releases
+[MuJoCo website]: https://mujoco.org/
+[publication]: https://doi.org/10.1016/j.simpa.2020.100022
+[`ctypes`]: https://docs.python.org/3/library/ctypes.html
+[`dm_control.mjcf`]: dm_control/mjcf/README.md
+[`dm_control.mujoco`]: dm_control/mujoco/README.md
+[`dm_control.suite`]: dm_control/suite/README.md
+[`dm_control.viewer`]: dm_control/viewer/README.md
+[`dm_control.locomotion`]: dm_control/locomotion/README.md
+[`dm_control.locomotion.soccer`]: dm_control/locomotion/soccer/README.md

dm_control/_render/__init__.py

@@ -0,0 +1,109 @@
+# Copyright 2017-2018 The dm_control Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or  implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ============================================================================
+
+"""OpenGL context management for rendering MuJoCo scenes.
+
+By default, the `Renderer` class will try to load one of the following rendering
+APIs, in descending order of priority: GLFW > EGL > OSMesa.
+
+It is also possible to select a specific backend by setting the `MUJOCO_GL=`
+environment variable to 'glfw', 'egl', or 'osmesa'.
+"""
+
+import collections
+import os
+
+from absl import logging
+from dm_control._render import constants
+
+BACKEND = os.environ.get(constants.MUJOCO_GL)
+
+
+# pylint: disable=g-import-not-at-top
+def _import_egl():
+  from dm_control._render.pyopengl.egl_renderer import EGLContext
+  return EGLContext
+
+
+def _import_glfw():
+  from dm_control._render.glfw_renderer import GLFWContext
+  return GLFWContext
+
+
+def _import_osmesa():
+  from dm_control._render.pyopengl.osmesa_renderer import OSMesaContext
+  return OSMesaContext
+
+
+# Import removed.
+# pylint: enable=g-import-not-at-top
+
+
+def _no_renderer():
+  def no_renderer(*args, **kwargs):
+    del args, kwargs
+    raise RuntimeError('No OpenGL rendering backend is available.')
+  return no_renderer
+
+
+_ALL_RENDERERS = (
+    (constants.GLFW, _import_glfw),
+    (constants.EGL, _import_egl),
+    (constants.OSMESA, _import_osmesa),
+    # Option removed.
+)
+
+_NO_RENDERER = (
+    (constants.NO_RENDERER, _no_renderer),
+)
+
+
+if BACKEND is not None:
+  # If a backend was specified, try importing it and error if unsuccessful.
+  import_func = None
+  for names, importer in _ALL_RENDERERS + _NO_RENDERER:
+    if BACKEND in names:
+      import_func = importer
+      BACKEND = names[0]  # canonicalize the renderer name
+      break
+  if import_func is None:
+    all_names = set()
+    for names, _ in _ALL_RENDERERS + _NO_RENDERER:
+      all_names.update(names)
+    raise RuntimeError(
+        'Environment variable {} must be one of {!r}: got {!r}.'
+        .format(constants.MUJOCO_GL, sorted(all_names), BACKEND))
+  logging.info('MUJOCO_GL=%s, attempting to import specified OpenGL backend.',
+               BACKEND)
+  Renderer = import_func()
+else:
+  logging.info('MUJOCO_GL is not set, so an OpenGL backend will be chosen '
+               'automatically.')
+  # Otherwise try importing them in descending order of priority until
+  # successful.
+  for names, import_func in _ALL_RENDERERS:
+    try:
+      Renderer = import_func()
+      BACKEND = names[0]
+      logging.info('Successfully imported OpenGL backend: %s', names[0])
+      break
+    except ImportError:
+      logging.info('Failed to import OpenGL backend: %s', names[0])
+  if BACKEND is None:
+    logging.info('No OpenGL backend could be imported. Attempting to create a '
+                 'rendering context will result in a RuntimeError.')
+    Renderer = _no_renderer()
+
+USING_GPU = BACKEND in constants.EGL + constants.GLFW