.. raw:: html

   <link rel="stylesheet" type="text/css" href="_static/custom.css">

Installation Guide
==================

From Quick Start to Advanced Options
------------------------------------

Create conda environment (recommended):

.. code-block:: bash

    conda create --name vbi python=3.10
    conda activate vbi

Install VBI:

.. code-block:: bash

    pip install vbi                    # Light version (CPU only)
    pip install vbi[light-gpu]         # Light + Cupy
    pip install vbi[inference]         # With (sbi, PyTorch)
    pip install vbi[all]               # Full (sbi, PyTorch, Cupy)

Installation Options
--------------------

.. list-table:: VBI Installation Variants
   :header-rows: 1
   :class: color-caption

   * - **Command**
     - **Includes**
     - **Best For**
   * - ``pip install vbi``
     - CPU simulation, feature extraction, CDE-based inference
     - Avoiding heavy dependencies
   * - ``pip install vbi[light-gpu]``
     - Everything + Cupy
     - GPU simulation
   * - ``pip install vbi[inference]``
     - Everything + PyTorch, SBI
     - Parameter inference (CPU)
   * - ``pip install vbi[inference-gpu]``
     - Everything + GPU acceleration
     - Full functionality with GPU

Docker Usage
------------

.. code-block:: bash

    # Quick start with pre-built image
    docker run --rm -it -p 8888:8888 ghcr.io/ins-amu/vbi:main

    # With GPU support
    docker run --gpus all --rm -it -p 8888:8888 ghcr.io/ins-amu/vbi:main

For Docker building and advanced usage, see :doc:`docker_build` and :doc:`docker_quickstart`.

Installation From Source
-------------------------

.. code-block:: bash

    git clone https://github.com/ins-amu/vbi.git
    cd vbi
    pip install .

For development:

.. code-block:: bash

    pip install -e .[all]

Platform-Specific Instructions
-------------------------------

**Google Colab**

Google Colab doesn't have VBI or SBI pre-installed, and **Docker is not supported** in Colab due to security restrictions. For optimal C++ module compilation, install from source:

.. code-block:: bash

    # In a Colab cell, run:
    !mkdir -p src && cd src
    !git clone --depth 1 https://github.com/ins-amu/vbi.git
    %cd src/vbi
    !pip install -e .

**Alternative: Use Colab Pro+ with Custom Runtimes**

If you have Colab Pro+ and need a containerized environment, consider:

- Using **Kaggle Notebooks** (supports Docker-based custom environments)
- Using **Binder** with our repository (though with limited resources)
- Setting up a **local Jupyter server** with our Docker image and connecting via ngrok

**Note:** The environment will be reset when the Colab runtime shuts down. You'll need to reinstall for each new session.

**EBRAINS Collab**

EBRAINS has dependency management restrictions. Here's a script to create a dedicated VBI environment:

.. code-block:: bash

    #!/bin/bash
    # Save this as setup_vbi_ebrains.sh

    set -eux

    # Create fresh environment
    rm -rf /tmp/vbi
    python3 -m venv /tmp/vbi
    unset PYTHONPATH
    source /tmp/vbi/bin/activate

    # Install core dependencies
    pip install ipykernel scikit_learn matplotlib

    # Install PyTorch (CPU version to save space)
    pip install torch --index-url https://download.pytorch.org/whl/cpu

    # Install SBI without dependencies to avoid reinstalling large packages
    pip install sbi --no-deps

    # Install SBI dependencies manually
    pip install pyro-ppl tensorboard nflows pyknos zuko arviz pymc

    # Install VBI from source
    mkdir -p /tmp/src && pushd /tmp/src
    git clone --depth 1 https://github.com/ins-amu/vbi.git
    cd vbi
    pip install -e .
    popd

    # Create Jupyter kernel
    python -m ipykernel install --user --name VBI

    echo "VBI environment created! Please reload your browser and select the 'VBI' kernel."
    echo "Note: This environment will be lost when the lab server shuts down."

Make the script executable and run it:

.. code-block:: bash

    chmod +x setup_vbi_ebrains.sh
    ./setup_vbi_ebrains.sh

**Important Notes:**

- Both environments are temporary and will be reset when the respective platforms shut down
- For EBRAINS, you'll need to rerun the setup script for each new session
- For Colab, you'll need to reinstall VBI in each new runtime

**Windows**

Windows installation is automatic - C++ compilation is automatically skipped:

.. code-block:: bash

    pip install vbi

Verification
------------

.. code-block:: python

    import vbi
    vbi.tests()
    vbi.test_imports()

Java JDK (for Information-Theoretic Features)
----------------------------------------------

Some feature-extraction functions in VBI use
`JIDT — Java Information Dynamics Toolkit <https://github.com/jlizier/jidt>`_
(bundled as ``infodynamics.jar``) via the `JPype <https://jpype.readthedocs.io>`_
bridge.  These features include transfer entropy and mutual information estimators.

A **Java JDK (version 8 or later)** must be installed for these functions to work.
``JPype1`` is required as a Python bridge and must be installed separately:

.. code-block:: bash

    pip install JPype1

**Install Java JDK:**

- **Linux (Debian/Ubuntu):**

  .. code-block:: bash

      sudo apt-get install default-jdk

- **macOS (via Homebrew):**

  .. code-block:: bash

      brew install openjdk

- **Windows:** Download and install from https://adoptium.net

**Verify your Java installation:**

.. code-block:: bash

    java -version

If Java is installed but JPype cannot find it, set the ``JAVA_HOME`` environment
variable to your JDK path.  For example on Linux:

.. code-block:: bash

    export JAVA_HOME=/usr/lib/jvm/default-java

Information-theoretic features are optional — all other VBI functionality works
without Java or JPype.

Troubleshooting
---------------

**C++ Compilation Issues**

Note: the package is configured with SKIP_CPP=0 by default (C++ extensions are enabled).
If you want to skip compilation of C++ components, set SKIP_CPP=1 when installing from source or via pip, for example:

.. code-block:: bash

    export SKIP_CPP=1
    pip install vbi

**Common Issues**

- **ImportError**: Check Python version (3.10+ recommended)
- **CUDA issues**: Verify GPU drivers and CUDA compatibility
- **Memory errors**: Try lighter installation variants

For detailed troubleshooting, platform guides, and advanced scenarios, see the complete `Installation Guide <https://github.com/ins-amu/vbi/blob/main/INSTALLATION.md>`_.