# DM Robotics: Controllers Library (Python)
Contents:
- [Cartesian 6D to Joint Velocity Mapper](#Cartesian-6D-to-Joint-Velocity-Mapper)
## Cartesian 6D to Joint Velocity Mapper
Python bindings for
`dm_robotics/controllers/lsqp/cartesian_6d_to_joint_velocity_mapper`.
This module consists of two classes:
* `cartesian_6d_to_joint_velocity_mapper.Parameters`
* `cartesian_6d_to_joint_velocity_mapper.Mapper`
The mapper solves a constrained linear least-squares optimization problem at
every iteration to compute the joint velocities that best achieve the desired
Cartesian 6D velocity of an object.
In its most basic configuration, it computes the joint velocities that achieve
the desired Cartesian 6d velocity with singularity robustness. In addition, this
mapper also supports the following functionality:
* Nullspace control can be enabled to bias the joint velocities to a desired
value without affecting the accuracy of the resultant Cartesian velocity;
* Collision avoidance can be enabled between any two MuJoCo geoms;
* Limits on the joint positions, velocities, and accelerations can be defined
to ensure that the computed joint velocities do not result in limit
violations.
Please refer to
`dm_robotics/controllers/lsqp/cartesian_6d_to_joint_velocity_mapper.h` or the
class docstrings for more information.
Dependencies:
- dm_robotics/least_squares_qp
- dm_robotics/controllers
- [dm_control](https://github.com/deepmind/dm_control)
### Usage
```python
from dm_control import mujoco
from dm_control.mujoco.wrapper.mjbindings import enums
from dm_robotics.controllers import cartesian_6d_to_joint_velocity_mapper
# Initialize simulation. Assumes velocity controlled robot.
# physics.data.ctrl[:] is an array of size 7 that corresponds to the commanded
# velocities of the joints with IDs 7, 8, 9, 10, 12, 13, 14.
physics = mujoco.Physics(...) # Create MuJoCo physics.
# Create mapper parameters.
params = cartesian_6d_to_joint_velocity_mapper.Parameters()
#
# Set model parameters.
params.model = physics.model
params.joint_ids = [7, 8, 9, 10, 12, 13, 14] # MuJoCo joint IDs being controlled.
params.object_type = enums.mjtObj.mjOBJ_SITE # MuJoCo object being controlled.
params.object_name = "end_effector" # name of MuJoCo object being controlled.
params.integration_timestep = 0.005 # Amount of time the joint velocities will be executed for.
#
# Enable joint position limit constraint. Limits are read automatically from the
# model.
params.enable_joint_position_limits = True
params.joint_position_limit_velocity_scale = 0.95
params.minimum_distance_from_joint_position_limit = 0.01 # ~0.5deg.
#
# Enable joint velocity limits.
params.enable_joint_velocity_limits = True
params.joint_velocity_magnitude_limits = [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]
#
# Enable joint acceleration limits.
params.enable_joint_acceleration_limits = True
params.remove_joint_acceleration_limits_if_in_conflict = True
params.joint_acceleration_magnitude_limits = [10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0]
#
# Enable collision avoidance between the following geoms:
# * "gripper" and "base_link"
# * "base_link" and "floor"
# * "link1" and "floor"
# * "gripper" and "floor"
# * "link1" and "link4"
# * "link1" and "link5"
# * "link1" and "link6"
# * "link2" and "link4"
# * "link2" and "link5"
# * "link2" and "link6"
# Note that collision avoidance will not be enabled for a pair of geoms if they
# are attached to the same body or are attached to bodies that have a
# parent-child relationship.
params.enable_collision_avoidance = True
params.collision_avoidance_normal_velocity_scale = 0.5
params.minimum_distance_from_collisions = 0.01
params.collision_detection_distance = 0.3
params.collision_pairs = [(["gripper"], ["base_link"]),
(["base_link", "link1", "gripper"], ["floor"]),
(["link1", "link2"], ["link4", "link5", "link6"])]
#
# Numerical stability parameters.
params.check_solution_validity = True
params.solution_tolerance = 1e-3
params.regularization_weight = 1e-2
params.enable_nullspace_control = True
params.return_error_on_nullspace_failure = False
params.nullspace_projection_slack = 1e-7
# Create mapper.
mapper = cartesian_6d_to_joint_velocity_mapper.Mapper(params)
# Compute joint velocities and apply them to the joint velocity actuator
# commands at every step.
while True:
# The nullspace bias is often chosen to be a velocity towards the mid-range of
# the joints, but can be chosen to be any 7D joint velocity vector.
nullspace_joint_velocity_bias = get_nullspace_bias()
target_cartesian_velocity = get_end_effector_target_velocity()
solution = mapper.compute_joint_velocities(physics.data, target_velocity,
nullspace_bias)
physics.data.ctrl[:] = solution
physics.step()
```
Raw data
{
"_id": null,
"home_page": "https://github.com/deepmind/dm_robotics/tree/main/cpp/controllers_py",
"name": "dm-robotics-controllers",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7, <3.11",
"maintainer_email": "",
"keywords": "",
"author": "DeepMind",
"author_email": "",
"download_url": "",
"platform": null,
"description": "# DM Robotics: Controllers Library (Python)\n\nContents:\n\n- [Cartesian 6D to Joint Velocity Mapper](#Cartesian-6D-to-Joint-Velocity-Mapper)\n\n## Cartesian 6D to Joint Velocity Mapper\n\nPython bindings for\n`dm_robotics/controllers/lsqp/cartesian_6d_to_joint_velocity_mapper`.\n\nThis module consists of two classes:\n\n* `cartesian_6d_to_joint_velocity_mapper.Parameters`\n* `cartesian_6d_to_joint_velocity_mapper.Mapper`\n\nThe mapper solves a constrained linear least-squares optimization problem at\nevery iteration to compute the joint velocities that best achieve the desired\nCartesian 6D velocity of an object.\n\nIn its most basic configuration, it computes the joint velocities that achieve\nthe desired Cartesian 6d velocity with singularity robustness. In addition, this\nmapper also supports the following functionality:\n\n* Nullspace control can be enabled to bias the joint velocities to a desired\n value without affecting the accuracy of the resultant Cartesian velocity;\n* Collision avoidance can be enabled between any two MuJoCo geoms;\n* Limits on the joint positions, velocities, and accelerations can be defined\n to ensure that the computed joint velocities do not result in limit\n violations.\n\nPlease refer to\n`dm_robotics/controllers/lsqp/cartesian_6d_to_joint_velocity_mapper.h` or the\nclass docstrings for more information.\n\nDependencies:\n\n- dm_robotics/least_squares_qp\n- dm_robotics/controllers\n- [dm_control](https://github.com/deepmind/dm_control)\n\n### Usage\n\n```python\nfrom dm_control import mujoco\nfrom dm_control.mujoco.wrapper.mjbindings import enums\nfrom dm_robotics.controllers import cartesian_6d_to_joint_velocity_mapper\n\n# Initialize simulation. Assumes velocity controlled robot.\n# physics.data.ctrl[:] is an array of size 7 that corresponds to the commanded\n# velocities of the joints with IDs 7, 8, 9, 10, 12, 13, 14.\nphysics = mujoco.Physics(...) # Create MuJoCo physics.\n\n# Create mapper parameters.\nparams = cartesian_6d_to_joint_velocity_mapper.Parameters()\n#\n# Set model parameters.\nparams.model = physics.model\nparams.joint_ids = [7, 8, 9, 10, 12, 13, 14] # MuJoCo joint IDs being controlled.\nparams.object_type = enums.mjtObj.mjOBJ_SITE # MuJoCo object being controlled.\nparams.object_name = \"end_effector\" # name of MuJoCo object being controlled.\nparams.integration_timestep = 0.005 # Amount of time the joint velocities will be executed for.\n#\n# Enable joint position limit constraint. Limits are read automatically from the\n# model.\nparams.enable_joint_position_limits = True\nparams.joint_position_limit_velocity_scale = 0.95\nparams.minimum_distance_from_joint_position_limit = 0.01 # ~0.5deg.\n#\n# Enable joint velocity limits.\nparams.enable_joint_velocity_limits = True\nparams.joint_velocity_magnitude_limits = [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]\n#\n# Enable joint acceleration limits.\nparams.enable_joint_acceleration_limits = True\nparams.remove_joint_acceleration_limits_if_in_conflict = True\nparams.joint_acceleration_magnitude_limits = [10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0]\n#\n# Enable collision avoidance between the following geoms:\n# * \"gripper\" and \"base_link\"\n# * \"base_link\" and \"floor\"\n# * \"link1\" and \"floor\"\n# * \"gripper\" and \"floor\"\n# * \"link1\" and \"link4\"\n# * \"link1\" and \"link5\"\n# * \"link1\" and \"link6\"\n# * \"link2\" and \"link4\"\n# * \"link2\" and \"link5\"\n# * \"link2\" and \"link6\"\n# Note that collision avoidance will not be enabled for a pair of geoms if they\n# are attached to the same body or are attached to bodies that have a\n# parent-child relationship.\nparams.enable_collision_avoidance = True\nparams.collision_avoidance_normal_velocity_scale = 0.5\nparams.minimum_distance_from_collisions = 0.01\nparams.collision_detection_distance = 0.3\nparams.collision_pairs = [([\"gripper\"], [\"base_link\"]),\n ([\"base_link\", \"link1\", \"gripper\"], [\"floor\"]),\n ([\"link1\", \"link2\"], [\"link4\", \"link5\", \"link6\"])]\n#\n# Numerical stability parameters.\nparams.check_solution_validity = True\nparams.solution_tolerance = 1e-3\nparams.regularization_weight = 1e-2\nparams.enable_nullspace_control = True\nparams.return_error_on_nullspace_failure = False\nparams.nullspace_projection_slack = 1e-7\n\n# Create mapper.\nmapper = cartesian_6d_to_joint_velocity_mapper.Mapper(params)\n\n# Compute joint velocities and apply them to the joint velocity actuator\n# commands at every step.\nwhile True:\n # The nullspace bias is often chosen to be a velocity towards the mid-range of\n # the joints, but can be chosen to be any 7D joint velocity vector.\n nullspace_joint_velocity_bias = get_nullspace_bias()\n target_cartesian_velocity = get_end_effector_target_velocity()\n solution = mapper.compute_joint_velocities(physics.data, target_velocity,\n nullspace_bias)\n physics.data.ctrl[:] = solution\n physics.step()\n```\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Python bindings for dm_robotics/cpp/controllers",
"version": "0.6.0",
"project_urls": {
"Homepage": "https://github.com/deepmind/dm_robotics/tree/main/cpp/controllers_py"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4c67b08b104e292244c7b4e027f3505cdb93f8d86551c368a5bd2404b5b8c8e1",
"md5": "43be187a9932aa10625c3fa5815d48f3",
"sha256": "d23c9fb6427ab8cd3e9ea565a94e50e1b4a04e68c171fb45ff894b312810a749"
},
"downloads": -1,
"filename": "dm_robotics_controllers-0.6.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "43be187a9932aa10625c3fa5815d48f3",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.7, <3.11",
"size": 2671114,
"upload_time": "2023-10-31T15:00:24",
"upload_time_iso_8601": "2023-10-31T15:00:24.145818Z",
"url": "https://files.pythonhosted.org/packages/4c/67/b08b104e292244c7b4e027f3505cdb93f8d86551c368a5bd2404b5b8c8e1/dm_robotics_controllers-0.6.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1aada0646355cf79ac99b803aa8bde682998dac0110da67f2bca396b0043cd2c",
"md5": "625e5911226d2de6cd13217c1b9b5503",
"sha256": "cdd615ce71e579d68cd8da2e9b94ba1cb51a5367d55623e1247c596b51eed750"
},
"downloads": -1,
"filename": "dm_robotics_controllers-0.6.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "625e5911226d2de6cd13217c1b9b5503",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": ">=3.7, <3.11",
"size": 2671034,
"upload_time": "2023-10-31T15:00:32",
"upload_time_iso_8601": "2023-10-31T15:00:32.725073Z",
"url": "https://files.pythonhosted.org/packages/1a/ad/a0646355cf79ac99b803aa8bde682998dac0110da67f2bca396b0043cd2c/dm_robotics_controllers-0.6.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "450d53540bfde13cad31195df1fd778ef3417154479d15179dfd9e2982585645",
"md5": "af5deda54586f09cc6777579e544ecb0",
"sha256": "495ea1f523de5308eab6448a18bcb19fe7b17c09f37ae57bf2fbc1ca3d6261cb"
},
"downloads": -1,
"filename": "dm_robotics_controllers-0.6.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "af5deda54586f09cc6777579e544ecb0",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.7, <3.11",
"size": 2671358,
"upload_time": "2023-10-31T15:00:35",
"upload_time_iso_8601": "2023-10-31T15:00:35.492487Z",
"url": "https://files.pythonhosted.org/packages/45/0d/53540bfde13cad31195df1fd778ef3417154479d15179dfd9e2982585645/dm_robotics_controllers-0.6.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-31 15:00:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "deepmind",
"github_project": "dm_robotics",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "dm-robotics-controllers"
}
JSON
