Installation

Installation

This guide provides step-by-step instructions for installing MASSTER. In principle, all you need is Python 3.11-3.13, but we recommend:

• installing uv to setup a dedicated virtual environment with all the dependencies. This can also be used as Kernel for e.g VSC, Marimo, etc
• installing Visual Studio Code (VSC), or your favorite IDE, to edit script
• MASSter can be used interactively in notebooks like Jupyter or Marimo. These can be installed in the virtual environment, or served from VSC.

##1. Install uv (optional but recommended)

uv is a fast Python package installer and resolver.

Installation on Windows: Using PowerShell:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Verify installation:

uv --version

For other systems, refer to [https://docs.astral.sh/uv/getting-started/installation/].

2. Create and initialize the environment folder

To avoid conflicts with other Python projects, isolate MASSTER in its own virtual environment. The recommended workflow uses uv to create a workspace that contains pyproject.toml, uv.lock, and a .venv folder.

Create a new directory and initialize uv:

# Create a new workspace folder (choose a parent folder first)
cd <to-parent-folder>
mkdir my-masster-workspace  # Note: avoid using the name "masster" alone

# Move into newly created folder
cd my-masster-workspace

# Initialize uv
uv init

# Pin Python version (example: 3.12)
uv python pin 3.12

This will create a pyproject.toml. Keep pyproject.toml as the source of truth — uv.lock and .venv can be recreated from it.

3. Install MASSTER

# Make sure you are in the workspace folder
cd <path-to-my-masster-workspace>

# Install MASSTER from the internal index
uv add --index https://zamboni-lab.github.io/masster-dist/simple masster

4. Optional: install an IDE (Visual Studio Code)

If you are not familiar with Python, we recommend Visual Studio Code to simplify scripting and environment management.

Download and Install VS Code:

1. Download VS Code from https://code.visualstudio.com/
2. Run the installer and follow the wizard.
3. Launch VS Code.

Recommended extensions:

• Python (Microsoft)
• Jupyter (Microsoft)
• marimo (marimo-team)

Selecting the correct Python interpreter in VS Code:

1. Click the Python version in the bottom-right corner of VS Code, or press Ctrl+Shift+P and run Python: Select Interpreter.
2. Choose the interpreter from your workspace .venv folder, for example:

<my-masster-workspace>\.venv\Scripts\python.exe

This ensures MASSTER dependencies are available in VS Code.

5. Test installation

Create a file named test_installation.py with the following content:

#!/usr/bin/env python3
"""
Test script to verify MASSTER and rawreader installation.
"""

import sys

def test_imports():
    """Test that required packages can be imported."""
    try:
        import masster
        print("✓ masster imported successfully")
        print(f"  masster version: {getattr(masster, '__version__', 'unknown')}")
    except ImportError as e:
        print(f"✗ Failed to import masster: {e}")
        return False
    
    print("\n✓ All imports successful!")
    return True

if __name__ == "__main__":
    success = test_imports()
    sys.exit(0 if success else 1)

Run the test script:

If your shell is in the workspace folder (where the .venv is active or via uv run):

uv run python test_installation.py

Or, if using the venv directly in PowerShell:

.<my-masster-workspace>\.venv\Scripts\Activate.ps1
python test_installation.py

If the installation is successful, you should see output confirming both imports.