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: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash 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 :ref:`studio-first-run` 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 --------------------------------------- .. code-block:: bash 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 :doc:`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 :ref:`studio-install` for browser access and :ref:`studio-first-run` 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]"``: .. list-table:: :header-rows: 1 :widths: 18 82 * - Extra - Adds * - ``test`` - pytest with pytest-cov, pytest-timeout and pytest-xdist, and coverage. * - ``lint`` - ruff, black, isort, mypy and pre-commit (see :doc:`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 :ref:`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: .. code-block:: bash 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 :doc:`releases` for package release preparation. Check the installation ---------------------- .. code-block:: bash 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 (:ref:`cli-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 :ref:`indexed-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 :doc:`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: .. code-block:: bash python setup/freeze_constraints.py --extras test lint gpu plotting \ --output setup/constraints/.txt See :ref:`run-reproducibility`.