Getting started with IndenToolBox

Install VSCode

Visual Studio Code (VSCode) is a lightweight but powerful source code editor that runs on your desktop. If you don’t already have a favorite Python IDE, follow this tutorial. Please, don’t use Spyder.

Procedure

  1. Download the installer from the VSCode website.

  2. Run the installer and follow the instructions.

Warning

For Windows users only Chose the “system installer” and not the “user installer”.

  1. Open VSCode and install the Python extension by Microsoft.

Install GIT

If you’re new to Python, learning Git is a game-changer! It helps you track changes, undo mistakes, and collaborate easily. With GitHub or GitLab, you can contribute to open-source projects and showcase your work. Start using Git early—it’ll make your coding journey way smoother!

Procedure

  • For Windows users: GIT-SCM

  • Linux: GIT is already instlalled

  • MAC OS: for example, install it via Brew brew install git

Setup Python

In order to work with IndenToolBox on a clean Python setup, you have two main options. The local installation and the Devcontainer installation.

Local python setup

A local setup runs directly on your operating system using a Conda/Mamba environment. It avoids Docker and gives you native performance and direct access to your hardware and OS features.

Tip

Choose this option if you want maximum native performance, no Docker dependency, and full access to local hardware (GPU, USB, file system) with minimal overhead.

Why choose a local setup

  • Native performance: fastest file I/O and lowest latency on your machine.

  • Full OS/hardware access: GPUs (with host drivers), USB devices, printers, VPN/proxy, and system GUIs work without container passthrough.

  • Lower overhead: no Docker engine, images, or container filesystem layers.

  • Offline friendly: after creating the environment once, day‑to‑day work can run without network.

  • Simple for quick scripts/notebooks: fewer moving parts, easy to launch from your terminal.

Warning

Trade‑offs vs Dev Container

  • Less reproducible: environments can drift across machines/OSes and “works on my machine” issues are more likely.

  • Dependency conflicts: may clash with other global or user Conda/Pip installs on the host.

  • More manual maintenance: you update packages, pre‑commit hooks, and tools yourself; teammates may have different versions.

  • Platform quirks: path/permission differences on Windows/macOS/Linux can cause platform‑specific bugs that containers often avoid.

Install Miniforge

As of January 2025, we recommend Install Miniforge rather than Anaconda, for reasons of simplicity and licensing:

  1. Miniforge installer, you may need to have a look at the Miniforge documentation for more information. Mamba is already included in Miniforge.

Warning

For Windows users only Please chose these 2 options during installation:

  • “install only for me” and

  • “add mini-forge to your PATH”.

Environment setup

Create an environment with the following command:

  1. Download the environment file environment.yml and put it in the current folder.

  2. Run the following command:

    mamba env create --file=environment.yml

    If you don’t have mamba installed, you can use conda instead:

    conda env create --file=environment.yml

    The install process will just be a bit slower.

  3. Activate the environment:

    conda activate science

Install IndenToolBox

For standard users

  • Install IndenToolBox with the following command:

pip install git+https://gitlab.com/indpp/indentoolbox.git@dev
For contributors

  • Fork the repo from GITLab.

  • Choose your working directory.

  • Clone the repo from your fork in this directory:

git clone https://gitlab.com/<user>/indentoolbox.git

Where <user> is your GITLab username.

  • Checkout to dev branch.

cd indentoolbox
git checkout dev

Or create a new branch.

cd indentoolbox
git checkout -b mybranch dev

conda activate science

  • And then install IndenToolBox in editable mode:

pip install -e .
pip install -r requirements.txt
pip install nbsphinx sphinx_copybutton sphinxcontrib-bibtex myst_nb sphinx_rtd_theme

Then you can work and, if you wish, commit your work, push it and finally create a pull request on GITLab to share your work with the main repository.

Devcontainer setup

The Dev Container provides a fully reproducible, pre‑configured environment that isolates your tools from your host system and works the same on Windows, macOS, and Linux.

Tip

Choose this option if you want a clean, consistent setup that matches the maintainers’ environment: dependencies are pinned in .devcontainer/environment.yml, VS Code settings and extensions are preconfigured, and the project is installed in editable mode automatically.

Why it’s often better than a local setup

  • Reproducible environment: same Python, packages, and tools for everyone.

  • Zero host pollution: no global installs; everything stays inside the container.

  • Faster onboarding: open → “Reopen in Container” → ready to work.

  • Consistent tooling: preconfigured VS Code extensions, formatter, linter, and pre‑commit hooks.

  • Easy reset: “Rebuild Container” returns you to a clean state in minutes.

Warning

Trade‑offs to be aware of

  • Requires Docker (large install) and virtualization; first build pulls images and packages.

  • More resource usage than local: higher disk space, slower cold starts, and slower I/O on mounted folders (notably on macOS/Windows).

  • Hardware/OS integration can need extra setup (e.g., GPU, USB devices, some networking/proxy configurations).

  • Initial build needs network access to fetch the base image and conda packages.

Procedure

  1. Install Docker (or a compatible container runtime).

  2. Install the “Dev Containers” VS Code extension.

  3. Clone the repo, open it in VS Code, then run “Dev Containers: Reopen in Container”.

    • The first build can take several minutes; subsequent starts are much faster.

    • The container creates the science conda env from .devcontainer/environment.yml and installs the project in editable mode.

Run Jupyter Lab

JupyterLab is a web-based interactive environment for notebooks, code, and data. It lets you mix runnable code cells with narrative text and plots, making it ideal for exploring datasets, prototyping algorithms, and sharing reproducible workflows. In this project, we use JupyterLab to run examples/notebooks, iterate quickly on analysis, and visualize results interactively (e.g., Plotly, Matplotlib via ipympl).

At this point, you should have all the necessary packages installed. You can run Jupyter Lab with the following command:

jupyter lab