Metadata-Version: 2.4
Name: rlinf-libero
Version: 0.1.0
Summary: LIBERO: Benchmark and simulation environments for lifelong robot learning (RLinf distribution)
Author: Bo Liu, Yifeng Zhu, Chongkai Gao, Yihao Feng, Qiang Liu, Yuke Zhu, Peter Stone
Maintainer: RLinf Team
License: MIT
Project-URL: Homepage, https://github.com/RLinf/LIBERO
Project-URL: Issues, https://github.com/RLinf/LIBERO/issues
Keywords: robotics,reinforcement-learning,simulation,benchmark,libero,rlinf
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: robosuite<1.5.0,>=1.4.0
Requires-Dist: bddl
Requires-Dist: mujoco<3.9.0,>=3.0.0
Requires-Dist: gym<0.27,>=0.25
Requires-Dist: numpy<2,>=1.22
Requires-Dist: imageio
Requires-Dist: opencv-python
Requires-Dist: matplotlib>=3.5.3
Requires-Dist: termcolor
Requires-Dist: tqdm
Requires-Dist: easydict
Requires-Dist: cloudpickle>=2.0.0
Requires-Dist: PyYAML
Requires-Dist: filelock
Requires-Dist: huggingface-hub
Provides-Extra: train
Requires-Dist: hydra-core<1.4,>=1.2; extra == "train"
Requires-Dist: robomimic==0.2.0; extra == "train"
Requires-Dist: transformers; extra == "train"
Requires-Dist: torchvision; extra == "train"
Requires-Dist: wandb; extra == "train"
Requires-Dist: thop; extra == "train"
Requires-Dist: einops; extra == "train"
Requires-Dist: omegaconf; extra == "train"
Dynamic: license-file

<div align="center">
<img src="https://github.com/Lifelong-Robot-Learning/LIBERO/blob/master/images/libero_logo.png" width="360">


<p align="center">
<a href="https://github.com/Lifelong-Robot-Learning/LIBERO/actions">
<img alt="Tests Passing" src="https://github.com/anuraghazra/github-readme-stats/workflows/Test/badge.svg" />
</a>
<a href="https://github.com/Lifelong-Robot-Learning/LIBERO/graphs/contributors">
<img alt="GitHub Contributors" src="https://img.shields.io/github/contributors/Lifelong-Robot-Learning/LIBERO" />
</a>
<a href="https://github.com/Lifelong-Robot-Learning/LIBERO/issues">
<img alt="Issues" src="https://img.shields.io/github/issues/Lifelong-Robot-Learning/LIBERO?color=0088ff" />

## **Benchmarking Knowledge Transfer for Lifelong Robot Learning**

Bo Liu, Yifeng Zhu, Chongkai Gao, Yihao Feng, Qiang Liu, Yuke Zhu, Peter Stone

