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 |
|---|---|
|
pytest with pytest-cov, pytest-timeout and pytest-xdist, and coverage. |
|
ruff, black, isort, mypy and pre-commit (see Contributing). |
|
|
|
Sphinx and the Read the Docs theme. The configured extensions are bundled with Sphinx. |
|
Jupyter, IPython and ipykernel for notebooks. |
|
Triton, for the Triton kernels of indexed synapses. The Linux CUDA wheels of PyTorch already include it. |
|
networkx, for the graph drawings of |
|
Hugging Face transformers, for
|
|
torchao, for the optional dense-runtime backends of compact
checkpoints ( |
|
|
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.