Installation instructions¶

The recommended way to use AgarCL is within a Docker container running a Linux OS. This ensures there are no conflicts with other installed packages or platforms. This installation script will allow you to interact with AgarCL in a headless mode.

Setting up the container¶

Follow these steps to set up the container:

Download the Dockerfile
- Download the Dockerfile.txt.
- You can jump to step 4 for instructions to use a pre-built image that we share.
Navigate to the Directory Containing the Dockerfile
- Open your terminal and navigate to the folder where the Dockerfile.txt is located:
```
cd /path/to/Dockerfile/directory
```
Build the Docker Image
- Build the Docker image by specifying the custom Dockerfile using the -f flag:
```
docker build -f Dockerfile.txt -t agarclimage .
```
- Skip to step 5, now that your image is built.
Directly use the pre-built image
- ```
docker pull agarcl/agarclimage
```
Run the Docker Container
- Once the image has been built, run the container:
```
docker run --gpus all -it --name agarclcontainer agarclimage
```
- This command will start the container with the name agarclcontainer. The --gpus all flag tells Docker to use all available GPUs on your host system for the container.

Installing the AgarCL Platform¶

Now, let’s install the platform on your system (agarclcontainer container):

Clone the AgarCL Repository
- Clone the repository with the --recursive flag to ensure all submodules are included:
```
git clone --recursive git@github.com:AgarCL/AgarCL.git
```
Install the Platform
- Change into the AgarCL directory:
```
cd AgarCL
```
- Run the installation command to set up the platform:
```
python setup.py install --user
```
- This will install the platform in your local user environment.

Done!¶

Installing the AgarCL Platform and benchmarking tools¶

Clone the AgarCL-benchmark Repository
- Clone the repository:
```
git clone git@github.com/AgarCL/AgarCL-benchmark.git
```
Navigate to the AgarCL-Benchmark Directory
- Change into the AgarCL-benchmark directory:
```
cd AgarCL-benchmark
```
Clone the AgarCLgit Repository
- Clone the AgarCL repository with the --recursive flag to ensure all submodules are included:
```
git clone --recursive git@github.com:AgarCL/AgarCL.git
```
Navigate to the AgarCL Directory
- Change into the AgarCL directory:
```
cd AgarCL
```
Install the Platform
- Run the installation command to set up the platform:
```
python setup.py install --user
```

Done!¶

macOS and Linux Installation Guide¶

Installation notes:¶

Ensure the project is compiled with clang++, not g++
A graphical user interface (GUI) is required to run self-play mode or enable real-time rendering. However, a GUI is not necessary for training agents or recording and saving videos of the environment’s execution.

macOS Installation Guide¶

💡 Before starting:

Follow the instructions here and make sure you have homebrew correctly installed and updated.

Make sure Command Line Tools are installed properly, follow the documentation.

Note: The installer will automatically install CMake 3.22 (a compatible version for this project)

Then follow these steps to set up the AgarCL environment on macOS:

Clone the repository:

git clone --recursive git@github.com:AgarCL/AgarCL.git

Change into the project directory:
```
cd AgarCL
```
Create a Python virtual environment:
```
python -m venv agarclenv
```
Activate the virtual environment:
```
source agarclenv/bin/activate
```
Run the installer script:
```
./install.sh
```
Install Python dependencies:
```
pip install -r requirements.txt
```
Build & install the Python package:
```
python setup.py install
```

Done!¶

Linux Installation Guide¶

Clone the repository:

git clone --recursive git@github.com:AgarCL/AgarCL.git

Change into the project directory:
```
cd AgarCL
```
Create a Python virtual environment:
```
python -m venv agarclenv
```
Activate the virtual environment:
```
source agarclenv/bin/activate
```
Make the install script executable:
```
chmod +x install.sh
```
Run the installer script (may require sudo):
```
sudo ./install.sh
```
Install Python dependencies:
```
pip install -r requirements.txt
```
Build and install the Python package:
```
python setup.py install
```