DeepDendrite
Source

DEEPDENDRITE DOCUMENTATION

Docs

Install, configure, and run DeepDendrite on a supported GPU system.

GET STARTED

Overview

DeepDendrite is an open-source GPU framework built on CoreNEURON. It integrates Dendritic Hierarchical Scheduling (DHS), an I/O module, and a learning module for detailed neuron simulation and network learning.

Repository layout

src/ contains DeepDendrite and the modified NEURON frontend. Figure_3_4/ contains solver benchmarks, Figure5/ contains the full-spine example, and Figure6/ contains the HPC-Net example.

GET STARTED

Requirements

DependencyMinimum / notes
CMake3.10.2 or newer
MPI3.0 or newer
Python3.6 or newer for the modified NEURON build
CompilerPGI OpenACC Compiler or NVIDIA HPC SDK
CUDA Toolkit10.1 or newer

Use versions compatible with your GPU driver and HPC SDK. The released code reflects the environment used for the published work; newer toolchains may require adaptation.

GET STARTED

Installation

1. Clone the repository

git clone https://github.com/pkuzyc/DeepDendrite.git
cd DeepDendrite

2. Build the modified NEURON simulator

AI tasks require the modified NEURON simulator shipped in the repository.

cd src/nrn_modify
./configure --prefix ../../install \
  --without-iv \
  --with-paranrn \
  --with-nrnpython=`which python`
make -j8
make install

3. Build DeepDendrite

Edit src/DeepDendrite/install.sh to load the correct PGI/NVHPC module and set the installation and mechanism paths used by CMake, then build:

cd ../DeepDendrite
# Review install.sh for your local module and paths.
source install.sh
Environment-specific step

The upstream install script contains paths that must be adapted to your cluster or workstation. Review it before running.

USER GUIDE

Run DHS

DeepDendrite embeds DHS into its CoreNEURON-based execution engine. The installed executable is install/bin/deepdendrite; select the GPU backend and permutation type 3 to use DHS.

./install/bin/deepdendrite \
  --datpath /path/to/coredat \
  --gpu \
  --cell-permute 3 \
  --cell-nthread 16 \
  --tstop 1000 \
  --dt 0.025

Additional arguments depend on the exported model and workload. Use the matching example scripts for a complete invocation.

USER GUIDE

Examples

EQUATION SOLVING

Solver performance

Evaluate equation-solving runtime across Hines, CoreNEURON, and DHS configurations.

Browse files ↗
FULL-SPINE SIMULATION

Full-spine model

Run clustered and distributed synaptic input experiments on a human pyramidal cell with explicit spines.

cd Figure5/run_samples
python3 run.py
Browse files ↗
DETAILED-NEURON LEARNING

HPC-Net

Train and test the detailed network, or evaluate pretrained weights.

cd Figure6/run_samples
python3 run.py       # train + test
python3 run_test.py  # test only
Browse files ↗

USER GUIDE

Architecture

01Modified NEURON

Model authoring and export, including support required by the learning demos.

→
02DHS engine

GPU equation construction and dependency-safe tree solving inside CoreNEURON.

→
03I/O + learning

Dataset delivery, simulation orchestration, and weight updates for AI tasks.

DHS correctness

Triangularization processes a node only after all children; back-substitution processes a node only after its parent. DHS preserves these dependencies and therefore produces the same solution as serial Hines while grouping independent nodes into parallel steps.

REFERENCE

Runtime options

OptionPurpose
--gpuRun simulation on GPU.
--datpath PATHRead CoreNEURON model data from PATH.
--cell-permute 0Do not permute compartments.
--cell-permute 1Optimize node adjacency.
--cell-permute 2Optimize parent adjacency.
--cell-permute 3Use the DHS method.
--cell-nthread NUse N threads to parallelize each cell (1–32).
--tstop MSSet the simulation stop time in milliseconds.
--dt MSSet the fixed timestep in milliseconds.

These names and ranges follow the command-line parser in the open-source DeepDendrite repository.

REFERENCE

Troubleshooting

Build script refers to unavailable module paths

Edit install.sh to load the NVHPC/PGI module available on your system and update install/mechanism paths.

The AI demo fails with a stock NEURON installation

Build and use src/nrn_modify. The repository explicitly requires its modified simulator for AI tasks.

CUDA or OpenACC compiler errors

Confirm that CUDA, the GPU driver, and NVIDIA HPC SDK versions are mutually compatible and visible in the same shell.

Results differ from the example output

Use the model assets and scripts from the matching example directory, preserve timestep and solver options, and separate warm-up from timed runs.

REFERENCE

Citation

@article{zhang2023gpu,
  title={A GPU-based computational framework that bridges neuron simulation and artificial intelligence},
  author={Zhang, Yichen and He, Gan and Ma, Lei and others},
  journal={Nature Communications},
  volume={14},
  pages={5798},
  year={2023},
  doi={10.1038/s41467-023-41553-7}
}

DeepDendrite source code is distributed under the Apache License 2.0.