USER GUIDE

BRAINCELL 2.0.

Brain cell in silico

© University College London, MIT licence

16/03/2026

TABLE OF CONTENTS

1 INTRODUCTION

1.1 Getting Started with BrainCell

1.1.1 Welcome to the BrainCell User Manual

BrainCell is a next-generation simulation platform for constructing and analysing multi-scale models of neurons and astroglia. It enables the creation of realistic, multi-compartmental biophysical representations of brain cells, linking detailed morphology with their physiological function.

Built on the NEURON–Python computational environment, BrainCell integrates cellular morphology, membrane dynamics, and intracellular mechanisms into a unified workspaceWith this tool, researchers can explore how geometry, ion transport, and cellular interactions shape neuronal and glial behaviour across spatial and temporal scales.

The primary goal of BrainCell is to facilitate the mechanistic interpretation of experimental data, allowing users to reproduce, test, and predict complex cellular processes within a biologically grounded computational framework.

This manual provides a step-by-step guide to BrainCell’s features, interface, and workflow - helping you make the most of its modelling capabilities and apply them effectively to your research.

1.1.2 Basic Windows Requirements (Quick Check)

This section provides only the minimal prerequisites required to run BrainCell on Windows. For detailed installation instructions and troubleshooting, see the next section.

Before installing BrainCell, make sure the following software is installed:

Python (Anaconda) Install Anaconda 2023.09 (Windows, x64) Download: https://neuroalgebra.net/assets/Anaconda3-2023.09-0-Windows-x86_64.exe

NEURON Install NEURON 8.2.2 (Windows, mingw build, Python 3.7–3.11 compatible) Download: https://neuroalgebra.net/assets/nrn-8.2.2-0-setup.exe

After installation, verify that NEURON’s Python environment script

C:\nrn\bin\nrnpyenv.bat

correctly points to your Anaconda installation.

Important note

NEURON uses the Windows environment variable %APPDATA%, which is specific to the current user. For this reason, Anaconda must be installed for the current user only. If it is installed for all users, NEURON may fail to detect the Python environment.

More detailed setup instructions are provided in the following section

2 BrainCell Installation Guide

2.1 Choose Your Starting Point

Before installing BrainCell, determine which of the following three categories applies to you. Each category has its own correct installation path.

2.1.1 About this Installation

This manual guides you through installing BrainCell, a computational neuroscience simulation tool. BrainCell requires NEURON (simulation environment) and Python (Anaconda recommended) to run.

Platforms covered: Windows 10/11, macOS 10.15+, Linux (Ubuntu 20.04+, Debian, Fedora)

Estimated installation time: 30-60 minutes for clean installation

2.1.2 Quick Start: Identify Your Category

Choose the category that matches your current system:

CategoryDescriptionWhen to Use
Category 1NEURON + Python is already workingYou run NEURON simulations regularly
Category 2Clean system (nothing installed)Fresh OS or new to NEURON
Category 3Mixed/incomplete installation⚠️ NEURON or Python is partially installed

⚠️ CRITICAL: If you're in Category 3 (mixed environment), DO NOT attempt to patch your installation. Follow the clean installation process - it's faster and more reliable.

2.1.3 System Requirements

Minimum:

2.2 Category 1 - Existing NEURON + Python Users

(Experienced users with a working environment)

2.2.1 Who belongs here?

You are in Category 1 if ALL of the following are true:

If any of these are false, go to Category 2 or Category 3.

2.2.2 Step 1: Download BrainCell

All Platforms

Windows:

C:\braincell

macOS/Linux:

~/braincell

Windows:

macOS:

xattr -d com.apple.quarantine ~/Downloads/cloudpackage-v1.zip

Linux:

2.2.3 Step 2: Compile NEURON Mechanisms (If Needed)

⚠️ Only perform this step if:

Windows

Double-click:

build_mechs.bat

If compilation fails: Install Microsoft C++ Build Tools (x64) from: https://visualstudio.microsoft.com/downloads/ (scroll to "Build Tools for Visual Studio")

Then run build_mechs.bat again.

macOS

Open Terminal in the BrainCell directory and run:

chmod +x build_mechs.sh
./build_mechs.sh

If compilation fails: Install Xcode Command Line Tools:

xcode-select --install

Linux

Open Terminal in the BrainCell directory and run:

chmod +x build_mechs.sh
./build_mechs.sh

If compilation fails: Install build essentials:

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install build-essential

Fedora/RHEL:

sudo dnf install gcc gcc-c++ make

2.2.4 Step 3: Platform-Specific Setup

Windows: Unblock Scripts

Right-click each of the following files → Properties → Check "Unblock" → Apply:

init.bat

If Windows blocks execution:

Open PowerShell and run:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

macOS: Make Scripts Executable

Open Terminal in the BrainCell directory:

chmod +x init.sh
chmod +x build_mechs.sh

Linux: Make Scripts Executable

Open Terminal in the BrainCell directory:

chmod +x init.sh
chmod +x build_mechs.sh

Step 4: Launch BrainCell

Windows

Double-click:

init.bat

macOS/Linux

