From b301010d63e31d479f3d4bb1ca1dc93cd2cb288f Mon Sep 17 00:00:00 2001 From: Ikechukwu Uchendu Date: Thu, 29 Aug 2024 16:57:49 -0400 Subject: [PATCH] Updated tutorial on adding domains --- docs/content/tutorials/add_domain.ipynb | 143 ------------------------ docs/content/tutorials/add_domain.md | 119 ++++++++++++++++++++ 2 files changed, 119 insertions(+), 143 deletions(-) delete mode 100644 docs/content/tutorials/add_domain.ipynb create mode 100644 docs/content/tutorials/add_domain.md diff --git a/docs/content/tutorials/add_domain.ipynb b/docs/content/tutorials/add_domain.ipynb deleted file mode 100644 index 96f96b4..0000000 --- a/docs/content/tutorials/add_domain.ipynb +++ /dev/null @@ -1,143 +0,0 @@ -{ - "cells": [ - { - "metadata": {}, - "cell_type": "markdown", - "source": [ - "# Adding Custom Domains\n", - "\n", - "This tutorial will demonstrate how to add additional domains to A2Perf.\n", - "\n", - "## Path to A2Perf Domains\n", - "\n", - "Domains are stored in `A2Perf/a2perf/domains`. Currently, you'll find the main domains in this folder such as `circuit_training`, `quadruped_locomotion`, and `web_navigation`. There are also additional modules such as `tfa` that is there for interfacing with Tensorflow Agents.\n", - "\n", - "
\n", - "\n", - "---\n", - "\n", - "\n", - "## Creating a new domain\n", - "\n", - "To add a new domain:\n", - "\n", - "1. Create a new folder in the domains directory. For the purposes of this tutorial, we will create a new domain called \"my_domain\":\n", - "\n", - "\n", - "```bash\n", - "cd A2Perf/a2perf/domains\n", - "mkdir my_domain\n", - "``` \n", - "\n", - "2. Inside of `my_domain`, create the following files:\n", - "- `__init__.py`\n", - "- [any other files needed for your domain]\n", - "\n", - "3. Inside of `__init__.py`, you will need to register your domain with gymnasium. Here is an example of how we do this for the web navigation domain:\n", - "\n", - "```python\n", - "import gymnasium as gym\n", - "import pkg_resources\n", - "\n", - "base_url_path = pkg_resources.resource_filename('a2perf.domains.web_navigation',\n", - " 'gwob')\n", - "base_url = f'file://{base_url_path}/'\n", - "data_dir = pkg_resources.resource_filename(\n", - " 'a2perf.domains.web_navigation.environment_generation', 'data')\n", - "\n", - "gym.envs.register(\n", - " id='WebNavigation-v0',\n", - " entry_point=(\n", - " 'a2perf.domains.web_navigation.gwob.CoDE.environment:WebNavigationEnv'\n", - " ),\n", - " apply_api_compatibility=False,\n", - " disable_env_checker=False,\n", - " kwargs=dict(\n", - " use_legacy_step=False,\n", - " use_legacy_reset=False,\n", - " data_dir=data_dir,\n", - " base_url=base_url),\n", - ")\n", - "```\n", - "\n", - "Note: The `base_url_path`, `base_url`, and `data_dir` are specific to web navigation and are not necessary for your domain.\n", - "\n", - "
\n", - "\n", - "---\n", - "\n", - "\n", - "\n", - "## Additional configurations\n", - "\n", - "\n", - "When adding a new domain, you may need to configure additional settings:\n", - "\n", - "1. Docker configurations:\n", - " In `a2perf/launch/docker_utils.py`, add entries for your new domain:\n", - "\n", - " a. In the `get_docker_instructions` function:\n", - " ```python\n", - " docker_instructions = {\n", - " # ... existing entries ...\n", - " BenchmarkDomain.MY_DOMAIN.value: common_setup + [\n", - " # Add your domain-specific Docker instructions here\n", - " # E.g., installing dependencies, setting up the environment\n", - " ],\n", - " }\n", - " ```\n", - " \n", - " b. In the `get_entrypoint` function:\n", - " ```python\n", - " entrypoints = {\n", - " # ... existing entries ...\n", - " BenchmarkDomain.MY_DOMAIN.value: xm.CommandList([\n", - " # Add your domain-specific entrypoint commands here\n", - " ]),\n", - " }\n", - "\n", - "2. Update constants:\n", - " In `a2perf/constants.py`, add your new domain to the `BenchmarkDomain` enum:\n", - " ```python\n", - " @gin.constants_from_enum\n", - " class BenchmarkDomain(enum.Enum):\n", - " QUADRUPED_LOCOMOTION = \"QuadrupedLocomotion-v0\"\n", - " WEB_NAVIGATION = \"WebNavigation-v0\"\n", - " CIRCUIT_TRAINING = \"CircuitTraining-v0\"\n", - " MY_DOMAIN = \"MyDomain-v0\"\n", - " ```\n", - " \n", - "These configurations ensure A2Perf can properly set up and run experiments for your new domain.\n", - "\n" - ], - "id": "e706fe6999459158" - }, - { - "metadata": {}, - "cell_type": "markdown", - "source": "", - "id": "8b69291819f7204f" - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 2 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython2", - "version": "2.7.6" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} diff --git a/docs/content/tutorials/add_domain.md b/docs/content/tutorials/add_domain.md new file mode 100644 index 0000000..9078897 --- /dev/null +++ b/docs/content/tutorials/add_domain.md @@ -0,0 +1,119 @@ +# Adding Custom Domains + +This tutorial will demonstrate how to add additional domains to A2Perf. + +## Path to A2Perf Domains + +Domains are stored in `A2Perf/a2perf/domains`. Currently, you'll find the main +domains in this folder such as `circuit_training`, `quadruped_locomotion`, and +`web_navigation`. There are also additional modules such as `tfa` that is there +for interfacing with Tensorflow Agents. + + +--- + +## Creating a new domain + +To add a new domain: + +1. Create a new folder in the domains directory. For the purposes of this + tutorial, we will create a new domain called "my_domain": + +```bash +cd A2Perf/a2perf/domains +mkdir my_domain +``` + +2. Inside of `my_domain`, create the following files: + +- `__init__.py` +- [any other files needed for your domain] + +3. Inside of `__init__.py`, you will need to register your domain with + gymnasium. Here is an example of how we do this for the web navigation + domain: + +```python +import gymnasium as gym +import pkg_resources + +base_url_path = pkg_resources.resource_filename('a2perf.domains.web_navigation', + 'gwob') +base_url = f'file://{base_url_path}/' +data_dir = pkg_resources.resource_filename( + 'a2perf.domains.web_navigation.environment_generation', 'data') + +gym.envs.register( + id='WebNavigation-v0', + entry_point=( + 'a2perf.domains.web_navigation.gwob.CoDE.environment:WebNavigationEnv' + ), + apply_api_compatibility=False, + disable_env_checker=False, + kwargs=dict( + use_legacy_step=False, + use_legacy_reset=False, + data_dir=data_dir, + base_url=base_url), +) +``` + +Note: The `base_url_path`, `base_url`, and `data_dir` are specific to web +navigation and are not necessary for your domain. + + +--- + +## Additional configurations + +When adding a new domain, you may need to configure additional settings: + +1. Docker configurations: + In `a2perf/launch/docker_utils.py`, add entries for your new domain: + + a. In the `get_docker_instructions` function: + ```python + docker_instructions = { + # ... existing entries ... + BenchmarkDomain.MY_DOMAIN.value: common_setup + [ + # Add your domain-specific Docker instructions here + # E.g., installing dependencies, setting up the environment + ], + } + ``` + + b. In the `get_entrypoint` function: + ```python + entrypoints = { + # ... existing entries ... + BenchmarkDomain.MY_DOMAIN.value: xm.CommandList([ + # Add your domain-specific entrypoint commands here + ]), + } + +2. Update constants: + In `a2perf/constants.py`, add your new domain to the `BenchmarkDomain` enum + and update the `ENV_NAMES` dictionary: + + ```python + import enum + import gin + + @gin.constants_from_enum + class BenchmarkDomain(enum.Enum): + QUADRUPED_LOCOMOTION = "QuadrupedLocomotion" + WEB_NAVIGATION = "WebNavigation" + CIRCUIT_TRAINING = "CircuitTraining" + MY_DOMAIN = "MyDomain" # Add your new domain here + + # ... (other existing code) + + ENV_NAMES = { + # ... (existing domains) + BenchmarkDomain.MY_DOMAIN: [ + "MyDomain-Task1-v0", + "MyDomain-Task2-v0", + # Add all the environment names for your new domain + ], + } + ```