Installation

DendriNet (Python package dendritic_modeling) needs Python 3.10 or newer and PyTorch 2.8 or newer. The continuous-integration tests run on Linux with Python 3.10, 3.11 and 3.12 on CPUs. A CUDA GPU is optional; the Triton kernels of indexed synapses need one.

Install from PyPI

Create a virtual environment on your computer. On Linux or macOS:

python3 -m venv .venv
source .venv/bin/activate

On Windows PowerShell, use py -m venv .venv and run .\.venv\Scripts\Activate.ps1. In the activated environment, install the released core package:

python -m pip install dendritic-modeling==0.5.0
python -m pip check

The Python import name is dendritic_modeling. For a graphical editor, install dendrinet-studio==0.1.0 and launch it locally:

python -m pip install dendrinet-studio==0.1.0
dendrinet-studio --workspace my-runs

Installing Studio on its own also installs a compatible core (0.5.x). See Train your first network to train a synthetic network in the browser. The published files are on the core PyPI page and the Studio PyPI page.

Pip resolves PyTorch and torchvision as dependencies. To select Linux CPU-only wheels or a particular CUDA build, install a compatible torch and torchvision pair in the same environment first, using the PyTorch installation selector.

Install from a checkout for development

git clone --branch develop https://github.com/KempnerInstitute/DendriNet.git
cd DendriNet
conda env create -f setup/environment.yml
conda activate dendritic_env
pip install -e ".[test]" -c setup/constraints/core-py310-torch2.9.1.txt

setup/environment.yml creates a conda environment named dendritic_env with Python 3.10 and pip only; a venv with Python 3.10 works the same. pip then installs the package in editable mode with its dependencies, including the PyTorch wheels.

These instructions select the maintained develop branch. For a study, check out and record the exact library commit before running experiments; see Project provenance.

To add the graphical editor, install both packages from the same checkout with python -m pip install -e . -e ./apps/studio. Start it locally with dendrinet-studio --workspace my-runs. See Install and start for browser access and Train your first network for a download-free tutorial.

The constraints file setup/constraints/core-py310-torch2.9.1.txt pins the versions the test suite passed with on Python 3.10: PyTorch 2.9.1 with its CUDA 12.8 wheels from PyPI, NumPy 2.2 and SciPy 1.15, among others. Without -c, pip resolves the version ranges in pyproject.toml; use that on other Python versions. pip install -e . installs the package without the test tools.

Optional dependencies

Extras add dependency groups, for example pip install -e ".[dev,gpu]":

Extra

Adds

test

pytest with pytest-cov, pytest-timeout and pytest-xdist, and coverage.

lint

ruff, black, isort, mypy and pre-commit (see Contributing).

dev

test and lint, plus build, setuptools, wheel and twine for packaging.

docs

Sphinx and the Read the Docs theme. The configured extensions are bundled with Sphinx.

train

Jupyter, IPython and ipykernel for notebooks.

gpu

Triton, for the Triton kernels of indexed synapses. The Linux CUDA wheels of PyTorch already include it.

plotting

networkx, for the graph drawings of dendritic_modeling.plotting.

transformers

Hugging Face transformers, for dendritic_modeling.networks.architectures.transformer, which replaces the feed-forward blocks of a pretrained transformer with dendritic layers.

compression

torchao, for the optional dense-runtime backends of compact checkpoints (torchao_*; see Compact checkpoints).

all

dev, train, docs, gpu and plotting.

The ablation and compartment-SNR analyses write their animations as MP4 videos when ffmpeg is installed (conda install -c conda-forge ffmpeg) and as GIF files otherwise.

Examples without a checkout

The installed package includes small tutorial configurations:

dendritic-example synthetic_population --output demo.yaml
dendritic-train demo.yaml --epochs 1

The synthetic example generates data locally. mnist_population downloads MNIST on its first run. These examples are independent of the current working directory and are not paper reproduction recipes. The exporter never overwrites an existing file. See Preparing a public release for package release preparation.

Check the installation

python -c "import dendritic_modeling; print(dendritic_modeling.__file__)"
dendritic-train --help
python -c "import torch; print(torch.cuda.is_available())"

The first command prints the path of the imported package, the second lists the training options (Command-line reference lists every command), and the third reports whether PyTorch sees a CUDA GPU. Without one, models train on the CPU. The Triton backends of indexed synapses (triton_*) need a CUDA GPU; with projection_backend: auto a model uses a Triton kernel where Triton runs on a CUDA device and the portable recompute implementation elsewhere. See Projection backends.

Data

Datasets are stored under one data root: data.base_dir when it is set (dendritic-train --data_dir sets it), else the directory named by the DENDRITIC_DATA_DIR environment variable, else $XDG_CACHE_HOME/dendritic_modeling (by default ~/.cache/dendritic_modeling). MNIST, Fashion-MNIST, CIFAR-10 and CIFAR-100 download into it on first use; ImageNet must be provided. See Datasets.

Numerical environments

The package accepts NumPy 1.x and 2.x and the other version ranges in pyproject.toml. An allowed range does not promise bitwise agreement across versions. Every training run records its library commit, package path and dependency versions in runtime_environment.json and its seeds and numerics settings in resolved_seeds.json. To repeat a result, install the recorded stack, for example from a constraints file that setup/freeze_constraints.py writes for an environment:

python setup/freeze_constraints.py --extras test lint gpu plotting \
  --output setup/constraints/<name>.txt

See Reproducibility.