Open Terminal in the BrainCell directory and run:

./init.sh

Or, using NEURON directly:

nrngui init.hoc

✅ Verification

After launch, you should see:

If you see this, installation is complete!

2.3 Category 2 - Clean System Installation

(No NEURON or Python installed)

2.3.1 Who belongs here?

You are in Category 2 if:

Typical users: New users, fresh installations, dedicated simulation machines

For reliable operation across all platforms:

Discussion and updates: https://forum.neuroalgebra.net/viewtopic.php?p=171#p171

2.3.3 Step 1: Install Anaconda

Windows

macOS

conda --version
python --version
echo 'export PATH="$HOME/anaconda3/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

(Use ~/.bash_profile if you're using bash instead of zsh)

Linux

wget https://repo.anaconda.com/archive/Anaconda3-2023.09-0-Linux-x86_64.sh
bash Anaconda3-2023.09-0-Linux-x86_64.sh
source ~/.bashrc
conda --version
python --version

2.3.4 Step 2: Install NEURON

Windows

nrniv -python

You should see the NEURON prompt. Type quit() to exit.

macOS

nrniv -python

If not recognized, add to PATH in ~/.zshrc (or ~/.bash_profile):

export PATH="/Applications/NEURON/nrn/x86_64/bin:$PATH"

Then reload:

source ~/.zshrc

Linux

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install neuron

Or compile from source:

sudo apt-get install build-essential libncurses-dev libreadline-dev \
                     libx11-dev libxt-dev bison flex automake libtool
wget https://github.com/neuronsimulator/nrn/releases/download/8.2.2/nrn-8.2.2.tar.gz
tar -xzf nrn-8.2.2.tar.gz
cd nrn-8.2.2
./configure --prefix=$HOME/neuron --with-nrnpython=python3
make
make install
export PATH="$HOME/neuron/x86_64/bin:$PATH"
export PYTHONPATH="$HOME/neuron/lib/python:$PYTHONPATH"
source ~/.bashrc
nrniv -python

2.3.5 Step 3: Download and Setup BrainCell

Follow the same steps as Category 1, Steps 1-3 for your platform.

2.3.6 Step 4: Compile Mechanisms

Run the build script for your platform (see Category 1, Step 2).

For clean installations, this step is usually required to compile the included mechanism files.

2.3.7 Step 5: Launch BrainCell

Follow Category 1, Step 4 for your platform.

✅ Verification

You should see:

Installation complete!

2.4 Category 3 - Mixed or Incomplete Environment

⚠️ CRITICAL: Most Common Failure Scenario

2.4.1 Who belongs here?

You are in Category 3 if ANY of the following apply:

This is the most common cause of installation problems.

2.4.2 ⚠️ CRITICAL RECOMMENDATION

❌ DO NOT:

✅ DO THIS INSTEAD:

Follow the clean installation process below.

Clean installation is faster and more reliable than troubleshooting mixed environments.

2.4.3 Clean Installation Process

2.4.3.1 🛑 Step 1: Remove ALL Existing Installations (CRITICAL)

This step is mandatory. Skipping it will cause problems.

2.4.3.2 Windows

2.4.3.3 macOS

rm -rf ~/anaconda3
rm -rf ~/.conda
sudo rm -rf /Applications/NEURON
rm -rf ~/neuron

Edit ~/.zshrc (or ~/.bash_profile):

nano ~/.zshrc

Remove lines containing "anaconda", "conda", "neuron", or "nrn"

Save and reload:

source ~/.zshrc

2.4.3.4 Linux

rm -rf ~/anaconda3
rm -rf ~/.conda

If installed via package manager:

# Ubuntu/Debian
sudo apt-get remove --purge neuron
sudo apt-get autoremove
# Fedora
sudo dnf remove neuron

If compiled from source:

rm -rf ~/neuron

Edit ~/.bashrc:

nano ~/.bashrc

Remove lines containing "anaconda", "conda", "neuron", or "nrn"

Save and reload:

source ~/.bashrc

2.4.3.5 Step 2: Verify Clean System

Open a new terminal/command prompt and verify these commands fail:

python --version    # Should fail or show system Python only
conda --version     # Should fail
nrniv              # Should fail

If any of these work, you haven't fully removed the installations. Return to Step 1.

2.4.3.6 Step 3: Fresh Installation

Now follow Category 2 (Clean System Installation) exactly as written for your platform.

Install in this exact order:

2.5 Advanced Option: Dedicated User Account (Optional)

For the cleanest possible environment, create a new OS user account:

Windows

macOS

Linux

sudo adduser braincell
sudo usermod -aG sudo braincell
su - braincell

Then follow Category 2 installation steps.

2.6 Troubleshooting

2.6.1 Common Issues & Solutions

2.6.1.1 Issue: BrainCell doesn't start

Windows

Symptoms: Double-clicking init.bat does nothing, or window closes immediately

Solutions:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
cd C:\braincellinit.bat

Check for error messages

macOS/Linux

Symptoms: Script doesn't execute or permission denied

Solutions:

chmod +x init.sh
./init.sh

2.6.1.2 Issue: Mechanisms fail to compile

Windows

Solution: Install Microsoft C++ Build Tools

macOS

Solution: Install Xcode Command Line Tools

xcode-select --install

Linux

Solution: Install build tools

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install build-essential

Fedora:

sudo dnf install gcc gcc-c++ make

Issue: NEURON can't find Python

Symptom: NEURON launches but Python commands fail

Platform: All

Solutions:

python --version
nrniv -python>>> import sys>>> print(sys.version)>>> quit()

If still failing: Go to Category 3 and perform clean installation

Issue: "Module not found" errors

Symptom: Python import errors when running BrainCell

Solutions:

which python     # macOS/Linux
where python     # Windows

Should point to Anaconda directory

conda install numpy matplotlib scipy
python -c "import neuron; print(neuron.__version__)"

2.6.1.3 Issue: Permission errors (macOS/Linux)

Symptom: "Permission denied" when running scripts

Solutions:

chmod +x *.sh *.hoc
ls -la

Files should be owned by your user, not root

sudo chown -R $USER:$USER ~/braincell

2.7 Platform-Specific Issues

macOS: Apple Silicon (M1/M2/M3) Compatibility

If BrainCell doesn't work on Apple Silicon:

softwareupdate --install-rosetta
arch -x86_64 python

Linux: Missing GUI libraries

Symptom: NEURON starts but no GUI appears

Solution: Install X11 libraries

Ubuntu/Debian:

sudo apt-get install libx11-dev libxt-dev

Fedora:

sudo dnf install libX11-devel libXt-devel

2.8 Getting Help

If you're still experiencing issues:

Forum support typically responds within 24-48 hours.

2.9 Appendix: Command Reference

Quick Commands by Platform

Windows

# Check Python
python --version
# Check Anaconda
conda --version
# Check NEURON
nrniv -python
# Launch BrainCell
cd C:\braincell
init.bat

macOS/Linux

# Check Python
python --version
# Check Anaconda
conda --version
# Check NEURON
nrniv -python
# Launch BrainCell
cd ~/braincell
./init.sh

2.10 Summary Flowchart

START
  │
  ├─ Do you have NEURON + Python working? ──YES──> Category 1
  │                                                   (Quick setup)
  NO
  │
  ├─ Is your system clean (nothing installed)? ──YES──> Category 2
  │                                                       (Fresh install)
  NO
  │
  └─ Mixed/partial installation? ──YES──> Category 3
                                           (Clean & reinstall)

Version: 2.0 Last Updated: January 2026 Platforms: Windows 10/11, macOS 10.15+, Linux (Ubuntu 20.04+) Feedback: https://forum.neuroalgebra.net

3 Experimental Data or Approximations Needed to Build a Realistic Cell Model

To create a biologically meaningful cell in BrainCell, gather the following data (or use reasonable estimates):

4 GETTING STARTED

4.1 Launching BrainCell

Figure 1. Download and installation overview. (a) Screenshot of the BrainCell download page on Neuroalgebra.net. (b) Example folder structure of the BrainCell 1.0 package on the host computer.

4.1.1 Starting BrainCell

Figure 2. Introductory menu of BrainCell 2.0 showing the Simulation Cell Configuration panel with options for Astrocyte or Neuron mode, and loading methods (Base Geometry, BrainCell Export, External Simulations).

4.2 Simulation Cell Configuration

When the program starts, you can choose the cell type and how to load its model:

Select the option that matches your workflow to proceed.

5 Astro/ Base. Setting up and running BRAINCELL: Astrocyte configuration.

5.1 Generate astocyte morphology.

FigureFigureFigure
Figure 1

5.1.1 Launching Astrocyte model

Figure 3. Astrocyte module control windows opened by the initialisation file init.hoc. (A) Command Console showing the loading of NEURON mechanisms. (B) Astrocyte Model Panel for selecting and loading predefined astrocyte geometries (basic or dendrite–soma combined). (C) Parameter Panel for setting nanoscopic morphology parameters - “Max number of stalks” and “Number of leaves.”

When you start BrainCell in Astrocyte mode, NEURON automatically opens three control windows that work together to initialise and configure the model (Figure 3):

5.1.2 Generating or Downloading the Astrocyte Stem Tree

To build a new astrocyte model, you first need to define the basic dendritic (stem) tree structure. BrainCell offers several ways to do this:

5.1.3 Option 1 - Select library stem tree from NeuroMorpho.org

Click “Select Library Stem Tree” to import an existing 3D reconstruction of an astrocyte. You can use files in general .zip, .hoc, or .swc formats obtained from the NeuroMorpho.org database. It is recommended to store these files in the directory: ...\Geometry\Astrocyte\New Style for easier access.

.

FigureFigure
Figure 2

Figure 4. Importing a 3D astrocyte structure. (A) Example from the NeuroMorpho.org webpage displaying a 3D cell reconstruction. (B) BrainCell operational panels for selecting astrocyte morphology..

5.1.4 Option 2 - Load from local directory

Alternatively, choose a file from your local BrainCell installation folder: ...\BrainCell\Geometry\ Files can be in SWC or HOC format.

To view a 3D structure:

If you change your mind, you can reselect a file at any time - simply click “Select Library Stem Tree” again or choose “Select Stem Tree with Endfoot.” When satisfied, click “Start Astro.” ⚠️ After pressing “Start Astro,” the setup will lock in and cannot be reversed.

5.1.5 Option 3 - Load reconstructed or endfoot-enhanced tree

Selecting “Select Stem Tree with Endfoot” opens a pop-up window (see Fig. 5B) for editing endfoot geometry. Here, you can define the morphology of both main and secondary endfoot branches and assign local biophysical mechanisms.

The option “Select reconstructed stem tree” loads a detailed 3D reconstruction (for example, RealAstrocyteSkeleton1.hoc in the ...\Geometry\ directory). This model represents a CA1 astrocyte skeleton reconstructed using the Vaa3D software (Allen Institute, available at vaa3d.org). The corresponding window (Fig. 5) provides tools for scaling and centring the structure at the coordinate origin, simplifying alignment and compartment placement. Adjustable parameters include:

💡 Note: In all cases, BrainCell will prompt you to locate the appropriate geometry file. Ensure that required 3D data have been downloaded in advance from NeuroMorpho.org.

5.1.6 Option 4 - Add nano-neometry to astrocytic tree

After defining the 3D stem structure, you can enrich the model with nanoscopic astrocytic processes. To do so:

BrainCell will then generate nanostructures randomly, following physiological constraints derived from experimental morphometric statistics. When learning the software, we recommend using “Start Astro” to familiarise yourself with its features and workflow.

5.2 Finalising and Preparing the Astrocyte Geometry

We recommend pressing the “Start Astro” key when first becoming familiar with the BrainCell software. This option automatically loads the selected geometry and initiates all relevant setup panels, allowing you to explore and understand the program’s functionality and available features.

.

FigureFigureFigureFigureFigure
Figure 3

Figure 5. Operational panels for creating and editing astroglial morphology in BrainCell.

(A) File Navigation Panel - lists available .hoc files that define 3D astrocytic structures within the user’s directory. (B) Endfoot Geometry Panel - enables editing of astrocyte endfeet and adding associated biophysical mechanisms. (C) 3D Export Panel - provides tools for exporting the constructed 3D astrocyte model for later analysis or integration with other simulations. (D) Morphology Transformation Panel - allows for precise scaling and spatial shifting of the 3D shape, which is essential for accurate astroglial morphology adjustments.

Note: Before proceeding to additional model design steps, ensure that the cell stem tree geometry has been successfully uploaded to the designated GEOMETRY directory.

6 Generating astroglial morphology on the nanoscale

6.1 The geometry of nanoscopic processes

Figure
Figure 4

Once the stem tree has been loaded, the next step is to define the astrocyte's nanostructure. A popup window (highlighted in yellow) offers two options:

Option 1 - Load Default Nano-Geometry

Press “Diameter Distribution for Nano-Geometry.” This loads a pre-computed file containing diameter statistics generated by the Nano (Geometry) module from sampled 3D-reconstructed astroglial processes. By default, BrainCell imports the file testshape.dat_radii_dist.txt which represents the distribution of process diameters measured in the CA1 stratum radiatum. After loading, press “Start Astro.”

Option 2 - Generate Nano-Geometry Automatically

Press “Start Astro” without selecting an external file. In this case, BrainCell automatically generates nanoscopic processes using internal algorithms that replicate experimentally observed morphometric trends.

In both cases, you can later adjust key morphometric parameters of the generated nanostructures. Detailed controls for these adjustments are provided in the chapter Simulating Astrocyte Physiology.

6.1.1 Populating astrocyte tree with nanoscopic processes

Pressing “Start Astro” launches the main operational interface - the Repertoire of Computation window - where complete astrocyte morphology is modelled (Figure 6).

FigureFigureFigure
Figure 5

Figure 6. Astrocyte Main Window and configuration panels.

(A) Control Panel: provides detailed settings for fine-tuning astrocyte geometry. (B) Simulated Variable Panel: displays simulated parameters mapped onto the astrocyte morphology (e.g., membrane voltage) and a live digital output plot. (C) Biophysics, Stochastic, and Extracellular Sources Settings: configure the cell’s biophysical properties, stochastic parameters, and extracellular input conditions. (D) Nanostructure Placement: defines where nanostructures are placed - across the entire astrocyte or restricted to specific dendrites. (E) Nanostructure Density Distribution: sets the density pattern of nanostructures (uniform or non-uniform), influencing both spatial coverage and physiological behaviour.

Localising Nano-Geometry

An important control located in the upper-left corner of the main window (Fig. 6A) allows the user to restrict nano-geometry generation to specific dendrites.

Follow these steps:

Note: Localised nano-geometry significantly increases computational load but is valuable for studying highly specific subcellular domains and local signalling dynamics.

6.1.2 Nano-Geometry Configuration Panels

Leaf Geometry Panel (Fig. 6A, top)

Defines the distribution of cylindrical leaf compartments (nanoscopic processes).

When experimental 3D statistics are unavailable, a uniform random distribution can be generated within user-defined lower and upper diameter limits.

Note: This panel is ignored if statistical data from a reconstructed nano-geometry file have already been loaded.

Stalk Geometry Panel (Fig. 6A, middle)

Sets upper and lower limits for stalk cylinder diameters, determining how densely the tissue is populated with transitional nanostructures between the main branches and leaves.

Specific Membrane Conductance Panel

Allows setting of membrane conductance using the control “Gm (mS/cm²)”, accounting for the total surface area of exposed nanostructures.

The default resting membrane potential is –85 mV, as defined in NEURON’s Distributed Mechanism panel.

Dendritic Geometry Panel (Fig. 6A, bottom)

Controls branch diameter scaling , i.e., how dendrite diameter decreases with distance from the soma, according to empirical measurements. The relationship follows:

where

6.1.3 Customising Cell Geometry

The “Edit Biophysics” and “Edit Morphology” options enable rule-based modifications of any morphological or biophysical property as a function of distance from the soma. This feature allows users to construct highly customised cell architectures for specific simulation goals.

Note: These editing panels should be skipped if a fully 3D-reconstructed stem tree has already been imported.

6.1.4 Tissue-filling properties of astroglial morphology

Tissue Volume Filling and Geometrical Parameters

The tissue volume-filling properties and surface-to-volume ratios of nanoscopic processes are determined by their individual shapes and by the effective density of simulated nanostructures, as defined in the previous section.

To monitor these parameters, press the “Geometrical Parameters” key (Figure 7). This command opens several analysis windows that display quantitative characteristics of the generated astrocyte morphology - including total cell volume, surface area, surface-to-volume ratio, and volume-filling fraction within the simulated tissue.

All calculated values are automatically saved to the file: ...\neuronSims\Text results\VolumFraction.txt

Below are the key features of the main window:

The neuron simulation tool's main window provides the necessary features to effectively simulate and analyse neuron behaviour.

6.2 "Geometric parameters" button

The “Geometrical Parameters” button calculates and visualises the principal morphometric characteristics of the modelled astrocyte. When pressed, it generates a series of analytical plots and data windows summarising the cell’s geometry.

FigureFigure
Figure 6

Figure 7. Geometrical analysis panels generated by the “Geometrical Parameters” command. Displayed windows (from top left):

The morphometric characteristics displayed in Figure 7 can be compared directly with experimental data derived from 3D electron microscopy reconstructions or two-photon excitation imaging of astroglia. Such comparison allows users to evaluate any discrepancy and adjust the density or scaling of nanoscopic processes accordingly, using the Stalk Geometry and Dendritic Geometry options (see Figure 6) until the model accurately reproduces measured tissue statistics. These geometric-parameter windows can be accessed at any stage of modelling to verify morphological realism and ensure parameter consistency. Once this step is complete, the astroglial morphology is fully established. Further fine structural tuning - such as for FRAP (fluorescence recovery after photobleaching) experiments - can be performed later, as described in subsequent sections. The model is now ready to simulate astroglial functions using the appropriate membrane and intracellular biophysical mechanisms introduced in the following chapters.

The simulation tool's main window provides the necessary features to simulate and analyse behaviour effectively.

7 Astrocyte - Loading a Pre-existing Astrocyte Morphology

BrainCell allows users to load previously created astrocyte morphologies that already include nanostructural detail. This feature enables users to continue simulations, analyse existing models, or apply new biophysical mechanisms without redefining geometry.

FigureFigureFigureFigure
Figure 7

Figure 8. Operational panels for loading pre-existing 3D astrocyte structures with nanoscopic detail. (A) Download Panel: provides access to a previously prepared 3D astrocyte morphology. (Visual: an icon representing data download.) (B) Roadmap Panel: lets users choose between creating a new astrocyte (Base) or loading a pre-existing nanostructured model (Nano). (Visual: a roadmap-style diagram branching to both options.) (C) Schematic Illustration Panel: displays a schematic view of the 3D astrocyte morphology, including its nanoscale architecture. (Visual: a simplified 3D diagram showing astrocytic nanostructure.)

7.1 Loading a Pre-existing Astrocyte (“Astro + Nano”)

To open a saved astrocyte model that already includes nano-geometry:

At this stage, you can:

Important: After loading a pre-existing astrocyte model, its geometry cannot be altered. All subsequent operations relate only to simulations, parameter tuning, and mechanism management.:

The neuron simulation tool's main window provides the necessary features to simulate and analyse neuron behaviour effectively.

8 Neuron mode. Setting up and running BRAINCELL: Neuron module.

8.1 Importing and generating complete neuron morphology

8.1.1 Building a 3D Neuron Model

The Neuron module of BrainCell enables the creation, import, and editing of fully 3D neuronal geometries, independent of the astrocyte module. When you load or create a neuron model, two main interface windows appear:

Allows you to define the maximum number of dendritic spines and modify their geometric characteristics. These parameters can be refined later if required.

To create a new neuron:

FigureFigureFigure
Figure 8

Figure 9. Import, selection, and finalisation of a 3D neuronal structure. (A) Cell Structure Definition Panel: defines the soma, dendrites, and axon. Future updates will support custom naming of geometry and dendritic subgrouping. (B) Cell Shape Selection Panel: provides options to choose or modify the desired neuron morphology. (C) Spine Density Control Panel: adjusts the maximum spine density per dendrite (noting that thicker dendrites generally host fewer spines). Future versions will support continuous spine-density editing.

Workflow Summary (Fig. 9):

To explore different neuron shapes, simply repeat the import and selection steps. When satisfied with the current morphology, click “Use this one” to confirm.

After confirmation, BrainCell opens the main Neuron Editor window, where you can:

This workflow enables the construction of realistic, fully customisable neuronal models ready for advanced simulation.

9 Navigating Neuron Simulation: Exploring Main Windows for Enhanced Analysis

BrainCell provides a powerful and intuitive environment for customising and analysing neuronal geometry and biophysical properties. Users can define how structural and functional components are grouped or divided during model setup:

In the main window (Figure 10), you can modify the neuron’s geometry, apply and test various biophysical mechanisms, and explore how these structural and functional choices influence neuronal behaviour.

.

Figure
Figure 9

Figure 10. Main window for neuron simulation. The main simulation interface provides all tools required to configure, simulate, and analyse neuronal behaviour.

Key Features of the Main Neuron Window

Myelinated Axon (SimMyelinatedAxon) is the most fully featured neuronal simulation. It models action potential propagation along an axon whose geometry can be imported from a morphology file, drawn by hand in the GUI, or set to a built-in predefined shape. The myelin sheath can be deployed, scalped, or removed entirely, and the simulation tracks how each configuration affects conduction velocity and ionic dynamics. Real-time graphs display membrane voltage at three points along the axon, K⁺ equilibrium potential, ionic currents, and ion concentrations as functions of both time and distance. A dedicated inside-out radial diffusion engine (using NEURON's RxD system) computes K⁺ accumulation in the periaxonal space between the axon and Schwann cells across multiple concentric shells, applying Dirichlet boundary conditions at the nodes of Ranvier and zero-flux conditions under the myelin.

Voltage CA1 Neuron (SimVoltageCA1Neuron) is a dedicated neuronal simulation for CA1 pyramidal cell electrophysiology, allowing exploration of dendritic integration and somatic firing patterns in a morphologically realistic neuron.

Calcium Dynamics (SimCalciumDynamics, astrocyte) simulates intracellular Ca²⁺ and IP₃ signalling within astrocyte morphologies, driven by the cadifus.mod kinetic scheme which couples IP₃ receptor gating, Ca²⁺ diffusion across radial annuli, and mobile/immobile buffer interactions.

Calcium Wave (SimCalciumWave) models the propagation of intercellular Ca²⁺ waves, using configurable initial calcium parameters to explore the spatiotemporal spread of calcium signals through coupled compartments.

Glutamate (SimGlutamate) simulates glutamate dynamics including uptake via the electrogenic astrocytic transporter (GluTrans.mod), iterating concentration and current variables across the cell morphology at each time step.

Potassium (SimPotassium) simulates extracellular K⁺ accumulation and clearance, iterating K⁺ fluxes and concentrations across compartments to study spatial buffering by astrocytes and the Na⁺/K⁺-ATPase pump (nkpump.mod).

Spatial Voltage Distributions (SimSpatialVoltageDistributions) maps steady-state and time-varying membrane potential distributions across the full cell morphology, useful for studying dendritic filtering and the spatial decay of synaptic inputs.

Constant Electrical Simulations (SimConstantElectricalSimulations) applies fixed-amplitude stimulation protocols to characterise passive and active membrane properties under controlled, time-invariant input conditions.

Frequency-Domain Electrical Simulation (SimFrequencyElectricalSimulation) analyses the cell's impedance and voltage transfer properties by driving the membrane with sinusoidal inputs across a range of frequencies, enabling resonance and filtering analysis.

FRAP - Cylinder / Plane / Sphere (SimFrapCylinder, SimFrapPlane, SimFrapSphere) simulate Fluorescence Recovery After Photobleaching experiments in three geometric configurations. Each simulation sets an initial bleached concentration profile (circular, planar, or spherical), then evolves the diffusion of a fluorescent species via FRAP.mod to recover the apparent diffusion coefficient from the recovery kinetics.

Outside-In Diffusion (SimOutsideInDiffusion) models the influx of extracellular species into the cell, using the outside-in diffusion engine and range variable history recording to track how extracellular sources (configurable via the Extracellular Manager) drive intracellular concentration changes over time.

Local Field Potential (SimLocalFieldPotential) computes the extracellular field potential generated by the simulated cell at one or more virtual electrode positions. It uses LFPCalculator.py to sum transmembrane currents weighted by the electrode–segment distance geometry, producing estimates of the LFP waveform that can be compared to electrophysiology recordings.

User Simulation is a template-based entry point that allows users to define and integrate their own custom simulation project directly into the SimManager framework. Rather than modifying BrainCell's built-in simulations, a user places their own Python simulation class - derived from the Simulation abstract base class defined in SimABCs.py - inside a dedicated folder under _Code/Simulations/Sims/. The simulation folder is registered with SimManager by adding it to sys.path via sourcePythonCode, after which SimManager instantiates the class and presents it alongside the built-in simulations. This mechanism gives user-defined simulations full access to BrainCell's loaded cell geometry, biophysics presets, Manager infrastructure, and GUI primitives, while keeping the custom code entirely separate from the core codebase and maintaining backward compatibility.

10 Customising Neuronal Connectivity: Spine Set Configuration.

10.1 Configuring Spine Sets

BrainCell lets you create and customise dendritic spines - the tiny protrusions where neurons form synapses. This feature helps you build realistic models and control how spines affect electrical and biochemical properties.

With the Spine Sets tool, you can:

10.2 How to Use the Spine Sets Feature

Figure
Figure 10

Figure 11a. The panel displayed is used to manage spine seeding.

The left panel - Manager of Spine Seeding - lists all existing spine sets and lets you:

The right panel - Spine Locations (all sets) - shows a visual map of spine positions along the dendritic tree, with the currently selected set highlighted.

Using these tools, you can add or adjust the nano-geometry of spines and explore how structural changes affect neuronal behaviour.

10.3 The editing of spine locations.

Figure
Figure 11

Figure 11b. Panels for managing the spatial distribution of spine seeds.

10.4 Spine Seeding Panels

Left Panel - Single Spine Set

Right Panel - Seeded Dendrite(s)

10.5 Panel “Where to Seed the Nanostructures”

The Spine Sets configuration system thus provides an integrated framework for shaping neuronal connectivity at the nanoscale, enabling BrainCell users to model realistic dendritic structures and study how spine organisation impacts synaptic processing and network behaviour.

10.6 The spine, head and neck geometry. Location over dendritic tree.

This part explains how to use the tool to analyse the geometry distribution of dendritic spines (Fig.12). The panel provides two distribution options, regular and uniform, allowing the user to set numerical parameters for each distribution via a window upon selection. The tool also considers the minimum distance between synapses in a dendritic tree as an essential parameter for synapse distribution.

FigureFigureFigure
Figure 12

Figure 12. Spine Geometry Modification Panel

10.7 Configuring Spine Distributions

10.7.1 1. Selecting a Distribution Type

To begin, choose how spines will be distributed along dendrites. Two options are available:

Select your preferred type by clicking the corresponding button (Fig. 12). A parameter window will appear, where you can enter the numerical settings for the chosen distribution.

10.7.2 2. Using Pre-Defined Distribution Types

For convenience, BrainCell includes experiment-based spine geometry templates from: Tønnesen J., Katona G., Rózsa B., et al. Spine neck plasticity regulates the compartmentalisation of synapses. Nat Neurosci 17, 678–685 (2014). https://doi.org/10.1038/nn.3682.

Click the corresponding button on the panel to load one of these pre-established distributions. The tool will automatically apply published experimental parameters for the selected type.

10.7.3 3. Adjusting Spine Complexity

You can control the complexity (number of segments) used to model each spine:

10.7.4 4. Defining Synapse Distance

Synapse spacing is critical for realistic models. BrainCell lets you:

This allows both randomised and user-defined spacing for fine-grained control.

10.7.5 Summary spine geometry and synapse placement

This tool gives full control over spine geometry and synapse placement.

11 Neuron mode. Download previously created neuron model.

The combination "Neuron + Nano” creates a new panel. Once the panel appears, you can proceed with the following steps and open the NEURON Basic Panel to locate the previously prepared Neuron with Nanostructure. To proceed with the simulation and management of biophysical mechanisms, select the neuron with Nanostructure in hoc-file. This will take you to a new option for simulation and management (see Fig.13).

Note: At this stage, you cannot modify the geometry.

Figure
Figure 13

Figure 13: Left: The "Alternative Run Control" panel is designed to initialise and run simulations with specific settings like initial membrane voltage, run time, and integration step size, including options for continuous or single-step simulation. It emphasises using this customised run control to maintain the defined stochasticity models.

Right: The "Repertoire of Computation" panel, referred to as "Previously created Neuron morphology ", appears to be a visualisation and simulation panel. It has sections for editing cell biophysics, gap junctions, synapses, and extracellular sources, as well as a range of simulation categories such as voltage, electric stimuli, and ion-specific dynamics. The panel also warns about integrating custom biophysics mechanisms into the simulation.

12 Manager of biophysical mechanisms.

The Manager of Biophysical Mechanisms lets you add, edit, and organise biophysical mechanisms within your neuron model to study their effect on neuronal behaviour.

Click the “Manage the Distance of Mechanisms” button in the upper-right corner of the main window (Fig. 10 . Main Window). This opens two main panels (Fig. 14):

12.1 Cell Compartments & Mechanisms

This panel provides tools for editing compartments and managing mechanisms:

These features let you customise the cell’s structural regions, integrate additional mechanisms, and keep a reusable library for future simulations.

FigureFigure
Figure 14

Figure 14. Panels for Managing Biophysical Mechanisms

A - Distributed Mechanisms Manager This panel lets users organise and edit the distribution of biophysical mechanisms across cell compartments. You can add or split regions, scan existing areas for their assigned mechanisms, adjust spatial distributions, and export or import mechanism sets for reuse in other models.

B - Area-Centric Mechanism List Shows all mechanisms available for the currently selected cell area. Use this view when you want to see which mechanisms are present in a particular compartment and add or remove them as needed.

C - Mechanism-Centric Area List Shows all cell areas associated with the currently selected mechanism. Use this view when you want to see where a given mechanism is applied and edit its distribution across compartments.

Use the Apply button to confirm additions or removals. The toggle button at the bottom switches between the area-centric (B) and mechanism-centric (C) views, providing a flexible way to manage mechanism placement and distribution.

12.2 Managing Mechanisms and Cell Parts

Windows B and C give you full control over biophysical mechanisms and the structural organisation of your neuron model.

12.2.1 1. Mechanism Management

12.2.2 2. Two Display Modes

12.2.3 3. Selecting Mechanisms

12.2.4 4. Cell-Part Operations

12.2.5 5. Mechanism Interaction & Advanced Tools

Windows B and C provide a powerful, visual way to edit cell parts and mechanisms, making it easier to customise, analyse, and refine your neuron model for accurate simulation results.

12.3 Split, Merge and Remain option.

12.4 Splitting Cell Compartments

The Split function in BrainCell lets you divide any part of a cell into multiple sub-compartments, give them custom names, and assign different biophysical mechanisms to each. This is especially useful when you want to model distinct properties within a single region (e.g., dividing a dendrite into sections with different ion channel densities).

12.4.1 Steps to Split a Compartment

This feature allows you to model fine-grained, localised cellular behaviour. For example, you can divide a single dendrite into over 150 segments, giving each its own electrical or synaptic properties to match experimental data or test specific hypotheses.

FigureFigureFigure
Figure 15

12.5 Merging Cell Compartments

The Merge function lets you combine two or more compartments into a single region. This is useful when you want to simplify a model, reduce the number of compartments, or make several regions share the same biophysical mechanisms.

Steps to Merge Compartments:

Figure
Figure 16

12.5.1 Notes on Merging

12.6 Renaming Cell Compartments

The Rename function allows you to assign custom names to existing compartments, making models easier to navigate and understand. This is especially helpful when compartments represent specific functional or anatomical regions.

Figure
Figure 17

12.6.1 Steps to Rename a Compartment

12.6.2 Notes about compartment

13 Adjust the spatial distribution of biophysical mechanisms.

The panel (Figure 15) adjusts the spatial distribution of the mechanism across any part of the cell, allowing the user different options to define the mathematical formula for the spatial distribution.

FigureFigureFigureFigure
Figure 18

13.1 Synapse distribution.

The tool facilitates the addition and distribution of different types of synapses on the dendritic tree, enabling the study of the neuron's connectivity and behaviour.

Figure 15: Panels for adding spatial properties to biophysical mechanisms in a cell. A) Mechanism Selection Panel: Users can select a biophysical mechanism and choose to modify its spatial. B) Spatial Property Definition Panel: Users can define the spatial properties of the selected parameters or variables. C) Examples Panel: Displays examples of the types of parameters and variables that can be modified for each biophysical mechanism. D) Spatial Model Activation Panel: Users can enable the spatial properties of the selected parameter or variable by pressing the "Define as a function " button.

