{"id":13807271,"url":"https://github.com/adaptive-intelligent-robotics/QDax","last_synced_at":"2025-05-14T00:31:08.699Z","repository":{"id":37772613,"uuid":"458247533","full_name":"adaptive-intelligent-robotics/QDax","owner":"adaptive-intelligent-robotics","description":"Accelerated Quality-Diversity","archived":false,"fork":false,"pushed_at":"2025-05-13T10:35:24.000Z","size":9723,"stargazers_count":294,"open_issues_count":34,"forks_count":51,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-13T10:43:32.777Z","etag":null,"topics":["framework","jax","neuroevolution","quality-diversity","reinforcement-learning","research"],"latest_commit_sha":null,"homepage":"https://qdax.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adaptive-intelligent-robotics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-02-11T15:48:57.000Z","updated_at":"2025-05-10T23:16:45.000Z","dependencies_parsed_at":"2023-12-26T06:40:36.194Z","dependency_job_id":"b0b35182-5724-4900-bac1-f7294580556e","html_url":"https://github.com/adaptive-intelligent-robotics/QDax","commit_stats":{"total_commits":129,"total_committers":18,"mean_commits":7.166666666666667,"dds":0.5891472868217054,"last_synced_commit":"a7212217da4ab5c058e900ff44b5efe02db85ce4"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptive-intelligent-robotics%2FQDax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptive-intelligent-robotics%2FQDax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptive-intelligent-robotics%2FQDax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adaptive-intelligent-robotics%2FQDax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adaptive-intelligent-robotics","download_url":"https://codeload.github.com/adaptive-intelligent-robotics/QDax/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254046264,"owners_count":22005566,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["framework","jax","neuroevolution","quality-diversity","reinforcement-learning","research"],"created_at":"2024-08-04T01:01:23.451Z","updated_at":"2025-05-14T00:31:03.680Z","avatar_url":"https://github.com/adaptive-intelligent-robotics.png","language":"Python","funding_links":[],"categories":["Libraries"],"sub_categories":["New Libraries"],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"docs/img/qdax_logo.png\" alt=\"qdax_logo\" width=\"140\"\u003e\u003c/img\u003e\n\u003c/div\u003e\n\n\n# QDax: Accelerated Quality-Diversity\n\n[![Documentation Status](https://readthedocs.org/projects/qdax/badge/?version=latest)](https://qdax.readthedocs.io/en/latest/?badge=latest)\n![pytest](https://github.com/adaptive-intelligent-robotics/QDax/actions/workflows/ci.yaml/badge.svg?branch=main)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/adaptive-intelligent-robotics/QDax/blob/main/LICENSE)\n[![codecov](https://codecov.io/gh/adaptive-intelligent-robotics/QDax/branch/feat/add-codecov/graph/badge.svg)](https://codecov.io/gh/adaptive-intelligent-robotics/QDax)\n\n\nQDax is a tool to accelerate Quality-Diversity (QD) and neuro-evolution algorithms through hardware accelerators and massive parallelization. QD algorithms usually take days/weeks to run on large CPU clusters. With QDax, QD algorithms can now be run in minutes! ⏩ ⏩ 🕛\n\nQDax has been developed as a research framework: it is flexible and easy to extend and build on and can be used for any problem setting. Get started with simple example and run a QD algorithm in minutes here! [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/mapelites.ipynb)\n\n- QDax [paper](https://arxiv.org/abs/2202.01258)\n- QDax [documentation](https://qdax.readthedocs.io/en/latest/)\n\n\n## Installation\nQDax is available on PyPI and can be installed with:\n```bash\npip install qdax\n```\n\nTo install QDax with CUDA 12 support, use:\n```bash\npip install qdax[cuda12]\n```\n\nAlternatively, the latest commit of QDax can be installed directly from source with:\n```bash\npip install git+https://github.com/adaptive-intelligent-robotics/QDax.git@main\n```\nInstalling QDax via ```pip``` installs a CPU-only version of JAX by default. To use QDax with NVidia GPUs, you must first install [CUDA, CuDNN, and JAX with GPU support](https://github.com/google/jax#installation).\n\nHowever, we also provide and recommend using either Docker or conda environments to use the repository which by default provides GPU support. Detailed steps to do so are available in the [documentation](https://qdax.readthedocs.io/en/latest/installation/).\n\n## Basic API Usage\nFor a full and interactive example to see how QDax works, we recommend starting with the tutorial-style [Colab notebook](./examples/mapelites.ipynb). It is an example of the MAP-Elites algorithm used to evolve a population of controllers on a chosen Brax environment (Walker by default).\n\nHowever, a summary of the main API usage is provided below:\n```python\nimport jax\nimport functools\nfrom qdax.core.map_elites import MAPElites\nfrom qdax.core.containers.mapelites_repertoire import compute_euclidean_centroids\nfrom qdax.tasks.arm import arm_scoring_function\nfrom qdax.core.emitters.mutation_operators import isoline_variation\nfrom qdax.core.emitters.standard_emitters import MixingEmitter\nfrom qdax.utils.metrics import default_qd_metrics\n\nseed = 42\nnum_param_dimensions = 100  # num DoF arm\ninit_batch_size = 100\nbatch_size = 1024\nnum_iterations = 50\ngrid_shape = (100, 100)\nmin_param = 0.0\nmax_param = 1.0\nmin_bd = 0.0\nmax_bd = 1.0\n\n# Init a random key\nrandom_key = jax.random.PRNGKey(seed)\n\n# Init population of controllers\nrandom_key, subkey = jax.random.split(random_key)\ninit_variables = jax.random.uniform(\n    subkey,\n    shape=(init_batch_size, num_param_dimensions),\n    minval=min_param,\n    maxval=max_param,\n)\n\n# Define emitter\nvariation_fn = functools.partial(\n    isoline_variation,\n    iso_sigma=0.05,\n    line_sigma=0.1,\n    minval=min_param,\n    maxval=max_param,\n)\nmixing_emitter = MixingEmitter(\n    mutation_fn=lambda x, y: (x, y),\n    variation_fn=variation_fn,\n    variation_percentage=1.0,\n    batch_size=batch_size,\n)\n\n# Define a metrics function\nmetrics_fn = functools.partial(\n    default_qd_metrics,\n    qd_offset=0.0,\n)\n\n# Instantiate MAP-Elites\nmap_elites = MAPElites(\n    scoring_function=arm_scoring_function,\n    emitter=mixing_emitter,\n    metrics_function=metrics_fn,\n)\n\n# Compute the centroids\ncentroids = compute_euclidean_centroids(\n    grid_shape=grid_shape,\n    minval=min_bd,\n    maxval=max_bd,\n)\n\n# Initializes repertoire and emitter state\nrepertoire, emitter_state, random_key = map_elites.init(init_variables, centroids, random_key)\n\n# Run MAP-Elites loop\nfor i in range(num_iterations):\n    (repertoire, emitter_state, metrics, random_key,) = map_elites.update(\n        repertoire,\n        emitter_state,\n        random_key,\n    )\n\n# Get contents of repertoire\nrepertoire.genotypes, repertoire.fitnesses, repertoire.descriptors\n```\n\n\n## QDax core algorithms\nQDax currently supports the following algorithms:\n\n\n| Algorithm                                                                                                                     | Example                                                                                                                                                                                         |\n|-------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| [MAP-Elites](https://arxiv.org/abs/1504.04909)                                                                                | [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/mapelites.ipynb)  |\n| [CVT MAP-Elites](https://arxiv.org/abs/1610.05729)                                                                            | [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/mapelites.ipynb)  |\n| [Policy Gradient Assisted MAP-Elites (PGA-ME)](https://hal.archives-ouvertes.fr/hal-03135723v2/file/PGA_MAP_Elites_GECCO.pdf) | [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/pgame.ipynb)      |\n| [DCRL-ME](https://arxiv.org/abs/2401.08632)                                                                                   | [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/dcrlme.ipynb)     |\n| [QDPG](https://arxiv.org/abs/2006.08505)                                                                                      | [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/qdpg.ipynb)       |\n| [CMA-ME](https://arxiv.org/pdf/1912.02400.pdf)                                                                                | [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/cmame.ipynb)      |\n| [OMG-MEGA](https://arxiv.org/abs/2106.03894)                                                                                  | [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/omgmega.ipynb)    |\n| [CMA-MEGA](https://arxiv.org/abs/2106.03894)                                                                                  | [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/cmamega.ipynb)    |\n| [Multi-Objective MAP-Elites (MOME)](https://arxiv.org/abs/2202.03057)                                                         | [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/mome.ipynb)       |\n| [MAP-Elites Evolution Strategies (MEES)](https://dl.acm.org/doi/pdf/10.1145/3377930.3390217)                                  | [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/mees.ipynb)       |\n| [MAP-Elites PBT (ME-PBT)](https://openreview.net/forum?id=CBfYffLqWqb)                                                        | [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/me_sac_pbt.ipynb) |\n| [MAP-Elites Low-Spread (ME-LS)](https://dl.acm.org/doi/abs/10.1145/3583131.3590433)                                           | [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/me_ls.ipynb)      |\n\n\n## QDax baseline algorithms\nThe QDax library also provides implementations for some useful baseline algorithms:\n\n| Algorithm  | Example |\n| --- | --- |\n| [DIAYN](https://arxiv.org/abs/1802.06070) | [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/diayn.ipynb) |\n| [DADS](https://arxiv.org/abs/1907.01657) | [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/dads.ipynb) |\n| [SMERL](https://arxiv.org/abs/2010.14484) | [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/smerl.ipynb) |\n| [NSGA2](https://ieeexplore.ieee.org/document/996017) | [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/nsga2_spea2.ipynb) |\n| [SPEA2](https://www.semanticscholar.org/paper/SPEA2%3A-Improving-the-strength-pareto-evolutionary-Zitzler-Laumanns/b13724cb54ae4171916f3f969d304b9e9752a57f) | [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/nsga2_spea2.ipynb) |\n| [Population Based Training (PBT)](https://arxiv.org/abs/1711.09846)                                                           | [![Open All Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adaptive-intelligent-robotics/QDax/blob/main/examples/sac_pbt.ipynb)    |\n\n## QDax Tasks\nThe QDax library also provides numerous implementations for several standard Quality-Diversity tasks.\n\nAll those implementations, and their descriptions are provided in the [tasks directory](./qdax/tasks).\n\n## Contributing\nIssues and contributions are welcome. Please refer to the [contribution guide](https://qdax.readthedocs.io/en/latest/guides/CONTRIBUTING/) in the documentation for more details.\n\n## Related Projects\n- [EvoJAX: Hardware-Accelerated Neuroevolution](https://github.com/google/evojax). EvoJAX is a scalable, general purpose, hardware-accelerated neuroevolution toolkit. [Paper](https://arxiv.org/abs/2202.05008)\n- [evosax: JAX-Based Evolution Strategies](https://github.com/RobertTLange/evosax)\n\n## Citing QDax\nIf you use QDax in your research and want to cite it in your work, please use:\n```\n@article{chalumeau2024qdax,\n  title={Qdax: A library for quality-diversity and population-based algorithms with hardware acceleration},\n  author={Chalumeau, Felix and Lim, Bryan and Boige, Raphael and Allard, Maxime and Grillotti, Luca and Flageat, Manon and Mac{\\'e}, Valentin and Richard, Guillaume and Flajolet, Arthur and Pierrot, Thomas and others},\n  journal={Journal of Machine Learning Research},\n  volume={25},\n  number={108},\n  pages={1--16},\n  year={2024}\n}\n```\n\n## Contributors\n\nQDax was developed and is maintained by the [Adaptive \u0026 Intelligent Robotics Lab (AIRL)](https://www.imperial.ac.uk/adaptive-intelligent-robotics/) and [InstaDeep](https://www.instadeep.com/).\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg align=\"center\" src=\"docs/img/AIRL_logo.png\" alt=\"AIRL_Logo\" width=\"220\"/\u003e \u003cimg align=\"center\" src=\"docs/img/instadeep_logo.png\" alt=\"InstaDeep_Logo\" width=\"220\"/\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\u003ca href=\"https://github.com/limbryan\" title=\"Bryan Lim\"\u003e\u003cimg src=\"https://github.com/limbryan.png\" height=\"auto\" width=\"50\" style=\"border-radius:50%\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/maxiallard\" title=\"Maxime Allard\"\u003e\u003cimg src=\"https://github.com/maxiallard.png\" height=\"auto\" width=\"50\" style=\"border-radius:50%\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Lookatator\" title=\"Luca Grilloti\"\u003e\u003cimg src=\"https://github.com/Lookatator.png\" height=\"auto\" width=\"50\" style=\"border-radius:50%\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/manon-but-yes\" title=\"Manon Flageat\"\u003e\u003cimg src=\"https://github.com/manon-but-yes.png\" height=\"auto\" width=\"50\" style=\"border-radius:50%\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Aneoshun\" title=\"Antoine Cully\"\u003e\u003cimg src=\"https://github.com/Aneoshun.png\" height=\"auto\" width=\"50\" style=\"border-radius:50%\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/felixchalumeau\" title=\"Felix Chalumeau\"\u003e\u003cimg src=\"https://github.com/felixchalumeau.png\" height=\"auto\" width=\"50\" style=\"border-radius:50%\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/ranzenTom\" title=\"Thomas Pierrot\"\u003e\u003cimg src=\"https://github.com/ranzenTom.png\" height=\"auto\" width=\"50\" style=\"border-radius:50%\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Egiob\" title=\"Raphael Boige\"\u003e\u003cimg src=\"https://github.com/Egiob.png\" height=\"auto\" width=\"50\" style=\"border-radius:50%\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/valentinmace\" title=\"Valentin Mace\"\u003e\u003cimg src=\"https://github.com/valentinmace.png\" height=\"auto\" width=\"50\" style=\"border-radius:50%\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/GRichard513\" title=\"Guillaume Richard\"\u003e\u003cimg src=\"https://github.com/GRichard513.png\" height=\"auto\" width=\"50\" style=\"border-radius:50%\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/flajolet\" title=\"Arthur Flajolet\"\u003e\u003cimg src=\"https://github.com/flajolet.png\" height=\"auto\" width=\"50\" style=\"border-radius:50%\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/remidebette\" title=\"Rémi Debette\"\u003e\u003cimg src=\"https://github.com/remidebette.png\" height=\"auto\" width=\"50\" style=\"border-radius:50%\"\u003e\u003c/a\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadaptive-intelligent-robotics%2FQDax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadaptive-intelligent-robotics%2FQDax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadaptive-intelligent-robotics%2FQDax/lists"}