[[Website]](https://libero-project.github.io)
[[Paper]](https://arxiv.org/pdf/2306.03310.pdf)
[[Docs]](https://lifelong-robot-learning.github.io/LIBERO/)
______________________________________________________________________
![pull_figure](https://github.com/Lifelong-Robot-Learning/LIBERO/blob/master/images//fig1.png)
</div>

**LIBERO** is designed for studying knowledge transfer in multitask and lifelong robot learning problems. Successfully resolving these problems require both declarative knowledge about objects/spatial relationships and procedural knowledge about motion/behaviors. **LIBERO** provides:
- a procedural generation pipeline that could in principle generate an infinite number of manipulation tasks.
- 130 tasks grouped into four task suites: **LIBERO-Spatial**, **LIBERO-Object**, **LIBERO-Goal**, and **LIBERO-100**. The first three task suites have controlled distribution shifts, meaning that they require the transfer of a specific type of knowledge. In contrast, **LIBERO-100** consists of 100 manipulation tasks that require the transfer of entangled knowledge. **LIBERO-100** is further splitted into **LIBERO-90** for pretraining a policy and **LIBERO-10** for testing the agent's downstream lifelong learning performance.
- five research topics.
- three visuomotor policy network architectures.
- three lifelong learning algorithms with the sequential finetuning and multitask learning baselines.

---


# Contents

- [Installation](#Installation)
- [Datasets](#Dataset)
- [Getting Started](#Getting-Started)
  - [Task](#Task)
  - [Training](#Training)
  - [Evaluation](#Evaluation)
- [Citation](#Citation)
- [License](#License)


# Installation

### Option A — install from PyPI (`rlinf-libero`)

```
pip install rlinf-libero
```

The PyPI wheel ships the code plus the small `bddl_files` / `init_files` data,
but **not** the ~405MB of mesh/texture assets (they exceed PyPI's 100MB limit).
After installing, download the assets once:

```
libero-download-assets
```

This fetches the assets from the Hugging Face Hub into the installed package's
`libero/libero/assets` directory. To point at a different source repo, pass
`--repo-id <org>/<repo>` or set the `LIBERO_ASSETS_REPO` environment variable.

### Option B — install from source (editable)

A git checkout already contains the assets, so no separate download is needed
(this is the flow RLinf uses):

```
conda create -n libero python=3.8.13
conda activate libero
git clone https://github.com/RLinf/LIBERO.git
cd LIBERO
pip install -e .
```

Add the lifelong-learning training stack (needed only for `libero.lifelong.*`)
with the `train` extra:

```
pip install -e ".[train]"
```

> **Note on PyTorch.** `torch` is left unpinned so it defers to whatever build
> you already have installed (e.g. a CUDA build from the PyTorch index). Install
> the torch/torchvision build matching your CUDA version before or after
> installing LIBERO if you need GPU support.

# Datasets
We provide high-quality human teleoperation demonstrations for the four task suites in **LIBERO**. To download the demonstration dataset, run:
```python
python benchmark_scripts/download_libero_datasets.py
```
By default, the dataset will be stored under the ```LIBERO``` folder and all four datasets will be downloaded. To download a specific dataset, use
```python
python benchmark_scripts/download_libero_datasets.py --datasets DATASET
```
where ```DATASET``` is chosen from `[libero_spatial, libero_object, libero_100, libero_goal`.

**NEW!!!**

Alternatively, you can download the dataset from HuggingFace by using:
```python
python benchmark_scripts/download_libero_datasets.py --use-huggingface
```

This option can also be combined with the specific dataset selection:
```python
python benchmark_scripts/download_libero_datasets.py --datasets DATASET --use-huggingface
```

The datasets hosted on HuggingFace are available at [here](https://huggingface.co/datasets/yifengzhu-hf/LIBERO-datasets).

# Assets

The simulation assets (meshes, textures, scenes; ~405MB) live under
`libero/libero/assets`. They are included in a git checkout but excluded from the
PyPI wheel. To download them into an installed package:

```
libero-download-assets                 # into the package assets dir
libero-download-assets --repo-id ORG/REPO --force
```

If the assets already exist somewhere on disk (a shared volume, another
checkout), skip the download and symlink the package at them — either
explicitly or via the `LIBERO_ASSET_PATH` environment variable:

```
libero-download-assets --link /path/to/existing/assets
# or
export LIBERO_ASSET_PATH=/path/to/existing/assets
libero-download-assets
```

or, from a source tree:

```
python benchmark_scripts/download_libero_assets.py
```

**For maintainers publishing `rlinf-libero`:** the assets must be hosted on a
Hugging Face repo (default `RLinf/LIBERO-assets`). Create it once and upload the
tree from a checkout that has the assets:

```
huggingface-cli repo create RLinf/LIBERO-assets --repo-type dataset
huggingface-cli upload RLinf/LIBERO-assets libero/libero/assets . --repo-type dataset
```


# Getting Started

For a detailed walk-through, please either refer to the documentation or the notebook examples provided under the `notebooks` folder. In the following, we provide example scripts for retrieving a task, training and evaluation.

## Task

The following is a minimal example of retrieving a specific task from a specific task suite.
```python
from libero.libero import benchmark
from libero.libero.envs import OffScreenRenderEnv


benchmark_dict = benchmark.get_benchmark_dict()
task_suite_name = "libero_10" # can also choose libero_spatial, libero_object, etc.
task_suite = benchmark_dict[task_suite_name]()

# retrieve a specific task
task_id = 0
task = task_suite.get_task(task_id)
task_name = task.name
task_description = task.language
task_bddl_file = os.path.join(get_libero_path("bddl_files"), task.problem_folder, task.bddl_file)
print(f"[info] retrieving task {task_id} from suite {task_suite_name}, the " + \
      f"language instruction is {task_description}, and the bddl file is {task_bddl_file}")

# step over the environment
env_args = {
    "bddl_file_name": task_bddl_file,
    "camera_heights": 128,
    "camera_widths": 128
}
env = OffScreenRenderEnv(**env_args)
env.seed(0)
env.reset()
init_states = task_suite.get_task_init_states(task_id) # for benchmarking purpose, we fix the a set of initial states
init_state_id = 0
env.set_init_state(init_states[init_state_id])

dummy_action = [0.] * 7
for step in range(10):
    obs, reward, done, info = env.step(dummy_action)
env.close()
```
Currently, we only support sparse reward function (i.e., the agent receives `+1` when the task is finished). As sparse-reward RL is extremely hard to learn, currently we mainly focus on lifelong imitation learning.

## Training
To start a lifelong learning experiment, please choose:
- `BENCHMARK` from `[LIBERO_SPATIAL, LIBERO_OBJECT, LIBERO_GOAL, LIBERO_90, LIBERO_10]`
- `POLICY` from `[bc_rnn_policy, bc_transformer_policy, bc_vilt_policy]`
- `ALGO` from `[base, er, ewc, packnet, multitask]`

then run the following:

```shell
export CUDA_VISIBLE_DEVICES=GPU_ID && \
export MUJOCO_EGL_DEVICE_ID=GPU_ID && \
python libero/lifelong/main.py seed=SEED \
                               benchmark_name=BENCHMARK \
                               policy=POLICY \
                               lifelong=ALGO
```
Please see the documentation for the details of reproducing the study results.

## Evaluation

By default the policies will be evaluated on the fly during training. If you have limited computing resource of GPUs, we offer an evaluation script for you to evaluate models separately.

```shell
python libero/lifelong/evaluate.py --benchmark BENCHMARK_NAME \
                                   --task_id TASK_ID \ 
                                   --algo ALGO_NAME \
                                   --policy POLICY_NAME \
                                   --seed SEED \
                                   --ep EPOCH \
                                   --load_task LOAD_TASK \
                                   --device_id CUDA_ID
```

# Citation
If you find **LIBERO** to be useful in your own research, please consider citing our paper:

```bibtex
@article{liu2023libero,
  title={LIBERO: Benchmarking Knowledge Transfer for Lifelong Robot Learning},
  author={Liu, Bo and Zhu, Yifeng and Gao, Chongkai and Feng, Yihao and Liu, Qiang and Zhu, Yuke and Stone, Peter},
  journal={arXiv preprint arXiv:2306.03310},
  year={2023}
}
```

# License
| Component        | License                                                                                                                             |
|------------------|-------------------------------------------------------------------------------------------------------------------------------------|
| Codebase         | [MIT License](LICENSE)                                                                                                                      |
| Datasets         | [Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/legalcode)                 |