13.1.1 Main Interface for Editing Biophysical Mechanisms

The main interface (Fig. 15A) provides a central view of the neuron, with each segment (soma, dendrites, axon, etc.) shown in its own panel. Within each segment’s panel, you can see and manage all the biophysical mechanisms assigned to that region.

13.1.1.1 Editing a Mechanism

This interface provides direct, visual control over each neuron part and its mechanisms, enabling precise customisation of electrical and biophysical properties.

In the Heterogeneity Editor, you can define the variable as a function of distance. This allows you to customise the properties of the variable based on the spatial location. Once you've described it, you can save your changes (by clicking the Apply button) and edit other mechanisms.

13.1.2 Spatial Inhomogeneity of Biophysical Mechanisms Editor.

The Heterogeneity Editor (Fig. 15B) lets you define how a mechanism’s properties vary across different segments of a neuron.

The window is divided into three main areas:

For example:

13.1.3 Spatial Inhomogeneity Specification

BrainCell lets you define how a biophysical mechanism varies across different parts of the neuron. This is done in the central panel of the Heterogeneity Editor, which provides five modes for setting spatial inhomogeneity.

13.1.3.1 Modes for Specifying Spatial Inhomogeneity

13.1.4 Visualising Spatial Heterogeneity

At the bottom of the panel, you can choose how to visualise heterogeneity:

These visualisation tools help you verify and refine the spatial variation of your chosen mechanism.

14 Adjust the stochastic distribution of mechanisms.

The central panel (Figure 16) adjusts the mechanism's stochastic properties across any part of the cell, allowing the user to define the mathematical formula for the stochastic distribution using different options.

FigureFigureFigure