Installation

The library can be run at Linux, Windows, MacOS, and EulerOS, etc. It is easy to install XuanCe.

Before installing XuanCe, it is recommended to set up a Python environment using Anaconda.

Once ready, open a terminal and follow these steps to install XuanCe. You can choose between two installation methods: from PyPI or GitHub repository.

Note

XuanCe can be installed on MacOS and be compatible with both Intel and Apple’s M CPUs.

Install XuanCe

Step 1: Create and activate a new conda environment (python>=3.8 is suggested).

conda create -n xuance_env python=3.8 && conda activate xuance_env

Step 2: Install xuance.

pip install xuance

Alternatively, you can also install xuance from its GitHub repository.

git clone https://github.com/agi-brain/xuance.git
cd xuance
pip install -e .

Attention

Some extra packages should be installed manually for further usage. See Install external dependencies

Error

During the installation of XuanCe, you might encount the following error:

Error: Failed to building wheel for mpi4py
Failed to build mpi4py
ERROR: Could not build wheels for mpi4py, which is required to install pyproject.toml-based projects

Solution 1: You can solve that issue by install mpi4py manually via

conda install mpi4py

Solution 2: If that doesn’t work, you can type and install gcc_linux-64 via:

conda install gcc_linux-64

And then, retype the installation command for mpi4py via pip:

pip install mpi4py

Note

This issue only affects XuanCe versions earlier than v1.4.0. Starting from v1.4.0, mpi4py is no longer a required dependency of XuanCe.

If you are using an older version of XuanCe and encounter this error, you can resolve it using the methods described above.

Tip

If your IP address is in Chinese mainland, you can install it with a mirror image to speed up the installation, for example, you can choose one of the following commands to finish installation.

pip install xuance -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install xuance -i https://pypi.mirrors.ustc.edu.cn/simple
pip install xuance -i http://mirrors.aliyun.com/pypi/simple/
pip install xuance -i http://pypi.douban.com/simple/

Test the installation

After installing XuanCe, you can enter the Python runtime environment by typing “python” in the terminal. Then, test the installation of xuance by typing:

import xuance

Error

(For XuanCe versions earlier than v1.4.0)

If you are using Windows OS to import xuance, you might get an error likes this:

...
from mpi4py import MPI
ImportError: DLL load failed: The specified module could not be found.

You can address the issue by the following steps:

Step 1: Download Microsoft MPI v10.0 from Official Microsoft Download Center.

Step 2: Remember to choose both “msmpisetup.exe” and “msmpisdk.msi” options, then click “Download” button and install the “.exe” file.

Step 3: Reinstall mpi4py:

pip uninstall mpi4py
pip install mpi4py

If no errors or warnings appear, XuanCe has been successfully installed. You can move on to the next step and begin using it. (Move to next page)


Install external dependencies

Some dependencies are not included in XuanCe’s installation process. You can install the external dependencies listed below as needed.

Box2D

Box2D environment is built using box2d for physics control. It contains three different tasks: Bipedal Walker, Car Racing, Lunar Lander. If you want to try these tasks, you can install it via commands below.

pip install swig==4.3.0
pip install gymnasium[box2d]==0.28.1

MuJoCo

MuJoCo environment is a physics engine for facilitating research and development in robotics, biomechanics, graphics and animation, and other areas where fast and accurate simulation is needed.

Step 1: Install MuJoCo

  • Download the MuJoCo version 2.1 binaries for Linux or OSX.

  • Extract the downloaded mujoco210 directory into ~/.mujoco/mujoco210.

Step 2: Install mujoco-py

pip install gymnasium[mujoco]

Atari

Atari environment is simulated via the Arcade Learning Environment (ALE), which contains 62 different tasks.

pip install gymnasium[accept-rom-license]==0.28.1
pip install gymnasium[atari]==0.28.1
pip install ale-py==0.8.1

MiniGrid

MiniGrid environment is a lightweight, grid-based environment designed for research in DRL. It is highly customizable, supporting a variety of tasks and challenges for training agents with partial observability, sparse rewards, and symbolic inputs.

pip install minigrid

MetaDrive

MetaDrive is an autonomous driving simulator that supports generating infinite scenes with various road maps and traffic settings for research of generalizable RL.

pip install metadrive

StarCraft2

The StarCraft multi-agent challenge (SMAC) is WhiRL’s environment for research of cooperative MARL algorithms. SMAC uses StarCraft II, a real-time strategy game developed by Blizzard Entertainment, as its underlying environment.

Note

Before installing the smac package, make sure your Python version is 3.8 or lower; otherwise, you may encounter errors when rendering the environment.

