Installation

Base Requirements

Depending on your installation method, other requirements may be necessary, but these are prerequisites that apply to all installation methods.

  • 64-bit Linux or Windows Operating System

While we don’t have known minimal requirements, we recommend having:

  • a dedicated GPU

  • 8 GB of RAM or more

  • Quad-core Intel or AMD CPU, 2.5 GHz or faster

Overview

Cloning BiguaSim

For all installation methods the first step is to clone the repository.

To get the most recent stable release of the BiguaSim library, download or clone our repo at: https://github.com/hydrone-furg/biguasim.git. We suggest cloning it with lowercase naming, as our example code uses, like so:

git clone https://github.com/hydrone-furg/biguasim.git biguasim

Installation Options

Depending on your use case, different installation methods may apply. Please refer to the following list and determine the instructions that are most appropriate for your purposes.

BiguaSim is installed in two parts:

  1. The Python client library (biguasim), which is installed first.

  2. The world packages (binaries), which are downloaded by the Python package after installation.

The Python portion is lightweight, but the world packages can be several gigabytes in size.

Standard Packaged Installation

Additional Requirements

  • Python >= 3.11

  • pip3

Python Library

To ensure all dependencies are managed correctly and do not interfere with your system’s Python, you must create and activate a virtual environment before installing. We recommend using Conda.

Create and activate the environment:

conda create -n biguasim_env python=3.11
conda activate biguasim_env

Install the package in editable mode:

cd biguasim
pip install -e .

Worlds Packages

Note

The SkyDive package is the only package currently available. Users can create custom worlds and packages if desired.

To install the most recent version of the SkyDive worlds package, open a Python shell by typing the following and hit enter:

python

Install the package by running the following Python commands:

import biguasim
biguasim.install("SkyDive")

To do these steps in a single console command, use:

python -c "import biguasim; biguasim.install('SkyDive')"

Installation for Development with Unreal Editor

If you desire to customize the simulation such as developing custom worlds, agents, or sensors, you will need to be able to modify C++ engine code that implements the simulation using Unreal Engine. This can be done in multiple ways:

  • Standalone Live Editing using Unreal Editor Tools - Unreal provides tools that enable you to edit your own worlds and modify C++ engine code and then build and test your worlds in real-time.

  • Packaged Custom Worlds - After developing BiguaSim using these tools, you can then package your own worlds for later use.

For more detailed instructions on installation for development, see Developing BiguaSim. official Biiguasim-engine documentation

Installation with Docker

BiguaSim Docker Containers

The docker directory contains resources to build and run Docker containers for the BiguaSim project, which integrates Unreal Engine 5 (UE5) and the BiguaSim client. The setup supports GPU-accelerated simulation and X11 display forwarding.

Requirements

Before using the containers, ensure the following are installed and configured on your host system:

Warning

Running these containers on a Windows host machine may cause problems with GPU access. The instructions provided below are intended for a Linux host machine.

  • CUDA and NVIDIA Drivers

    • Install CUDA and a compatible NVIDIA driver. CUDA version and NVIDIA driver version are dependent on system requirements.

    • See the official NVIDIA documentation for installation instructions.

  • NVIDIA Container Toolkit

    • Required for GPU passthrough to Docker containers.

    • Follow the official installation guide to set up the toolkit and configure Docker.

  • Docker

Overview

The provided Docker containers enable both development and runtime workflows for BiguaSim. The Python/client development container is designed for interactive development and compilation of BiguaSim, limited to changes of Python source code, whereas the runtime container is intended for executing pre-built BiguaSim applications in a minimal environment.

For advanced Docker usage, consult the Docker and NVIDIA Container Toolkit documentation.

This repository provides two main container types:

Runtime Container

  • Purpose: For running pre-built BiguaSim applications and distributing BiguaSim internally.

  • Features:

    • Minimal environment (no build tools).

    • BiguaSim code is pre-installed.

    • Intended for deployment and production.

  • Availability:

    • Not distributed publicly online due to the Epic Games End User License Agreement (EULA).

  • Building:

    • The Docker image must be built locally and cannot be pulled from Docker Hub. Build the image using the Dockerfile located in the docker/runtime directory.

  • Usage

    1. Allow display access by running on the host machine:

      xhost +local:docker

    2. Navigate to the runtime directory inside the docker folder:

      cd docker/runtime

    3. To start a container, use docker compose up with the following options:

      • -d: Run the container in detached mode.

      • --build: Build the Docker image before starting the container.

      To build the image and start the container in detached mode, run:

      docker compose up --build -d

    4. Test the example script:

      docker cp ../../client/example.py biguasim:/home/ue4  # Copy the example script into the container
docker exec -it biguasim bash   # Create bash terminal inside the container

      Inside the container run:

      python3 -c "from example import *; torpedo_example()"

    5. To stop and remove the container, run from the same directory:

      docker compose down

Python/Client Development Container

  • Purpose: For active development and compilation of the BiguaSim Python client (non-engine code).

  • Features:

    • Source code is volume-mounted for live editing.

    • Includes all necessary build tools.

    • Suitable for iterative testing and debugging BiguaSim Python client code.

  • Availability:

    • Pre-built Docker images are available on Docker Hub.

    • Docker containers can be built and modified locally.

  • Usage

    1. Allow display access by running on the host machine:

      xhost +local:docker

    2. Navigate to the development directory inside the docker folder and change permissions of build cache for isolated pip installation:

      cd docker/dev
sudo chmod -R a+w build_cache/

    3. To start a container, use docker compose up with the following options:

      • -d: Run the container in detached mode.

      • --build: Build the Docker image before starting the container.

      To start a container in detached mode run:

      docker compose up -d

      If no local image is found, then the image will be attempted to be pulled from Docker Hub.

    4. Test the example script:

      docker exec -it biguasim bash   # Create bash terminal inside the container

      Inside the container run:

      cd client
python3 -c "from example import *; torpedo_example()"

    5. To stop and remove the container, run from the same directory:

      docker compose down

Troubleshooting

  • Display Issues:

    • Ensure xhost +local:docker has been run on the host.

    • Confirm the DISPLAY environment variable is set.

    • Make sure your X11 server is running and Docker has access.

  • CUDA Version:

    • Ensure that the CUDA version used in the Docker container is:

    • Lower than or equal to your host CUDA installation

    • Compatible with your NVIDIA Driver

    • Change CUDA versions by modifying the Dockerfiles

  • Verify GPU Access:

    • Inside the container, run:

      nvidia-smi

  • Docker Not Found:

    • Ensure Docker is properly installed and the daemon is running.