Add a document about migrating dm_control client code after MuJoCo python bindings change.

PiperOrigin-RevId: 433559491
Change-Id: Ia64262001ce02a6e62391e780e0ad962409ca644

Author: nimrod-gileadi

migration_guide_1.0.md

@@ -0,0 +1,150 @@
+# dm_control: 1.0.0 update guide
+
+With 1.0.0, we changed the way dm_control uses the MuJoCo physics simulator, and
+migrated to new python bindings. For most users, this will require no code
+changes. However, some more advanced users will need to change their code
+slightly. Below is a list of known changes that need to be made. Please contact
+us if you've had to make any further changes that are not listed below.
+
+## Required changes
+
+`dm_control.mujoco.wrapper.mjbindings.types` should not be used This module was
+specific to the previous implementation of the dm_control python bindings. For
+example, `types.MJRRECT` should be replaced with `mujoco.MjrRect`.
+
+### `MjData.contact` has changed
+
+`MjData.contact` (often accessed as Physics.data.contact) used to offer an
+interface similar to a numpy structured array. For example, `data.contact.geom1`
+used to be a numpy array of geom IDs.
+
+With the recent update, `MjData.contact` will appear as a list of MjContact
+structs. Code that used to operate on the structured array will have to change.
+For example, the following code would get an array containing the contact
+distance for all contacts that involve geom_id:
+
+```
+contact = physics.data.contact
+involves_geom = (contact.geom1 == geom_id) | (contact.geom2 == geom_id)
+dists = contact[involves_geom].dist
+```
+
+After the upgrade:
+
+```
+contacts = physics.data.contact
+dists = [
+    c.dist for c in contacts if c.geom1 == geom_id or c.geom2 == geom_id
+]
+```
+
+### `.ptr.contents` will not work
+
+Code that accesses `.ptr.contents` on objects such as `MjvScene` will need to be
+updated. In most cases, simply using `scene` instead of `scene.ptr.contents`
+will work.
+
+### Different exceptions will be thrown from MuJoCo
+
+Code (mostly in tests) that expects `dm_control.mujoco.wrapper.core.Error`
+exceptions, will receive different exceptions, thrown by the `mujoco` library.
+These will often be `ValueError` (for errors caused by input parameters), or
+`mujoco.FatalError` (for low level errors in MuJoCo).
+
+### Better error handling
+
+The Python interpreter no longer crashes out when
+[`mju_error`](https://mujoco.readthedocs.io/en/latest/APIreference.html#mju-error)
+is called. Instead, `mju_error` calls are translated into `mujoco.FatalError`
+exceptions in Python.
+
+When Python callables are used as user-defined MuJoCo callbacks, they are now
+permitted to raise exceptions, which will be correctly propagated back down the
+Python call stack.
+
+### Change of signature for `mj_saveModel`
+
+[`mj_saveModel`](https://mujoco.readthedocs.io/en/latest/APIreference.html#mj-savemodel)
+now expects a numpy `uint8` array rather than a ctypes string buffer, and
+doesn't require a "size" parameter (it's inferred from the numpy array size).
+
+Before:
+```
+model_size = mjlib.mj_sizeModel(model.ptr)
+buf = ctypes.create_string_buffer(model_size)
+mjlib.mj_saveModel(model.ptr, None, buf, model_size)
+```
+
+After:
+```
+model_size = mujoco.mj_sizeModel(model)
+buf = np.empty(model_size, np.uint8)
+mjlib.mj_saveModel(model.ptr, None, buf)
+```
+
+## Optional changes
+
+The following are some changes that can make your code more concise, but are not
+required for it to continue working.
+
+### Use the mujoco module directly, instead of mjlib
+
+Existing code that uses `dm_control.mujoco.wrapper.mjbindings.mjlib` can
+directly replace these modules with mujoco. Code that uses `enums` or
+`constants` from `dm_control.mujoco.wrapper.mjbindings` can also use mujoco,
+with slight type changes. All mujoco functions will accept the old enum values
+or the new ones.
+
+Before:
+```
+import dm_control.mujoco.wrapper.mjbindings
+mjlib = mjbindings.mjlib
+
+mjlib.mj_objectVelocity(
+    physics.model.ptr, physics.data.ptr,
+    enums.mjtObj.mjOBJ_SITE,
+    site_id, vel, 0)
+```
+
+After:
+```
+import mujoco
+
+mujoco.mj_objectVelocity(
+    physics.model.ptr, physics.data.ptr,
+    mujoco.mjtObj.mjOBJ_SITE,
+    site_id, vel, 0)
+```
+
+### Assume structs are correctly initialized and memory is managed
+
+The MuJoCo C API includes functions that manage the memory for certain structs.
+Those include functions that allocate memory (e.g. `mj_makeModel`,
+`mj_makeData`, `mjv_makeScene`), functions that free memory (e.g.
+`mj_deleteModel`, `mj_deleteData`, `mjv_freeScene`), and functions that reset a
+struct to its default value (e.g. `mjv_defaultOption`, `mj_defaultVisual`).
+
+The new Python bindings take care of this. Wrapper classes like
+`mujoco.MjvScene` will automatically allocate memory when they're created, and
+release it when they're deleted, and be created with default values set.
+
+As such, allocating and freeing functions are not available through the mujoco
+Python bindings. The "default" functions are still available, but in most cases
+the calls can simply be removed.
+
+Before:
+```
+from dm_control.mujoco import wrapper
+from dm_control.mujoco.wrapper import mjbindings
+mjlib = mjbindings.mjlib
+
+scene_option = wrapper.core.MjvOption()
+mjlib.mjv_defaultOption(scene_option.ptr)
+```
+
+After:
+```
+from dm_control.mujoco import wrapper
+
+scene_option = wrapper.core.MjvOption()
+```

setup.py

@@ -193,7 +193,7 @@ def is_excluded(s):
 
 setup(
     name='dm_control',
-    version='0.0.433501881',
+    version='0.0.433559491',
     description='Continuous control environments and MuJoCo Python bindings.',
     author='DeepMind',
     license='Apache License, Version 2.0',