From 9f3b4f9f1587221309a8c2aebd6a9b60d5fb744c Mon Sep 17 00:00:00 2001 From: Shantanu Date: Mon, 29 Jul 2024 13:02:20 -0500 Subject: [PATCH 1/8] First draft --- docs/operation.rst | 1 + docs/operation/training.rst | 210 ++++++++++++++++++++++++++++++++++++ 2 files changed, 211 insertions(+) create mode 100644 docs/operation/training.rst diff --git a/docs/operation.rst b/docs/operation.rst index d2f9961..3017d7c 100644 --- a/docs/operation.rst +++ b/docs/operation.rst @@ -8,3 +8,4 @@ Operation ./operation/mobile.rst ./operation/stationary.rst ./operation/data_collection.rst + ./operation/training.rst diff --git a/docs/operation/training.rst b/docs/operation/training.rst new file mode 100644 index 0000000..a8349b3 --- /dev/null +++ b/docs/operation/training.rst @@ -0,0 +1,210 @@ +=============== +Data Collection +=============== + +Task Creation +============= + +Task configuration can be found in the ALOHA package's aloha module under ``constants.py`` in the ``TASK_CONFIGS`` dictionary. +A template task (``aloha_template``) is provided containing all possible fields and some placeholder values. +Here, we will focus only on the task name, the dataset directory, the episode length, and the observation cameras. + +.. list-table:: + :align: center + :widths: 25 75 + :header-rows: 1 + :width: 60% + + * - Configuration Field + - Description + * - Task Name + - The task name should accurately describe the task that the ALOHA is performing. + * - Dataset Directory + - The ``dataset_dir`` field sets the directory episodes will saved to. + * - Episode Length + - The ``episode_len`` field sets the length of the episode in number of timesteps. + * - Camera Names + - The ``camera_names`` field takes in a list of strings corresponding to camera names. + These camera names will be used as observation sources during dataset collection. + +Recording Episodes +================== + +To record an episode, follow the steps below: + +#. Bring up the ALOHA control stack according to your platform + + * Stationary: :ref:`operation/stationary:Running ALOHA Bringup` + * Mobile: :ref:`operation/mobile:Running ALOHA Bringup` + +#. Configure the environment and run the episode recording script as follows: + + .. code-block:: bash + + $ source /opt/ros/humble/setup.bash # configure ROS system install environment + $ source ~/interbotix_ws/install/setup.bash # configure ROS workspace environment + $ source //bin/activate # configure ALOHA Python environment + $ cd ~/interbotix_ws/src/aloha/scripts/ + $ python3 record_episodes.py --task_name --episode_idx + + .. note:: + + The ``task_name`` argument should match one of the task names in the ``TASK_CONFIGS``, as configured in the :ref:`operation/data_collection:Task Creation` section. + + .. tip:: + + Each platform has a "dummy" task that can be used to test basic data collection and playback. + For the Stationary variant, use the ``aloha_stationary_dummy`` task. + For the Mobile variant, use the ``aloha_mobile_dummy`` task. + + An example for the Mobile variant would look like: + + .. code-block:: bash + + $ python3 record_episodes.py --task_name aloha_mobile_dummy --episode_idx 0 + +Episode Playback +================ + +To play back a previously-recorded episode, follow the steps below: + +#. Bring up the ALOHA control stack according to your platform + + * Stationary: :ref:`operation/stationary:Running ALOHA Bringup` + * Mobile: :ref:`operation/mobile:Running ALOHA Bringup` + +#. Configure the environment and run the episode playback script as follows: + + .. code-block:: bash + + $ source /opt/ros/humble/setup.bash # configure ROS system install environment + $ source ~/interbotix_ws/install/setup.bash # configure ROS workspace environment + $ source //bin/activate # configure ALOHA Python environment + $ cd ~/interbotix_ws/src/aloha/scripts/ + $ python3 replay_episodes.py --dataset_dir --episode_idx + + .. tip:: + + An example for replaying the dummy Mobile episode recorded above would look like: + + .. code-block:: bash + + $ python3 replay_episodes.py --dataset_dir ~/aloha_data/aloha_mobile_dummy/ --episode_idx 0 + +Episode Auto-Recording +====================== + +A helpful bash script, ``auto_record.sh``, is provided to allow users to collect many episodes consecutively without having to interact with the control computer. + +Configuration +------------- + +This script, whose `source`_ can be found on the ALOHA GitHub repository, has a few configuration options that should be verified or set before running. + +.. _`source`: https://github.com/Interbotix/aloha/blob/main/scripts/auto_record.sh + +``ROS_DISTRO`` +^^^^^^^^^^^^^^ + +Set the codename of the ROS distribution used on the control computer. +This value is used to set the path to the ``ROS_SETUP_PATH`` variable used later in the script. +``ROS_DISTRO`` defaults to ``humble``. + +.. code-block:: bash + + ROS_DISTRO=humble + +``VENV_ACTIVATE_PATH`` +^^^^^^^^^^^^^^^^^^^^^^ + +Set the path to the virtual environment's activate file. +This value is used when setting up the Python virtual environment. +``VENV_ACTIVATE_PATH`` defaults to ``"$HOME/act/bin/activate"``. + +.. code-block:: bash + + VENV_ACTIVATE_PATH="$HOME/act/bin/activate" + +``ROS_SETUP_PATH`` +^^^^^^^^^^^^^^^^^^ + +Set the path to the ROS distribution's setup script. +This value is used when setting up the system-installed ROS environment. +Setting the ``ROS_DISTRO`` variable from before should be sufficient to configure this variable. +``ROS_SETUP_PATH`` defaults to ``"/opt/ros/$ROS_DISTRO/setup.bash"``. + +.. code-block:: bash + + ROS_SETUP_PATH="/opt/ros/$ROS_DISTRO/setup.bash" + +``WORKSPACE_SETUP_PATH`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +Set the path to the Interbotix workspace's setup script. +This value is used when setting up the Interbotix workspace's ROS environment. +``WORKSPACE_SETUP_PATH`` defaults to ``"$HOME/interbotix_ws/install/setup.bash"``. + +.. code-block:: bash + + WORKSPACE_SETUP_PATH="$HOME/interbotix_ws/install/setup.bash" + +``RECORD_EPISODES`` +^^^^^^^^^^^^^^^^^^^ + +Set the path to the ``record_episodes.py`` script. +This value is used when calling the record_episodes script. +``RECORD_EPISODES`` defaults to ``"$HOME/interbotix_ws/src/aloha/scripts/record_episodes.py"``. + +.. code-block:: bash + + RECORD_EPISODES="$HOME/interbotix_ws/src/aloha/scripts/record_episodes.py" + +Usage +----- + +Once configured, the auto_record script is now ready to use. To auto-record a specific amount of episodes, follow the steps below: + +#. Bring up the ALOHA control stack according to your platform + + * Stationary: :ref:`operation/stationary:Running ALOHA Bringup` + * Mobile: :ref:`operation/mobile:Running ALOHA Bringup` + +#. In a new terminal, navigate to the directory storing the auto_record script and run the command below: + + .. code-block:: + + $ auto_record.sh + + .. tip:: + + An example for auto-recording 50 episodes of the dummy Mobile ALOHA task would look like: + + .. code-block:: bash + + $ auto_record.sh aloha_mobile_dummy 50 + + The auto_record script will then call the record_episodes Python script the specified number of times. + + .. note:: + + If episodes of the specified task already exist, episode indices will be automatically calculated as one greater than the number of tasks in the episode save directory. + +Dataset Format +============== + +ALOHA saves its episodes in the `hdf5 format`_ with the following format: + +.. _`hdf5 format`: https://en.wikipedia.org/wiki/Hierarchical_Data_Format#HDF5 + +.. code-block:: + + - images + - cam_high (480, 640, 3) 'uint8' + - cam_low (480, 640, 3) 'uint8' (on Stationary) + - cam_left_wrist (480, 640, 3) 'uint8' + - cam_right_wrist (480, 640, 3) 'uint8' + - qpos (14,) 'float64' + - qvel (14,) 'float64' + + action (14,) 'float64' + base_action (2,) 'float64' (on Mobile) From 06eb6036e36d1ddcbe9bf731dddb9ce58fe9c8cb Mon Sep 17 00:00:00 2001 From: Shantanu Date: Wed, 31 Jul 2024 10:39:55 -0500 Subject: [PATCH 2/8] ACT Training Documentation Update --- docs/operation.rst | 1 + docs/operation/training.rst | 331 +++++++++++++++++++----------------- 2 files changed, 180 insertions(+), 152 deletions(-) diff --git a/docs/operation.rst b/docs/operation.rst index 3017d7c..0d027ac 100644 --- a/docs/operation.rst +++ b/docs/operation.rst @@ -9,3 +9,4 @@ Operation ./operation/stationary.rst ./operation/data_collection.rst ./operation/training.rst + ./operation/hugging_face.rst diff --git a/docs/operation/training.rst b/docs/operation/training.rst index a8349b3..fcc61c3 100644 --- a/docs/operation/training.rst +++ b/docs/operation/training.rst @@ -1,210 +1,237 @@ -=============== -Data Collection -=============== +======================== +Training and Evaluation +======================== -Task Creation -============= - -Task configuration can be found in the ALOHA package's aloha module under ``constants.py`` in the ``TASK_CONFIGS`` dictionary. -A template task (``aloha_template``) is provided containing all possible fields and some placeholder values. -Here, we will focus only on the task name, the dataset directory, the episode length, and the observation cameras. - -.. list-table:: - :align: center - :widths: 25 75 - :header-rows: 1 - :width: 60% - - * - Configuration Field - - Description - * - Task Name - - The task name should accurately describe the task that the ALOHA is performing. - * - Dataset Directory - - The ``dataset_dir`` field sets the directory episodes will saved to. - * - Episode Length - - The ``episode_len`` field sets the length of the episode in number of timesteps. - * - Camera Names - - The ``camera_names`` field takes in a list of strings corresponding to camera names. - These camera names will be used as observation sources during dataset collection. - -Recording Episodes -================== - -To record an episode, follow the steps below: - -#. Bring up the ALOHA control stack according to your platform - - * Stationary: :ref:`operation/stationary:Running ALOHA Bringup` - * Mobile: :ref:`operation/mobile:Running ALOHA Bringup` - -#. Configure the environment and run the episode recording script as follows: - - .. code-block:: bash - - $ source /opt/ros/humble/setup.bash # configure ROS system install environment - $ source ~/interbotix_ws/install/setup.bash # configure ROS workspace environment - $ source //bin/activate # configure ALOHA Python environment - $ cd ~/interbotix_ws/src/aloha/scripts/ - $ python3 record_episodes.py --task_name --episode_idx - - .. note:: - - The ``task_name`` argument should match one of the task names in the ``TASK_CONFIGS``, as configured in the :ref:`operation/data_collection:Task Creation` section. - - .. tip:: - Each platform has a "dummy" task that can be used to test basic data collection and playback. - For the Stationary variant, use the ``aloha_stationary_dummy`` task. - For the Mobile variant, use the ``aloha_mobile_dummy`` task. - An example for the Mobile variant would look like: +Virtual Environment Setup +========================= - .. code-block:: bash +Effective containerization is important when it comes to running machine learning models as there can be conflicting dependencies. You can either use a Virtual Environment or Conda. - $ python3 record_episodes.py --task_name aloha_mobile_dummy --episode_idx 0 +Virtual Environment Installation and Setup +---------------------------------------------- -Episode Playback -================ +#. Install the virtual environment package: -To play back a previously-recorded episode, follow the steps below: - -#. Bring up the ALOHA control stack according to your platform - - * Stationary: :ref:`operation/stationary:Running ALOHA Bringup` - * Mobile: :ref:`operation/mobile:Running ALOHA Bringup` - -#. Configure the environment and run the episode playback script as follows: - - .. code-block:: bash +.. code-block:: bash - $ source /opt/ros/humble/setup.bash # configure ROS system install environment - $ source ~/interbotix_ws/install/setup.bash # configure ROS workspace environment - $ source //bin/activate # configure ALOHA Python environment - $ cd ~/interbotix_ws/src/aloha/scripts/ - $ python3 replay_episodes.py --dataset_dir --episode_idx + sudo apt-get install python3-venv - .. tip:: +#. Create a virtual environment: - An example for replaying the dummy Mobile episode recorded above would look like: +.. code-block:: bash - .. code-block:: bash + python3 -m venv ~/act # Creates a venv "act" in the home directory, can be created anywhere - $ python3 replay_episodes.py --dataset_dir ~/aloha_data/aloha_mobile_dummy/ --episode_idx 0 +#. Activate the virtual environment: -Episode Auto-Recording -====================== +.. code-block:: bash -A helpful bash script, ``auto_record.sh``, is provided to allow users to collect many episodes consecutively without having to interact with the control computer. + source ~/act/bin/activate -Configuration -------------- +Conda Setup +---------------------------------------------- -This script, whose `source`_ can be found on the ALOHA GitHub repository, has a few configuration options that should be verified or set before running. +#. Create a virtual environment: -.. _`source`: https://github.com/Interbotix/aloha/blob/main/scripts/auto_record.sh +.. code-block:: bash -``ROS_DISTRO`` -^^^^^^^^^^^^^^ + conda create -n aloha python=3.8.10 -Set the codename of the ROS distribution used on the control computer. -This value is used to set the path to the ``ROS_SETUP_PATH`` variable used later in the script. -``ROS_DISTRO`` defaults to ``humble``. +#. Activate the virtual environment: .. code-block:: bash - ROS_DISTRO=humble + conda activate aloha -``VENV_ACTIVATE_PATH`` -^^^^^^^^^^^^^^^^^^^^^^ +Install Dependencies +=============================================== -Set the path to the virtual environment's activate file. -This value is used when setting up the Python virtual environment. -``VENV_ACTIVATE_PATH`` defaults to ``"$HOME/act/bin/activate"``. +Install the necessary dependencies inside your containerized environment: .. code-block:: bash - VENV_ACTIVATE_PATH="$HOME/act/bin/activate" - -``ROS_SETUP_PATH`` -^^^^^^^^^^^^^^^^^^ - -Set the path to the ROS distribution's setup script. -This value is used when setting up the system-installed ROS environment. -Setting the ``ROS_DISTRO`` variable from before should be sufficient to configure this variable. -``ROS_SETUP_PATH`` defaults to ``"/opt/ros/$ROS_DISTRO/setup.bash"``. + pip install dm_control==1.0.14 + pip install einops + pip install h5py + pip install ipython + pip install matplotlib + pip install mujoco==2.3.7 + pip install opencv-python + pip install packaging + pip install pexpect + pip install pyquaternion + pip install pyyaml + pip install rospkg + pip install torch + pip install torchvision + +Clone Repository +========================= + +Clone ACT if using Aloha Stationary .. code-block:: bash - ROS_SETUP_PATH="/opt/ros/$ROS_DISTRO/setup.bash" + git clone https://github.com/shantanuparab-tr/act.git act_training_evaluation -``WORKSPACE_SETUP_PATH`` -^^^^^^^^^^^^^^^^^^^^^^^^ -Set the path to the Interbotix workspace's setup script. -This value is used when setting up the Interbotix workspace's ROS environment. -``WORKSPACE_SETUP_PATH`` defaults to ``"$HOME/interbotix_ws/install/setup.bash"``. +Clone ACT++ if using Aloha Mobile .. code-block:: bash - WORKSPACE_SETUP_PATH="$HOME/interbotix_ws/install/setup.bash" + git clone https://github.com/shantanuparab-tr/act_plus_plus.git act_training_evaluation -``RECORD_EPISODES`` -^^^^^^^^^^^^^^^^^^^ -Set the path to the ``record_episodes.py`` script. -This value is used when calling the record_episodes script. -``RECORD_EPISODES`` defaults to ``"$HOME/interbotix_ws/src/aloha/scripts/record_episodes.py"``. +Build and Install ACT Models +=================================== .. code-block:: bash + :emphasize-lines: 4 + + ├── act + │   ├── assets + │   ├── constants.py + │   ├── detr + │   ├── ee_sim_env.py + │   ├── imitate_episodes.py + │   ├── __init__.py + │   ├── policy.py + │   ├── record_sim_episodes.py + │   ├── scripted_policy.py + │   ├── sim_env.py + │   ├── utils.py + │   └── visualize_episodes.py + ├── COLCON_IGNORE + ├── conda_env.yaml + ├── LICENSE + └── README.md + + +Navigate to the ``detr`` directory inside the repository and install the detr module whihc contains the model definitions using the below command: - RECORD_EPISODES="$HOME/interbotix_ws/src/aloha/scripts/record_episodes.py" - -Usage ------ - -Once configured, the auto_record script is now ready to use. To auto-record a specific amount of episodes, follow the steps below: +.. code-block:: bash -#. Bring up the ALOHA control stack according to your platform + cd /path/to/act/detr && pip install -e . - * Stationary: :ref:`operation/stationary:Running ALOHA Bringup` - * Mobile: :ref:`operation/mobile:Running ALOHA Bringup` +Training +============= -#. In a new terminal, navigate to the directory storing the auto_record script and run the command below: +To start the training, follow the steps below: - .. code-block:: +1. **Sanity Check**: - $ auto_record.sh +Ensure you have all the hdf5 episodes located in the correct folder after following the data collection steps :ref:`operation/data_collection:Task Creation`. - .. tip:: +2. **Source ROS Environment**: - An example for auto-recording 50 episodes of the dummy Mobile ALOHA task would look like: + .. code-block:: bash - .. code-block:: bash + source /opt/ros/humble/setup.bash + source interbotix_ws/install/setup.bash - $ auto_record.sh aloha_mobile_dummy 50 +3. **Activate Virtual Environment**: - The auto_record script will then call the record_episodes Python script the specified number of times. + .. code-block:: bash - .. note:: + source act/bin/activate - If episodes of the specified task already exist, episode indices will be automatically calculated as one greater than the number of tasks in the episode save directory. +4. **Start Training**: -Dataset Format -============== + .. code-block:: bash -ALOHA saves its episodes in the `hdf5 format`_ with the following format: + cd repo/act/ + python3 imitate_episodes.py \ + --task_name aloha_stationary_dummy \ + --ckpt_dir \ + --policy_class ACT \ + --kl_weight 10 \ + --chunk_size 100 \ + --hidden_dim 512 \ + --batch_size 8 \ + --dim_feedforward 3200 \ + --num_epochs 2000 \ + --lr 1e-5 \ + --seed 0 -.. _`hdf5 format`: https://en.wikipedia.org/wiki/Hierarchical_Data_Format#HDF5 +.. note:: -.. code-block:: + - ``task_name`` argument should match one of the task names in the ``TASK_CONFIGS``, as configured in the :ref:`operation/data_collection:Task Creation` section. + - ``ckpt_dir``: The relative location where the checkpoints and best policy will be stored. + - ``policy_class``: Determines the choice of policy 'ACT'/'CNNMLP'. + - ``kl_weight``: Controls the balance between exploration and exploitation. + - ``chunk_size``: Determines the length of the action sequence. K=1 is no action chunking and K=episode length is full open loop control. + - ``batch_size``: Low batch size leads to better generalization and high batch size results in slower convergence but faster training time. + - ``num_epochs``: Too many epochs lead to overfitting; too few epochs may not allow the model to learn. + - ``lr``: Higher learning rate can lead to faster convergence but may overshoot the optima, while lower learning rate might lead to slower but stable optimization. - - images - - cam_high (480, 640, 3) 'uint8' - - cam_low (480, 640, 3) 'uint8' (on Stationary) - - cam_left_wrist (480, 640, 3) 'uint8' - - cam_right_wrist (480, 640, 3) 'uint8' - - qpos (14,) 'float64' - - qvel (14,) 'float64' +We recommend the following parameters: - action (14,) 'float64' - base_action (2,) 'float64' (on Mobile) +.. list-table:: + :align: center + :widths: 25 75 + :header-rows: 1 + + * - Parameter + - Value + * - Policy Class + - ACT + * - KL Weight + - 10 + * - Chunk Size + - 100 + * - Batch Size + - 2 + * - Num of Epochs + - 3000 + * - Learning Rate + - 1e-5 + +Evaluation +===================== + +To evaluate a trained model, follow the steps below: + +1. **Bring up the ALOHA control stack** according to your platform: + + - Stationary: :ref:`operation/stationary:Running ALOHA Bringup` + - Mobile: :ref:`operation/mobile:Running ALOHA Bringup` + + +2. **Configure the environment**: + + .. code-block:: bash + + source /opt/ros/humble/setup.bash # Configure ROS system install environment + source ~/interbotix_ws/install/setup.bash # Configure ROS workspace environment + source //bin/activate # Configure ALOHA Python environment + cd ~//act/ + + +3. **Run the evaluation script** + + .. code-block:: bash + :emphasize-lines: 13-14 + + python3 imitate_episodes.py \ + --task_name aloha_stationary_dummy \ + --ckpt_dir \ + --policy_class ACT \ + --kl_weight 10 \ + --chunk_size 100 \ + --hidden_dim 512 \ + --batch_size 8 \ + --dim_feedforward 3200 \ + --num_epochs 2000 \ + --lr 1e-5 \ + --seed 0 \ + --eval \ + --temporal_agg + +.. note:: + + - The ``task_name`` argument should match one of the task names in the ``TASK_CONFIGS``, as configured in the :ref:`operation/data_collection:Task Creation` section. + - The ``ckpt_dir`` argument should match the correct relative directory location of the trained policy. + - The ``eval`` flag will set the script into evaluation mode. + - The ``temporal_agg`` is not required, but helps to smoothen the trajectory of the robots. \ No newline at end of file From ed13fd6e9dd997a1b7f0d7cef629aa17d484fe5b Mon Sep 17 00:00:00 2001 From: Shantanu Date: Wed, 31 Jul 2024 10:40:21 -0500 Subject: [PATCH 3/8] Hugging Face Documentation Update --- docs/operation/hugging_face.rst | 117 ++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 docs/operation/hugging_face.rst diff --git a/docs/operation/hugging_face.rst b/docs/operation/hugging_face.rst new file mode 100644 index 0000000..779c477 --- /dev/null +++ b/docs/operation/hugging_face.rst @@ -0,0 +1,117 @@ +======================== +Hugging Face Guide +======================== + +Uploading and Downloading Datasets on Hugging Face +================================================== + +Creating an Account +------------------- + +If you don't already have an account, sign up for a new account on the `Hugging Face Sign Up `_. + +Creating a New Dataset Repository +--------------------------------- + +1. **Web Interface**: + - Navigate to the `Hugging Face website `_. + - Log in to your account. + - Click on your profile picture in the top-right corner and select "New dataset." + - Follow the on-screen instructions to create a new dataset repository. + +2. **Command Line Interface (CLI)**: + - Ensure you have the ``huggingface_hub`` library installed. + - Use the following Python script to create a new repository: + +.. code-block:: python + + from huggingface_hub import HfApi + api = HfApi() + + api.create_repo(repo_id="username/repository_name", repo_type="dataset") + +For more information on creating repositories, refer to the `Hugging Face Repositories `_. + +Uploading Your Dataset +---------------------- + +You have two primary methods to upload datasets: through the web interface or using the Python API. + +1. **Web Interface** + +i. Navigate to your dataset repository on the Hugging Face website. +ii. Click on the "Files and versions" tab. +iii. Drag and drop your dataset files into the files section. +iv. Click "Commit changes" to save the files in the repository. + +2. **Python API** + +You can use the following Python script to upload your dataset: + +.. code-block:: python + + from huggingface_hub import HfApi + api = HfApi() + + api.upload_folder( + folder_path="path/to/dataset", + repo_id="username/repository_name", + repo_type="dataset", + ) + +**Example**: + +.. code-block:: python + + from huggingface_hub import HfApi + api = HfApi() + + api.upload_folder( + folder_path="~/aloha_data/aloha_stationary_block_pickup", + repo_id="TrossenRoboticsCommunity/aloha_static_datasets", + repo_type="dataset", + ) + +For more information on uploading datasets, refer to the `Hugging Face Uploading `_. + +Downloading Datasets +-------------------- + +You can download datasets either by cloning the repository or using the Hugging Face CLI. + +1. **Cloning the Repository** + +To clone the repository, use the following command: + +.. code-block:: bash + + git clone https://huggingface.co/datasets/username/repository_name + +2. **Using the Hugging Face CLI** + +You can also use the Hugging Face CLI to download datasets with the following Python script: + +.. code-block:: python + + from huggingface_hub import snapshot_download + + # Download the dataset + snapshot_download(repo_id="username/repository_name", + repo_type="dataset", + local_dir="path/to/local/directory", + allow_patterns="*.hdf5") + +.. note:: + + - The dataset episodes are stored in ``.hdf5`` format. Therefore, ensure that you only allow these patterns during download. + +For more information on downloading datasets, refer to the `Hugging Face Datasets `_. + +Additional Information +---------------------- + +- **Repository Management**: Utilize the `Hugging Face Hub documentation `_ for detailed instructions on managing repositories, handling versions, and setting permissions. +- **Dataset Formats**: Hugging Face supports various dataset formats. For this guide, we specifically use the ``.hdf5`` format. +- **Community Support**: If you encounter any issues, refer to the `Hugging Face community forums `_ for additional support. + +By following this guide, you should be able to seamlessly upload and download datasets using the Hugging Face platform. For more detailed guides and examples, refer to the `Hugging Face Documentation `_. From 4b22dae3506375dd6e4663e312d9db9bbc5ddd05 Mon Sep 17 00:00:00 2001 From: Shantanu Date: Wed, 31 Jul 2024 12:36:20 -0500 Subject: [PATCH 4/8] PR Review Resolution --- docs/operation/hugging_face.rst | 102 +++++++++++++----------- docs/operation/training.rst | 134 ++++++++++++++++---------------- 2 files changed, 121 insertions(+), 115 deletions(-) diff --git a/docs/operation/hugging_face.rst b/docs/operation/hugging_face.rst index 779c477..c2ca831 100644 --- a/docs/operation/hugging_face.rst +++ b/docs/operation/hugging_face.rst @@ -1,6 +1,6 @@ -======================== +================== Hugging Face Guide -======================== +================== Uploading and Downloading Datasets on Hugging Face ================================================== @@ -13,22 +13,24 @@ If you don't already have an account, sign up for a new account on the `Hugging Creating a New Dataset Repository --------------------------------- -1. **Web Interface**: - - Navigate to the `Hugging Face website `_. - - Log in to your account. - - Click on your profile picture in the top-right corner and select "New dataset." - - Follow the on-screen instructions to create a new dataset repository. +Web Interface +^^^^^^^^^^^^^ +#. Navigate to the `Hugging Face website `_. +#. Log in to your account. +#. Click on your profile picture in the top-right corner and select "New dataset." +#. Follow the on-screen instructions to create a new dataset repository. -2. **Command Line Interface (CLI)**: - - Ensure you have the ``huggingface_hub`` library installed. - - Use the following Python script to create a new repository: +Command Line Interface (CLI) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + #. Ensure you have the `huggingface_hub `_ library installed. + #. Use the following Python script to create a new repository: -.. code-block:: python + .. code-block:: python - from huggingface_hub import HfApi - api = HfApi() + from huggingface_hub import HfApi + api = HfApi() - api.create_repo(repo_id="username/repository_name", repo_type="dataset") + api.create_repo(repo_id="username/repository_name", repo_type="dataset") For more information on creating repositories, refer to the `Hugging Face Repositories `_. @@ -37,40 +39,42 @@ Uploading Your Dataset You have two primary methods to upload datasets: through the web interface or using the Python API. -1. **Web Interface** +Web Interface +^^^^^^^^^^^^^ -i. Navigate to your dataset repository on the Hugging Face website. -ii. Click on the "Files and versions" tab. -iii. Drag and drop your dataset files into the files section. -iv. Click "Commit changes" to save the files in the repository. +#. Navigate to your dataset repository on the Hugging Face website. +#. Click on the "Files and versions" tab. +#. Drag and drop your dataset files into the files section. +#. Click "Commit changes" to save the files in the repository. -2. **Python API** +Python API +^^^^^^^^^^ You can use the following Python script to upload your dataset: -.. code-block:: python + .. code-block:: python - from huggingface_hub import HfApi - api = HfApi() + from huggingface_hub import HfApi + api = HfApi() - api.upload_folder( - folder_path="path/to/dataset", - repo_id="username/repository_name", - repo_type="dataset", - ) + api.upload_folder( + folder_path="path/to/dataset", + repo_id="username/repository_name", + repo_type="dataset", + ) **Example**: -.. code-block:: python + .. code-block:: python - from huggingface_hub import HfApi - api = HfApi() + from huggingface_hub import HfApi + api = HfApi() - api.upload_folder( - folder_path="~/aloha_data/aloha_stationary_block_pickup", - repo_id="TrossenRoboticsCommunity/aloha_static_datasets", - repo_type="dataset", - ) + api.upload_folder( + folder_path="~/aloha_data/aloha_stationary_block_pickup", + repo_id="TrossenRoboticsCommunity/aloha_static_datasets", + repo_type="dataset", + ) For more information on uploading datasets, refer to the `Hugging Face Uploading `_. @@ -79,27 +83,31 @@ Downloading Datasets You can download datasets either by cloning the repository or using the Hugging Face CLI. -1. **Cloning the Repository** +Cloning the Repository +^^^^^^^^^^^^^^^^^^^^^^ To clone the repository, use the following command: -.. code-block:: bash + .. code-block:: bash - git clone https://huggingface.co/datasets/username/repository_name + $ git clone https://huggingface.co/datasets/username/repository_name -2. **Using the Hugging Face CLI** +Using the Hugging Face CLI +^^^^^^^^^^^^^^^^^^^^^^^^^^ You can also use the Hugging Face CLI to download datasets with the following Python script: -.. code-block:: python + .. code-block:: python - from huggingface_hub import snapshot_download + from huggingface_hub import snapshot_download - # Download the dataset - snapshot_download(repo_id="username/repository_name", - repo_type="dataset", - local_dir="path/to/local/directory", - allow_patterns="*.hdf5") + # Download the dataset + snapshot_download( + repo_id="username/repository_name", + repo_type="dataset", + local_dir="path/to/local/directory", + allow_patterns="*.hdf5" + ) .. note:: diff --git a/docs/operation/training.rst b/docs/operation/training.rst index fcc61c3..550e4a5 100644 --- a/docs/operation/training.rst +++ b/docs/operation/training.rst @@ -1,6 +1,6 @@ -======================== +======================= Training and Evaluation -======================== +======================= @@ -10,82 +10,82 @@ Virtual Environment Setup Effective containerization is important when it comes to running machine learning models as there can be conflicting dependencies. You can either use a Virtual Environment or Conda. Virtual Environment Installation and Setup ----------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Install the virtual environment package: -.. code-block:: bash + .. code-block:: bash - sudo apt-get install python3-venv + $ sudo apt-get install python3-venv #. Create a virtual environment: -.. code-block:: bash + .. code-block:: bash - python3 -m venv ~/act # Creates a venv "act" in the home directory, can be created anywhere + $ python3 -m venv ~/act # Creates a venv "act" in the home directory, can be created anywhere #. Activate the virtual environment: -.. code-block:: bash + .. code-block:: bash - source ~/act/bin/activate + $ source act/bin/activate Conda Setup ----------------------------------------------- +^^^^^^^^^^^ #. Create a virtual environment: -.. code-block:: bash + .. code-block:: bash - conda create -n aloha python=3.8.10 + $ conda create -n aloha python=3.8.10 #. Activate the virtual environment: -.. code-block:: bash + .. code-block:: bash - conda activate aloha + $ conda activate aloha Install Dependencies -=============================================== +^^^^^^^^^^^^^^^^^^^^ Install the necessary dependencies inside your containerized environment: .. code-block:: bash - pip install dm_control==1.0.14 - pip install einops - pip install h5py - pip install ipython - pip install matplotlib - pip install mujoco==2.3.7 - pip install opencv-python - pip install packaging - pip install pexpect - pip install pyquaternion - pip install pyyaml - pip install rospkg - pip install torch - pip install torchvision + $ pip install dm_control==1.0.14 + $ pip install einops + $ pip install h5py + $ pip install ipython + $ pip install matplotlib + $ pip install mujoco==2.3.7 + $ pip install opencv-python + $ pip install packaging + $ pip install pexpect + $ pip install pyquaternion + $ pip install pyyaml + $ pip install rospkg + $ pip install torch + $ pip install torchvision Clone Repository -========================= +================ Clone ACT if using Aloha Stationary .. code-block:: bash - git clone https://github.com/shantanuparab-tr/act.git act_training_evaluation + $ git clone https://github.com/Interbotix/act.git act_training_evaluation Clone ACT++ if using Aloha Mobile .. code-block:: bash - git clone https://github.com/shantanuparab-tr/act_plus_plus.git act_training_evaluation + $ git clone https://github.com/Interbotix/act_plus_plus.git act_training_evaluation Build and Install ACT Models -=================================== +============================ .. code-block:: bash :emphasize-lines: 4 @@ -113,49 +113,49 @@ Navigate to the ``detr`` directory inside the repository and install the detr mo .. code-block:: bash - cd /path/to/act/detr && pip install -e . + $ cd /path/to/act/detr && pip install -e . Training -============= +======== To start the training, follow the steps below: -1. **Sanity Check**: +#. Sanity Check: -Ensure you have all the hdf5 episodes located in the correct folder after following the data collection steps :ref:`operation/data_collection:Task Creation`. + Ensure you have all the hdf5 episodes located in the correct folder after following the data collection steps :ref:`operation/data_collection:Task Creation`. -2. **Source ROS Environment**: +#. Source ROS Environment: .. code-block:: bash - source /opt/ros/humble/setup.bash - source interbotix_ws/install/setup.bash + $ source /opt/ros/humble/setup.bash + $ source interbotix_ws/install/setup.bash -3. **Activate Virtual Environment**: +#. Activate Virtual Environment: .. code-block:: bash - source act/bin/activate + $ source act/bin/activate -4. **Start Training**: +#. Start Training .. code-block:: bash - cd repo/act/ - python3 imitate_episodes.py \ - --task_name aloha_stationary_dummy \ - --ckpt_dir \ - --policy_class ACT \ - --kl_weight 10 \ - --chunk_size 100 \ - --hidden_dim 512 \ - --batch_size 8 \ - --dim_feedforward 3200 \ - --num_epochs 2000 \ - --lr 1e-5 \ - --seed 0 - -.. note:: + $ cd /path/to/act/repository/ + $ python3 imitate_episodes.py \ + --task_name aloha_stationary_dummy \ + --ckpt_dir \ + --policy_class ACT \ + --kl_weight 10 \ + --chunk_size 100 \ + --hidden_dim 512 \ + --batch_size 8 \ + --dim_feedforward 3200 \ + --num_epochs 2000 \ + --lr 1e-5 \ + --seed 0 + +.. tip:: - ``task_name`` argument should match one of the task names in the ``TASK_CONFIGS``, as configured in the :ref:`operation/data_collection:Task Creation` section. - ``ckpt_dir``: The relative location where the checkpoints and best policy will be stored. @@ -189,27 +189,25 @@ We recommend the following parameters: - 1e-5 Evaluation -===================== +========== To evaluate a trained model, follow the steps below: -1. **Bring up the ALOHA control stack** according to your platform: +#. Bring up the ALOHA - Stationary: :ref:`operation/stationary:Running ALOHA Bringup` - Mobile: :ref:`operation/mobile:Running ALOHA Bringup` - -2. **Configure the environment**: +#. Configure the environment .. code-block:: bash - source /opt/ros/humble/setup.bash # Configure ROS system install environment - source ~/interbotix_ws/install/setup.bash # Configure ROS workspace environment - source //bin/activate # Configure ALOHA Python environment - cd ~//act/ - + $ source /opt/ros/humble/setup.bash # Configure ROS system install environment + $ source interbotix_ws/install/setup.bash # Configure ROS workspace environment + $ source //bin/activate # Configure ALOHA Python environment + $ cd ~//act/ -3. **Run the evaluation script** +#. Run the evaluation script .. code-block:: bash :emphasize-lines: 13-14 From c6ee73f76d89533cca436022c30ebbe9822f73ae Mon Sep 17 00:00:00 2001 From: Shantanu Date: Wed, 31 Jul 2024 12:38:13 -0500 Subject: [PATCH 5/8] Indentation Fix --- docs/operation/training.rst | 48 ++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/operation/training.rst b/docs/operation/training.rst index 550e4a5..002a631 100644 --- a/docs/operation/training.rst +++ b/docs/operation/training.rst @@ -143,17 +143,17 @@ To start the training, follow the steps below: $ cd /path/to/act/repository/ $ python3 imitate_episodes.py \ - --task_name aloha_stationary_dummy \ - --ckpt_dir \ - --policy_class ACT \ - --kl_weight 10 \ - --chunk_size 100 \ - --hidden_dim 512 \ - --batch_size 8 \ - --dim_feedforward 3200 \ - --num_epochs 2000 \ - --lr 1e-5 \ - --seed 0 + --task_name aloha_stationary_dummy \ + --ckpt_dir \ + --policy_class ACT \ + --kl_weight 10 \ + --chunk_size 100 \ + --hidden_dim 512 \ + --batch_size 8 \ + --dim_feedforward 3200 \ + --num_epochs 2000 \ + --lr 1e-5 \ + --seed 0 .. tip:: @@ -213,19 +213,19 @@ To evaluate a trained model, follow the steps below: :emphasize-lines: 13-14 python3 imitate_episodes.py \ - --task_name aloha_stationary_dummy \ - --ckpt_dir \ - --policy_class ACT \ - --kl_weight 10 \ - --chunk_size 100 \ - --hidden_dim 512 \ - --batch_size 8 \ - --dim_feedforward 3200 \ - --num_epochs 2000 \ - --lr 1e-5 \ - --seed 0 \ - --eval \ - --temporal_agg + --task_name aloha_stationary_dummy \ + --ckpt_dir \ + --policy_class ACT \ + --kl_weight 10 \ + --chunk_size 100 \ + --hidden_dim 512 \ + --batch_size 8 \ + --dim_feedforward 3200 \ + --num_epochs 2000 \ + --lr 1e-5 \ + --seed 0 \ + --eval \ + --temporal_agg .. note:: From 51bf62d4ec6908337920de4a396282f7fa53861c Mon Sep 17 00:00:00 2001 From: Shantanu Date: Wed, 31 Jul 2024 12:48:12 -0500 Subject: [PATCH 6/8] Aloha --- docs/operation/hugging_face.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/operation/hugging_face.rst b/docs/operation/hugging_face.rst index c2ca831..68d5689 100644 --- a/docs/operation/hugging_face.rst +++ b/docs/operation/hugging_face.rst @@ -119,7 +119,7 @@ Additional Information ---------------------- - **Repository Management**: Utilize the `Hugging Face Hub documentation `_ for detailed instructions on managing repositories, handling versions, and setting permissions. -- **Dataset Formats**: Hugging Face supports various dataset formats. For this guide, we specifically use the ``.hdf5`` format. +- **Dataset Formats**: Hugging Face supports various dataset formats. For this guide, we specifically use the Aloha's native ``.hdf5`` format. - **Community Support**: If you encounter any issues, refer to the `Hugging Face community forums `_ for additional support. By following this guide, you should be able to seamlessly upload and download datasets using the Hugging Face platform. For more detailed guides and examples, refer to the `Hugging Face Documentation `_. From 577d3b799f92e1909704efeb6246aed8e9f41f8f Mon Sep 17 00:00:00 2001 From: Shantanu Date: Wed, 31 Jul 2024 15:35:48 -0500 Subject: [PATCH 7/8] Resolving PR review --- docs/operation/hugging_face.rst | 60 ++++++++++++------------ docs/operation/training.rst | 81 +++++++++++++++++---------------- 2 files changed, 74 insertions(+), 67 deletions(-) diff --git a/docs/operation/hugging_face.rst b/docs/operation/hugging_face.rst index 68d5689..1f444ec 100644 --- a/docs/operation/hugging_face.rst +++ b/docs/operation/hugging_face.rst @@ -15,6 +15,7 @@ Creating a New Dataset Repository Web Interface ^^^^^^^^^^^^^ + #. Navigate to the `Hugging Face website `_. #. Log in to your account. #. Click on your profile picture in the top-right corner and select "New dataset." @@ -22,8 +23,9 @@ Web Interface Command Line Interface (CLI) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - #. Ensure you have the `huggingface_hub `_ library installed. - #. Use the following Python script to create a new repository: + +#. Ensure you have the `huggingface_hub `_ library installed. +#. Use the following Python script to create a new repository: .. code-block:: python @@ -52,29 +54,29 @@ Python API You can use the following Python script to upload your dataset: - .. code-block:: python +.. code-block:: python - from huggingface_hub import HfApi - api = HfApi() + from huggingface_hub import HfApi + api = HfApi() - api.upload_folder( - folder_path="path/to/dataset", - repo_id="username/repository_name", - repo_type="dataset", - ) + api.upload_folder( + folder_path="path/to/dataset", + repo_id="username/repository_name", + repo_type="dataset", + ) **Example**: - .. code-block:: python +.. code-block:: python - from huggingface_hub import HfApi - api = HfApi() + from huggingface_hub import HfApi + api = HfApi() - api.upload_folder( - folder_path="~/aloha_data/aloha_stationary_block_pickup", - repo_id="TrossenRoboticsCommunity/aloha_static_datasets", - repo_type="dataset", - ) + api.upload_folder( + folder_path="~/aloha_data/aloha_stationary_block_pickup", + repo_id="TrossenRoboticsCommunity/aloha_static_datasets", + repo_type="dataset", + ) For more information on uploading datasets, refer to the `Hugging Face Uploading `_. @@ -88,26 +90,26 @@ Cloning the Repository To clone the repository, use the following command: - .. code-block:: bash +.. code-block:: bash - $ git clone https://huggingface.co/datasets/username/repository_name + $ git clone https://huggingface.co/datasets/username/repository_name Using the Hugging Face CLI ^^^^^^^^^^^^^^^^^^^^^^^^^^ You can also use the Hugging Face CLI to download datasets with the following Python script: - .. code-block:: python + .. code-block:: python - from huggingface_hub import snapshot_download + from huggingface_hub import snapshot_download - # Download the dataset - snapshot_download( - repo_id="username/repository_name", - repo_type="dataset", - local_dir="path/to/local/directory", - allow_patterns="*.hdf5" - ) + # Download the dataset + snapshot_download( + repo_id="username/repository_name", + repo_type="dataset", + local_dir="path/to/local/directory", + allow_patterns="*.hdf5" + ) .. note:: diff --git a/docs/operation/training.rst b/docs/operation/training.rst index 002a631..ae28279 100644 --- a/docs/operation/training.rst +++ b/docs/operation/training.rst @@ -7,7 +7,8 @@ Training and Evaluation Virtual Environment Setup ========================= -Effective containerization is important when it comes to running machine learning models as there can be conflicting dependencies. You can either use a Virtual Environment or Conda. +Effective containerization is important when it comes to running machine learning models as there can be conflicting dependencies. +You can either use a Virtual Environment or Conda. Virtual Environment Installation and Setup ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -52,20 +53,20 @@ Install the necessary dependencies inside your containerized environment: .. code-block:: bash - $ pip install dm_control==1.0.14 - $ pip install einops - $ pip install h5py - $ pip install ipython - $ pip install matplotlib - $ pip install mujoco==2.3.7 - $ pip install opencv-python - $ pip install packaging - $ pip install pexpect - $ pip install pyquaternion - $ pip install pyyaml - $ pip install rospkg - $ pip install torch - $ pip install torchvision + $ pip install dm_control==1.0.14 + $ pip install einops + $ pip install h5py + $ pip install ipython + $ pip install matplotlib + $ pip install mujoco==2.3.7 + $ pip install opencv-python + $ pip install packaging + $ pip install pexpect + $ pip install pyquaternion + $ pip install pyyaml + $ pip install rospkg + $ pip install torch + $ pip install torchvision Clone Repository ================ @@ -74,6 +75,7 @@ Clone ACT if using Aloha Stationary .. code-block:: bash + $ cd ~ $ git clone https://github.com/Interbotix/act.git act_training_evaluation @@ -81,9 +83,9 @@ Clone ACT++ if using Aloha Mobile .. code-block:: bash + $ cd ~ $ git clone https://github.com/Interbotix/act_plus_plus.git act_training_evaluation - Build and Install ACT Models ============================ @@ -155,7 +157,7 @@ To start the training, follow the steps below: --lr 1e-5 \ --seed 0 -.. tip:: +.. note:: - ``task_name`` argument should match one of the task names in the ``TASK_CONFIGS``, as configured in the :ref:`operation/data_collection:Task Creation` section. - ``ckpt_dir``: The relative location where the checkpoints and best policy will be stored. @@ -166,27 +168,30 @@ To start the training, follow the steps below: - ``num_epochs``: Too many epochs lead to overfitting; too few epochs may not allow the model to learn. - ``lr``: Higher learning rate can lead to faster convergence but may overshoot the optima, while lower learning rate might lead to slower but stable optimization. -We recommend the following parameters: - -.. list-table:: - :align: center - :widths: 25 75 - :header-rows: 1 - - * - Parameter - - Value - * - Policy Class - - ACT - * - KL Weight - - 10 - * - Chunk Size - - 100 - * - Batch Size - - 2 - * - Num of Epochs - - 3000 - * - Learning Rate - - 1e-5 + +.. tip:: + + We recommend the following parameters: + + .. list-table:: + :align: center + :widths: 25 75 + :header-rows: 1 + + * - Parameter + - Value + * - Policy Class + - ACT + * - KL Weight + - 10 + * - Chunk Size + - 100 + * - Batch Size + - 2 + * - Num of Epochs + - 3000 + * - Learning Rate + - 1e-5 Evaluation ========== From ac9e1d5496c4b8146aff4598572daf579f362b50 Mon Sep 17 00:00:00 2001 From: lukeschmitt-tr <85308904+lukeschmitt-tr@users.noreply.github.com> Date: Wed, 31 Jul 2024 15:56:30 -0500 Subject: [PATCH 8/8] Apply suggestions from code review --- docs/operation/training.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/operation/training.rst b/docs/operation/training.rst index ae28279..7e00245 100644 --- a/docs/operation/training.rst +++ b/docs/operation/training.rst @@ -2,8 +2,6 @@ Training and Evaluation ======================= - - Virtual Environment Setup ========================= @@ -78,7 +76,6 @@ Clone ACT if using Aloha Stationary $ cd ~ $ git clone https://github.com/Interbotix/act.git act_training_evaluation - Clone ACT++ if using Aloha Mobile .. code-block:: bash