Getting started

This project uses uv (https://docs.astral.sh/uv/) for dependency management, which provides fast and reliable Python package installation. uv will automatically handle Python version management and create virtual environments. The workflow is as follows:

Quick Installation

1. Install uv (if not already installed):

   On Linux and macOS use

   curl -LsSf https://astral.sh/uv/install.sh | sh

   For Windows instructions see the documentation

2. Clone the repository:

   git clone https://github.com/DurstewitzLab/hier-MTF.git
   cd hier-MTF

3. Install dependencies and create virtual environment:

   uv sync

   This will:

   • Create a virtual environment (.venv)
   • Install all dependencies from pyproject.toml
   • Use the exact versions specified in uv.lock for reproducibility

4. (Optional) Install pre-commit hooks:

   Pre-commit hooks help maintain code quality by automatically formatting code and checking for common issues before commits. To install pre-commit hooks, run the following in a terminal with the environment activated:

   pre-commit install

   Note that this correct code formatting is mandatory for contributions to be accepted.

Running the code

The workflow for running the code is centered around the ubermain.py file (or variant thereof). This file serves as both the entry point and the configuration file for your experiments.

1. Configure the Experiment: Open ubermain.py and modify the config dictionary to suit your data and model requirements. This dictionary controls data loading, model architecture (encoder, decoder, latent step), training parameters, and evaluation settings.

2. Run the Training: After installation, you can run the code by:

   # Activate the environment
   $ source .venv/bin/activate
   
   # Run the configured experiment
   (hier-mtf) $ python ubermain.py

   Or use uv directly:

   $ uv run python ubermain.py

Fixing TensorBoard path length issues on Windows

When running TensorBoard on Windows, you may encounter errors related to path length limitations. These errors typically occur during the automatic generation of temporary files and logging directories. Windows has a default path length limit of 260 characters, which TensorBoard's auto-generated paths can exceed. Solution

To resolve this issue, you need to enable long path support in Windows Registry:

Open Registry Editor: Press Win + R Type regedit and press Enter

Navigate to:

Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem

Find the LongPathsEnabled entry Double-click on LongPathsEnabled Set the value to 1 Click OK

Restart your system for changes to take effect

Note: This modification requires administrative privileges. If you don't have access to modify the registry, please contact your system administrator.

After applying this change, TensorBoard should work without path length-related errors.