Step 1: Install the smac python package

You can install the SMAC package directly from the GitHub:

pip install git+https://github.com/oxwhirl/smac.git

Step 2: Install StarCraft II

Please use the Blizzard’s repository to download the Linux version of StarCraft II.

Note

You would need to set the SC2PATH environment variable with the correct location of the game. By default, the game is expected to be in ~/StarCraftII/ directory. This can be changed by setting the environment variable SC2PATH.

Step 3: SMAC Maps

Once you have installed smac and StarCraft II, you need to download the SMAC Maps, and extract it to the $SC2PATH/Maps$ directory. If you installed smac via git, simply copy the SMAC_Maps directory from smac/env/starcraft2/maps/ into $SC2PATH/Maps directory.

Google Research Football

Google Research Football Environment (GRF) is an MARL environment developed by the Google Brain team. It is specifically designed for RL research, particularly for MARL scenarios.

Step 1: Install required packages

sudo apt-get install git cmake build-essential libgl1-mesa-dev libsdl2-dev \
libsdl2-image-dev libsdl2-ttf-dev libsdl2-gfx-dev libboost-all-dev \
libdirectfb-dev libst-dev mesa-utils xvfb x11vnc python3-pip

python3 -m pip install --upgrade pip setuptools psutil wheel

Step 2: Install gfootball

python3 -m pip install gfootball

Attention

All python packages including gfootball environment should be installed in a same conda environment. See https://xuance.org/latest/documents/usage/installation.html#install-xuance.

Robotic Warehouse

Robotic Warehouse is an MARL environment often used to simulate warehouse automation scenarios. It serves as a testbed for studying cooperative, competitive, and mixed interaction among multiple agents, such as robots. The environment is designed to model tasks commonly found in real-world warehouses, such as navigation, item retrieval, obstacle avoidance, and task allocation.

pip install rware

gym-pybullet-drones

Tip

Before preparing the software packages for this simulator, it is recommended to create a new conda environment with Python 3.10.

Open terminal and type the following commands, then a new conda environment for xuance with drones could be built:

conda create -n xuance_drones python=3.10
conda activate xuance_drones
pip install xuance  # refer to the installation of XuanCe.

git clone https://github.com/utiasDSL/gym-pybullet-drones.git
cd gym-pybullet-drones/
pip install --upgrade pip
pip install -e .  # if needed, `sudo apt install build-essential` to install `gcc` and build `pybullet`

During the installation of gym-pybullet-drones, you might encounter the errors like:

Error

gym-pybullet-drones 2.0.0 requires numpy<2.0,>1.24, but you have numpy 1.22.4 which is incompatible.
gym-pybullet-drones 2.0.0 requires scipy<2.0,>1.10, but you have scipy 1.7.3 which is incompatible.

Solution: Upgrade the above incompatible packages.

pip install numpy==1.24.0
pip install scipy==1.12.0

DCG algorithm dependency (torch-scatter)

The DCG algorithm in the XuanCe project relies on the torch-scatter library. In most cases, you can install it directly using the following command:

pip install torch-scatter

However, on certain systems (e.g., specific operating systems or hardware environments), this command may result in installation errors. To ensure compatibility, follow the steps below to correctly install torch-scatter:

1. Check Your PyTorch and CUDA Versions

Use the following command to check the installed version of PyTorch and CUDA in your environment:

python -c "import torch; print(torch.__version__, torch.version.cuda)"

Take note of the PyTorch version (e.g., 2.0.1) and the CUDA version (e.g., 11.8) as they will be needed to select the appropriate version of torch-scatter.

2. Refer to the Official torch-scatter Installation Guide

Visit the official torch-scatter installation page (internet connection required). Find the installation command that matches your PyTorch and CUDA versions. For example:

  • If your PyTorch version is 2.0.1 and CUDA version is 11.8, run:

pip install torch-scatter -f https://data.pyg.org/whl/torch-2.0.1+cu118.html

  • If you are using the CPU-only version of PyTorch, choose the +cpu installation link, such as:

pip install torch-scatter -f https://data.pyg.org/whl/torch-2.0.1+cpu.html

3. Troubleshooting Compatibility Issues

If you encounter issues during installation, ensure the following: - PyTorch is correctly installed and the version matches the selected torch-scatter wheel. - Your Python and pip versions are up to date. You can update pip using:

python -m pip install --upgrade pip

4. Verify Installation

After installation, verify that torch-scatter is installed successfully by running:

python -c "import torch_scatter; print('torch-scatter installed successfully')"