.. _installation: ============ 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. - :ref:`Standard Packaged installation ` – Simplest method for using BiguaSim out of the box. - :ref:`Docker-based installation ` – Alternate setup using preconfigured Docker containers. 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. .. _install-packaged: 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')" .. _install-dev: 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 :ref:`develop`. `official Biiguasim-engine documentation `_ .. _install-docker: 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** - Ensure Docker Engine is installed and the daemon is running. Issues may occur when running Docker Desktop with the NVIDIA Container Toolkit. - See the `official Docker installation guide `_. - Follow `Post-installation steps `_ for Linux to run Docker without sudo. 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: .. code-block:: bash xhost +local:docker 2. Navigate to the runtime directory inside the ``docker`` folder: .. code-block:: bash 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: .. code-block:: bash docker compose up --build -d 4. Test the example script: .. code-block:: bash 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: .. code-block:: bash python3 -c "from example import *; torpedo_example()" 5. To stop and remove the container, run from the same directory: .. code-block:: bash 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: .. code-block:: bash xhost +local:docker 2. Navigate to the development directory inside the ``docker`` folder and change permissions of build cache for isolated pip installation: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash docker exec -it biguasim bash # Create bash terminal inside the container Inside the container run: .. code-block:: bash cd client python3 -c "from example import *; torpedo_example()" 5. To stop and remove the container, run from the same directory: .. code-block:: bash 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: .. code-block:: bash nvidia-smi - **Docker Not Found:** - Ensure Docker is properly installed and the daemon is running.