A high-performance 3D neural network simulator with real-time OpenGL visualization, leveraging NVIDIA CUDA/CuPy for massively parallel GPU computation. Simulates large-scale networks (10K-100K+ neurons) with biologically-inspired models including Izhikevich and Hodgkin-Huxley neurons, synaptic plasticity, and spatial connectivity.
- CuPy-based computation: All neural dynamics run on GPU using fused CUDA kernels
- Scalable: Efficiently handles 10K-100K+ neurons with millions of synaptic connections
- Real-time performance: 60 FPS visualization with parallel simulation updates
- Memory optimized: Smart GPU memory management with automatic garbage collection
- Izhikevich 2007 (9-parameter formulation): Fast, biologically plausible spiking neurons
- Wide range of cortical and subcortical cell types
- Efficient GPU computation with rich dynamics
- Supports regular spiking, fast spiking, bursting, chattering, and more
- Per-neuron parameter customization
- Hodgkin-Huxley (multi-current): Detailed biophysical conductance-based model
- Extensive library of region-specific presets (cortex, hippocampus, thalamus, basal ganglia)
- Temperature-dependent kinetics with Q10 scaling
- Standard Na⁺/K⁺/leak channels plus optional extended currents:
- M-current (KCNQ, spike frequency adaptation)
- T-type Ca²⁺ (low-threshold bursting)
- I_h (hyperpolarization-activated cation current)
- Persistent Na⁺ (NaP, subthreshold oscillations)
- Profile-matched presets for realistic network simulations
- Adaptive Exponential Integrate-and-Fire (AdEx): Efficient spiking model with adaptation
- Exponential spike generation mechanism
- Two-variable system (voltage + adaptation current)
- Balanced speed and biological realism
- Ideal for large-scale network simulations
- Hebbian Learning (LTP/LTD): Activity-dependent weight modification
- Short-Term Plasticity (STP): Tsodyks-Markram depression and facilitation
- STDP (Spike-Timing-Dependent Plasticity): Classical Bi & Poo asymmetric learning window
- LTP when postsynaptic spike follows presynaptic spike
- LTD when presynaptic spike follows postsynaptic spike
- Exponentially decaying timing window (~20ms)
- GPU-accelerated weight updates
- Reward-Modulated Plasticity: Three-factor learning rule (Izhikevich 2007)
- Eligibility traces track recent synaptic activity
- Dopamine-like reward signal modulates weight changes
- Enables reinforcement learning and delayed reward tasks
- Structural Plasticity: Dynamic synapse formation and elimination
- Activity-dependent connection formation
- Weak synapse pruning
- Distance-dependent spatial clustering
- Homeostatic connection density regulation
- Homeostatic Plasticity: Adaptive firing thresholds for network stability
- Conductance-based synapses: Separate excitatory (AMPA) and inhibitory (GABA) channels
- Parameter Heterogeneity: Per-neuron variability via lognormal/Gaussian distributions
- Biologically realistic coefficients of variation (CV ~0.3-0.4)
- Scientifically grounded defaults from experimental literature
- Applied to all neuron models automatically
- Enhanced Channel Noise: Intrinsic stochasticity for realistic dynamics
- Ornstein-Uhlenbeck background current (synaptic bombardment model)
- Multiplicative conductance noise for HH model channels (5% relative)
- Configurable noise levels with GPU-accelerated generation
- Produces realistic membrane potential fluctuations (2-5mV)
- Neural Structure Profiles: Brain-region specific network templates
- Cortex (L2/3 RS/FS), Hippocampus (CA1), Striatum (MSNs), and more
- Predefined cell-type mixtures and E/I ratios
- Profile-compatible HH presets (e.g., CA1 bursting, STN pacemaker)
- 3D spatial connectivity: Distance-dependent connection probabilities
- Trait-based organization: Neuron populations with shared properties
- Watts-Strogatz networks: Small-world topology generation
- Inhibitory interneurons: Configurable E/I balance with multi-trait support
- Real-time 3D OpenGL rendering: Hardware-accelerated graphics
- Interactive camera: Orbit, pan, zoom controls
- Activity visualization: Color-coded neuron states (firing, silent, recent activity)
- Synaptic pulse rendering: Visual feedback for spike propagation
- GPU-efficient filtering: Type-based and activity-based neuron filtering on GPU
- HDF5-based recording: Efficient compression and streaming to disk
- GPU-buffered recording: Zero-copy recording of entire simulations in VRAM
- Frame-accurate playback: Scrub through recorded simulations
- State checkpointing: Save and restore full simulation state
- DearPyGUI control panel: Comprehensive parameter configuration
- Live monitoring: Real-time metrics (firing rate, spike counts, plasticity events)
- System logs panel: Real-time console output with search, export, and auto-scroll
- Profile management: Save/load simulation configurations as JSON
- Performance testing: Built-in benchmarking with stop/start controls
- Keyboard shortcuts: Quick access to common operations
python >= 3.8
cupy-cuda12x >= 12.0.0 # For CUDA 12.x (adjust for your CUDA version)
numpy >= 1.21.0
h5py >= 3.7.0
dearpygui >= 1.9.0
PyOpenGL >= 3.1.6
PyOpenGL-accelerate >= 3.1.6
- GPU: NVIDIA GPU with CUDA compute capability 6.0+ (Pascal or newer)
- VRAM:
- 4GB minimum (for 1K-10K neurons)
- 8GB recommended (for 10K-50K neurons)
- 16GB+ for large networks (50K-100K+ neurons)
- RAM: 8GB+ system memory
- Display: OpenGL 3.3+ compatible graphics
-
Install CUDA Toolkit (if not already installed):
- Download from NVIDIA CUDA Downloads
- Version 11.x or 12.x recommended
-
Install CuPy (match your CUDA version):
# For CUDA 12.x pip install cupy-cuda12x # For CUDA 11.x pip install cupy-cuda11x
-
Install other dependencies:
pip install numpy h5py dearpygui PyOpenGL PyOpenGL-accelerate
-
Clone and run:
git clone https://github.com/danthi123/neural-simulator.git cd neural-simulator python neural-simulator.py
- Launch the simulator:
python neural-simulator.py - Configure parameters in the DearPyGUI control panel (left side)
- Click "Apply Changes & Reset Sim" to initialize the network
- Click "Start" to begin simulation
- Use mouse in OpenGL window to navigate:
- Left click + drag: Rotate camera
- Right click + drag: Pan camera
- Scroll wheel: Zoom in/out
The simulator includes a visualization performance benchmark that determines your hardware's maximum neuron and synapse count for real-time simulation with visualization enabled.
- Run benchmark from GUI: Click "Run Viz Performance Test" in Testing & Optimization section
- Run from command line:
python viz_benchmark.py --output benchmarks/viz_performance_results.json python viz_benchmark.py --quick # Faster reduced sweep
The benchmark:
- Tests incrementally scaled networks (1K to 100K neurons)
- Measures visualization update times at 30/60/90+ FPS thresholds
- Identifies GPU→CPU data transfer bottlenecks
- Generates a hardware performance note displayed in the GUI
- Results auto-load on simulator startup from
benchmarks/viz_performance_results.json
Note: The FPS counter in the OpenGL HUD shows current visualization update rate (0 when stopped/paused).
The simulator includes a headless auto-tuning workflow that scans combinations of neuron model, neural structure profile, and Hodgkin–Huxley preset to pick sensible external drive scales so networks are active but not saturated.
- Run a full tuning sweep (all profiles and presets):
python neural-simulator.py --auto-tune
- Run a faster, reduced sweep (for testing):
python neural-simulator.py --auto-tune --quick
This produces simulation_profiles/auto_tuned_overrides.json, which contains
per-combination overrides (e.g. hh_external_drive_scale, adex_external_drive_scale).
These are automatically loaded and applied whenever you:
- Select the corresponding Neuron Model / Neural Structure Profile / HH preset in the UI
- Click "Apply Changes & Reset Sim"
In the HH and AdEx parameter panels you can see and adjust these as:
- External Drive Scale (HH, auto-tuned) – scales baseline HH DC input
- External Drive Scale (AdEx, auto-tuned) – scales baseline AdEx DC input
You can also click the "Reset HH Drive to Auto-Tuned" or "Reset AdEx Drive to Auto-Tuned" buttons to restore the slider to the auto-tuned value for the current combination, then press Apply & Reset to use it in the simulation.
Neurons: 1,000
Connections per neuron: 100
Model: Izhikevich (RS Cortical Pyramidal)
dt: 1.0 ms
Neurons: 10,000
Connections per neuron: 500
Model: Izhikevich (mixed RS/FS)
Enable Hebbian Learning: Yes
Enable STP: Yes
dt: 1.0 ms
Neurons: 50,000+
Connections per neuron: 1,000+
Model: Izhikevich
dt: 1.0 ms
Note: Requires 16GB+ VRAM
- Total Simulation Time: Duration in milliseconds
- dt (Time Step): Integration timestep (0.025-1.0 ms)
- Smaller values = more accurate but slower
- Izhikevich: 1.0 ms typical
- Hodgkin-Huxley: 0.025-0.05 ms recommended
- Seed: Random seed for reproducibility (-1 for random)
- Connections per Neuron: Average outgoing synapses
- Num Traits: Number of neuron populations/types
- Enable Watts-Strogatz: Use small-world topology vs spatial
- Hebbian Learning Rate: LTP strength (0.0001-0.001 typical)
- STP Parameters:
- U: Baseline utilization (0.1-0.5)
- tau_d: Depression timescale (50-500 ms)
- tau_f: Facilitation timescale (20-200 ms)
- STDP Parameters (enabled by default):
- A+: LTP amplitude (0.005-0.02, default: 0.01)
- A-: LTD amplitude (0.005-0.02, default: 0.0105)
- τ+/τ-: Time constants (~20ms)
- Reward Modulation (enabled by default):
- Learning rate: 0.001-0.05 (default: 0.01)
- Eligibility trace decay: 500-2000ms (default: 1000ms)
- Reward signal: Set dynamically during simulation
- Structural Plasticity (enabled by default):
- Formation rate: ~1e-6 per timestep
- Elimination rate: ~5e-7 per timestep
- Update interval: Every 100 steps for efficiency
- Homeostasis Target Rate: Desired firing rate for stability (0.01-0.05)
- Viz Update Interval: Steps between visual updates (17 for ~60fps at dt=1.0ms)
- Point Size: Neuron rendering size
- Max Neurons to Render: Performance cap for visualization
- Spiking Mode:
- Highlight Spiking: Show recent activity
- Show Only Spiking: Filter inactive neurons
- No Spiking Highlight: Static colors
The main entry point is neural-simulator.py.
python neural-simulator.pyStarts the DearPyGUI control window and the OpenGL 3D visualization (if PyOpenGL is available). All configuration is done through the UI.
python neural-simulator.py --auto-tune [--quick]--auto-tune– run the headless tuning workflow instead of launching the GUI.--quick– optional; restricts the sweep to a smaller subset of profiles/presets for faster runs (useful while developing).
The tuner:
- Iterates through Hodgkin–Huxley + AdEx model combinations with all defined Neural Structure Profiles.
- For HH, only uses profile-compatible HH presets (e.g. striatum → MSN, CA1 → CA1 pyramidal, STN–GPe → STN bursting). Generic/unstructured profiles still allow all HH presets.
- For each combination, tests several external drive scales.
- Measures spike activity, fraction of neurons that spiked, and connectivity.
- Chooses the best scale according to simple criteria (network is alive but not seizure-like).
- Saves the results into
simulation_profiles/auto_tuned_overrides.json.
At runtime, whenever a matching combination is selected in the GUI, these values are applied automatically before initialization.
- ESC: Exit application
- R: Reset camera position
- S: Toggle synapse visibility
- N: Cycle neuron display modes (Highlight Spiking → Show Only Spiking → No Spiking Highlight)
- Space: Pause/Resume simulation (or Start if stopped)
- Ctrl+S: Save profile
- Ctrl+L: Load profile
- Ctrl+Shift+S: Save checkpoint
- Ctrl+Shift+L: Load checkpoint
- Stores simulation configuration parameters
- Includes GUI settings and visualization preferences
- Human-readable, can be edited manually
- Location:
simulation_profiles/
- HDF5 format with full simulation state
- Includes neuron states, connectivity, plasticity variables
- Compressed for efficient storage
- Location:
simulation_checkpoints_h5/
- HDF5 format with frame-by-frame simulation data
- GPU-buffered recording for maximum performance
- Includes initial state and all dynamic variables per frame
- Location:
simulation_recordings_h5/
Configure GPU-specific features via GPUConfig dataclass:
Recording Modes:
gpu_buffered(default): Store all frames in VRAM for maximum speedstreaming: Write frames directly to disk as generateddisabled: No recording
Playback Modes:
gpu_cached(default): Load entire recording into VRAM for instant seekingstreaming: Read frames from disk on demandauto: Automatically choose based on available GPU memory
CUDA-OpenGL Interop: Enable zero-copy GPU→OpenGL transfers for visualization with no CPU roundtrip.
Memory Management:
memory_pool_limit_fraction: Max GPU memory for CuPy pool (default: 0.8)memory_pressure_threshold: Trigger cleanup above this usage (default: 0.9)enable_adaptive_quality: Reduce quality under memory pressure
Enable detailed profiling in your simulation:
from neural_simulator import GPUConfig, SimulationBridge, CoreSimConfig
gpu_config = GPUConfig(
enable_profiling=True,
profiling_detailed=True,
profiling_window_size=1000 # Keep last 1000 step timings
)
sim = SimulationBridge(
core_config=CoreSimConfig(num_neurons=10000),
gpu_config=gpu_config
)Get profiling statistics:
stats = sim.get_profiling_stats()
print(f"Mean step time: {stats['step_total']['mean']*1000:.2f}ms")
print(f"P95 step time: {stats['step_total']['p95']*1000:.2f}ms")Export full profiling report:
sim.export_profiling_report("profile_report.json")Run comprehensive benchmark suite:
python benchmark.py --output results.jsonQuick benchmark (reduced configurations):
python benchmark.py --quickCompare against baseline:
python benchmark.py --compare benchmarks/baseline_v1.jsonThe benchmark suite:
- Sweeps network sizes (1K, 10K, 50K neurons)
- Tests different connection densities
- Runs all neuron models (Izhikevich, HH, AdEx)
- Measures step time, GPU memory, throughput
- Outputs JSON report with system info
For reproducible simulations:
- Set explicit seed:
config = CoreSimConfig(seed=42)- Track actual seed used:
sim._initialize_simulation_data()
print(f"Actual seed: {sim.runtime_state.actual_seed_used}")- Run determinism tests:
pytest tests/test_determinism.py -vAll RNG sources (CuPy, NumPy, random) are initialized together for full determinism.
The simulator automatically manages GPU memory, but you can optimize:
- Configure
GPUConfig.memory_pool_limit_fraction(default: 0.8) - Adjust
memory_pressure_thresholdfor earlier cleanup - Reduce
Max Neurons to Renderif visualization is slow - Disable synaptic pulses for better performance
- Use larger
Viz Update Intervalto reduce GPU-CPU transfers - Close other GPU-intensive applications
| Network Size | VRAM Usage | Expected FPS | Notes |
|---|---|---|---|
| 1K neurons | ~500 MB | 60+ FPS | Real-time interactive |
| 10K neurons | ~2 GB | 60 FPS | Smooth, recommended |
| 50K neurons | ~8 GB | 30-60 FPS | High performance GPU |
| 100K neurons | ~20 GB | 15-30 FPS | Enthusiast/research |
- GPU bottleneck: Reduce network size or disable STP/Hebbian learning
- CPU bottleneck: Increase visualization update interval
- Transfer bottleneck: Enable GPU-buffered recording
- Memory constraints: Networks >100K neurons require very large VRAM (20GB+)
- Visualization performance: Rendering >50K neurons simultaneously may reduce FPS
- Platform: Currently Windows/Linux with NVIDIA GPUs only (CUDA requirement)
- Precision: Uses float32 for performance; float64 not currently supported
- Reduce number of neurons or connections per neuron
- Close other applications using GPU memory
- Check GPU memory with
nvidia-smi - Disable Hebbian learning and STP for reduced memory usage
- Reduce
Max Neurons to Render - Increase
Viz Update Interval - Disable synaptic pulse rendering
- Use "Show Only Spiking" filter mode
- Ensure CUDA drivers are up to date
- Verify CuPy installation:
python -c "import cupy; print(cupy.cuda.runtime.getDeviceCount())" - Check that GPU compute capability is 6.0+
- Main Thread: DearPyGUI event loop and OpenGL rendering
- Simulation Thread: GPU-accelerated neural dynamics computation
- Communication: Lock-free queues for inter-thread messaging
- Fused CUDA kernels: Minimized kernel launches for dynamics updates
- Sparse matrix operations: CSR format for connectivity
- Vectorized operations: Full GPU parallelization of neuron updates
- Zero-copy transfers: CUDA-OpenGL interop for visualization
- Memory pooling: Reduced allocation overhead with CuPy memory pool
Contributions are welcome! Areas for improvement:
- Additional neuron models (LIF/GLIF, multi-compartment)
- Spike-timing dependent plasticity (STDP)
- Layered connectivity motifs and topographic organization
- Network analysis tools (connectivity statistics, firing patterns)
- Export to SONATA/NeuroML formats
- Multi-GPU support for larger networks
- AMD ROCm/HIP port for non-NVIDIA GPUs
MIT License - See LICENSE file for details
If you use this simulator in your research, please cite:
@software{neural_simulator_2025,
title = {GPU-Accelerated Neural Network Simulator},
author = {danthi123},
year = {2025},
url = {https://github.com/danthi123/neural-simulator}
}- Izhikevich neuron model: Izhikevich, E. M. (2007). Dynamical Systems in Neuroscience
- Hodgkin-Huxley model: Hodgkin & Huxley (1952). J. Physiol.
- AdEx model: Brette & Gerstner (2005). J. Neurophysiol.
- STP model: Tsodyks & Markram (1997). PNAS
- Parameter heterogeneity: Marder & Goaillard (2006), Tripathy et al. (2013)
- OU process noise: Destexhe et al. (2001), Destexhe & Rudolph-Lilith (2012)
- Channel noise: White et al. (2000)
- CuPy library for GPU acceleration
- DearPyGUI for UI framework
- OpenGL for 3D visualization
For questions, issues, or suggestions:
- GitHub Issues: Project Issues
Note: This is a research/educational tool. For production neuroscience simulations, consider established frameworks like NEST, Brian2, or NEURON.